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" <[EMAIL PROTECTED]> To: "Ant Developers List" <[EMAIL PROTECTED]> 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:[EMAIL PROTECTED]> > For additional commands, e-mail: <mailto:[EMAIL PROTECTED]> > -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
