I agree with Christopher LenzI think there could be links with sample "build.xml" files illustrating howSpecifying links to external examples that get merged in in the generation process sounds much more reasonable to me.
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:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
