cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [Documentation] clarifications about docs
Date Sat, 05 Nov 2005 21:50:56 GMT
hepabolu wrote:
> just to get the confusion level down I'd like to verify that my ideas 
> about the current docs are complete and correct.

Good idea, I've been a little confused by the need for continuing the 
cocoon-site build. Here's what I think I understand...

>  From what I've gathered from the various threads the idea is currently 
> as follows:
> 
> In general:
> - Daisy at the cocoon.zones is our staging server for the documentation 
> of all current and future version of Cocoon. The main advantage is the 
> ease of creating/editing the documentation. It is not our main 
> documentation site, because both the server and Daisy will most likely 
> not be able to handle the performance load of a large number of visitors.

Yes, although sine the 2.2 xdocs are still in SVN (cocoon/site) so there 
may be overlap at present.

> - cocoon.apache.org is our main documentation site and there should be 
> an automated process that updates this site based on the info in Daisy.

There is some data on that site that is not currently in Daisy. For 
example, the index page. I suspect this is why the cocoon-site 
forrestbot is working on 
http://forrest.zones.apache.org/fr/build/cocoon-site/

> - we want to include a snapshot of the documentation in every cocoon 
> release, i.e. it should be available for download, but separated from 
> the cocoon release.

Yes

> Cocoon 2.1.8+
> - to keep the documentation "backward compatible", cocoon.apache.org 
> should look very similar to the old version, i.e. with a blue header 
> bar, a blue menu bar with rounded edges. It should also have the same 
> urls as the old version.

I hope the URLs point is correct. I worked hard on that part ;-)

There are some docs in Daisy at present that do not have a name in the 
URL, I suspect that these are new documents, but have not yet had the 
time to verify this. For example, see document 755

> - the site is generated using Forrest with an automated process set up 
> on forrest.zones. The result is currently available at 
> http://forrest.zones.apache.org/ft/build/cocoon-docs/2.1/ but will be 
> moved to cocoon.apache.org after the 2.1.8 release.

Yes, that is the current state of play. During the release process 
either David Crossley or myself will have to zip the build in the 
Forrest zone for the release.

For future releases, if Cocoon sticks with Forrest, I think we should 
set up a Forrestbot in the Cocoon Zone so that Cocoon devs have access 
to it and its generated files.

> Cocoon 2.2+
> - the documentation is generated as a Daisy book in both PDF and HTML.

It is, but the current structure does not lend itself to being a book. 
We should discuss this.

> - there is a minimal static part of the website, that is generated and 
> maintained by Maven2. The content of this part of the site is mostly 
> what can be defined in the top-level pom.xml:
>   - "about us" with a link to the Daisy documentation,
>   - "changes.xml" with the info of our current status.xml
>   - some extra default Maven pages, like info on mailing lists, SVN access

I have no idea about the maven stuff. But currently this is part of the 
Forrest generated cocoon-site as well.

> - both the "maven site" as well as the HTML Daisy book are restyled and 
> can have a different look. I do suggest something different, although I 
> think the main color should be blue, to at least keep some link with the 
> previous versions. A change of logo is also ok, _BUT_ it should be at 
> least recognizable as the word cocoon. Hint: <cocoon/> ?

There is nothing to stop us creating a new skin for Forrest generated 
docs as well. I don't recall any discussion about moving to a Maven + 
Daisy setup.

I have no objection right now, but is it the right thing?

> - there is an automated process that can generate the static site as 
> well as the do the Daisy book generation and exportation to 
> cocoon.apache.org.

Is there? I am only aware of the ForrestBot as an automated process. 
That can build the static site and it could be configured to extract the 
Daisy Book. I'm not aware of any other automation at this time.

There is no automated process for exporting directly to 
cocoon.apache.org (that I am aware of).

Ross

Mime
View raw message