Reinhard Poetz wrote:
> David Crossley wrote:
>> 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.
>> [*]
>> 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