On Wed, 09 Mar 2005, Kev Jackson <[EMAIL PROTECTED]> wrote:
I've read this thread with interest (as you tend to do when your work is 'critiqued' :) ), but I'm still not sure what anyone actually wants, apart from some kind of generated docs that produce nice HTML output, and as an added bonus can be transformed by Fop into a PDF.
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.
(2) throw in additional information in an easy to edit format.
(3) create HTML and PDF versions of the docs from a single source.
An effort to do (1) has been started in the proposals directory (xdocs). This one uses XDoclet and I have no idea about its state.
Erik wrote it for the reference for our book; it hasnt been touched much since. We also had to go through all the source and add the code snippets. That took a weekend or so. I've used it to generate some ant docs, plus also in Axis and smartfrog...the sole changes to the build file was to make third party use easier.
Its brittle, needs -Xmx1024M to work, etc, etc. But it does generate HTML. Not good HTML, and it loses <pre> formatting in javadoc sections.
Needs
-nested element support -types, conditions, filters, etc as well as just tasks -cross referencing -moving to Ant1.2
Basically since I never looked at it - I find other things that I prefer to work on all the time 8-)
For (2), as much as I'm comfortable with LaTeX, I wouldn't consider it easy to edit for a newbie, either. The main things we need as additional informations are the examples AFAIK - and in that case a custom simplistic XML format may be the best option, something like
IMO, LaTeX is a downstream format :) It's good for doc authoring, but the output is then mostly .DVI and .PDF: printables.
<example> <description>The following fuzzes the foo into a bar</description> <code><[CDATA[ <fuzz from="foo" to="bar"/> ]]> </code> </example>
The less powerful that DTD the better since it would force us to move the important pieces of documentation to the code.
A bit like 'pragmatic xml' the pragmatic programmers use, perhaps.
If the result of (1) and (2) is XML, then it would be a matter of stylesheets (be they XSLT or Velocity stylesheets or anything else) to go from there to XHTML or PDF. Again, something I personally don't enjoy too much, so I walk away and work on something else.
There are tools we can use there. I hear that going via TeX gives you the best typesetting.
-steve
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
