Add docs for <indexjars>

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

WHATSNEW

@@ -128,6 +128,10 @@ Fixed bugs:
 
 * JDependTask did not close an output file. Bugzilla Report 28557.
 
+* <jar> can now optionally create an index for jars different than the
+  one it currently builds as well.  See the new <indexjars> element
+  for details.  Bugzilla Report 14255.
+
 Other changes:
 --------------
 

docs/manual/CoreTasks/jar.html

@@ -160,7 +160,13 @@ being wrapped and continued on the next line.
   </tr>
   <tr>
     <td valign="top">index</td>
-    <td valign="top">whether to create an <A HREF="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#JAR%20Index">index list</A> to speed up classloading.  This is a JDK 1.3+ specific feature.  Defaults to false. </td>
+    <td valign="top">whether to create an <A
+    HREF="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#JAR%20Index">index
+    list</A> to speed up classloading.  This is a JDK 1.3+ specific
+    feature.  Unless you specify additional jars with nested <a
+    href="#indexjars"><code>indexjars</code></a> elements, only the
+    contents of this jar will be included in the index.  Defaults to
+    false.</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
@@ -210,6 +216,32 @@ If the manifest values have changed the jar will be updated or rebuilt, as
 appropriate.
 </p>
 
+<a name="indexjars"><h4>indexjars</h4></a>
+
+<p><em>since ant 1.6.2</em></p>
+
+<p>The nested <code>indexjars</code> element specifies a <a
+href="../using.html#path">PATH like structure</a>.  Its content is
+completely ignored unless you set the index attribute of the task to
+true.</p>
+
+<p>The index created by this task will contain indices for the
+archives contained in this path, the names used for the archioves
+depend on your manifest:</p>
+<ul>
+  <li>If the generated jar's manifest contains no Class-Path
+  attribute, the file name without any leading directory path will be
+  used and all parts of the path will get indexed.</li>
+  <li>If the manifest contains a Class-Path attribute, this task will
+  try to guess which part of the Class-Path belongs to a given
+  archive.  If it cannot guess a name, the archive will be skipped,
+  otherwise tha name listed inside the Class-PAth attribute will be
+  used.</li>
+</ul>
+
+<p>This task will not create any index entries for archives that are
+empty or only contain files inside the META-INF directory.</p>
+
 <h3>Examples</h3>
 <pre>  &lt;jar destfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot;/&gt;</pre>
 <p>jars all files in the <code>${build}/classes</code> directory into a file

src/main/org/apache/tools/ant/taskdefs/Jar.java

@@ -126,7 +126,7 @@ public class Jar extends Zip {
     /**
      * Path containing jars that shall be indexed in addition to this archive.
      *
-     * @since Ant 1.7
+     * @since Ant 1.6.2
      */
     private Path indexJars;
 
@@ -320,7 +320,7 @@ public class Jar extends Zip {
     }
 
     /**
-     * @since Ant 1.7
+     * @since Ant 1.6.2
      */
     public void addConfiguredIndexJars(Path p) {
         if (indexJars == null) {
@@ -706,7 +706,7 @@ public class Jar extends Zip {
      * Writes the directory entries from the first and the filenames
      * from the second list to the given writer, one entry per line.
      *
-     * @since Ant 1.7
+     * @since Ant 1.6.2
      */
     protected final void writeIndexLikeList(List dirs, List files,
                                             PrintWriter writer)
@@ -764,7 +764,7 @@ public class Jar extends Zip {
      * <p>if there is a classpath and the given file doesn't match any
      * of its entries, return null.</p>
      *
-     * @since Ant 1.7
+     * @since Ant 1.6.2
      */
     protected static final String findJarName(String fileName, 
                                               String[] classpath) {