Documentation for command line arguments (the nested elements for them).

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

docs/index.html

@@ -441,6 +441,56 @@ location attributes of its own, so</p>
     &lt;classpath path=&quot;${classpath}&quot; /&gt;
 </pre>
 
+<h3><a name="arg">Command line arguments</a></h3>
+
+<p>Several tasks take arguments that shall be passed to another
+process on the command line. To make it easier to specify arguments
+that contain space characters, nested elements can be used.</p>
+<table border="1" cellpadding="2" cellspacing="0">
+<tr>
+  <td width="12%" valign="top"><b>Attribute</b></td>
+  <td width="78%" valign="top"><b>Description</b></td>
+  <td width="10%" valign="top"><b>Required</b></td>
+</tr>
+  <tr>
+    <td valign="top">value</td> 
+    <td valign="top">a single command line argument, can contain space
+      characters.</td>
+    <td align="center" rowspan="4">Exactly one of these.</td>
+  </tr>
+  <tr>
+    <td valign="top">line</td> 
+    <td valign="top">a space delimited list of command line arguments.</td>
+  </tr>
+  <tr>
+    <td valign="top">file</td> 
+    <td valign="top">The name of a file as a single command line
+      argument. Will be replaced with the absolute filename of the file
+      by Ant.</td>
+  </tr>
+  <tr>
+    <td valign="top">path</td> 
+    <td valign="top">A string that shall be treated as a PATH like
+      string as a single command line argument. You can use ; or : as
+      path separators and Ant will convert it to the platform's local
+      conventions.</td>
+  </tr>
+</table>
+<h4>Examples</h4>
+<blockquote><pre>
+  &lt;arg value=&quot;-l -a&quot; /&gt;
+</pre></blockquote>
+<p>is a single command line argument containing a space character.</p>
+<blockquote><pre>
+  &lt;arg line=&quot;-l -a&quot; /&gt;
+</pre></blockquote>
+<p>stands for two separate command line arguments.</p>
+<blockquote><pre>
+  &lt;arg path=&quot;/dir;/dir2:\dir3&quot; /&gt;
+</pre></blockquote>
+<p>is a single command line argument with value
+<code>\dir;\dir2;\dir3</code> on DOS based systems and
+<code>/dir:/dir2:/dir3</code> on Unix like systems.</p>
 <hr>
 <h2><a name="directorybasedtasks">Directory based tasks</a></h2>
 <p>Some tasks use directory trees for the task they perform. For instance, the <a
@@ -1128,8 +1178,15 @@ systems.</p>
   </tr>
   <tr>
     <td valign="top">command</td>
-    <td valign="top">the command to execute.</td>
-    <td align="center" valign="top">Yes</td>
+    <td valign="top">the command to execute with all command line
+      arguments. <b>deprecated, use executable and nested
+      <code>&lt;arg&gt;</code> elements instead</b>.</td>
+    <td align="center" rowspan="2">Exactly one of the two.</td>
+  </tr>
+  <tr>
+    <td valign="top">executable</td>
+    <td valign="top">the command to execute without any command line
+      arguments.</b></td>
   </tr>
   <tr>
     <td valign="top">dir</td>
@@ -1148,6 +1205,12 @@ systems.</p>
       redirected.</td>
     <td align="center" valign="top">No</td>
   </tr>
+  <tr>
+    <td valign="top">timeout</td>
+    <td valign="top">Stop the command if it doesn't finish within the
+      specified time (given in milliseconds).</td>
+    <td align="center" valign="top">No</td>
+  </tr>
   <tr>
     <td valign="top">failonerror</td>
     <td valign="top">Stop the buildprocess if the command exits with a
@@ -1157,11 +1220,15 @@ systems.</p>
 </table>
 <h3>Examples</h3>
 <blockquote>
-  <p><code>&lt;exec dir=&quot;${src}&quot; command=&quot;dir&quot; os=&quot;windows&quot;
+  <p><code>&lt;exec dir=&quot;${src}&quot; executable=&quot;dir&quot; os=&quot;windows&quot;
   output=&quot;dir.txt&quot; /&gt;</code></p>
 </blockquote>
 
 <h3>Parameters specified as nested elements</h3>
+<h4>arg</h4>
+<p>Command line arguments should be specified as nested
+<code>&lt;arg&gt;</code> elements. See <a
+href="index.html#arg">Command line arguments</a>.</p>
 <h4><a name="env">env</a></h4>
 <p>It is possible to specify environment variables to pass to the
 system command via nested <code>&lt;env&gt;</code> elements.</p>
@@ -1198,7 +1265,7 @@ system command via nested <code>&lt;env&gt;</code> elements.</p>
 </table>
 <h5>Examples</h5>
 <blockquote><pre>
-&lt;exec command="emacs" &gt;
+&lt;exec executable="emacs" &gt;
   &lt;env key=&quot;DISPLAY&quot; value=&quot;:1.0&quot; /&gt;
 &lt;/exec&gt;
 </pre></blockquote>
@@ -1793,7 +1860,9 @@ the one that is currently running Ant.</p>
   </tr>
   <tr>
     <td valign="top">args</td>
-    <td valign="top">the arguments for the class that is executed.</td>
+    <td valign="top">the arguments for the class that is
+      executed. <b>deprecated, use nested <code>&lt;arg&gt;</code>
+      elements instead.</b></td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -1817,15 +1886,15 @@ the one that is currently running Ant.</p>
   </tr>
   <tr>
     <td valign="top">jvmargs</td>
-    <td valign="top">the arguments to pass to the forked VM (ignored if fork is
-      disabled)</td>
+    <td valign="top">the arguments to pass to the forked VM (ignored
+      if fork is disabled). <b>deprecated, use nested
+      <code>&lt;arg&gt;</code> elements instead.</b></td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">maxmemory</td>
     <td valign="top">Max amount of memory to allocate to the forked VM
       (ignored if fork is disabled)</td>
-    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -1836,12 +1905,18 @@ the one that is currently running Ant.</p>
   </tr>
 </table>
 <h3>Parameters specified as nested elements</h3>
+<h4>arg and jvmarg</h4>
+<p>Use nested <code>&lt;arg&gt;</code> and <code>&lt;jvmarg&gt;</code>
+elements to specify arguments for the or the forked VM. See <a
+href="index.html#arg">Command line arguments</a>.</p>
+<h4>classpath</h4>
 <p><code>Java</code>'s <em>classpath</em> attribute is a <a
 href="#path">PATH like structure</a> and can also be set via a nested
 <em>classpath</em> element.</p>
-<h4>Example</h4>
+<h5>Example</h5>
 <pre>  
-       &lt;java classname=&quot;test.Main&quot; args=&quot;-h&quot; &gt;
+       &lt;java classname=&quot;test.Main&quot; &gt;
+         &lt;arg value=&quot;-h&quot; /&gt; 
          &lt;classpath&gt;
            &lt;pathelement location=&quot;\test.jar&quot; /&gt;
            &lt;pathelement path=&quot;${java.class.path}&quot; /&gt;
@@ -1850,12 +1925,12 @@ href="#path">PATH like structure</a> and can also be set via a nested
 </pre>
 <h3>Examples</h3>
 <pre>  &lt;java classname=&quot;test.Main&quot; /&gt;</pre>
-<pre>  &lt;java classname=&quot;test.Main&quot; args=&quot;-h&quot; /&gt;</pre>
 <pre>  &lt;java classname=&quot;test.Main&quot;
-        args=&quot;-h&quot;
-        fork=&quot;yes&quot;
-        jvmargs=&quot;-Xrunhprof:cpu=samples,file=log.txt,depth=3&quot;
-  /&gt;</pre>
+        fork=&quot;yes&quot; &gt;
+    &lt;arg value=&quot;-h&quot; /&gt; 
+    &lt;jvmarg value=&quot;-Xrunhprof:cpu=samples,file=log.txt,depth=3&quot; /&gt; 
+  &lt;/java&gt;
+</pre>
 
 <hr>
 <h2><a name="javac">Javac</a></h2>

docs/junit.html

@@ -34,7 +34,7 @@ elements</a>.</p>
   </tr>
   <tr>
     <td valign="top">haltonerror</td> 
-    <td valign="top">Stop the build process if an error occures during the test
+    <td valign="top">Stop the build process if an error occurs during the test
        run.</td>
     <td align="center" valign="top">No, default is "off"</td>
   </tr>
@@ -85,32 +85,8 @@ VM via nested <code>&lt;jvmarg&gt;</code> attributes, for example:</p>
 </blockquote></pre>
 would run the test in a VM without JIT.</p>
 
-<table border="1" cellpadding="2" cellspacing="0">
-<tr>
-  <td width="12%" valign="top"><b>Attribute</b></td>
-  <td width="78%" valign="top"><b>Description</b></td>
-  <td width="10%" valign="top"><b>Required</b></td>
-</tr>
-  <tr>
-    <td valign="top">value</td> 
-    <td valign="top">a single command line argument.</td>
-    <td align="center" rowspan="4">Exactly one of these.</td>
-  </tr>
-  <tr>
-    <td valign="top">file</td> 
-    <td valign="top">The name of a file as a single command line argument.</td>
-  </tr>
-  <tr>
-    <td valign="top">path</td> 
-    <td valign="top">A string that shall be treated as a PATH
-      (i.e. the PATH separator will be set according to the plattform's
-      convention) as a single command line argument.</td>
-  </tr>
-  <tr>
-    <td valign="top">line</td> 
-    <td valign="top">a space delimited list of command line arguments.</td>
-  </tr>
-</table>
+<p><code>&lt;jvmarg&gt;</code> allows all attributes described in <a
+href="index.html#arg">Command line arguments</a>.</p>
 
 <h4>formatter</h4>
 
@@ -138,7 +114,7 @@ can be specified.</p>
   </tr>
   <tr>
     <td valign="top">classname</td> 
-    <td valign="top">Name of a custo formatter class.</td>
+    <td valign="top">Name of a custom formatter class.</td>
   </tr>
   <tr>
     <td valign="top">extension</td> 
@@ -170,7 +146,7 @@ can be specified.</p>
   </tr>
   <tr>
     <td valign="top">haltonerror</td> 
-    <td valign="top">Stop the build process if an error occures during the test
+    <td valign="top">Stop the build process if an error occurs during the test
        run. Overrides value set in <code>&lt;junit&gt;</code>.</td>
     <td align="center" valign="top">No</td>
   </tr>
@@ -183,7 +159,7 @@ can be specified.</p>
   </tr>
   <tr>
     <td valign="top">outfile</td> 
-    <td valign="top">Basename of the test result. The full filename is
+    <td valign="top">Base name of the test result. The full filename is
       determined by this attribute and the extension of
       <code>formatter</code>.</td>
     <td align="center" valign="top">No, default is
@@ -228,7 +204,7 @@ class name for each file that ends in <code>.java</code> or
   </tr>
   <tr>
     <td valign="top">haltonerror</td> 
-    <td valign="top">Stop the build process if an error occures during the test
+    <td valign="top">Stop the build process if an error occurs during the test
        run. Overrides value set in <code>&lt;junit&gt;</code>.</td>
     <td align="center" valign="top">No</td>
   </tr>
@@ -301,7 +277,7 @@ stopped if the test fails.</p>
 
 <p>Runs <code>my.test.TestCase</code> in the same VM (ignoring the
 given CLASSPATH), only a warning is printed if this test fails. In
-addition to the plain text testresults, for this test a XML result
+addition to the plain text test results, for this test a XML result
 will be output to <code>result.xml</code>.</p>
 
 <p>For each matching file in the directory <code>${src.tests}</code> a

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

@@ -111,6 +111,9 @@ public class ExecTask extends Task {
      * The full commandline to execute, executable + arguments.
      */
     public void setCommand(Commandline cmdl) {
+        log("The command attribute is deprecated. " +
+            "Please use the executable attribute and nested arg elements.",
+            Project.MSG_WARN);
         this.cmdl = cmdl;
     }
 

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

@@ -166,6 +166,9 @@ public class Java extends Task {
      * Set the command line arguments for the class.
      */
     public void setArgs(String s) {
+        log("The args attribute is deprecated. " +
+            "Please use nested arg elements.",
+            Project.MSG_WARN);
         cmdl.createArgument().setLine(s);
     }
 
@@ -187,6 +190,9 @@ public class Java extends Task {
      * Set the command line arguments for the JVM.
      */
     public void setJvmargs(String s) {
+        log("The args attribute is deprecated. " +
+            "Please use nested arg elements.",
+            Project.MSG_WARN);
         cmdl.createVmArgument().setLine(s);
     }