ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Erik Hatcher <jakarta-...@ehatchersolutions.com>
Subject Re: XDoclet and Ant descriptor generation
Date Mon, 06 Jan 2003 18:37:02 GMT
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?

	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" <jakarta-ant@ehatchersolutions.com>
> To: "Ant Developers List" <ant-dev@jakarta.apache.org>
> 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:   
>> <mailto:ant-dev-unsubscribe@jakarta.apache.org>
>> For additional commands, e-mail: 
>> <mailto:ant-dev-help@jakarta.apache.org>
>>
>
>
> --
> To unsubscribe, e-mail:   
> <mailto:ant-dev-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail: 
> <mailto:ant-dev-help@jakarta.apache.org>
>
>


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


Mime
View raw message