ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bill Burton <>
Subject Re: XDoclet and Ant descriptor generation
Date Mon, 06 Jan 2003 20:03:16 GMT

Good to see some interest in the xdocs project again.

Erik Hatcher wrote:
> Before we proceed with writing the "supplements" - which would just be 
> cut-and-paste (or sed-and-awk :) of the original HTML files, we should 
> get an end-to-end documentation generation process rolling with a few 
> samples, get the process and data formats ironed out, and then run with it.


> But, yes, I'll happily commit such submissions from folks as we get a 
> process going and everyone is happy with the results.
> So, who's volunteering to beef up the DVSL or get it put into some other 
> kind of presentation generation process?

I'll take a look at getting the DVSL stuff working better.  You 
mentioned it was broken?


>     Erik
> On Monday, January 6, 2003, at 11:44  AM, Antoine Levy-Lambert wrote:
>> I have updated my local ant cvs and tried Erik's latest version of
>> proposal/xdocs, and seen how the merge works. It looks good.
>> In my build environment, there are 171 tasks which could be documented (I
>> would guess that there are 20+ other which
>> could not be built on my machine because I do not have the VAJ jars or 
>> the
>> Starteam jars). Erik has written it seems 4 supplements,
>> this means there would be 167+ supplements to prepare, which should 
>> not be a
>> big deal.
>> I am willing to help, if Erik or another committer is then also 
>> willing to
>> commit my work.
>> Yours
>> Antoine
>> ----- Original Message -----
>> From: "Erik Hatcher" <>
>> To: "Ant Developers List" <>
>> Sent: Monday, January 06, 2003 4:20 PM
>> Subject: Re: XDoclet and Ant descriptor generation
>>> On Monday, January 6, 2003, at 04:04  AM, Antoine Levy-Lambert wrote:
>>>> I agree with Christopher Lenz
>>>>>> Specifying links to external examples that get merged in in the
>>>>>> generation process sounds much more reasonable to me.
>>>> I think there could be links with sample "build.xml" files
>>>> illustrating how
>>>> to use a task, or links with gif or jpeg files if something needs to be
>>>> illustrated graphically.
>>>> The question (for Erik) is : what is the correct syntax to specify such
>>>> links in the java source files, so that they get processed properly by
>>>> the
>>>> xdoc build, and the results are seen in the html documentation of the
>>>> task,
>>>> but not in the Javadoc API documentation ?
>>> Actually its the other way around.  We would not specify links in the
>>> Java file if we are going the party-line XDoclet Way(tm).  We would use
>>> merge points.  In fact, there are a few .xml files in the src tree of
>>> proposal/xdocs, and I just added the merge point to the template (in
>>> the apache XDoclet JAR - crack it open to see the template yourself,
>>> task_xml.xdt) and enabled the mergedir.  So, for example, now generate
>>> the XML files again and look at build/gen/java/javac.xml - it now has
>>> merged in the src/org/apache/tools/ant/taskdefs/javac.xml.  The DVSL
>>> generation of HTML files is not currently configured to show those
>>> results, but you should get the idea of how this works.
>>> Whether we want external information to live alongside our .java task
>>> files, or in a separate directory tree is up for debate - I am leaning
>>> towards preferring a separate directory tree mirroring the package
>>> structure of the tasks.
>>> Again, I am _not_ expending any effort on the HTML generation at this
>>> point.  Feel free to jump in and contribute if you have ideas on how
>>> this should be done.  What format the merge files take is another
>>> discussion - I'm of the opinion they should be HTML fragments that are
>>> suitable for putting directly into an XML file as-is - this will us to
>>> craft them with tables, <pre> tags, <em> tags, and bulleted/numbered
>>> lists.
>>> Let me emphasize this point again... what you now see is what you'll
>>> get unless others jump in and contribute :)  I've taken it (almost) as
>>> far as it needs to go and will gladly expend effort on the XDoclet side
>>> of things to facilitate the generation of any type of metadata
>>> descriptors desired from our tasks.  Those with strong interest in how
>>> this gets presented are strongly encouraged to jump in and run with it.
>>>   I feel obligated to give this disclaimer so folks are waiting for me
>>> to bring this all the way around.  The Antlib crew definitely should
>>> look at what is possible here and provide feedback on what they need,
>>> and those interested in seeing Ant's documentation auto-generated
>>> should step up, and also the tool vendors that integrate with Ant out
>>> to have their interest piqued and take a look.  This is where its at,
>>> I'm convinced.  But I cannot do it alone :)
>>> Erik
>>> -- 
>>> To unsubscribe, e-mail:   
>>> <>
>>> For additional commands, e-mail: 
>>> <>

To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message