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
