From c07b787a9a0e4311b93f7bbeafa79cc98af7daaa Mon Sep 17 00:00:00 2001
From: Matthew Jason Benson <mbenson@apache.org>
Date: Tue, 31 May 2005 15:30:53 +0000
Subject: [PATCH] Clearly (hopefully) document '$'-escaping relating to Ant
 properties; increase findability of this information by linking from property
 task. PR: 34534

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@278384 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/CoreTasks/property.html |  3 ++-
 docs/manual/using.html              | 13 +++++++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/manual/CoreTasks/property.html b/docs/manual/CoreTasks/property.html
index ffe73f57d..f3e2f2b99 100644
--- a/docs/manual/CoreTasks/property.html
+++ b/docs/manual/CoreTasks/property.html
@@ -10,7 +10,8 @@
 
 <h2><a name="property">Property</a></h2>
 <h3>Description</h3>
-<p>Sets a property (by name and value), or set of properties (from file or
+<p>Sets a <a href="../using.html#properties">property</a>
+(by name and value), or set of properties (from file or
 resource) in the project.  Properties are case sensitive.</p>
  Properties are immutable: whoever sets a property first freezes it for the
  rest of the build; they are most definitely not variable.
diff --git a/docs/manual/using.html b/docs/manual/using.html
index 5d8b8c85a..4b50f2241 100644
--- a/docs/manual/using.html
+++ b/docs/manual/using.html
@@ -245,6 +245,19 @@ 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