> > The main problem here is that there is no unique answer 8-) > > > > My guess is the following is more or less true: > > > > (1) autogenerate as much of the docs as possible from the Java sources.
yes within reason > > (2) throw in additional information in an easy to edit format. I would further seperate this; I have proposed for tasks a task xml markup, will be posting my results soon on this. perhaps with libraries, there is a need for a minimal libary ,metadata as well. Note, after all this discussion, I am going to opt for a minimal subset of docbook to mark these up. IMHO its very easy to start marking up with limited docbook set of elements...also I would contend that there are much more people using docbook then xdocs on the planet...though we would have to ask NWALSH this question. > > (3) create HTML and PDF versions of the docs from a single source. I would suggest to achieve maximum flexibility e.g. ability to work in both docbook and xdocs whilst being able to generate PDF to follow Forrests recc. on this. A) there is a docbook -> xdocs transform for those who want to work in a limited subset of docbook. or B) you could configure forrest to work with native docbook. I would scale the effort and initially go for option A) which means that some of the docs can be in limited docbook format and some in native xdoc. Perhaps the natural breakdown is that xdoc deals with core Ant, with limited docbook with tasks, library metadata....going to pdf could be end result of xdoc processing by Forrest. -- Jim Fuller -------------------------------------------------------------------------------- FYI: from Forrest site FAQ http://forrest.apache.org/faq.html#docbook Forrest can transform the DocBook format into the Forrest "xdocs" format on-the-fly and then render that as normal Forrest documents. Be aware that the stylesheet that does this transformation is deliberately very limited and does not attempt to deal with all DocBook elements. The other way is to use the full DocBook stylesheets directly. The DocBook DTDs are shipped with Forrest and automatically handled. However, you will need to have the DocBook stylesheets on your system (they are too massive to ship with Forrest) and configure Forrest accordingly. You will need to create a project sitemap as explained in Using Forrest and add matches to handle your DocBook documents. Here is an example. Note that you need to change it to suit your situation. The match must be very specific so that only the DocBook documents are matched. The rest of the documents will be handled by Forrest core. Powerful regex capabilities are available. <?xml version="1.0"?> <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0";> <map:pipelines> <map:pipeline> <map:match pattern="resolver-*.html"> <map:generate src="{project:content.xdocs}resolver-{1}.xml"/> <map:transform src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/> <map:serialize type="xhtml"/> </map:match> </map:pipeline> </map:pipelines> </map:sitemap> You can also use a mixture of the two methods, some handled automatically by Forrest and some directly using DocBook stylesheets. You can also have a mixture of source files as "document-v*" DTD and DocBook. Ensure that the document type declaration in your xml instance is well specified. Use a public identifier. The DTD will then be properly resolved by Forrest. If you need to use different DTDs, then see Using Forrest for configuration guidance.
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
