Hello,
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.
Yes.
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?
-Bill
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" <[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]>
