ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Loughran <ste...@apache.org>
Subject Re: Ant documentation
Date Wed, 09 Mar 2005 09:58:37 GMT
Stefan Bodewig wrote:
> On Wed, 09 Mar 2005, Kev Jackson <kevin.jackson@it.fts-vn.com> 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: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message