cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: [VOTE] Use Forrest to build Cocoon docs
Date Mon, 28 Oct 2002 13:24:32 GMT
I'm generally in agreement with Ken (in fact I proposed a separate CVS 
module for docs, powered by a Forrest webapp back in July on 
forrest-dev), but I agree with David that we need to clarify a number of 
key issues to make such a transition successful and efficient.

While I haven't posted much recently on forrest-dev, I do keep up with 
the list. I'm also scrutinizing the latest cvs version and will have 
more comments soon. Here's a few issues that I have at this moment.

1. Is Forrest Ready?
After all, it's still considered alpha, isn't it? I agree that docs need 
a stable framework for reliable generation, but at this point in time, 
I'd argue that the release branch of Cocoon is more stable than the 
current Forrest distro. Still, all of us are Cocoon-proficient and could 
most likely fix bugs caused by the use of the current alpha Forrest 
distro. Nevertheless, I would argue that such a transition **may** be a 
bit premature, unless we decide some kind of reliable update cycle for a 
distro that's still alpha (and that lacks any known release schedule).

2. What kind of docs and doc building facilities should we provide users?
I agree with Ken that we it would be nice to move docs generation 
facilities and doc source files out of the code-oriented cvs branches. I 
think we should move them to a separate cvs module/branch that users can 
also download if they want to build docs locally. However, if users just 
want (prebuilt) docs, they should be able to download html files as they 
do nightly snapshots -- or something similar. Moving the docs out of the 
code branches does raise a few other issues. For example, we'd need to 
distinguish in docs builds between a web site build and a local docs 
build. Local docs can link to webapp samples (generated by the code cvs 
branches build), while a live site build cannot.

3. What is Forrest?
Because Forrest is a Cocoon webapp, it's a bit unclear what 
"distribution updates" mean. It's not a simple issue like a few updated 
jars as is the case with most inter-project dependencies. The Forrest 
distro contains so many other files! For example, in the early days of 
Forrest, it wasn't clear if users were "allowed" to have their own 
sitemaps and sub-sitemaps. I don't think that's the case anymore, but I 
would like to get a better understanding of this. Still, even a few 
months ago, you guys were discussing the prospect of abandoning 
document-v11.dtd. How backwards-compatible can Forrest be at this early 
alpha state, and how easy would it be to "fork" Forrest unintentionally, 
like making some "inappropriate" edits to one of the distro files that 
later gets overwritten by a distro/cvs update?


View raw message