cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Upayavira ...@upaya.co.uk>
Subject Re: [docs] "docs" Ant target
Date Thu, 10 Mar 2005 10:47:06 GMT
Reinhard Poetz wrote:
> David Crossley wrote:

<snip/>
>> Perhaps we should step back a bit and assess the situation. It seems
>> a cumbersome process to double-handle all of the source docs, just to
>> add some specially-generated docs. Would it help to put these special
>> docs into a completely separate workspace?
> 
> I don't like this duplicaton process either. Well, as far as I 
> understand, the reasons for this is that we want to style the docs using 
> the common skin and not something different. The question is, do we 
> really need the sitemap-component docs (some kind of API documentation) 
> in this common style? I'd say no. They are similar to javadocs and 
> nobody has ever complained about not having the tightly integrated in 
> our website. (I don't want to say that I wouldn't like seeing all docs 
> in the common style but it's not worth doing the huge amount of work to 
> get it done.)
> 
> Maybe  we can agree on this: Generated documentation is linked from our 
> documenation but is not integrated in our common style:
> 
> http://cocoon.apache.org/2.2/apidocs/
> http://cocoon.apache.org/2.2/sitemap-components/
> http://cocoon.apache.org/2.2/jars/

If we are to do this, then we've at least to be consistent in linking to 
the generated docs from the other documentation. i.e. the 
SearchGenerator needs to have a prominent link directly to the section 
describing the SearchGenerator.

> This would make thinks much easier. WDOT?

It would, but could easily relegate the generated docs into a place 
never visited if we're not careful.

<snip/>

>> [*]
>> The other thing to bear in mind, and this was one of the big hold-ups
>> in the past with improving the docs, is that all of the docs are also
>> generated via the Cocoon webapp ... 'cocoon.sh servlet'. They use old
>> stylesheets that are probably dependent on an old version of xdocs DTD.
>> I don't have any answer to that.
> 
> 
> I don't think we need this anymore. "forrest webapp" is more than a 
> replacement for people who want to see the docs "live".

Well, I really _don't_ like the idea of not shipping HTML docs with a 
distribution, whether that is shipping ready made HTML, or as viewable 
via Cocoon. Telling a beginner who wants to read the docs offline that 
he has to go and download Forrest to find out how Cocoon works is just 
not acceptable.

Regards, Upayavira



Mime
View raw message