cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <>
Subject Re: [VOTE] Use Forrest to build Cocoon docs
Date Mon, 28 Oct 2002 10:21:41 GMT

David Crossley wrote:
> STOP !!
> This is not ready for a "vote" we need to discuss the
> "proposal" first.


> There are many issues. Some we have discussed on Forrest
> and we even have scratchpad builds to help transform the
> Cocoon xdocs. However, it needs careful consideration.
> (Work with Forrest in general has progressed since then and
> the demo transformation now needs to catch up.)
> Also, why is this being copied to cocoon-dev. We agreed
> that documentation stuff would get discussed only on
> cocoon-docs working under the assumption that all Cocoon
> developers are subscribed there.

This is a VOTE for a structural decision in the Cocoon distribution, so 
it should always happen in the cocoon-dev list IMHO.

Also, lately there have been some crosspost by other developers here to 

I'll stick to discussing here then, but I still think that the VOTE 
needs to go to both lists.

> More below ...
> Nicola Ken Barozzi wrote:
>>It's time we move the Cocoon docs to Forrest.
>>There is still a problem to solve though.
>>How are we going to generate the documentation?
>>Currently Cocoon uses itself to generate the documentation, but now we 
>>want to use Forrest, which has an indipendent distribution.
>>I would propose that we remove the current "docs" target from Cocoon 
>>altogether, and use the Forrest distro for it.
> No, not remove docs target. Forrest can remotely build
> it as well as Cocoon being able to build its own docs
> in place.
> As a user, when i download Cocoon via my dial-up 56k modem
> (yes i am lucky, lots of Australia has 28.8k and twitchy)
> i expect to be able to build the core docs locally via
> Cocoon. I expect to just do "build docs" then start
> at index.html and become enlightened.

I disagree with this.

If an apache-incubator developer uses Forrest to build docs, it has to 
download Forrest, no?
The same for any project that uses Forrest.

Cocoon just happens to be the project we use to make Forrest work, but 
it always has a newer version of the core, different libraries, and I 
honestly don't want to rely on the CVS Cocoon to be able to build the docs.

If the Cocoon in CVS is in alpha state, or simply slightly incompatible 
with the Forrest one, why can't I be able to build the project docs?

IMNSHO the docs should compile at all times, or else the doc committers 
will be at the mercy of the core committers.

If we use a separate installation we have stability of the docs build, 
and overmore it's ready to help the write to use Forrest also for other 

Anyway, the built docs *will* be included in distributions, so users 
won't need Forrest at all.

>>This way we move the concern of the docs system to Forrest and don't 
>>have to cut-n-paste and keep in synch the Forrest build system with the 
>>Cocoon one.
> I do not know what you mean by "cut-n-paste" - we do
> not do that for the Cocoon-docs experiment in Forrest.

There have been changes IIUC, and now I have embedded Jetty working on 
my version... I'm also working on in-place editing and stuff, and it 
could become more complicated on the lib dependencies as time goes by.

We will maybe need libre libs too, and copy Forrest stuff to Cocoon that 
will have to be maintained also in Cocoon.
I don't think it's a good idea.

>>The "docs" target in Cocoon will thus become just a call to the Forrest 
>>build process, and the docs will be included in the distributions 
>>generated statically.
>>I think this will make things simpler to manage and update.
>>What do you think?
> Discuss a proposal first.

The proposal is to use Forrest for Cocoon docs.
Not use a Forrest-based docs build system with the Cocoon distro, but to 
use Forrest as any other projec tdoes..

There is not much to discuss about or propose /if/ we use Forrest, since 
the shbat distro works well, and the project-howto is clear enough.

Of course, this is my view, I'd be happy to hear other opinions too.

Nicola Ken Barozzi         
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)

View raw message