> 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. 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. 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 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! > 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. > > 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]
