hepabolu wrote:
Ross Gardler wrote:
See: http://people.apache.org/~rgardler/cocoon-site/653.daisy.html
Correct. It looks much slicker than the "official" site, although my
fingers itch to do something about the navigation (CSS wise).
My SVN committership has now been enabled. As soon as I get chance I'll
commit the cocoon-site module. Where should it go?
There are broken links now we switched to the new navigation. See
http://people.apache.org/~rgardler/cocoon-site/brokenlinks.xml
Hmm, I've looked this page but there are quite a few odd broken links.
Looking into this:
- page 417 is actually wrong in its source, i.e. the links are wrong in
the original xdoc version as well. Since it's more or less outdated I'm
not really interested in updating it.
The same goes for other pages.
The problem is that the Forrest build system reports a "build failed"
when there is a single broken link. That is, Forrest can't tell whether
it's an "OK" broken link or a real broken link. We need to either remove
the page or fix the link.
- page 654 should be excluded from the export, since it has only
relevance in Daisy and does not contain any Cocoon related information.
The export is defined by the navigation document. Page 654 is identified
as home in the navigation document, therefore it is included. Removing
it from the navigation document means that when using Daisy it is
difficult to return to that page.
The solution is to have a navigation document that is exclusively for
the published site, and another that is exclusively for the editing of
the site.
- the reference to index.xml/index.html I cannot explain. Have you
looked at the nodeID attribute of each doc in the navigation file? I've
entered the "original" filename to avoid the numbering in the URL as
well as give some "backward compatibility".
That is a problem with the Daisy plugin. For some reson the locationmap
is not rewriting the index.html request. It works in another Daisy
export I have, but not in this one. I will explore ASAP.
It is worth noting that you can break up the navigation into multiple
documents within Diasy and then bring them together into a single site
structure for Forrest. This makes it a little easier on the Daisy side
of things since you only see nav elements of interest to your current
focus.
Well, I've done this for the legacydocs to get everything in one place
and to have "backward compatibility".
Now that Daisy books are available, things have changed. I've discussed
this with the guys from Outerthought and actually we feel that the Daisy
navigation should be geared towards the editors. So there should be
queries like "my documents", "legacy documents not yet decided on", "all
documents A-Z". In any case, adding a new page should not mean you have
to manually edit the navigation file.
+1 (see my comment above re different navs for publishing and editing)
The navigation for Daisy books should be geared towards the reader/user
and would follow the current navigation much more. We might even end up
with several Daisy books (e.g. User Manual, Reference Guide).
Good. I will look into the Daisy Books definition files to see how we
can use them as the published site navigation. That way there is no need
to maintain two sets of files.
Would you like me to illustrate this by splitting the user and dev doc
navigation files out?
I get the idea, but I think it is not worth the effort. The legacy docs
are there as an effort to consolidate all CURRENT documentation and
provide the best quality of documentation we currently have. I'll finish
my project of removing docs from the repository ASAP, to avoid further
confusion of where to modify/add documentation.
OK.
I've turned PDF's off for now. Currently the Forrest plugin does not
support Daisy Books, but it should. In the meantime we can pull the
published book from Daisy. This is not a problem as long as we are not
trying to integrate content from different sources into the book
(which at present we are not doing).
No, I don't think integration is necessary. As stated in a previous post
I'm thinking about a few relatively static pages with the most prominent
info on Cocoon and a link to the Daisy book(s) for the actual
documentation.
Since Cocoon 2.2-dev switched to Maven2 for the build I figured we might
as well use a part of the site building functionality in Maven.
I'm currently filling in the blanks for the "project info" and some of
the "project reports", i.e. only the info that is part of the main pom.xml.
That will give enough information to users and potential contributers to
get up and running and after that there's the Daisy documentation.
This information is almost static and answers a lot of the FAQs I've
seen lately (i.e. SVN address, mailing lists etc.).
Of course, skinning should be done as well.
WDYT?
The problem with using different build tools for different parts of the
documentation is that you end up with multiple locations for skinning.
As you seem to appreciate, this is the strength of Forrest, pulling
content from various sources and skinning it consistently. We've always
had the intention of creating plugins for Forrest that integrates
reports etc. from Maven. Perhaps this will be the use case that finally
makes it happen.
Ross
