You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Diana Shannon <sh...@apache.org> on 2003/03/23 15:48:47 UTC
Stages of Forrest Transition
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)
- 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.
- 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
- setup mechanism to update (via automated cvs update?) static docs
in 2.0 and 2.1 repos. This removes the "burden" of doc-building from
code repos. Webapp samples can simply link to static doc files (copied
over during webapp build).
3. Remove xdoc, stylesheets, and dtds related to core documentation from
2.0 and 2.1 repos.
4. Consider merging 2.0 and 2.1 into a single trunk (based on Andrew's
findings/protype)
Thoughts?
Diana
Re: Stages of Forrest Transition
Posted by Stephan Michels <st...@apache.org>.
On 26 Mar 2003, David Crossley wrote:
> Diana Shannon wrote:
> > Stephan Michels wrote:
> > > David Crossley wrote:
> > >>>>> - transition to document v-11
> > >>
> > >> Yes, this is a big stage.
> > >
> > > It shouldn't, because there is already a stylesheet for doing this:
> > > xml-forrest/src/resources/stylesheets/docv10todocv11.xsl
> >
> > You're right, this part is trivial (having worked hard over the past
> > year bring docv10 docs up to a state where they can be transformed so
> > easily...)
> >
> > > It shouldn't be great thing to write a little ant script.
> >
> > Yes, I did this myself ages ago. We had to do this for pre 0.5 versions
> > of Forrest. What David means by a "big stage" is the ramification of
> > changing all dtds. This means, for example, that the existing webapp
> > build (which links to docs created by a non-Forrest mechanism), has to
> > be updated. This means either fixing the old sitemap/stylesheets/etc. or
> > pulling in bits and pieces from Forrest distro.
>
> That is right ... Diana sees the importance.
> I think that a lot of people have been not quite
> understanding this.
Yes, I'm understanding, but it is really necessary that cocoon serves his
own documents by the webapp? Are the samples not enough to should the
possibilities of Cocoon? If somebody ask for documentation system, we can
point to Forrest.
So I'm +1 for cancel the docs target, remove all stylesheets and dtds etc.
for the docs, and then the transition is done. It's a bit too easy, I
guess, but I think thats the best way.
Stephan.
Re: Stages of Forrest Transition
Posted by David Crossley <cr...@indexgeo.com.au>.
Diana Shannon wrote:
> Stephan Michels wrote:
> > David Crossley wrote:
> >>>>> - transition to document v-11
> >>
> >> Yes, this is a big stage.
> >
> > It shouldn't, because there is already a stylesheet for doing this:
> > xml-forrest/src/resources/stylesheets/docv10todocv11.xsl
>
> You're right, this part is trivial (having worked hard over the past
> year bring docv10 docs up to a state where they can be transformed so
> easily...)
>
> > It shouldn't be great thing to write a little ant script.
>
> Yes, I did this myself ages ago. We had to do this for pre 0.5 versions
> of Forrest. What David means by a "big stage" is the ramification of
> changing all dtds. This means, for example, that the existing webapp
> build (which links to docs created by a non-Forrest mechanism), has to
> be updated. This means either fixing the old sitemap/stylesheets/etc. or
> pulling in bits and pieces from Forrest distro.
That is right ... Diana sees the importance.
I think that a lot of people have been not quite
understanding this.
--David
Re: Stages of Forrest Transition
Posted by Diana Shannon <sh...@apache.org>.
On Monday, March 24, 2003, at 07:10 AM, Stephan Michels wrote:
>>>>> - transition to document v-11
>>
>> Yes, this is a big stage.
>
> It shouldn't, because there is already a stylesheet for doing this:
> xml-forrest/src/resources/stylesheets/docv10todocv11.xsl
You're right, this part is trivial (having worked hard over the past
year bring docv10 docs up to a state where they can be transformed so
easily...)
> It shouldn't be great thing to write a little ant script.
Yes, I did this myself ages ago. We had to do this for pre 0.5 versions
of Forrest. What David means by a "big stage" is the ramification of
changing all dtds. This means, for example, that the existing webapp
build (which links to docs created by a non-Forrest mechanism), has to
be updated. This means either fixing the old sitemap/stylesheets/etc. or
pulling in bits and pieces from Forrest distro.
>
>>>>> - 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.
>
> I have also objections, to add static generated docs into the CVS.
> My proposal is that the bin-dist includes all static generated docs, and
> the war file, the source-dist, need a installation of Forrest to
> generate
> the docs. And a 'ant war' generate only a samples webapp.
As a user, I don't have a problem with this. However, I believe many
users may resent the extra step required to get docs.
Diana
Re: Stages of Forrest Transition
Posted by Stephan Michels <st...@apache.org>.
On 24 Mar 2003, David Crossley wrote:
> Diana Shannon wrote:
> > > 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.
It shouldn't, because there is already a stylesheet for doing this:
xml-forrest/src/resources/stylesheets/docv10todocv11.xsl
It shouldn't be great thing to write a little ant script.
> > >> - 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.
I have also objections, to add static generated docs into the CVS.
My proposal is that the bin-dist includes all static generated docs, and
the war file, the source-dist, need a installation of Forrest to generate
the docs. And a 'ant war' generate only a samples webapp.
Thoughts?
Stephan.
Re: Stages of Forrest Transition
Posted by David Crossley <cr...@indexgeo.com.au>.
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
Re: Stages of Forrest Transition
Posted by Diana Shannon <sh...@apache.org>.
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
Re: Stages of Forrest Transition
Posted by Jeff Turner <je...@apache.org>.
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? 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?
> - 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?
Also, having XML in a separate cocoon-docs module is likely to trigger
the "out of sight, out of mind" syndrome. 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.
> - 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 :)
--Jeff
(in wet blanket mode, and not seeing the forest for the trees:)
> - setup mechanism to update (via automated cvs update?) static docs
> in 2.0 and 2.1 repos. This removes the "burden" of doc-building from
> code repos. Webapp samples can simply link to static doc files (copied
> over during webapp build).
>
> 3. Remove xdoc, stylesheets, and dtds related to core documentation from
> 2.0 and 2.1 repos.
>
> 4. Consider merging 2.0 and 2.1 into a single trunk (based on Andrew's
> findings/protype)
>
> Thoughts?
>
> Diana
>
Re: Stages of Forrest Transition
Posted by Diana Shannon <sh...@apache.org>.
On Sunday, March 23, 2003, at 09:48 AM, Diana Shannon wrote:
> 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)
> - 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.
Forgot to add:
- transition to document v-11.
> - 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
> - setup mechanism to update (via automated cvs update?) static docs
> in 2.0 and 2.1 repos. This removes the "burden" of doc-building from
> code repos. Webapp samples can simply link to static doc files (copied
> over during webapp build).
>
> 3. Remove xdoc, stylesheets, and dtds related to core documentation
> from 2.0 and 2.1 repos.
>
> 4. Consider merging 2.0 and 2.1 into a single trunk (based on Andrew's
> findings/protype)