Diana Shannon wrote: > Jeff Turner wrote: > >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.
Me too. > >> - 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. We probably need to have a separate discussion on this topic of "separate repository for docs" to solve it once and for all. > > 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). > >> - transition to document v-11 Yes, this is a big stage. > >> - setup docs build capability for user docs and web site We already have this: forrestbot for the website, and a choice of 'forrest' command-line for local docs, or './cocoon servlet' or 'forrest webapp'. Is that your intention too? > >> - 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. But they would not need to build docs. They have a running Cocoon webapp which generates its own docs. So i think that we do not need to checkin the produced docs to cvs nor do we need a separate snapshot of produced docs. And yes, it suddenly occurs to me that the practice *is* old-school! I hope that i am right, because it seems an elegant solution. --David
