ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From (David Makower)
Subject RE: documenting your build file
Date Thu, 19 Oct 2000 14:51:36 GMT
At 9:29 AM -0500 10/19/00, wrote:
>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                        <> |
| Director of Engineering                                           |
|  Shooting Gallery Interactive  |  tel: (212) 905-2200 x155        |
|  609 Greenwich St., 9th Floor  |  fax: (212) 905-2249             |
|  New York, NY  10014           | |

View raw message