cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: Stages of Forrest Transition
Date Mon, 24 Mar 2003 02:44:38 GMT
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




Mime
View raw message