This looks like a really cool method.
Dominique Devienne wrote:
From: Stefan Bodewig [mailto:[EMAIL PROTECTED]
The main problem here is that there is no unique answer 8-)
Right. I'm partial to XML + XSL myself for example. I like
authoring the XML and just have to hit reload to see the HTML.
Nice.
I looked at docbook briefly, and found it verbose and unwieldy,
but I didn't dig that much.
I like Tex/LaTex printed output a lot, and the markup seems clean
enough, but all these macros and modules and stuff look very
intimidating. You need an existing doc to piggy back on, and a
mentor to use latex is seemed to me.
My guess is the following is more or less true:
(1) autogenerate as much of the docs as possible from the Java
sources.
What I currently have (coded in a weekend, and not touched since...)
is basically a task that takes as argument an antlib uri, introspects
all the tasks/types declared, thru the new IH assessors I added and
were committed by Peter.
It at least gets us to the point we can have a dynamic list of all
attributes and nested elements, not forgetting to document some in
the manual.
What I didn't finish is the custom doclet (just a regular DocLet)
that given this list grabs just the javadoc elements for the valid
attributes / elements.
Would this be difficult?
And what don't even have a good handle on yet is how to merge the
auto-extracted type-related javadoc info with hand written doc.
(2) throw in additional information in an easy to edit format.
Every time I read the HTML source code for the manual, I cringe
at all the tables and examples...
What I would prefer is an Ant-specific XML dialect for the manual.
I think that this is the way to go.
xml + xsl --> html -- css --> viewer
We should be able to scrape the current ant manual into the
ant task/types xml format.
I have good experience with converting XML sources into nice
syntax highlighted HTML (I prototyped it for Ant builds, it's
just a single .xsl file + a .css for the syntax highlighting,
a la VIM right now).
I also created an little very simple XML dialect for release
notes. This is also done, and I can share a source document,
and the style sheets. It's not very fancy, but it works.
(3) create HTML and PDF versions of the docs from a single source.
I can help with the conversion to HTML, if we go XML + XSL.
I don't care much for PDF, but once we have some XML docs,
it's just matter of time for a direct bridge to FOP, or a
bridge to docbook for example, and then to FOP.
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>
In what I have in mind, examples are not text (or CDATA sections),
but actual XML, in order to keep the XML infoset, which is used to
do the syntax highlighting. And along with syntax highlighting, you
can add links to actual doc for all the attributes/elements used
in the examples!
Awsome!,
Would XML name-space examples cause problems?
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.
Believe it or not, I actually enjoy working with XSL ;-)
It's often frustrating, like IE eating up the space text nodes,
so the XML syntax highlighting I describe above doesn't work with
IE, and needs to be done with a proper (standard compliant) XSL
engine (Xalan, Saxon, FireFox's XSL engine, etc...), but it's
rewarding work ;-) I like it's functional model.
XSL 2.0 looks very promising has an improvement over 1.0,
being even more functional, and having regexp and sequences,
but that requires Saxon. I don't know how people feel about
a Saxon 8.x dependency.
This should not be too much of a problem. It will be used
during the build phase (in the same way that junit is used),
and maybe using <libraries>, however it would be nicer
just to use xalan.
I'm willing to lend a hand to get the docs done,
Which really is apreciated, even if my comments may sound different.
And there the rub lies... I wish I could do more in Ant that I
actually do, but right now it ain't possible. Two of my coworkers
quit early this year, and they have yet to be replaced, so I'm
swamped with much more than before.
I can share the little I have, and talk things out on the list,
but the time to develop non-trivial XSLs, well it's more difficult
to find... Sorry about that. --DD
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
