Return-Path: Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm Delivered-To: mailing list ant-dev@jakarta.apache.org Received: (qmail 98813 invoked from network); 19 Oct 2000 14:30:28 -0000 Received: from brick.eb.com (HELO CHIEC01.eb.com) (208.154.71.2) by locus.apache.org with SMTP; 19 Oct 2000 14:30:28 -0000 Received: by chiec01.eb.com with Internet Mail Service (5.5.2650.21) id ; Thu, 19 Oct 2000 09:29:54 -0500 Message-ID: <4538F96A1478D211BEC40008C7A4CD9D059CF8BF@chiec01.eb.com> From: rwaldhof@us.britannica.com To: ant-dev@jakarta.apache.org Subject: RE: documenting your build file Date: Thu, 19 Oct 2000 09:29:51 -0500 MIME-Version: 1.0 X-Mailer: Internet Mail Service (5.5.2650.21) Content-Type: multipart/alternative; boundary="----_=_NextPart_001_01C039D9.0AC39450" X-Spam-Rating: locus.apache.org 1.6.2 0/1000/N This message is in MIME format. Since your mail reader does not understand this format, some or all of this message may not be legible. ------_=_NextPart_001_01C039D9.0AC39450 Content-Type: text/plain; charset="iso-8859-1" An XML parser is not required to transmit XML comments to the document/content handler (SAX) or place it into the document tree (DOM), so this wouldn't be truly reliable, but XSLT does let you match on comments: ... Perhaps a would be better suited? (Assuming Ant ignores them right now.) You can match on those in XSLT as well, and the XML parser must transmit them upstream: ... Adding a tag that is simply ignored by Ant might be more convenient. The description attribute is useful, especially in light of -projecthelp, but allowing html/xml markup ala JavaDoc comments would be convenient. - Rod Waldhoff Britannica.com PS: I really like the idea of using XSLT to generate this documentation, since it would give the documentation-generating-engine access to the actual build.xml source. -----Original Message----- From: Chris Todd [mailto:chris@christophertodd.com] Sent: Thursday, October 19, 2000 3:48 AM To: ant-dev@jakarta.apache.org Subject: RE: documenting your build file Hmmm, this is an interesting idea. I suppose the easiest way to do this would be to create a new Ant Task that interprets a tag like or and have the contents of that tag formatted into HTML or whatever format you want. Alternatively, if Ant will tolerate having tags in build.xml that it doesn't know about (my guess is it would not - is that correct?), then you could include tags in your build.xml, then simply transform build.xml into HTML (or whatever) using an XSL stylesheet. Actually, can an XSL stylesheet recognize XML comments and transform them (sorry, I left my XML/XSL book at work)? If so, then you could just comment your build.xml normally and transform it with such a stylesheet. Sincerest regards, Chris Todd Software Engineer Alabanza Corporation ctodd@alabanza.com -----Original Message----- From: Julian M. Savage [mailto:jsavage@fisci.com] Sent: Thursday, October 19, 2000 4:16 AM To: ant-dev@jakarta.apache.org Subject: documenting your build file Is there a way that I can easily generate documentation from my build file for developers who use it? Basically what I want is javadoc like functionality of some sort. Is there an easy way to do this somehow? Thanks, Julian. ------_=_NextPart_001_01C039D9.0AC39450 Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable RE: documenting your build file

An XML parser is not required to transmit XML = comments to the document/content handler (SAX) or place it into the = document tree (DOM), so this wouldn't be truly reliable, but XSLT does = let you match on comments:

<xsl:template = match=3D"comment()">...</xsl:template>

Perhaps a <? processing instruction ?> would be = better suited?  (Assuming Ant ignores them right now.) You can = match on those in XSLT as well, and the XML parser must transmit them = upstream:

<xsl:template = match=3D"processing-instruction()">...</xsl:template>=

Adding a <doc> tag that is simply ignored by = Ant might be more convenient.  The description attribute is = useful, especially in light of -projecthelp, but allowing html/xml = markup ala JavaDoc comments would be convenient.

 - Rod Waldhoff <mailto:rwaldhof@us.britannica= .com>
   Britannica.com <http://britannica.com/>


PS: I really like the idea of using XSLT to generate = this documentation, since it would give the = documentation-generating-engine access to the actual build.xml = source.

-----Original Message-----
From: Chris Todd [mailto:chris@christophertodd.c= om]
Sent: Thursday, October 19, 2000 3:48 AM
To: ant-dev@jakarta.apache.org
Subject: RE: documenting your build file


Hmmm, this is an interesting idea.  I suppose = the easiest way to do this
would be to create a new Ant Task that interprets a = tag like <doc> or
<builddoc> and have the contents of that tag = formatted into HTML or whatever
format you want.

Alternatively, if Ant will tolerate having tags in = build.xml that it doesn't
know about (my guess is it would not - is that = correct?), then you could
include <doc> tags in your build.xml, then = simply transform build.xml into
HTML (or whatever) using an XSL stylesheet.  = Actually, can an XSL stylesheet
recognize XML comments <!-- --> and transform = them (sorry, I left my XML/XSL
book at work)?  If so, then you could just = comment your build.xml normally
and transform it with such a stylesheet.

Sincerest regards,
Chris Todd
Software Engineer
Alabanza Corporation
ctodd@alabanza.com

-----Original Message-----
From: Julian M. Savage [mailto:jsavage@fisci.com]
Sent: Thursday, October 19, 2000 4:16 AM
To: ant-dev@jakarta.apache.org
Subject: documenting your build file


Is there a way that I can easily generate = documentation from my build file
for developers who use it? Basically what I want is = javadoc like
functionality of some sort. Is there an easy way to = do this somehow?

Thanks,

Julian.

------_=_NextPart_001_01C039D9.0AC39450--