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.
It would be interesting if one could choose from one or more existing DTDs for the content of the <doc> tag. For instance, we use DocBook for documentation. Allowing DocBook tags (e.g., <para>, <itemizedlist>, <programlisting>) within doc would allow us to create a simple XSLT stylesheet that extracts the doc tags into a DocBook document. Others may prefer HTML, in which case it would be easier for them to use HTML tags (e.g., <p>, <ol>, <pre>) inside <doc>. Still others may prefer stylebook, or something else...
This poses problems if you want the build.xml file to conform to a DTD, since it makes it difficult to define the content model of the <doc> element.
One possible solution is to define build.xml in terms of an XML Schema rather than a DTD, and have the allowed content model vary based on an attribute of the <doc> element, such as <doc format="docbook" version="4.1.2"> or <doc format="html" version="4.0">. But XML Schema is not finalized, and not as widely supported as DTDs are.
Another solution that is DTD-compatible is to define different outermost elements for each format, such as <htmldoc>, <docbook>, <stylebook>, etc., each with their own content model.
Both of these solutions seem kind of limited, however. I obviously haven't thought it through fully, but I would hope there would be a way to allow the <doc> tag (or its equivalent) to have an extensible content model, while still gaining the benefit of working with a DTD. I suppose it could be done by extending the DTD with an internal subset, perhaps by breaking variant portions of the DTD out into modules that can be included as external entities.
-- +-------------------------------------------------------------------+ | Dave Makower <[EMAIL PROTECTED]> | | Director of Engineering | +--------------------------------+----------------------------------+ | Shooting Gallery Interactive | tel: (212) 905-2200 x155 | | 609 Greenwich St., 9th Floor | fax: (212) 905-2249 | | New York, NY 10014 | http://www.shootinggallery.com/ | +--------------------------------+----------------------------------+
