cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [docs] test publish from daisy
Date Wed, 12 Oct 2005 12:29:55 GMT
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

Mime
View raw message