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.
Yesterday, Upayavira and I talked about this and we think we found a solution. Currently every document in Forrest consists of
document-name/ ./content_en.xml or ./content_en.html ./meta.xml ./comments_en.xml
Additionally I introduced
./generated-before_en.xml ./generated-after_en.xml
These two documents can contain automatically generated stuff like that comming from the the sitemap task. The aggregation process takes care that the automatically generated docs are added either before or after the actual content (content_en.xml).
Upayavira will adapt the existing task to support the flat document space. So the procedure in the future is, that whenever somebody is changing the Javadocs of a sitemap component, he has to run "build prepare-docs" too and this will update the generated-*.xml documents. He also has to check in these documents.
Those two additional steps shouldn't be too difficult, but they help us to build our docs out of the box using Forrest *without* some "black magic" (--> duplication of xdocs before they can be generated).
Additionally this makes writing an online-editor for the docs much easier as the separation between editable docs and automatically-generated docs is very clear.
A further idea: Forrest-bot could run this "build prepare-docs" target too and ensure this way that it always uses the latest docs.
Upayavira, is this in the sense of what we talked about yesterday? WDOT?
--
Reinhard Pötz Independant Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}web(log): http://www.poetz.cc --------------------------------------------------------------------
