Re: [PROPOSAL] Use Forrest to build Cocoon docs

[David Crossley <cr...@indexgeo.com.au>]

Moved from the cocoon-dev thread to cocoon-docs. Was:
 Re: closing cocoon-docs? (was: Cocoon Project Report)
 http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=104557472909525

Diana Shannon wrote:
> Steven Noels wrote:
> > David Crossley wrote:
> >>
> >> I thought that "square one" was working out the proposal
> >> to use Forrest to process the Cocoon docs. That conversion
> >> from docv10->docv11 is a part of the process.
> >> http://wiki.cocoondev.org/Wiki.jsp?page=ForrestProposal
>
> > Sure, David - fully aware of that. My 'big hidden agenda' (duh)
> > was to add a first step to the main cocoon build, so that
> > others could jump in and expand.

Yikes, please no hidden agenda. Our plan with that proposal
was to initiate a co-ordinated effort.

> > That doc makes reference to a trail-run-F target
> > which was buried somewhere in Forrest and since it is only
> > of limited concern to Forrest, I wonder why it should be there.
>
> This was based on very helpful advice Nicola Ken provided me
> off-list as I was working on the transition. Because the Forrest
> transition work was a WIP, it seemed inappropriate to place them
> in Cocoon's CVS. Given the fact that Forrest's ability to mount
> "external" xdocs is fundamental, it seemed appropriate to place
> the transition files there.
> 
> > Also, I figured a mass-convert to the new format would make it
> > easier to start the clean-up work.
> 
> I guess I don't understand what you mean by a mass-convert. We've 
> already done that, haven't we?

We have only done an experiment based on Diana's Wiki doc
HowToForrestTransition. The conversion of xdocs from v10 to v11
format is a once-off task, but there are many ramifications.
Hence the Wiki doc ForrestProposal to attempt some co-ordinated
plan for doing the whole job.

> All that remains are tweaking a few configuration files.
> Have you tried using the existing files David and I developed?

I think much more is involved. For example, how does the
Cocoon webapp continue to work with the new documentation
v11 format. I expect that all the documentation stylesheets
and documentation/sitemap.xmap need to change too.

                       ---O---

Let us not dampen anyone's enthusiasm on this. The last
time we started raising the associated issues, everyone
went quiet for many months.

At some stage we need to just do the once-off conversion,
and then pick up the pieces. This would be better done
before Cocoon-2.1 is released.

--David

Re: [PROPOSAL] Use Forrest to build Cocoon docs

[Bertrand Delacretaz <bd...@codeconsult.ch>]

Le Mercredi, 19 fév 2003, à 05:11 Europe/Zurich, David Crossley a écrit 
:

> ...For example, how does the
> Cocoon webapp continue to work with the new documentation
> v11 format. I expect that all the documentation stylesheets
> and documentation/sitemap.xmap need to change too.

IMHO maintaining both sets of documentation (Forrest and non-Forrest 
versions) would be confusing for users and a waste of energy for 
contributors.

As we're going to use Forrest, I'd generate all docs with Forrest and 
remove the existing standalone stuff.

Technically I think this requires having a binary version of Forrest in 
our CVS, used as a blackbox tool to generate the docs. It won't help 
make our CVS codebase smaller, but is there another way? This is really 
what we want to do conceptually, use Forrest as a stable tool for our 
docs.

> ...The last
> time we started raising the associated issues, everyone
> went quiet for many months.

On my part it is mainly due to events unrelated to Cocoon, but I must 
admit some uncertainty about exactly what is required to move our docs 
to Forrest, which made me even quieter than I should have been. I'm 
probably not alone in this case.

> ...At some stage we need to just do the once-off conversion,
> and then pick up the pieces.

Yes. Going concrete would certainly help, so how about:

-adding a binary version of Forrest (including Cocoon, weird but 
required IMHO) to the CVS, in /tools
-using a separate build.xml (called from the main one) to build the 
docs using Forrest
-doing this on a CVS branch until the Forrestized docs are usable

Whaddyathink?

-Bertrand