ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Reilly <peterrei...@apache.org>
Subject Re: Ant documentation
Date Wed, 09 Mar 2005 15:23:58 GMT
This looks like a really cool method.

Dominique Devienne wrote:

>>From: Stefan Bodewig [mailto:bodewig@apache.org]
>>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: dev-unsubscribe@ant.apache.org
>For additional commands, e-mail: dev-help@ant.apache.org
>
>
>
>  
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message