On Sunday, March 23, 2003, at 10:39 AM, Jeff Turner wrote:
On Sun, Mar 23, 2003 at 09:48:47AM -0500, Diana Shannon wrote:How should we transition? How about:
1. Set up live protoype Forrest environment (now happening) - work out remaining configuration issues
2. Set up separate Cocoon docs repo(s) - decide what the repo will include (simply docs and/or tools)
Do you mean, commit a Forrest binary into cocoon-docs CVS?
Not what **I** want, just what some were suggesting earlier. Also, doc tools can include tools that aren't necessarily Forrest.
Why not just make a snaphot available for download, or let people run 'cvs update -r stable' on Forrest to get a known-working version?
I'd vote for this myself.
- copy both 2.1 and 2.0 docs and associated files into separate modules/branches/repos. Maintain "old" doc build capability, as currently functioning, in 2.1 and 2.0.
Sounds like a lot of work.. why go to all that effort to keep the old system alive, if the Forrest system is 95% working?
Just during a transition. To keep doc builds functioning for users. To avoid down time during v11 transition.
Also, having XML in a separate cocoon-docs module is likely to trigger the "out of sight, out of mind" syndrome.
I hope this isn't true. I also believe it's an overgeneralization. We've had this debate a lot. I had the impression that consensus is moving toward supporting a single docs cvs.
Right now, when I change some code (say, rename DefaultsMetaModule to DefaultsModule), I can simply grep cocoon-2.1 and find all references to the old class in code *and* docs, and update them. With a separate module I'd probably forget, or forget to 'cvs up' it.
Well, some of us believe a single docs cvs, which can produce 2.0 or 2.1 docs will be even better. In your above-described scenario, you'd also "forget" to update cocoon-2.0 (if necessary) since it's now in a separate repo. That "forgetfulness" issue didn't prevent the repo separation of code.
Think about a wiki/html editing system which writes to cvs. Wouldn't you want a separate docs cvs for that? As far as docs which depend on specific files in a code cvs (e.g. jars.xml), Forrest simply needs to know where such cvs repos live (locally or via view-cvs or similar).
- setup docs build capability for user docs and web site - add static documentation (built by cocoon-docs repo with Forrest) to both 2.0 and 2.1 repos
?! Do you mean, commit 10mb of generated HTML/PDF to cocoon-2.1? I hope not :)
As a matter of fact, yes, with or without pdf. Most of the cvs-based projects I download have static doc files in their cvs, not dynamic doc-generating capability with doc source files. Are you saying this practice is "old school"? I personally **really** like to simply double click a doc file to get started instead of figure out how to build the docs first.
And/or, we could make doc set snapshots available, as we do now for code.
Diana
