Reinhard Poetz wrote:- copy trunk/src/documentation over to trunk/build/templ-docs - create sitemap component docs and put them into trunk/build/templ-docs/src/documentation/content/xdocs/userdocs - create the JAR files document and copy it into the xdocs dir - create the Javadocs and put them in the xdocs dir - use the "exec" task to run forrest on the temporary directory and generate the docs
I think this shouldn't be too difficult. Does this sound reasonable?
That seems to be the same as what was happening already. The "build docs" was copying all of the source xml to build/... then the jars.xml was generated, then the SitemapTask read the *.java and appended info to /userdocs/*.xml So perhaps all that is needed is to fix the pathnames in docs-build.xml and trunk/forrest.properties to reflect the new location of the docs. (Actually i am not sure why that needed to change.)
We separated the 'forrest' command from the Cocoon build, because the Cocoon build system was getting so complex. So the procedure was to do 'build docs' then do 'forrest' at the top-level cocoon/trunk/ If you can get it to happen using the "exec" Ant task, then fine.
ok, will give it a try. My goal is that people can still use "forrest only" to build the docs. If they use the "build docs" command, they get the API docs (see below) in addition. This will also be the target that has to be called by forrestbot.
The generated Javadocs don't need to go into the xdocs source directory. They are a separate thing that get copied manually into the cocoon/site SVN repository. By the way, the 2.1 javadocs on the website are probably way past due for an update.
ok
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/
This would make thinks much easier. WDOT?
The only thing that I have to figure out is how to integrate book.xml into site.xml-driven pages. Does anybody know this or shall I ask on [EMAIL PROTECTED]
Ask at Forrest. Here are some references you have probably already seen: http://forrest.apache.org/faq.html#generating_menus http://forrest.apache.org/docs/linking.html#book-menu-selection
thank you
[*] 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".
--
Reinhard Pötz Independant Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}web(log): http://www.poetz.cc --------------------------------------------------------------------
