cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: Stages of Forrest Transition
Date Mon, 24 Mar 2003 12:59:08 GMT

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


Mime
View raw message