From 9c0ef01928a8ecfe25110c8a4778543296d4da6b Mon Sep 17 00:00:00 2001
From: Stefan Bodewig <bodewig@apache.org>
Date: Tue, 26 Oct 2010 12:45:40 +0000
Subject: [PATCH] clarify documentation on regexp mapper, suggestions by
 Francis Galiegue.  PR 47984

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@1027518 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/Types/mapper.html | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/manual/Types/mapper.html b/docs/manual/Types/mapper.html
index f28d46a3e..a480c19f6 100644
--- a/docs/manual/Types/mapper.html
+++ b/docs/manual/Types/mapper.html
@@ -350,15 +350,22 @@ that don't match the <code>from</code> pattern will be ignored.</p>
     <!--                                        -->
 
 <h4><a name="regexp-mapper">regexp</a></h4>
-<p>Both <code>to</code> and <code>from</code> are required and define regular
-expressions. If the source file name matches the <code>from</code>
-pattern, the target file name will be constructed from the
+
+<p>Both <code>to</code> and <code>from</code> are required and define
+regular expressions. If the source file name (as a whole or in part)
+matches the <code>from</code> pattern, the target file name will be
+constructed from the
 <code>to</code> pattern, using <code>\0</code> to <code>\9</code> as
-back-references for the full
-match (<code>\0</code>) or the matches of the subexpressions in
-parentheses.
-Source
-files not matching the <code>from</code> pattern will be ignored.</p>
+back-references for the full match (<code>\0</code>) or the matches of
+the subexpressions in parentheses.  The <code>to</code> pattern
+determines the <strong>whole</strong> file name, so if you wanted to
+replace the extension of a file you should not use <code>from="\.old$"
+to=".new"</code> but rather <code>from="(.*)\.old$" to="\1.new"</code>
+(or rather use a glob mapper in this case).</p>
+
+<p>Source files not matching the <code>from</code> pattern will be
+ignored.</p>
+
 <p>Note that you need to escape a dollar-sign (<code>$</code>) with
 another dollar-sign in Ant.</p>
 <p>The regexp mapper needs a supporting library and an implementation