#30606: add 'executable' attr to <javadoc>.

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

WHATSNEW

@@ -79,6 +79,8 @@ Fixed bugs:
 Other changes:
 --------------
 
+* <javadoc> can now take an attribute 'executable'. Bugzilla report 30606.
+
 * <WsdlToDotnet> and <style> are now deprecated in favor of <wsdltodotnet> and
   <xslt>, respectively. Bugzilla report 25832.
 

docs/manual/CoreTasks/javadoc.html

@@ -19,16 +19,16 @@ and management costs over time. This task, however, has no notion of
 &quot;changed&quot; files, unlike the <a href="javac.html">javac</a> task. This means
 all packages will be processed each time this task is run. In general, however,
 this task is used much less frequently.</p>
-<p>This task works seamlessly between different javadoc versions (1.1,
-1.2 and 1.4), with the obvious restriction that the 1.2 attributes
-will be ignored if run in a 1.1 VM.</p>
+<p>This task works seamlessly between different javadoc versions (1.2 and 1.4),
+with the obvious restriction that the 1.4 attributes
+will be ignored if run in a 1.2 VM.</p>
 <p>NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the
-same VM as ant without breaking functionality. For this reason, this task
+same VM as Ant without breaking functionality. For this reason, this task
 always forks the VM. This overhead is not significant since javadoc is normally a heavy
 application and will be called infrequently.</p>
 <p>NOTE: the packagelist attribute allows you to specify the list of packages to
 document outside of the Ant file. It's a much better practice to include everything
-inside the build.xml file. This option was added in order to make it easier to
+inside the <code>build.xml</code> file. This option was added in order to make it easier to
 migrate from regular makefiles, where you would use this option of javadoc.
 The packages listed in packagelist are not checked, so the task performs even
 if some packages are missing or broken. Use this option if you wish to convert from
@@ -40,9 +40,11 @@ there for back compatibility reasons. Since this task will be removed in future
 versions, you are strongly encouraged to use <a href="javadoc.html">javadoc</a>
 instead.</i></p>
 
-<p>In the table below, 1.1 means available if your current Java VM is
-a 1.1 VM, 1.2 for either 1.2 or 1.3 and 1.4+ for any VM of at least version 1.4.  1.2+
-means any VM of at least version 1.2.</p>
+<p>In the table below, 1.2 means available if your current Java VM is
+a 1.2 VM (but not 1.3 or later), 1.4+ for any VM of at least version 1.4, otherwise
+any VM of at least version 1.2 is acceptable. JDK 1.1 is no longer supported.
+If you specify the <code>executable</code> attribute it is up to you
+to ensure that this command supports the attributes you wish to use.</p>
 
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
@@ -94,7 +96,7 @@ means any VM of at least version 1.2.</p>
   <tr>
     <td valign="top">packageList</td>
     <td valign="top">The name of a file containing the packages to process</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -107,7 +109,7 @@ means any VM of at least version 1.2.</p>
     <td valign="top">Bootclasspath</td>
     <td valign="top">Override location of class files loaded by the bootstrap
       class loader</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -122,19 +124,19 @@ means any VM of at least version 1.2.</p>
     <td valign="top">Override location of class files loaded by the
       bootstrap class loader by <a href="../using.html#references">reference</a> to a
       PATH defined elsewhere.</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Extdirs</td>
     <td valign="top">Override location of installed extensions</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Overview</td>
     <td valign="top">Read overview documentation from HTML file</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -177,13 +179,13 @@ means any VM of at least version 1.2.</p>
   <tr>
     <td valign="top">Verbose</td>
     <td valign="top">Output messages about what Javadoc is doing</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Locale</td>
     <td valign="top">Locale to be used, e.g. en_US or en_US_WIN</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -201,7 +203,7 @@ means any VM of at least version 1.2.</p>
   <tr>
     <td valign="top">Use</td>
     <td valign="top">Create class and package usage pages</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -213,44 +215,44 @@ means any VM of at least version 1.2.</p>
   <tr>
     <td valign="top">Splitindex</td>
     <td valign="top">Split index into one file per letter</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Windowtitle</td>
     <td valign="top">Browser window title for the documentation (text)</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Doctitle</td>
     <td valign="top">Include title for the package index(first) page (html-code)</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Header</td>
     <td valign="top">Include header text for each page (html-code)</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Footer</td>
     <td valign="top">Include footer text for each page (html-code)</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">bottom</td>
     <td valign="top">Include bottom text for each page (html-code)</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">link</td>
     <td valign="top">Create links to javadoc output at the given URL
     -- see also the nested <code>link</code> element.</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -258,7 +260,7 @@ means any VM of at least version 1.2.</p>
     <td valign="top">Link to docs at <code>&lt;url&gt;</code> using package list at
     <code>&lt;url2&gt;</code> - separate the URLs by using a space character -- see
     also the nested <code>link</code> element.</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -267,7 +269,7 @@ means any VM of at least version 1.2.</p>
     page.  The format is as described <a
     href="#groupattribute">below</a> -- see also the nested
     <code>group</code> element.</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -279,7 +281,7 @@ means any VM of at least version 1.2.</p>
   <tr>
     <td valign="top">nodeprecatedlist</td>
     <td valign="top">Do not generate deprecated list</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -297,38 +299,38 @@ means any VM of at least version 1.2.</p>
   <tr>
     <td valign="top">nohelp</td>
     <td valign="top">Do not generate help link</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">nonavbar</td>
     <td valign="top">Do not generate navigation bar</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">serialwarn</td>
     <td valign="top">Generate warning about @serial tag</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">helpfile</td>
     <td valign="top">Specifies the HTML help file to use</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">stylesheetfile</td>
     <td valign="top">Specifies the CSS stylesheet to use</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">charset</td>
     <td valign="top">Charset for cross-platform viewing of generated
       documentation</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -342,13 +344,13 @@ means any VM of at least version 1.2.</p>
     <td valign="top">Specifies the class file that starts the doclet
     used in generating the documentation -- see also the nested
     <code>doclet</code> element.</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">docletpath</td>
     <td valign="top">Specifies the path to the doclet class file that is specified with the -doclet option.</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -356,7 +358,7 @@ means any VM of at least version 1.2.</p>
     <td valign="top">Specifies the path to the doclet class file that
       is specified with the -doclet option by <a
       href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -397,7 +399,7 @@ means any VM of at least version 1.2.</p>
       the package names specified via the packagenames attribute or
       nested package elements.
       (<code>yes</code> | <code>no</code>). Default is no.</td>
-    <td align="center" valign="top">1.2+</td>
+    <td align="center" valign="top">all</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
@@ -692,6 +694,14 @@ todo:a:"To Do"</pre>
     </td>
     <td align="center" valign="top">No</td>
   </tr>
+  <tr>
+    <td valign="top">executable</td>
+    <td valign="top">Specify a particular <code>javadoc</code> executable
+      to use in place of the default binary (found in the same JDK as Ant is running in).
+      <em>since Ant 1.7</em>.</td>
+    <td align="center" valign="top">all</td>
+    <td align="center" valign="top">No</td>
+  </tr>
 </table>
 
 <h4><a name="tagletelement">taglet</a></h4>