cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: Status new Cocoon documentation
Date Tue, 15 Feb 2005 11:39:42 GMT
Reinhard Poetz wrote:
> David Crossley wrote:
> 
> >Here is one thing that i cannot grasp yet:
> >How will the automatically generated "Sitemap Component Documentation"
> >(i.e. the old /userdocs/) fit in with these static repositories?
> >Currently we need to run 'build docs' to prepare them, then do 'forrest'.
> >http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html
> 
> For me it's very important that whatever the solution is, it must be usable 
> with forrestbot because otherwise we would lose the automatic deployment.
> 
> IIUC you build the sitemap-component-docs (SCD) on your local machine and 
> commit them into the SVN, don't you?

I am not sure what you are asking.
The 'build docs' generates some extra xml source for forrest to consume.
It copies the xml sources to a temp directory, generates the installing/jars.xml,
re-writes the /userdocs/*.xml by reading the original manually maintained
content and merging it with stuff gathered from the relevant *.java source.
Nothing is committed to svn there.

Then forrest is called to generate the html/pdf which is then manually
committed to cocoon-site svn.

> You ask how this can be done with the static repositories. I see following 
> alternatives:
> 
> 1) do it similarly as it is done now. Have an Ant target that generates the 
> SCD file and it has to be committed into SVN whenever we think that it has 
> to be updated.
> 
> pro: simple
> con: danger of out-dated docs

Sorry, i don't understand Option 1. What gets committed to SVN?

> 2) automatic process that generates the SCD and commits them into our SVN
> 
> pro: docs are up-to-date
> con: IIUC this isn't allowed because of Apache policies (not automatic 
> commits)

IIUC policies can be changed if all bases are covered.

> 3) tweak Forrest so that it can call Ant targets (checkout sources, 
> generate SCD)
> 
> pro: solution within Forrest
> con: a lot of work, upgrade to the unstable Forrest 0.7

I have actually considered that that is probably the best.
Personally i don't have the wherewithall to do that at the moment.

> 4) build and deploy the SCD without Forrest and put the SCD docs into
> http://cocoon.apache.org/2.2/sitemap-components/ and
> 
> If the docs are build at your local machine this could be achieved by an 
> Ant target that runs forrest, a sitemap-components-generation-target and 
> the javadocs-target.
> 
> pro: to Forrest changes, SCD are up-to-date
> con: The disadvantage of this solution is that those generated docs don't 
> use the general skin and are not within the menu structure. That's no 
> problem for the javadocs but for the sitemap components docs.

That sounds like just as much work as the other solutions

>                                        - o -
> 
> For SCD I propose 1) so that SCD use the style and the navigation and for 
> Javadocs option 4)
> 
> WDY(O)T?

I would like to hear.

--David

Mime
View raw message