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.
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
<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.
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.
> I'm willing to lend a hand to get the docs done,
Which really is apreciated, even if my comments may sound different.
> Also with the amount of recent changes (jeez I was away from work
> for one day and someone edited practically every html source in the
> CVS!!),
Yep, but almost all changes only added a new CSS stylesheet.
Cheers
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
