Here is an element of style, and also a disagreement RE: your example
element.
- Use description attributes to comment your build file.
All tasks have a description attribute, as do targets and projects. By
using them, you can build documentation for your build process using
something like this XSL transform:
<?xml version="1.0" ?>
<!-- Create documentation from an ant build file -->
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" >
<xsl:output method="html" indent="yes"/>
<xsl:template match="project">
<html>
<body>
<h1><xsl:value-of select="./@name"/></h1>
<xsl:value-of select="./description"/>
<p />
<xsl:apply-templates select="target"/>
</body>
</html>
</xsl:template >
<xsl:template match="*[ @description | @taskname]">
<!-- use taskname if it exists, otherwise use the task element name
-->
<li><b>
<xsl:if test="not(@taskname)">
<xsl:value-of select="name()"/>
</xsl:if>
<xsl:value-of select="@taskname"/></b>
<xsl:text> </xsl:text>
<xsl:value-of select="@description"/>
</li>
</xsl:template>
<xsl:template match="//target">
<b><xsl:value-of select="@name"/></b> -
<xsl:value-of select="@description"/>
<ul><xsl:apply-templates select="./*"/></ul>
<p />
</xsl:template>
<xsl:template match="*"/>
</xsl:stylesheet>
As for your example of building paths up from previously defined properties,
I used to use that strategy but found with complex builds it took too many
steps to figure out exactly what path corresponds to a property. With
built-up properties, you have to look at the property definition of the
property in question, then the definitions of the properties used appearing
in that defintion, and so on and so on. I now prefer to define the
properties directly, so that when I'm looking at a property I simply do a
text search for the property name and since it's at the top of my build
file, its full definition shows up instantly. If I need to change a base
directory, I simply use global search and replace. It doesn't sound as
elegant, but I breath a sigh of relief when I find a property defined
directly.
I suppose the direct technique is most useful when you have a fragmented
heirarchy (files from multiple servers/shares, more like a forest than a
tree) whereas built-up properties might be best when you have a nice tree
structure to the files your build is using.
Gregory Cosmo Haun
Architect, Interactive Development
Cenquest, Inc.
Phone: 503.276.7943
Email: ghaun@cenquest.com
Learn more about Cenquest collaborative e-learning at www.cenquest.com
> -----Original Message-----
> From: Erik Hatcher [mailto:jakarta-ant@ehatchersolutions.com]
> Sent: Thursday, April 18, 2002 5:22 PM
> To: ant-dev; ant-user@jakarta.apache.org
> Subject: The Elements of Ant Style
>
>
> The Ant book that I'm co-authoring is entering its last phase
> of development
> and we would like to involve the entire Ant community in our
> efforts. The [...]
Here is an example:
>
> - Build paths up from previously defined properties rather
> than directly.
>
> Don't do this:
> <property name="build.dir" location="build"/>
> <property name="build.classes" location="build/classes"/>
>
> Do this instead:
> <property name="build.dir" location="build"/>
> <property name="build.classes" location="${build.dir}/classes"/>
>>
--
To unsubscribe, e-mail: <mailto:ant-user-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-user-help@jakarta.apache.org>
|