svn commit: r703136 - in /ant/core/trunk: docs/manual/CoreTasks/copy.html src/tests/antunit/taskdefs/copy-test.xml

[bodewig]

Author: bodewig
Date: Thu Oct  9 04:29:17 2008
New Revision: 703136

URL: http://svn.apache.org/viewvc?rev=703136&view=rev
Log:
Improve copy documentation,  PR 45944.

Modified:
    ant/core/trunk/docs/manual/CoreTasks/copy.html
    ant/core/trunk/src/tests/antunit/taskdefs/copy-test.xml

Modified: ant/core/trunk/docs/manual/CoreTasks/copy.html
URL: 
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTasks/copy.html?rev=703136&r1=703135&r2=703136&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTasks/copy.html (original)
+++ ant/core/trunk/docs/manual/CoreTasks/copy.html Thu Oct  9 04:29:17 2008
@@ -33,7 +33,12 @@
 
 <p><a href="../CoreTypes/resources.html#collection">Resource
 Collection</a>s are used to select a group of files to copy.  To use a
-resource collection, the <code>todir</code> attribute must be set.</p>
+resource collection, the <code>todir</code> attribute must be set.
+<strong>Note</strong> that some resources (for example
+the <a href="../CoreTypes/resources.html#file">file</a> resource)
+return absolute paths as names and the result of using them without
+using a nested mapper (or the flatten attribute) may not be what you
+expect.</p>
 
 <p>
 <strong>Note: </strong>If you employ filters in your copy operation,
@@ -153,6 +158,7 @@
     systems.  This can also be useful if source and target files live
     on separate machines with clocks being out of sync.  <em>since Ant
     1.6.2</em>.</td>
+    <td align="center">No</td>
   </tr>
 </table>
 <h3>Parameters specified as nested elements</h3>
@@ -263,6 +269,13 @@
   &lt;/copy&gt;
 </pre>
 
+<p>If the example above didn't use the flatten attribute,
+  the <code>&lt;file&gt;</code> resource would have returned its full
+  path as source and target name and would not have been copied at
+  all.  In general it is a good practice to use an explicit mapper
+  together with resources that use an absolute path as their
+  names.</p>
+
 <p><b>Copies the two newest resources into a destination directory.</b></p>
 <pre>
   &lt;copy todir=&quot;dest&quot; flatten=&quot;true&quot;&gt;
@@ -280,6 +293,8 @@
   &lt;/copy&gt;
 </pre>
 
+<p>The paragraph following the previous example applies to this
+  example as well.</p>
 
 <p><strong>Unix Note:</strong> File permissions are not retained when files
 are copied; they end up with the default <code>UMASK</code> permissions

Modified: ant/core/trunk/src/tests/antunit/taskdefs/copy-test.xml
URL: 
http://svn.apache.org/viewvc/ant/core/trunk/src/tests/antunit/taskdefs/copy-test.xml?rev=703136&r1=703135&r2=703136&view=diff
==============================================================================
--- ant/core/trunk/src/tests/antunit/taskdefs/copy-test.xml (original)
+++ ant/core/trunk/src/tests/antunit/taskdefs/copy-test.xml Thu Oct  9 04:29:17 
2008
@@ -24,24 +24,6 @@
     <touch file="${input}/file.txt"/>
   </target>
 
-  <target name="xtestCopyFile" depends="-fileResourceSetup">
-    <au:assertFileDoesntExist file="${output}/file.txt"/>
-    <copy todir="${output}">
-      <file file="${input}/file.txt"/>
-    </copy>
-    <au:assertFileExists file="${output}/file.txt"/>
-  </target>
-
-  <target name="xtestCopyFileInResources" depends="-fileResourceSetup">
-    <au:assertFileDoesntExist file="${output}/file.txt"/>
-    <copy todir="${output}">
-      <resources>
-        <file file="${input}/file.txt"/>
-      </resources>
-    </copy>
-    <au:assertFileExists file="${output}/file.txt"/>
-  </target>
-
   <target name="testCopyFileFlatten" depends="-fileResourceSetup">
     <au:assertFileDoesntExist file="${output}/file.txt"/>
     <copy todir="${output}" flatten="true">