Clarify the to attribute of the mapper nested element of uptodate

PR: 24249
Obtained from: nakato@qute.co.jp


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@275675 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/CoreTasks/uptodate.html

@@ -70,7 +70,10 @@ attribute or nested <code>&lt;srcfiles&gt;</code> elements, but not both.
 <p>The nested <code>&lt;mapper&gt;</code> element allows you to specify
 a set of target files to check for being up-to-date with respect to a
 set of source files.</p>
-
+   <p>
+      The mapper "to" attribute is relative to the target file, or to
+      the "dir" attribute of the nested srcfiles element.
+   </p>
 <h3>Examples</h3>
 <pre>  &lt;uptodate property=&quot;xmlBuild.notRequired&quot; targetfile=&quot;${deploy}\xmlClasses.jar&quot; &gt;
     &lt;srcfiles dir= &quot;${src}/xml&quot; includes=&quot;**/*.dtd&quot;/&gt;
@@ -111,9 +114,30 @@ against a single target file:</p>
 if <code>/usr/local/bin/testit</code> is newer than
 <code>${build}/.flagfile</code>.</p>
 </p>
+  <p>
+    The following shows usage of a relative mapper.
+  </p>
+  <pre>
+    &lt;uptodate property="checkUptodate.uptodate"&gt;
+      &lt;srcfiles dir="src" includes="*" /&gt;
+      &lt;mapper type="merge" to="../dest/output.done"/&gt;
+    &lt;/uptodate&gt;
+    &lt;echo message="checkUptodate result: ${checkUptodate.uptodate}" /&gt;
+  </pre>
+  <p>
+    The previous example can be a bit confusing, so it may be better to
+    use absolute paths:
+  </p>
+  <pre>
+    &lt;property name="dest.dir" location="dest"/&gt;
+    &lt;uptodate property="checkUptodate.uptodate"&gt;
+      &lt;srcfiles dir="src" includes="*" /&gt;
+      &lt;mapper type="merge" to="${dest.dir}/output.done"/&gt;
+    &lt;/uptodate&gt;
+  </pre>
 
 <hr>
-<p align="center">Copyright &copy; 2000-2002 Apache Software Foundation.
+<p align="center">Copyright &copy; 2000-2003 Apache Software Foundation.
 All rights Reserved.</p>
 
 </body>