ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Greg 'Cosmo' Haun <GH...@cenquest.com>
Subject RE: The Elements of Ant Style - self-documenting build file
Date Mon, 22 Apr 2002 22:42:23 GMT
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>


Mime
View raw message