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 15:20:03 GMT
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>


Mime
View raw message