Re: [VOTE] Use Forrest to build Cocoon docs

[Diana Shannon]

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?

Diana


---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]