bodewig 00/08/11 05:45:19
Modified: . WHATSNEW
docs index.html
Log:
Added documentation for the ID attribute and classpathref.
Revision Changes Path
1.21 +3 -4 jakarta-ant/WHATSNEW
Index: WHATSNEW
===================================================================
RCS file: /home/cvs/jakarta-ant/WHATSNEW,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- WHATSNEW 2000/08/10 12:58:51 1.20
+++ WHATSNEW 2000/08/11 12:45:17 1.21
@@ -16,7 +16,7 @@
org.apache.tools.ant to org.apache.tools.ant.types.
* the class attributes of <available>, <java>, <rmic> and <taskdef>
-has been removed.
+have been removed.
* the src attribute of <chmod> has been removed.
@@ -31,10 +31,9 @@
Other changes:
--------------
-* New tasks: antstructure, cab, ftp, genkey, junit, sql.
+* New tasks: antstructure, cab, execon, ftp, genkey, junit, sql.
-* New tasks mparse, execon. All pending documentation, most of
-them pending review.
+* New tasks mparse pending documentation.
* <java> uses ClassLoader of its own in no-fork mode if a classpath is
specified.
1.79 +129 -22 jakarta-ant/docs/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/index.html,v
retrieving revision 1.78
retrieving revision 1.79
diff -u -r1.78 -r1.79
--- index.html 2000/08/10 15:57:59 1.78
+++ index.html 2000/08/11 12:45:18 1.79
@@ -232,6 +232,9 @@
<hr>
<h2><a name="buildfile">Writing a simple buildfile</a></h2>
<p>The buildfile is written in XML. Each buildfile contains one project.</p>
+<p>Each element of the buildfile can have an <code>ID</code> attribute and
+can later be referred to by the value supplied to this. The value has
+to be unique.</p>
<h3>Projects</h3>
<p>A project has three attributes:</p>
<table border="1" cellpadding="2" cellspacing="0">
@@ -507,6 +510,46 @@
<p>is a single command line argument with value
<code>\dir;\dir2;\dir3</code> on DOS based systems and
<code>/dir:/dir2:/dir3</code> on Unix like systems.</p>
+<h3><a name="references">References</a></h3>
+<p>The <code>ID</code> attribute of the buildfile's elements can be
+used to refer to them. This can useful if you are going to replicate
+the same snippet of XML over and over again - using a
+<code><classpath></code> structure more than once for
+example.</p>
+<p>The following example</p>
+<blockquote><pre>
+<rmic ...>
+ <classpath>
+ <pathelement location="lib/" />
+ <pathelement path="${java.class.path}/" />
+ <pathelement path="${additional.path}" />
+ </classpath>
+</rmic>
+<javac ...>
+ <classpath>
+ <pathelement location="lib/" />
+ <pathelement path="${java.class.path}/" />
+ <pathelement path="${additional.path}" />
+ </classpath>
+</javac>
+</pre></blockquote>
+<p>could be rewritten as</p>
+<blockquote><pre>
+<rmic ...>
+ <classpath ID="project.class.path">
+ <pathelement location="lib/" />
+ <pathelement path="${java.class.path}/" />
+ <pathelement path="${additional.path}" />
+ </classpath>
+</rmic>
+<javac ...>
+ <classpathref refid="project.class.path" />
+</javac>
+</pre></blockquote>
+<p>All tasks that use nested elements for <a
+href="#patternset">PatternSet</a>s, <a href="#fileset">FileSet</a>s or
+<a href="#path">PATH like structures</a> accept references to these
+structures as well.</p>
<hr>
<h2><a name="directorybasedtasks">Directory based tasks</a></h2>
<p>Some tasks use directory trees for the task they perform. For instance,
the <a
@@ -663,9 +706,9 @@
</pre></blockquote>
<p>Builds a set of patterns, that matches all <code>.java</code> files
that do not contain the text <code>Test</code> in their name. This set
-can be referred to via <code><patternsetref
-refid="non.test.sources" /></code> by tasks that support
-this feature or by FileSets.</p>
+can be <a href="#references">referred</a> to via
+<code><patternsetref refid="non.test.sources"
+/></code> by tasks that support this feature or by FileSets.</p>
<h3><a name="fileset">FileSets</a></h3>
<p>FileSets are groups of files. These files can be found in a
directory tree starting in a base directory and are matched by
@@ -2085,6 +2128,12 @@
<td align="center" valign="top">No</td>
</tr>
<tr>
+ <td valign="top">classpathref</td>
+ <td valign="top">the classpath to use, given as <a
+ href="#references">reference</a> to a PATH defined elsewhere.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
<td valign="top">fork</td>
<td valign="top">if enabled triggers the class execution in another VM
(disabled by default)</td>
@@ -2123,10 +2172,12 @@
<p>Use nested <code><arg></code> and <code><jvmarg></code>
elements to specify arguments for the or the forked VM. See <a
href="index.html#arg">Command line arguments</a>.</p>
-<h4>classpath</h4>
+<h4>classpath and classpathref</h4>
<p><code>Java</code>'s <em>classpath</em> attribute is a <a
href="#path">PATH like structure</a> and can also be set via a nested
-<em>classpath</em> element.</p>
+<em>classpath</em> element. PATHs defined elsewhere can be
+<a href="#references">referred</a> to via nested <em>classpathref</em>
+elements.</p>
<h5>Example</h5>
<pre>
<java classname="test.Main" >
@@ -2232,6 +2283,18 @@
<td align="center" valign="top">No</td>
</tr>
<tr>
+ <td valign="top">classpathref</td>
+ <td valign="top">the classpath to use, given as <a
+ href="#references">reference</a> to a PATH defined elsewhere.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">bootclasspathref</td>
+ <td valign="top">location of bootstrap class files, given as by <a
+ href="#references">reference</a> to a PATH defined elsewhere.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
<td valign="top">extdirs</td>
<td valign="top">location of installed extensions.</td>
<td align="center" valign="top">No</td>
@@ -2268,12 +2331,14 @@
<code><include></code>, <code><exclude></code>,
<code><patternset></code> and <code><patternsetref></code>
elements.</p>
-<h4>src, classpath, bootclasspath and extdirs</h4>
+<h4>src, classpath, classpathref, bootclasspath, bootclasspathref and
extdirs</h4>
<p><code>Javac</code>'s <em>srcdir</em>, <em>classpath</em>,
<em>bootclasspath</em> and <em>extdirs</em> attributes are <a
href="#path">PATH like structure</a> and can also be set via nested
<em>src</em>, <em>classpath</em>, <em>bootclasspath</em> and
-<em>extdirs</em> elements respectively.</p>
+<em>extdirs</em> elements respectively. PATHs defined elsewhere can be
+<a href="#references">referred</a> to via nested <em>classpathref</em>
+and <em>bootclasspathref</em> elements.</p>
<h3>Examples</h3>
<pre> <javac srcdir="${src}"
@@ -2361,7 +2426,15 @@
<td valign="top">sourcepath</td>
<td valign="top">Specify where to find source files</td>
<td align="center" valign="top">all</td>
- <td align="center" valign="top">Yes</td>
+ <td align="center" rowspan="2">At least one of the two or nested
+ <code><sourcepath></code> or
+ <code><sourcepathref></code></td>
+ </tr>
+ <tr>
+ <td valign="top">sourcepathref</td>
+ <td valign="top">Specify where to find source files by <a
+ href="#references">reference</a> to a PATH defined elsewhere.</td>
+ <td align="center" valign="top">all</td>
</tr>
<tr>
<td valign="top">destdir</td>
@@ -2407,6 +2480,21 @@
<td align="center" valign="top">No</td>
</tr>
<tr>
+ <td valign="top">classpathref</td>
+ <td valign="top">Specify where to find user class files by <a
+ href="#references">reference</a> to a PATH defined elsewhere.</td>
+ <td align="center" valign="top">all</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">bootclasspathref</td>
+ <td valign="top">Override location of class files loaded by the
+ bootstrap class loader by <a href="#references">reference</a> to a
+ PATH defined elsewhere.</td>
+ <td align="center" valign="top">1.2</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
<td valign="top">Extdirs</td>
<td valign="top">Override location of installed extensions</td>
<td align="center" valign="top">1.2</td>
@@ -2619,6 +2707,14 @@
<td align="center" valign="top">No</td>
</tr>
<tr>
+ <td valign="top">docletpathref</td>
+ <td valign="top">Specifies the path to the doclet class file that
+ is specified with the -doclet option by <a
+ href="#references">reference</a> to a PATH defined elsewhere.</td>
+ <td align="center" valign="top">1.2</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
<td valign="top">additionalparam</td>
<td valign="top">Lets you add additional parameters to the javadoc
command line. Useful for doclets</td>
<td align="center" valign="top">1.2</td>
@@ -2634,14 +2730,11 @@
</table>
<h3>Parameters specified as nested elements</h3>
-Two parameters of the Javadoc task may be specified as nested elements of the
-Javadoc task element: link and group.
-When present, there can be any number of each of these elements.
-They perform the same role as the link, linkoffline and
-group attributes. You can use either syntax (or both at once), but with the
nested
-elements you can easily specify multiple occurrences of the arguments.
<h4>link</h4>
-Create link to javadoc output at the given URL
+<p>Create link to javadoc output at the given URL. This performs the
+same role as the link and linkoffline attributes. You can use either
+syntax (or both at once), but with the nested elements you can easily
+specify multiple occurrences of the arguments.</p>
<h4>Parameters</h4>
<table width="60%" border="1" cellpadding="2" cellspacing="0">
@@ -2669,9 +2762,12 @@
</tr>
</table>
-<h4>groups</h4>
-Separates packages on the overview page into whatever groups you specify,
-one group per table.
+<h4>groups</h4>
+<p>Separates packages on the overview page into whatever groups you
+specify, one group per table. This performs the same role as the group
+attribute. You can use either syntax (or both at once), but with the
+nested elements you can easily specify multiple occurrences of the
+arguments.</p>
<table width="60%" border="1" cellpadding="2" cellspacing="0">
<tr>
@@ -2691,12 +2787,15 @@
</tr>
</table>
-<h4>sourcepath, classpath and bootclasspath</h4>
+<h4>sourcepath, classpath, bootclasspath, sourcepathref, classpathref
+and bootclasspathref</h4>
<p><code>Javadoc</code>'s <em>sourcepath</em>, <em>classpath</em> and
<em>bootclasspath</em> attributes are <a href="#path">PATH like
structure</a> and can also be set via nested <em>sourcepath</em>,
<em>classpath</em> and <em>bootclasspath</em> elements
-respectively.</p>
+respectively. PATHs defined elsewhere can be <a
+href="#references">referred</a> to via nested <em>sourcepathref</em>,
+<em>classpathref</em> and <em>bootclasspathref</em> elements.</p>
<h3>Example</h3>
<pre> <javadoc packagenames="com.dummy.test.*"
@@ -3060,6 +3159,12 @@
<td align="center" valign="top">No</td>
</tr>
<tr>
+ <td valign="top">classpathref</td>
+ <td valign="top">The classpath to use during compilation, given as <a
+ href="#references">reference</a> to a PATH defined elsewhere</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
<td valign="top">includes</td>
<td valign="top">comma separated list of patterns of files that must be
included. All files are included when omitted.</td>
@@ -3097,10 +3202,12 @@
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
-<h4>classpath</h4>
+<h4>classpath and classpathref</h4>
<p><code>Rmic</code>'s <em>classpath</em> attribute is a <a
href="#path">PATH like structure</a> and can also be set via a nested
-<em>classpath</em> elements.</p>
+<em>classpath</em> elements. PATHs defined elsewhere can be
+<a href="#references">referred</a> to via nested <em>classpathref</em>
+elements.</p>
<h3>Examples</h3>
<pre> <rmic classname="com.xyz.FooBar"
base="${build}/classes" /></pre>
<p>runs the rmic compiler for the class <code>com.xyz.FooBar</code>. The
