cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [Documentation] clarifications about docs
Date Sun, 06 Nov 2005 10:48:27 GMT
Ross Gardler wrote:
> 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...

The Cocoon docs are basically in two sections:

1) The top-level docs, i.e. the "Home" tab at
cocoon.apache.org (and the "Fr" tab).

2) The docs for each version, i.e. 2.1

All the *generated* docs are stored in
http://svn.apache.org/repos/asf/cocoon/site/site
and that is made live on the server by doing
svn checkout of that section of the repository.

The sources and forrest config for the top-level
website are at http://svn.apache.org/repos/asf/cocoon/site

There is some scanty documentation at
http://wiki.apache.org/cocoon/CocoonWebsiteUpdate

> > 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.

I presume you are talking about the Cocoon 2.1 generated docs.
See above.

> >- 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/

Helma, no there is no automated process to publish the site.
Forrestbot is only building the documentation so that
doc editors can see the result. Also it makes sure that
people don't break the integrity of the site with broken
internal links and missing images etc. It also lets us tweak
the colours and placement of logos etc.

You will understand more with the above wiki page.
Also see the instructions for all ASF committers
about building their project websites.
http://www.apache.org/dev/project-site.html

> >- 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 ;-)

Thanks for your efforts with that.

I hope that someone else has checked that we are not
going to make a mess of the URL space at
cocoon.apage.org/2.1/ as it would be very important
a technology like Cocoon and Forrest do not break any URLs.

> 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 the release, someone needs to decide how we are
going to package the docs with the release.

For the website, the generated content needs svn checkin.

> 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.

I am not so sure about that. It would be better that
we worked together at the infra site-dev mailing list
to solve some of the broader issues.

> >- 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).

That is correct. Cocoon committers need to build it locally
using Forrest and commit the generated docs. Generally they
don't bother. So the website stagnates.

-David

Mime
View raw message