extract and expand property documentation

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@828198 13f79535-47bb-0310-9956-ffa450edef68
16 years ago · 2f1a9d25bf
--- a/docs/manual/CoreTasks/property.html
+++ b/docs/manual/CoreTasks/property.html
@@ -57,7 +57,7 @@ instance.</p>
 properties. These references are resolved at the time these properties are set.
 This also holds for properties loaded from a property file.</p>
 <p>A list of predefined properties can be found <a
 href="../using.html#built-in-props">here</a>.</p>
 href="../properties.html#built-in-props">here</a>.</p>
 <p>Since Ant 1.7.1 it is possible to load properties defined in xml
 according to <a href="http://java.sun.com/dtd/properties.dtd">Suns DTD</a>,
 if Java5+ is present. For this the name of the file, resource or url has 
--- a/docs/manual/CoreTasks/propertyhelper.html
+++ b/docs/manual/CoreTasks/propertyhelper.html
@@ -31,7 +31,7 @@
 <b>(b)</b> (hopefully more often) install one or more PropertyHelper Delegates into the
 PropertyHelper active on the current Project. This is somewhat advanced Ant usage and
 assumes a working familiarity with the modern Ant APIs. See the description of Ant's
 <a href="../using.html#propertyHelper">Property Helper</a> for more information.
 <a href="../properties.html#propertyHelper">Property Helper</a> for more information.
 <b>Since Ant 1.8.0</b></p>
 <h3>Parameters specified as nested elements</h3>
--- a/docs/manual/conceptstypeslist.html
+++ b/docs/manual/conceptstypeslist.html
@@ -28,6 +28,7 @@
 <h2><a href="toc.html" target="navFrame">Table of Contents</a></h2>
 <h3>Concepts</h3>
 <a href="properties.html">Properties and PropertyHelpers</a>
 <a href="clonevm.html">ant.build.clonevm</a><br/>
 <a href="sysclasspath.html">build.sysclasspath</a><br/>
 <a href="javacprops.html">Ant properties controlling javac</a><br/>
--- a/docs/manual/properties.html
+++ b/docs/manual/properties.html
@@ -0,0 +1,326 @@
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <html>
 <head>
  <meta http-equiv="Content-Language" content="en-us"/>
  <link rel="stylesheet" type="text/css" href="stylesheets/style.css"/>
  <title>Properties and PropertyHelpers</title>
 </head>
 <body>
  <h1>Properties</h1>
  <p>Properties are key-value-pairs where Ant tries to
    expand <code>${key}</code> to <code>value</code> at runtime.</p>
  <p>There are many tasks that can set properties, the most common one
    is the <a href="CoreTasks/property.html">property</a> task.  In
    addition properties can be defined
    via <a href="running.html">command line arguments</a> or similar
    mechanisms from outside of Ant.</p>
  <p>Normally property values can not be changed, once a property is
    set, most tasks will not allow its value to be modified.  In
    general properties are of global scope, i.e. once they have been
    defined they are available for any task or target invoked
    subsequently - it is not possible to set a property in a child
    build process created via
    the <a href="CoreTasks/ant.html">ant</a>, antcall or subant tasks
    and make it available to the calling build process, though.</p>
  <p>Starting with Ant 1.8.0
    the <a href="CoreTasks/local.html">local</a> task can be used to
    create properties that are locally scoped to a target or
    a <a href="CoreTasks/sequential.html">sequential</a> element like
    the one of the <a href="CoreTasks/macrodef.html">macrodef</a>
    task.</p>
  <a name="built-in-props"><h2>Built-in Properties</h2></a>
  <p>Ant provides access to all system properties as if they had been
    defined using a <code>&lt;property&gt;</code> task.  For
    example, <code>${os.name}</code> expands to the name of the
    operating system.</p>
  <p>For a list of system properties see
    <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>.
  </p>
  <p>In addition, Ant has some built-in properties:</p>
 <pre>
 basedir             the absolute path of the project's basedir (as set
                    with the basedir attribute of <a href="using.html#projects">&lt;project&gt;</a>).
 ant.file            the absolute path of the buildfile.
 ant.version         the version of Ant
 ant.project.name    the name of the project that is currently executing;
                    it is set in the name attribute of &lt;project&gt;.
 ant.project.default-target
                    the name of the currently executing project's
                    default target;  it is set via the default
                    attribute of &lt;project&gt;.
 ant.project.invoked-targets
                    a comma separated list of the targets that have
                    been specified on the command line (the IDE,
                    an &lt;ant&gt; task ...) when invoking the current
                    project.
 ant.java.version    the JVM version Ant detected; currently it can hold
                    the values &quot;1.2&quot;, &quot;1.3&quot;,
                    &quot;1.4&quot;,  &quot;1.5&quot; and &quot;1.6&quot;.
 ant.core.lib        the absolute path of the <code>ant.jar</code> file.
 </pre>
  <p>There is also another property, but this is set by the launcher
    script and therefore maybe not set inside IDEs:</p>
 <pre>
 ant.home            home directory of Ant
 </pre>
  <p>The following property is only set if Ant is started via the
    Launcher class (which means it may not be set inside IDEs
    either):</p>
 <pre>
 ant.library.dir     the directory that has been used to load Ant's
                    jars from.  In most cases this is ANT_HOME/lib.
 </pre>
  <a name="propertyHelper"><h1>PropertyHelpers</h1></a>
  <p>Ant's property handling is accomplished by an instance of
    <code>org.apache.tools.ant.PropertyHelper</code> associated with
    the current Project.  You can learn more about this class by
    examining Ant's Java API. In Ant 1.8 the PropertyHelper class was
    much reworked and now itself employs a number of helper classes
    (actually instances of
    the <code>org.apache.tools.ant.PropertyHelper$Delegate</code>
    marker interface) to take care of discrete tasks such as property
    setting, retrieval, parsing, etc. This makes Ant's property
    handling highly extensible; also of interest is the
    new <a href="CoreTasks/propertyhelper.html">propertyhelper</a>
    task used to manipulate the PropertyHelper and its delegates from
    the context of the Ant buildfile.
  <p>There are three sub-interfaces of <code>Delegate</code> that may be
    useful to implement.</p>
  <ul>
    <li><code>org.apache.tools.ant.property.PropertyExpander</code> is
      responsible for finding the property name inside a string in the
      first place (the default extracts <code>foo</code>
      from <code>${foo}</code>).
      <p>This is the interface you'd implement if you wanted to invent
        your own property syntax - or allow nested property expansions
        since the default implementation doesn't balance braces
        (see <a href="http://svn.apache.org/viewvc/ant/antlibs/props/trunk/src/main/org/apache/ant/props/NestedPropertyExpander.java?view=log"><code>NestedPropertyExpander</code>
        in the "props" Antlib</a> for an example).</p>
    </li>
    <li><code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code>
      is used to expand <code>${some-string}</code> into
      an <code>Object</code>.
      <p>This is the interface you'd implement if you want to provide
        your own storage independent of Ant's project instance - the
        interface represents the reading end.  An example for this
        would
        be <code>org.apache.tools.ant.property.LocalProperties</code>
        which implements storage
        for <a href="CoreTasks/local.html">local properties</a>.</p>
      <p>Another reason to implement this interface is if you wanted
        to provide your own "property protocol" like
        expanding <code>toString:foo</code> by looking up the project
        reference foo and invoking <code>toString()</code> on it
        (which is already implemented in Ant, see below).</p>
    </li>
    <li><code>org.apache.tools.ant.PropertyHelper$PropertySetter</code>
      is responsible for setting properties.
      <p>This is the interface you'd implement if you want to provide
        your own storage independent of Ant's project instance - the
        interface represents the reading end.  An example for this
        would
        be <code>org.apache.tools.ant.property.LocalProperties</code>
        which implements storage
        for <a href="CoreTasks/local.html">local properties</a>.</p>
    </li>
  </ul>
  <p>The default <code>PropertyExpander</code> looks similar to:</p>
 <pre>
 public class DefaultExpander implements PropertyExpander {
    public String parsePropertyName(String s, ParsePosition pos,
                                    ParseNextProperty notUsed) {
        int index = pos.getIndex();
        if (s.indexOf("${", index) == index) {
            int end = s.indexOf('}', index);
            if (end < 0) {
                throw new BuildException("Syntax error in property: " + s);
            }
            int start = index + 2;
            pos.setIndex(end + 1);
            return s.substring(start, end);
        }
        return null;
    }
 }
 </pre>
  <p>The logic that replaces <code>${toString:some-id}</code> with the
    stringified representation of the object with
    id <code>some-id</code> inside the current build is contained in a
    PropertyEvaluator similar to the following code:</p>
 <pre>
 public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator {
    private static final String prefix = "toString:";
    public Object evaluate(String property, PropertyHelper propertyHelper) {
        Object o = null;
        if (property.startsWith(prefix) && propertyHelper.getProject() != null) {
            o = propertyHelper.getProject().getReference(property.substring(prefix.length()));
        }
        return o == null ? null : o.toString();
    }
 }
 </pre>
  <h1>Property Expansion</h1>
  <p>When Ant encounters a construct <code>${some-text}</code> the
    exact parsing semantics are subject to the configured property
    helper delegates.</p>
  <h2><code>$$</code> Expansion</h2>
  <p>In its default configuration Ant will expand the
    text <code>$$</code> to a single <code>$</code> and suppress the
    normal property expansion mechanism for the text immediately
    following it, i.e. <code>$${key}</code> expands
    to <code>${key}</code> and not <code>value</code> even though a
    property named <code>key</code> was defined and had the
    value <code>value</code>.  This can be used to escape
    literal <code>$</code> characters and is useful in constructs that
    only look like property expansions or when you want to provide
    diagnostic output like in</p>
 <pre>  &lt;echo&gt;$${builddir}=${builddir}&lt;/echo&gt;</pre>
    <p>which will echo this message:</p>
 <pre>  ${builddir}=build/classes</pre>
  <p>if the property <code>builddir</code> has the
    value <code>build/classes</code>.</p>
  <p>In order to maintain backward compatibility with older Ant
    releases, a single '$' character encountered apart from a
    property-like construct (including a matched pair of french
    braces) will be interpreted literally; that is, as '$'.  The
    "correct" way to specify this literal character, however, is by
    using the escaping mechanism unconditionally, so that "$$" is
    obtained by specifying "$$$$".  Mixing the two approaches yields
    unpredictable results, as "$$$" results in "$$".</p>
  <h2>Nesting of Braces</h2>
  <p>In its default configuration Ant will not try to ballance braces
    in property expansions, it will only consume the text up to the
    first closing brace when creating a property name.  I.e. when
    expanding something like <code>${a${b}}</code> it will be
    translated into two parts:</p>
  <ol>
    <li>the expansion of property <code>a${b</code> - likely nothing
      useful.</li>
    <li>the literal text <code>}</code> resulting from the second
      closing brace</li>
  </ol>
  <p>This means you can't use easily expand properties whose names are
    given by properties, but there
    are <a href="http://ant.apache.org/faq.html#propertyvalue-as-name-for-property">some
    workarounds</a> for older versions of Ant.  With Ant 1.8.0 and the
    <a href="http://ant.apache.org/antlib/props/">the props Antlib</a>
    you can configure Ant to use
    the <code>NestedPropertyExpander</code> defined there if you need
    such a feature.</p>
  <h2>Expanding a "Property Name"</h2>
  <p>In its most simple form <code>${key}</code> is supposed to look
    up a property named <code>key</code> and expand to the value of
    the property.  Additional <code>PropertyEvaluator</code>s may
    result in a different interpretation of <code>key</code>,
    though.</p>
  <p>The <a href="http://ant.apache.org/antlibs/props/">props
      Antlib</a> provides a few interesting evaluators but there are
      also a few built-in ones.</p>
  <a name="toString"><h3>Getting the value of a Reference with
      ${toString:}</h3></a>
  <p>Any Ant type which has been declared with a reference can also
    its string value extracted by using the <code>${toString:}</code>
    operation, with the name of the reference listed after
    the <code>toString:</code> text.  The <code>toString()</code>
    method of the Java class instance that is referenced is invoked
    -all built in types strive to produce useful and relevant output
    in such an instance.</p>
  <p>For example, here is how to get a listing of the files in a fileset,<p>
 <pre>
 &lt;fileset id=&quot;sourcefiles&quot; dir=&quot;src&quot; includes=&quot;**/*.java&quot; /&gt;
 &lt;echo&gt; sourcefiles = ${toString:sourcefiles} &lt;/echo&gt;
 </pre>
  <p>There is no guarantee that external types provide meaningful
    information in such a situation</p>
  <h3><a name="ant.refid">Getting the value of a Reference with
      ${ant.refid:}</a></h3>
  <p>Any Ant type which has been declared with a reference can also be
    used as a property by using the <code>${ant.refid:}</code>
    operation, with the name of the reference listed after
    the <code>ant.refid:</code> text.  The difference between this
    operation and <a href="#toString"><code>${toString:}</code></a> is
    that <code>${ant.refid:}</code> will expand to the referenced
    object itself.  In most circumstances the toString method will be
    invoked anyway, for example if the <code>${ant.refid:}</code> is
    surrounded by other text.</p>
  <p>This syntax is most useful when using a task with attribute
    setters that accept objects other than String.  For example if the
    setter accepts a Resource object as in</p>
 <pre>
 public void setAttr(Resource r) { ... }
 </pre>
  <p>then the syntax can be used to pass in resource subclasses
    preciously defined as references like</p>
 <pre>
  &lt;url url="http://ant.apache.org/" id="anturl"/&gt;
  &lt;my:task attr="${ant.refid:anturl}"/&gt;
 </pre>
 </body>
--- a/docs/manual/tutorial-tasks-filesets-properties.html
+++ b/docs/manual/tutorial-tasks-filesets-properties.html
@@ -317,7 +317,7 @@ whithout being complex :-)</p>
 <p>The test case uses the ant property <i>ant.home</i> as reference. This property is set by the
 <tt>Launcher</tt> class which starts ant. We can use that property in our buildfiles as a
 <a href="using.html#built-in-props">build-in property [3]</a>. But if we create a new ant
 <a href="properties.html#built-in-props">build-in property [3]</a>. But if we create a new ant
 environment we have to set that value for our own. And we use the <code>&lt;junit&gt;</code> task in fork-mode.
 Therefore we have do modify our buildfile:
 <pre class="code">
@@ -952,7 +952,7 @@ Now the new task is uploaded into the bug database.
 <h2><a name="resources">Resources</a></h2>
 &nbsp;&nbsp;[1] <a href="tutorial-writing-tasks.html">tutorial-writing-tasks.html</a><br>
 &nbsp;&nbsp;[2] <a href="tutorial-tasks-filesets-properties.zip">tutorial-tasks-filesets-properties.zip</a><br>
 &nbsp;&nbsp;[3] <a href="using.html#built-in-props">using.html#built-in-props</a><br>
 &nbsp;&nbsp;[3] <a href="properties.html#built-in-props">properties.html#built-in-props</a><br>
 &nbsp;&nbsp;[4] <a href="http://ant-contrib.sourceforge.net/">http://ant-contrib.sourceforge.net/</a><br>
 &nbsp;&nbsp;[5] <a href="CoreTasks/java.html">CoreTasks/java.html</a><br>
 &nbsp;&nbsp;[6] <a href="http://ant.apache.org/ant_task_guidelines.html">http://ant.apache.org/ant_task_guidelines.html</a><br>
--- a/docs/manual/tutorial-writing-tasks.html
+++ b/docs/manual/tutorial-writing-tasks.html
@@ -102,7 +102,7 @@ the execution of some steps bofore. So the refactored code is:
 &lt;/project&gt;
 </pre>
 <i>ant.project.name</i> is one of the
 <a href="http://ant.apache.org/manual/using.html#built-in-props" target="_blank">
 <a href="http://ant.apache.org/manual/properties.html#built-in-props" target="_blank">
 build-in properties [1]</a> of Ant.
@@ -755,7 +755,7 @@ The last sources and the buildfile are also available
 Used Links:<br>
 &nbsp;&nbsp;[1] <a href="http://ant.apache.org/manual/using.html#built-in-props">http://ant.apache.org/manual/using.html#built-in-props</a><br>
 &nbsp;&nbsp;[1] <a href="http://ant.apache.org/manual/properties.html#built-in-props">http://ant.apache.org/manual/properties.html#built-in-props</a><br>
 &nbsp;&nbsp;[2] <a href="http://ant.apache.org/manual/CoreTasks/taskdef.html">http://ant.apache.org/manual/CoreTasks/taskdef.html</a><br>
 &nbsp;&nbsp;[3] <a href="http://ant.apache.org/manual/develop.html#set-magic">http://ant.apache.org/manual/develop.html#set-magic</a><br>
 &nbsp;&nbsp;[4] <a href="http://ant.apache.org/manual/develop.html#nested-elements">http://ant.apache.org/manual/develop.html#nested-elements</a><br>
--- a/docs/manual/using.html
+++ b/docs/manual/using.html
@@ -267,170 +267,27 @@ task instances at all, only proxies.
 </p>
 <h3><a name="properties">Properties</a></h3>
 <p>A project can have a set of properties. These might be set in the buildfile
 by the <a href="CoreTasks/property.html">property</a> task, or might be set outside Ant. A
 property has a name and a value; the name is case-sensitive. Properties may be used in the value of
 task attributes. This is done by placing the property name between
 &quot;<code>${</code>&quot; and &quot;<code>}</code>&quot; in the
 attribute value. For example,
 if there is a &quot;builddir&quot; property with the value
 &quot;build&quot;, then this could be used in an attribute like this:
 <code>${builddir}/classes</code>.
 This is resolved at run-time as <code>build/classes</code>.</p>
 <p>In the event you should need to include this construct literally
 (i.e. without property substitutions), simply "escape" the '$' character
 by doubling it. To continue the previous example:
 <pre>  &lt;echo&gt;$${builddir}=${builddir}&lt;/echo&gt;</pre>
 will echo this message:
 <pre>  ${builddir}=build/classes</pre></p>
 <p>In order to maintain backward compatibility with older Ant releases,
 a single '$' character encountered apart from a property-like construct
 (including a matched pair of french braces) will be interpreted literally;
 that is, as '$'.  The "correct" way to specify this literal character,
 however, is by using the escaping mechanism unconditionally, so that "$$"
 is obtained by specifying "$$$$".  Mixing the two approaches yields
 unpredictable results, as "$$$" results in "$$".</p>
 <h3><a name="built-in-props">Built-in Properties</a></h3>
 <p>Ant provides access to all system properties as if they had been
 defined using a <code>&lt;property&gt;</code> task.
 For example, <code>${os.name}</code> expands to the
 name of the operating system.</p>
 <p>For a list of system properties see
 <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>.
 </p>
 <p>In addition, Ant has some built-in properties:</p>
 <pre>
 basedir             the absolute path of the project's basedir (as set
                    with the basedir attribute of <a href="#projects">&lt;project&gt;)</a>.
 ant.file            the absolute path of the buildfile.
 ant.version         the version of Ant
 ant.project.name    the name of the project that is currently executing;
                    it is set in the name attribute of &lt;project&gt;.
 ant.project.default-target
                    the name of the currently executing project's
                    default target;  it is set via the default
                    attribute of &lt;project&gt;.
 ant.project.invoked-targets
                    a comma separated list of the targets that have
                    been specified on the command line (the IDE,
                    an &lt;ant&gt; task ...) when invoking the current
                    project.
 ant.java.version    the JVM version Ant detected; currently it can hold
                    the values &quot;1.2&quot;, &quot;1.3&quot;,
                    &quot;1.4&quot;,  &quot;1.5&quot; and &quot;1.6&quot;.
 ant.core.lib        the absolute path of the <code>ant.jar</code> file.
 </pre>
 <p>There is also another property, but this is set by the launcher script and therefore
 maybe not set inside IDEs:</p>
 <pre>
 ant.home            home directory of Ant
 </pre>
 <p>The following property is only set if Ant is started via the
  Launcher class (which means it may not be set inside IDEs
  either):</p>
 <pre>
 ant.library.dir     the directory that has been used to load Ant's
                    jars from.  In most cases this is ANT_HOME/lib.
 </pre>
 <a name="propertyHelper"><h3>Property Helpers</h3></a>
 Ant's property handling is accomplished by an instance of
 <code>org.apache.tools.ant.PropertyHelper</code> associated with the current Project.
 You can learn more about this class by examining Ant's Java API. In Ant 1.8 the
 PropertyHelper class was much reworked and now itself employs a number of helper
 classes (actually instances of the <code>org.apache.tools.ant.PropertyHelper$Delegate</code>
 marker interface) to take care of discrete tasks such as property setting, retrieval,
 parsing, etc. This makes Ant's property handling highly extensible; also of interest is the
 new <a href="CoreTasks/propertyhelper.html">propertyhelper</a> task used to manipulate the
 PropertyHelper and its delegates from the context of the Ant buildfile.
 <p>There are three sub-interfaces of <code>Delegate</code> that may be
  useful to implement.</p>
 <ul>
  <li><code>org.apache.tools.ant.property.PropertyExpander</code> is
    responsible for finding the property name inside a string in the
    first place (the default extracts <code>foo</code>
    from <code>${foo}</code>).
    <p>This is the interface you'd implement if you wanted to invent
      your own property syntax - or allow nested property expansions
      since the default implementation doesn't balance braces
      (see <a href="http://svn.apache.org/viewvc/ant/sandbox/antlibs/props/trunk/src/main/org/apache/ant/props/NestedPropertyExpander.java?view=log"><code>NestedPropertyExpander</code>
        in the "props" Antlib in Ant's sandbox</a> for an
      example).</p>
  </li>
  <li><code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code>
    is used to expand <code>${some-string}</code> into
    an <code>Object</code>.
    <p>This is the interface you'd implement if you want to provide
      your own storage independent of Ant's project instance - the
      interface represents the reading end.  An example for this would
      be <code>org.apache.tools.ant.property.LocalProperties</code>
      which implements storage
      for <a href="CoreTasks/local.html">local properties</a>.</p>
    <p>Another reason to implement this interface is if you wanted to
      provide your own "property protocol" like
      expanding <code>toString:foo</code> by looking up the project
      reference foo and invoking <code>toString()</code> on it (which
      is already implemented in Ant, see below).</p>
  </li>
  <li><code>org.apache.tools.ant.PropertyHelper$PropertySetter</code>
    is responsible for setting properties.
    <p>This is the interface you'd implement if you want to provide
      your own storage independent of Ant's project instance - the
      interface represents the reading end.  An example for this would
      be <code>org.apache.tools.ant.property.LocalProperties</code>
      which implements storage
      for <a href="CoreTasks/local.html">local properties</a>.</p>
  </li>
 </ul>
 <p>The default <code>PropertyExpander</code> looks similar to:</p>
 <pre>
 public class DefaultExpander implements PropertyExpander {
    public String parsePropertyName(String s, ParsePosition pos,
                                    ParseNextProperty notUsed) {
        int index = pos.getIndex();
        if (s.indexOf("${", index) == index) {
            int end = s.indexOf('}', index);
            if (end < 0) {
                throw new BuildException("Syntax error in property: " + s);
            }
            int start = index + 2;
            pos.setIndex(end + 1);
            return s.substring(start, end);
        }
        return null;
    }
 }
 </pre>
 <p>The logic that replaces <code>${toString:some-id}</code> with the
  stringified representation of the object with
  id <code>some-id</code> inside the current build is contained in a
  PropertyEvaluator similar to the following code:</p>
 <pre>
 public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator {
    private static final String prefix = "toString:";
    public Object evaluate(String property, PropertyHelper propertyHelper) {
        Object o = null;
        if (property.startsWith(prefix) && propertyHelper.getProject() != null) {
            o = propertyHelper.getProject().getReference(property.substring(prefix.length()));
        }
        return o == null ? null : o.toString();
    }
 }
 </pre>
 <p>Properties are an important way to customize a build process or
  to just provide shortcuts for strings that are used repeatedly
  inside a build file.</p>
 <p>In its most simple form properties are defined in the build file
  (for example by the <a href="CoreTasks/property.html">property</a>
  task) or might be set outside Ant.  A property has a name and a
  value; the name is case-sensitive. Properties may be used in the
  value of task attributes or in the nested text of tasks that support
  them.  This is done by placing the property name between
  &quot;<code>${</code>&quot; and &quot;<code>}</code>&quot; in the
  attribute value. For example, if there is a &quot;builddir&quot;
  property with the value &quot;build&quot;, then this could be used
  in an attribute like this: <code>${builddir}/classes</code>.  This
  is resolved at run-time as <code>build/classes</code>.</p>
 <p>With Ant 1.8.0 property expansion has become much more powerful
  than simple key value pairs, more details can be
  found <a href="properties.html">in the concepts section</a> of this
  manual.</p>
 <a name="example"><h3>Example Buildfile</h3></a>
 <pre>
@@ -784,52 +641,6 @@ implementation of the element upon which it is specified. Some tasks (the
 deliberately assign a different meaning to <code>refid</code>.</p>
 <h3><a name="toString">Getting the value of a Reference with ${toString:}</a></h3>
 <p>
 Any Ant type which has been declared with a reference can also its string
 value extracted by using the <code>${toString:}</code> operation,
 with the name of the reference listed after the  <code>toString:</code> text. 
 The  <code>toString()</code> method of the Java class instance that is
 referenced is invoked -all built in types strive to produce useful and relevant
 output in such an instance.
 </p>
 <p>
 For example, here is how to get a listing of the files in a fileset, 
 <p>
 <pre>
 &lt;fileset id=&quot;sourcefiles&quot; dir=&quot;src&quot; includes=&quot;**/*.java&quot; /&gt;
 &lt;echo&gt; sourcefiles = ${toString:sourcefiles} &lt;/echo&gt;
 </pre>
 <p>
 There is no guarantee that external types provide meaningful information in such
 a situation</p>
 <h3><a name="ant.refid">Getting the value of a Reference with
    ${ant.refid:}</a></h3>
 <p>Any Ant type which has been declared with a reference can also be
  used as a property by using the <code>${ant.refid:}</code>
  operation, with the name of the reference listed after
  the <code>ant.refid:</code> text.  The difference between this
  operation and <a href="#toString"><code>${toString:}</code></a> is
  that <code>${ant.refid:}</code> will expand to the referenced object
  itself.  In most circumstances the toString method will be invoked
  anyway, for example if the <code>${ant.refid:}</code> is surrounded
  by other text.</p>
 <p>This syntax is most useful when using a task with attribute setters
  that accept objects other than String.  For example if the setter
  accepts a Resource object as in</p>
 <pre>
 public void setAttr(Resource r) { ... }
 </pre>
 <p>then the syntax can be used to pass in resource subclasses
  preciously defined as references like</p>
 <pre>
  &lt;url url="http://ant.apache.org/" id="anturl"/&gt;
  &lt;my:task attr="${ant.refid:anturl}"/&gt;
 </pre>
 <h3><a name="external-tasks">Use of external tasks</a></h3> 
 Ant supports a plugin mechanism for using third party tasks. For using them you 
 have to do two steps: 
--- a/docs/manual/usinglist.html
+++ b/docs/manual/usinglist.html
@@ -34,8 +34,8 @@
  <a href="using.html#targets">Targets</a><br/>
  <a href="using.html#tasks">Tasks</a><br/>
  <a href="using.html#properties">Properties</a><br/>
  <a href="using.html#built-in-props">Built-in Properties</a><br/>
  <a href="using.html#propertyHelper">Property Helpers</a><br />
  <a href="properties.html#built-in-props">Built-in Properties</a><br/>
  <a href="properties.html#propertyHelper">Property Helpers</a><br />
  <a href="using.html#example">Example Buildfile</a><br/>
  <a href="using.html#filters">Token Filters</a><br/>
  <a href="using.html#path">Path-like Structures</a><br/>