document <archives>. PR 46257.

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

WHATSNEW

@@ -575,6 +575,12 @@ Other changes:
    processing in Xerces, for example.
    Bugzilla Report 36653.
 
+ * a new resource collection <archives> can be used to specify
+   collections of ZIP and TAR archives as source and extracts them on
+   the fly.  This is a generalization of the <zipgroupfileset> found
+   as nested element of <zip> and friends.
+   Bugzilla Report 46257.
+
 Changes from Ant 1.7.0 TO Ant 1.7.1
 =============================================
 

docs/manual/CoreTasks/zip.html

@@ -314,6 +314,22 @@ The code
 </pre>
 <p>
 <p>zips all files in the <code>htdocs/manual</code> directory into the <code>docs/user-guide</code> directory in the archive and includes all the files in any file that maches <code>examples*.zip</code>, such as all files within <code>examples1.zip</code> or <code>examples_for_brian.zip</code>.
+The same can be achieved with
+<pre>
+  &lt;zip destfile=&quot;${dist}/manual.zip&quot;&gt;
+    &lt;mappedresources&gt;
+      &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
+      &lt;globmapper from="*" to="docs/user-guide/*"/&gt;
+    &lt;/mappedresources&gt;
+    &lt;archives&gt;
+      &lt;zips&gt;
+        &lt;fileset dir=&quot;.&quot; includes=&quot;examples*.zip&quot;/&gt;
+      &lt;/zips&gt;
+    &lt;/archives&gt;
+  &lt;/zip&gt;
+</pre>
+
+The next example
 
 <pre>
 &lt;zip dest="release.zip"&gt;
@@ -321,7 +337,7 @@ The code
 &lt;/zip&gt;
 </pre>
 
-<p>Re-packages a TAR archive as a ZIP archive.  If Unix file
+<p>re-packages a TAR archive as a ZIP archive.  If Unix file
 permissions have been stored as part of the TAR file, they will be
 retained in the resulting ZIP archive.</p>
 

docs/manual/CoreTypes/resources.html

@@ -349,6 +349,9 @@ Ant's "legacy" datatypes have been modified to behave as Resource Collections:
   <li><a href="#mappedresources">mappedresources</a> - generic
     resource collection wrapper that maps the names of the nested
     resources using a <a href="mapper.html">mapper</a>.</li>
+  <li><a href="#archives">archives</a> - wraps around different
+    resource collections and treats the nested resources as ZIP or TAR
+    archives that will be extracted on the fly.</li>
 </ul>
 <h4><a name="resources">resources</a></h4>
 <p>A generic resource collection, designed for use with
@@ -1075,5 +1078,50 @@ larger collection. <strong>Since Ant 1.7.1</strong>.</p>
   </pre>    
 </blockquote>
 
+<h4><a name="archives">archives</a></h4>
+
+<p>This resource collection accepts an arbitrary number of nested
+  resources and assumes that all those resources must be either ZIP or
+  TAR archives.  The resources returned
+  by <code>&lt;archives&gt;</code> are the contents of the nested
+  archives.</p>
+
+<p>This resource collection is a generalization
+  of <a href="../CoreTasks/zip.html#zipgroupfileset">zipgroupfileset</a>
+  which is only supported by the zip family of tasks.</p>
+
+<p><em>archives</em> doesn't support any attributes.</p>
+
+<blockquote>
+  <h4>Parameters specified as nested elements</h4>
+
+  <p><code>&lt;archives&gt;</code> has two nested
+    elements <code>&lt;zips&gt;</code> and
+    <code>&ls;tars&gt;</code> that are <a href="#union">unions</a>
+    themselves, i.e. they accept arbitrary many resource(collection)s
+    as nested elements.</p>
+
+  <p>The nested resources of &lt;zips&gt; are treated as ZIP archives,
+    the nested resources of &lt;tars&gt; as TAR archives.</p>
+
+  <h4>Examples</h4>
+
+  <p>Copies all files from all jars that are on the classpath
+    to <code>${target}</code>.</p>
+
+  <pre>
+    &lt;copy todir="${target}"&gt;
+      &lt;archives&gt;
+        &lt;zips&gt;
+          &lt;restrict&gt;
+            &lt;path path="${java.class.path}"/&gt;
+            &lt;name name="*.jar"/&gt;
+          &lt;/restrict&gt;
+        &lt;/zips&gt;
+      &lt;/archives&gt;
+    &lt;/copy&gt;
+  </pre>
+</blockquote>
+
 </body>
 </html>

src/tests/antunit/types/resources/archives-test.xml

@@ -93,4 +93,44 @@
     </au:expectfailure>
   </target>    
 
+  <!-- works but takes a veeeeeery long time -->
+  <target name="XtestResourcesManualExample">
+    <mkdir dir="${output}"/>
+    <copy todir="${output}">
+      <archives>
+        <zips>
+          <restrict>
+            <path path="${java.class.path}"/>
+            <name name="*.jar"/>
+          </restrict>
+        </zips>
+      </archives>
+    </copy>
+    <au:assertFileExists
+       file="${output}/org/apache/tools/ant/launch/Launcher.class"/>
+  </target>
+
+  <target name="testZipManualExample">
+    <mkdir dir="${output}/control"/>
+    <mkdir dir="${input}/htdocs/manual"/>
+    <touch file="${input}/htdocs/manual/foo.txt"/>
+    <zip destfile="${input}/examples-a.zip">
+      <fileset dir="." includes="*.xml"/>
+    </zip>
+    <zip destfile="${output}/manual.zip">
+      <mappedresources>
+        <fileset dir="${input}/htdocs/manual"/>
+        <globmapper from="*" to="docs/user-guide/*"/>
+      </mappedresources>
+      <archives>
+        <zips>
+          <fileset dir="${input}" includes="examples*.zip"/>
+        </zips>
+      </archives>
+    </zip>
+    <unzip src="${output}/manual.zip" dest="${output}/control"/>
+    <au:assertFileExists file="${output}/control/archives-test.xml"/>
+    <au:assertFileExists file="${output}/control/docs/user-guide/foo.txt"/>
+  </target>
+
 </project>