You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by gi...@apache.org on 2018/02/28 07:01:52 UTC
[37/47] ant git commit: Use HTML 5(-ish), fix links
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/Tasks/image.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/image.html b/manual/Tasks/image.html
index e3153e2..6d8d4f0 100644
--- a/manual/Tasks/image.html
+++ b/manual/Tasks/image.html
@@ -33,174 +33,166 @@
<img src="image-classdiagram.gif" border="0" alt="Class-Diagram">
<h3>Parameters</h3>
-<table>
+<table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr>
- <td valign="top">failonerror</td>
- <td valign="top">Boolean value. If false, note errors to the output but keep going.</td>
- <td align="center">no (defaults to <i>true</i>)</td>
+ <td>failonerror</td>
+ <td>Boolean value. If <q>false</q>, note errors to the output but keep going.</td>
+ <td>No; defaults to <q>true</q></td>
</tr>
<tr>
- <td valign="top">srcdir</td>
- <td valign="top">Directory containing the images.</td>
- <td align="center">yes, unless nested fileset is used</td>
+ <td>srcdir</td>
+ <td>Directory containing the images.</td>
+ <td>Yes, unless nested fileset is used</td>
</tr>
<tr>
- <td valign="top">encoding</td>
- <td valign="top">Image encoding type.<br>
- Valid (caseinsensitive) are: jpg, jpeg, tif, tiff
+ <td>encoding</td>
+ <td>Image encoding type.<br/>Valid (case insensitive)
+ are: <q>jpg</q>, <q>jpeg</q>, <q>tif</q>, <q>tiff</q>
</td>
- <td align="center">no (defaults to <i>JPEG</i>)</td>
+ <td>No; defaults to <q>jpeg</q></td>
</tr>
<tr>
- <td valign="top">overwrite</td>
- <td valign="top">Boolean value. Sets whether or not to overwrite
- a file if there is naming conflict.
- </td>
- <td align="center">no (defaults to <i>false</i>)</td>
+ <td>overwrite</td>
+ <td>Boolean value. Sets whether or not to overwrite a file if there is naming conflict.</td>
+ <td>No; defaults to <q>false</q></td>
</tr>
<tr>
- <td valign="top">gc</td>
- <td valign="top">Boolean value. Enables garbage collection after
- each image processed.
- </td>
- <td align="center">no (defaults to <i>false</i>)</td>
+ <td>gc</td>
+ <td>Boolean value. Enables garbage collection after each image processed.</td>
+ <td>No; defaults to <q>false</q></td>
</tr>
<tr>
- <td valign="top">destdir</td>
- <td valign="top">Directory where the result images are stored.</td>
- <td align="center">no (defaults to value of <i>srcdir</i>)</td>
+ <td>destdir</td>
+ <td>Directory where the result images are stored.</td>
+ <td>No; defaults to value of <var>srcdir</var></td>
</tr>
<!-- attributes inherited from MatchingTask -->
<tr>
- <td valign="top">includes</td>
- <td valign="top">comma- or space-separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
+ <td>includes</td>
+ <td>comma- or space-separated list of patterns of files that must be included.</td>
+ <td>No; defaults to all (<q>**</q>)</td>
</tr>
<tr>
- <td valign="top">includesfile</td>
- <td valign="top">the name of a file. Each line of this file is
- taken to be an include pattern</td>
- <td valign="top" align="center">No</td>
+ <td>includesfile</td>
+ <td>name of a file. Each line of this file is taken to be an include pattern</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">excludes</td>
- <td valign="top">comma- or space-separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when omitted.</td>
- <td valign="top" align="center">No</td>
+ <td>excludes</td>
+ <td>comma- or space-separated list of patterns of files that must be excluded.</td>
+ <td>No; defaults to default excludes or none if <var>defaultexcludes</var> is <q>no</q></td>
</tr>
<tr>
- <td valign="top">excludesfile</td>
- <td valign="top">the name of a file. Each line of this file is
- taken to be an exclude pattern</td>
- <td valign="top" align="center">No</td>
+ <td>excludesfile</td>
+ <td>name of a file. Each line of this file is taken to be an exclude pattern</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when omitted.</td>
- <td valign="top" align="center">No</td>
+ <td>defaultexcludes</td>
+ <td>indicates whether default excludes should be used or not (<q>yes|no</q>).</td>
+ <td>No; defaults to <q>yes</q></td>
</tr>
<tr>
- <td valign="top">caseSensitive</td>
- <td valign="top">Boolean value. Sets case sensitivity of the file system.</td>
- <td align="center">no (defaults to <i>false</i>)</td>
+ <td>caseSensitive</td>
+ <td>Boolean value. Sets case sensitivity of the file system.</td>
+ <td>No; defaults to <q>false</q></td>
</tr>
<tr>
- <td valign="top">followSymlinks</td>
- <td valign="top">Boolean value. Sets whether or not symbolic links should be followed.</td>
- <td align="center">no (defaults to <i>true</i>)</td>
+ <td>followSymlinks</td>
+ <td>Boolean value. Sets whether or not symbolic links should be followed.</td>
+ <td>No; defaults to <q>true</q></td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
-<p>This task forms an implicit <a href="../Types/fileset.html">FileSet</a> and
-supports most attributes of <code><fileset></code> as well as the
-nested <code><include></code>, <code><exclude></code> and
-<code><patternset></code> elements.</p>
-
+<p>This task forms an implicit <a href="../Types/fileset.html">FileSet</a> and supports most
+attributes of <code><fileset></code> as well as the
+nested <code><include></code>, <code><exclude></code>
+and <code><patternset></code> elements.</p>
<h4>ImageOperation</h4>
<p>Adds an ImageOperation to chain.</p>
<h5>Nested Elements</h5>
-ImageOperation can handle nested Rotate, Draw, Rectangle, Text and Scale objects.
+<p>ImageOperation can handle
+nested <code>Rotate</code>, <code>Draw</code>, <code>Rectangle</code>, <code>Text</code>
+and <code>Scale</code> objects.</p>
<h4>Rotate</h4>
<p>Adds a Rotate ImageOperation to chain.</p>
<h5>Parameters</h5>
-<table>
+<table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr>
- <td valign="top">angle</td>
- <td valign="top">Float value. Sets the angle of rotation in degrees.</td>
- <td align="center">no (defaults to <i>0.0F</i>)</td>
+ <td>angle</td>
+ <td>Float value. Sets the angle of rotation in degrees.</td>
+ <td>No; defaults to <q>0.0F</q></td>
</tr>
</table>
<h4>Scale</h4>
<p>Adds a Scale ImageOperation to chain.</p>
<h5>Parameters</h5>
-<table>
+<table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr>
- <td valign="top">proportions</td>
- <td valign="top">Sets which dimension to control proportions from. Valid values are:
+ <td>proportions</td>
+ <td>Sets which dimension to control proportions from. Valid values are:
<ul>
- <li>"ignore" - treat the dimensions independently.</li>
- <li>"height" - keep proportions based on the width.</li>
- <li>"width" - keep proportions based on the height.</li>
- <li>"cover" - keep proportions and fit in the supplied dimensions.</li>
- <li>"fit" - keep proportions and cover the supplied dimensions.</li>
+ <li><q>ignore</q>— treat the dimensions independently.</li>
+ <li><q>height</q>—keep proportions based on the width.</li>
+ <li><q>width</q>—keep proportions based on the height.</li>
+ <li><q>cover</q>—keep proportions and fit in the supplied dimensions.</li>
+ <li><q>fit</q>—keep proportions and cover the supplied dimensions.</li>
</ul>
</td>
- <td align="center">no (defaults to <i>ignore</i>)</td>
+ <td>No; defaults to <q>ignore</q></td>
</tr>
<tr>
- <td valign="top">width</td>
- <td valign="top">Sets the width of the image, either as an integer or a %.</td>
+ <td>width</td>
+ <td>Sets the width of the image, either as an integer or a %.</td>
<!-- todo: if integer, what kind? cm, px, inches, ... -->
- <td align="center">no (defaults to <i>100%</i>)</td>
+ <td>No; defaults to <q>100%</q></td>
</tr>
<tr>
- <td valign="top">height</td>
- <td valign="top">Sets the height of the image, either as an integer or a %.</td>
+ <td>height</td>
+ <td>Sets the height of the image, either as an integer or a %.</td>
<!-- todo: if integer, what kind? cm, px, inches, ... -->
- <td align="center">no (defaults to <i>100%</i>)</td>
+ <td>No; defaults to <q>100%</q></td>
</tr>
</table>
<h4>Draw</h4>
-<p>Adds a Draw ImageOperation to chain. DrawOperation DataType objects can be
-nested inside the Draw object.</p>
+<p>Adds a Draw ImageOperation to chain. DrawOperation DataType objects can be nested inside the Draw
+object.</p>
<h5>Parameters</h5>
-<table>
+<table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr>
- <td valign="top">xloc</td>
- <td valign="top">X-Position where to draw nested image elements.</td>
- <td align="center">no (defaults to <i>0</i>)</td>
+ <td>xloc</td>
+ <td>X-Position where to draw nested image elements.</td>
+ <td>No; defaults to <q>0</q></td>
</tr>
<tr>
- <td valign="top">yloc</td>
- <td valign="top">Y-Position where to draw nested image elements.</td>
- <td align="center">no (defaults to <i>0</i>)</td>
+ <td>yloc</td>
+ <td>Y-Position where to draw nested image elements.</td>
+ <td>No; defaults to <q>0</q></td>
</tr>
</table>
@@ -208,51 +200,44 @@ nested inside the Draw object.</p>
<p><em>Since Apache Ant 1.8.0</em></p>
<p>You can define filename transformations by using a
- nested <a href="../Types/mapper.html">mapper</a> element. The
- default mapper used by
- <code><image></code> is
- the <a href="../Types/mapper.html#identity-mapper">identity
- mapper</a>.</p>
+nested <a href="../Types/mapper.html">mapper</a> element. The default mapper used
+by <code><image></code> is the <a href="../Types/mapper.html#identity-mapper">identity
+mapper</a>.</p>
-<p>You can also use a filenamemapper type in place of the mapper
- element.</p>
+<p>You can also use a <code>filenamemapper</code> type in place of the <code>mapper</code>
+element.</p>
<h3>Examples</h3>
<pre>
- <image destdir="samples/low" overwrite="yes">
- <fileset dir="samples/full">
- <include name="**/*.jpg"/>
- </fileset>
- <scale width="160" height="160" proportions="fit"/>
- </image>
-</pre>
+<image destdir="samples/low" overwrite="yes">
+ <fileset dir="samples/full">
+ <include name="**/*.jpg"/>
+ </fileset>
+ <scale width="160" height="160" proportions="fit"/>
+</image></pre>
<p>Create thumbnails of my images and make sure they all fit within the 160x160 size whether the
image is portrait or landscape.</p>
<pre>
<image srcdir="src" includes="*.png">
<scale proportions="width" width="40"/>
-</image>
-</pre>
-<p>Creates a thumbnail for all PNG-files in <i>src</i> in the size of 40 pixel keeping the proportions
-and stores the <i>src</i>.</p>
+</image></pre>
+<p>Creates a thumbnail for all PNG files in <samp>src</samp> of the size of 40 pixel keeping the
+proportions and stores the <samp>src</samp>.</p>
<pre>
<image srcdir="src" destdir="dest" includes="*.png">
<scale proportions="width" width="40"/>
-</image>
-</pre>
-<p>Same as above but stores the result in <i>dest</i>.</p>
+</image></pre>
+<p>Same as above but stores the result in <samp>dest</samp>.</p>
<pre>
<image srcdir="src" destdir="dest" includes="*.png">
<scale proportions="width" width="40"/>
<globmapper from="*" to="scaled-*"/>
-</image>
-</pre>
-<p>Same as above but stores the resulting file names will be prefixed
- by "scaled-".</p>
+</image></pre>
+<p>Same as above but stores the resulting file names will be prefixed by <samp>scaled-</samp>.</p>
</body>
</html>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/Tasks/import.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/import.html b/manual/Tasks/import.html
index d588a31..b446315 100644
--- a/manual/Tasks/import.html
+++ b/manual/Tasks/import.html
@@ -23,100 +23,81 @@
<body>
<h2 id="import">Import</h2>
<h3>Description</h3>
- <p>
- Imports another build file into the current project.
- </p>
-
- <p>
- On execution it will select the proper ProjectHelper to parse the imported
- file, using the same algorithm as the one executed at
- <a href="../projecthelper.html">startup</a>. The selected ProjectHelper
- instance will then be responsible to actually parse the imported file.
- </p>
-
- <p>
- <strong>Note</strong> as seen above, this task heavily relies on the ProjectHelper
- implementation and doesn't really perform any work of its own. If
- you have configured Apache Ant to use a ProjectHelper other than Ant's
- default, this task may or may not work.
- </p>
-
- <p>
- In the common use case where only Ant's default project helper is
- used, it basically works like the
- <a href="http://ant.apache.org/faq.html#xml-entity-include">Entity
- Includes as explained in the Ant FAQ</a>, as if the imported file was
- contained in the importing file, minus the top <code><project></code>
- tag.
- </p>
-
- <p>
- The import task may only be used as a top-level task. This means that
- it may not be used in a target.
- </p>
- <p>
-There are two further functional aspects that pertain to this task and
-that are not possible with entity includes:</p>
-<ul>
- <li>target overriding</li>
- <li>special properties</li>
-</ul>
-<h4>Target overriding</h4>
-
-<p>If a target in the main file is also present in at least one of the
-imported files, the one from the main file takes precedence.</p>
-
-<p>So if I import for example a <i>docsbuild.xml</i> file named <b>builddocs</b>,
-that contains a "<b>docs</b>" target, I can redefine it in my main
-buildfile and that is the one that will be called. This makes it easy to
-keep the same target name, so that the overriding target is still called
-by any other targets--in either the main or imported buildfile(s)--for which
-it is a dependency, with a different implementation. The target from <i>docsbuild.xml</i> is
-made available by the name "<b>builddocs</b><b>.docs</b>".
-This enables the new implementation to call the old target, thus
-<i>enhancing</i> it with tasks called before or after it.</p>
-
-<p>If you use the <i>as</i> attribute of the task, its value will be
- used to prefix the overridden target's name instead of the name
- attribute of the project tag.</p>
-
-<h4>Special Properties</h4>
-
-<p>Imported files are treated as they are present in the main
-buildfile. This makes it easy to understand, but it makes it impossible
-for them to reference files and resources relative to their path.
-Because of this, for every imported file, Ant adds a property that
-contains the path to the imported buildfile. With this path, the
-imported buildfile can keep resources and be able to reference them
-relative to its position.</p>
-
-<p>So if I import for example a <i>docsbuild.xml</i> file named <b>builddocs</b>,
-I can get its path as <b>ant.file.builddocs</b>, similarly to the <b>ant.file</b>
-property of the main buildfile.</p>
-
-<p>Note that "builddocs" is not the filename, but the name attribute
-present in the imported project tag.</p>
- <p>
- If the imported file does not have a name attribute, the ant.file.projectname
- property will not be set.
- </p>
-
-<p>Since Ant 1.8.0 the task can also import resources from URLs or
- classpath resources (which are URLs, really). If you need to know
- whether the current build file's source has been a file or an URL
- you can consult the
- property <b>ant.file.type.<em>projectname</em></b> (using the same
- example as above <b>ant.file.type.builddocs</b>) which either have
- the value "file" or "url".</p>
-
-<h4>Resolving files against the imported file</h4>
-
-<p>Suppose your main build file called <code>importing.xml</code>
-imports a build file <code>imported.xml</code>, located anywhere on
-the file system, and <code>imported.xml</code> reads a set of
-properties from <code>imported.properties</code>:</p>
-
-<pre><!-- importing.xml -->
+ <p>Imports another build file into the current project.</p>
+
+ <p>On execution it will select the proper ProjectHelper to parse the imported file, using the same
+ algorithm as the one executed at <a href="../projecthelper.html">startup</a>. The selected
+ ProjectHelper instance will then be responsible to actually parse the imported file.</p>
+
+ <p><strong>Note</strong> as seen above, this task heavily relies on the ProjectHelper
+ implementation and doesn't really perform any work of its own. If you have configured Apache
+ Ant to use a ProjectHelper other than Ant's default, this task may or may not work.</p>
+
+ <p>In the common use case where only Ant's default project helper is used, it basically works like
+ the <a href="https://ant.apache.org/faq.html#xml-entity-include">Entity Includes as explained in
+ the Ant FAQ</a>, as if the imported file was contained in the importing file, minus the
+ top <code><project></code> tag.</p>
+
+ <p>The <code>import</code> task may only be used as a top-level task. This means that it may not
+ be used in a target.</p>
+
+ <p>There are two further functional aspects that pertain to this task and that are not possible
+ with entity includes:</p>
+ <ul>
+ <li>target overriding</li>
+ <li>special properties</li>
+ </ul>
+ <h4>Target overriding</h4>
+
+ <p>If a target in the main file is also present in at least one of the imported files, the one
+ from the main file takes precedence.</p>
+
+ <p>So if I import for example a <samp>docsbuild.xml</samp> file named <q>builddocs</q>, that
+ contains a <q>docs</q> target, I can redefine it in my main buildfile and that is the one that
+ will be called. This makes it easy to keep the same target name, so that the overriding target
+ is still called by any other targets—in either the main or imported buildfile(s)—for
+ which it is a dependency, with a different implementation. The target
+ from <samp>docsbuild.xml</samp> is made available by the name <q>builddocs.docs</q>. This
+ enables the new implementation to call the old target, thus <em>enhancing</em> it with tasks
+ called before or after it.</p>
+
+ <p>If you use the <var>as</var> attribute of the task, its value will be used to prefix the
+ overridden target's name instead of the <var>name</var> attribute of the <code>project</code>
+ tag.</p>
+
+ <h4>Special Properties</h4>
+
+ <p>Imported files are treated as they are present in the main buildfile. This makes it easy to
+ understand, but it makes it impossible for them to reference files and resources relative to
+ their path. Because of this, for every imported file, Ant adds a property that contains the
+ path to the imported buildfile. With this path, the imported buildfile can keep resources and be
+ able to reference them relative to its position.</p>
+
+ <p>So if I import for example a <samp>docsbuild.xml</samp> file named <q>builddocs</q>, I can get
+ its path as <code>ant.file.builddocs</code>, similarly to the <code>ant.file</code> property of
+ the main buildfile.</p>
+
+ <p>Note that <q>builddocs</q> is not the filename, but the <var>name</var> attribute present in
+ the imported <code>project</code> tag.</p>
+
+ <p>If the imported file does not have a <var>name</var> attribute,
+ the <code>ant.file.<i>projectname</i></code> property will not be set.</p>
+
+ <p><em>Since Ant 1.8.0</em>, the task can also import resources from URLs or classpath resources
+ (which are URLs, really). If you need to know whether the current build file's source has been
+ a file or an URL you can consult the property <code>ant.file.type.<i>projectname</i></code>
+ (using the same example as above <code>ant.file.type.builddocs</code>) which either have the
+ value <q>file</q> or <q>url</q>.</p>
+
+ <h4>Resolving files against the imported file</h4>
+
+ <p>Suppose your main build file called <samp>importing.xml</samp> imports a build
+ file <samp>imported.xml</samp>, located anywhere on the file system,
+ and <samp>imported.xml</samp> reads a set of properties
+ from <samp>imported.properties</samp>:</p>
+
+ <pre>
+<!-- importing.xml -->
<project name="importing" basedir="." default="...">
<import file="${path_to_imported}/imported.xml"/>
</project>
@@ -124,156 +105,121 @@ properties from <code>imported.properties</code>:</p>
<!-- imported.xml -->
<project name="imported" basedir="." default="...">
<property file="imported.properties"/>
-</project>
-</pre>
+</project></pre>
-<p>This snippet however will resolve <code>imported.properties</code>
-against the basedir of <code>importing.xml</code>, because the basedir
-of <code>imported.xml</code> is ignored by Ant. The right way to use
-<code>imported.properties</code> is:</p>
+ <p>This snippet however will resolve <samp>imported.properties</samp> against
+ the <var>basedir</var> of <samp>importing.xml</samp>, because the <var>basedir</var>
+ of <samp>imported.xml</samp> is ignored by Ant. The right way to
+ use <samp>imported.properties</samp> is:</p>
-<pre>
+ <pre>
<!-- imported.xml -->
<project name="imported" basedir="." default="...">
<dirname property="imported.basedir" file="${ant.file.imported}"/>
<property file="${imported.basedir}/imported.properties"/>
-</project>
-</pre>
+</project></pre>
-<p>As explained above <code>${ant.file.imported}</code> stores the
-path of the build script, that defines the project called
-<code>imported</code>, (in short it stores the path to
-<code>imported.xml</code>) and <a
-href="dirname.html"><code><dirname></code></a> takes its
-directory. This technique also allows <code>imported.xml</code> to be
-used as a standalone file (without being imported in other
-project).</p>
-
-<p>The above description only works for imported files that actually
- are imported from files and not from URLs. For files imported from
- URLs using resources relative to the imported file requires you to
- use tasks that can work on non-file resources in the first place.
- To create a relative resource you'd use something like:</p>
+ <p>As explained above <code>ant.file.imported</code> stores the path of the build script, that
+ defines the project called <q>imported</q>, (in short it stores the path
+ to <samp>imported.xml</samp>) and <a href="dirname.html"><code><dirname></code></a> takes
+ its directory. This technique also allows <samp>imported.xml</samp> to be used as a standalone
+ file (without being imported in other project).</p>
-<pre>
- <loadproperties>
- <url baseUrl="${ant.file.imported}"
- relativePath="imported.properties"/>
- </loadproperties>
-</pre>
+ <p>The above description only works for imported files that actually are imported from files and
+ not from URLs. For files imported from URLs using resources relative to the imported file
+ requires you to use tasks that can work on non-file resources in the first place. To create a
+ relative resource you'd use something like:</p>
+
+ <pre>
+<loadproperties>
+ <url baseUrl="${ant.file.imported}"
+ relativePath="imported.properties"/>
+</loadproperties></pre>
<h3>Parameters</h3>
-<table>
+<table class="attr">
<tbody>
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr>
- <td valign="top">
- file
- </td>
- <td valign="top">
- The file to import. If this is a relative file name, the file name will be resolved
- relative to the <i>importing</i> file. <strong>Note</strong>: this is unlike most other
- Ant file attributes, where relative files are resolved relative to ${basedir}.
- </td>
- <td valign="top" align="center">Yes or a nested resource collection</td>
+ <td>file</td>
+ <td>The file to import. If this is a relative file name, the file name will be resolved
+ relative to the <em>importing</em> file. <strong>Note</strong>: this is unlike most other
+ Ant file attributes, where relative files are resolved relative to <var>basedir</var>.</td>
+ <td>Yes or a nested resource collection</td>
</tr>
<tr>
- <td valign="top">
- optional
- </td>
- <td valign="top">
- If true, do not stop the build if the file does not exist,
- default is false.
- </td>
- <td valign="top" align="center">No</td>
+ <td>optional</td>
+ <td>If <q>true</q>, do not stop the build if the file does not exist.</td>
+ <td>No; default is <q>false</q></td>
</tr>
<tr>
- <td valign="top">
- as
- </td>
- <td valign="top">
- Specifies the prefix prepended to the target names. If
- omitted, the name attribute of the project tag of the
- imported file will be used.
- </td>
- <td valign="top" align="center">No</td>
+ <td>as</td>
+ <td>Specifies the prefix prepended to the target names.</td>
+ <td>No; defaults to <var>name</var> attribute of the <code>project</code> tag of the imported
+ file</td>
</tr>
<tr>
- <td valign="top">
- prefixSeparator
- </td>
- <td valign="top">
- Specifies the separator to be used between the prefix and the
- target name. Defaults to ".".
- </td>
- <td valign="top" align="center">No</td>
+ <td>prefixSeparator</td>
+ <td>Specifies the separator to be used between the prefix and the target name.</td>
+ <td>No; defaults to <q>.</q></td>
</tr>
</tbody>
</table>
<h3>Parameters specified as nested elements</h3>
-<h4>any <a href="../Types/resources.html">resource</a> or resource
-collection</h4>
+<h4>any <a href="../Types/resources.html">resource</a> or resource collection</h4>
-<p>The specified resources will be imported. <em>Since Ant
- 1.8.0</em></p>
+<p>The specified resources will be imported. <em>Since Ant 1.8.0</em></p>
<h3>Examples</h3>
-<pre> <import file="../common-targets.xml"/></pre>
+<pre><import file="../common-targets.xml"/></pre>
-<p>Imports targets from the common-targets.xml file that is in a parent
-directory.</p>
+<p>Imports targets from the <samp>common-targets.xml</samp> file that is in a parent directory.</p>
-<pre> <import file="${deploy-platform}.xml"/></pre>
+<pre><import file="${deploy-platform}.xml"/></pre>
-<p>Imports the project defined by the property deploy-platform</p>
+<p>Imports the project defined by the property <code>deploy-platform</code></p>
<pre>
- <import>
- <javaresource name="common/targets.xml">
- <classpath location="common.jar"/>
- </javaresource>
- </import>
-</pre>
+<import>
+ <javaresource name="common/targets.xml">
+ <classpath location="common.jar"/>
+ </javaresource>
+</import></pre>
-<p>Imports targets from the targets.xml file that is inside the
- directory common inside the jar file common.jar.</p>
+<p>Imports targets from the <samp>targets.xml</samp> file that is inside the
+directory <samp>common</samp> inside the jar file <samp>common.jar</samp>.</p>
-<h3>How is <import> different
- from <a href="include.html"><include></a>?</h3>
+<h3>How is <import> different from <a href="include.html"><include></a>?</h3>
-<p>The short version: Use import if you intend to override a target,
- otherwise use include.</p>
+<p>The short version: Use <code>import</code> if you intend to override a target, otherwise
+use <code>include</code>.</p>
-<p>When using import the imported targets are available by up to two
- names. Their "normal" name without any prefix and potentially with
- a prefixed name (the value of the as attribute or the imported
- project's name attribute, if any).</p>
+<p>When using <code>import</code> the imported targets are available by up to two names. Their
+"normal" name without any prefix and potentially with a prefixed name (the value of
+the <var>as</var> attribute or the imported project's <var>name</var> attribute, if any).</p>
-<p>When using include the included targets are only available in the
- prefixed form.</p>
+<p>When using <code>include</code> the included targets are only available in the prefixed form.</p>
-<p>When using import, the imported target's depends attribute
- remains unchanged, i.e. it uses "normal" names and allows you to
- override targets in the dependency list.</p>
+<p>When using <code>import</code>, the imported target's <var>depends</var> attribute remains
+unchanged, i.e. it uses "normal" names and allows you to override targets in the dependency
+list.</p>
-<p>When using include, the included targets cannot be overridden and
- their depends attributes are rewritten so that prefixed names are
- used. This allows writers of the included file to control which
- target is invoked as part of the dependencies.</p>
+<p>When using <code>include</code>, the included targets cannot be overridden and
+their <var>depends</var> attributes are rewritten so that prefixed names are used. This allows
+writers of the included file to control which target is invoked as part of the dependencies.</p>
-<p>It is possible to include the same file more than once by using
- different prefixes, it is not possible to import the same file more
- than once.</p>
+<p>It is possible to <code>include</code> the same file more than once by using different prefixes,
+it is not possible to <code>import</code> the same file more than once.</p>
<h4>Examples</h4>
-<p><i>nested.xml</i> shall be:</p>
+<p><samp>nested.xml</samp> shall be:</p>
<pre>
<project>
@@ -284,10 +230,9 @@ directory.</p>
<target name="echo" depends="setUp">
<echo>prop has the value ${prop}</echo>
</target>
-</project>
-</pre>
+</project></pre>
-<p>When using import like in</p>
+<p>When using <code>import</code> like in</p>
<pre>
<project default="test">
@@ -298,10 +243,9 @@ directory.</p>
<import file="nested.xml" as="nested"/>
<target name="test" depends="nested.echo"/>
-</project>
-</pre>
+</project></pre>
-<p>Running the build file will emit:
+<p>Running the build file will emit:</p>
<pre>
setUp:
@@ -313,7 +257,7 @@ test:
</pre>
-<p>When using include like in</p>
+<p>When using <code>include</code> like in</p>
<pre>
<project default="test">
@@ -324,10 +268,9 @@ test:
<include file="nested.xml" as="nested"/>
<target name="test" depends="nested.echo"/>
-</project>
-</pre>
+</project></pre>
-<p>Running the target build file will emit:
+<p>Running the target build file will emit:</p>
<pre>
nested.setUp:
@@ -339,7 +282,7 @@ test:
</pre>
-<p>and there won't be any target named "echo" on the including build file.</p>
+<p>and there won't be any target named <q>echo</q> on the including build file.</p>
</body>
</html>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/Tasks/include.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/include.html b/manual/Tasks/include.html
index 1c9ab32..46c7135 100644
--- a/manual/Tasks/include.html
+++ b/manual/Tasks/include.html
@@ -23,95 +23,75 @@
<body>
<h2 id="include">Include</h2>
<h3>Description</h3>
- <p>
- Include another build file into the current project.
- </p>
+ <p>Include another build file into the current project.</p>
<p><em>since Apache Ant 1.8.0</em></p>
- <p>
- <strong>Note</strong> this task heavily relies on the ProjectHelper
- implementation and doesn't really perform any work of its own. If
- you have configured Ant to use a ProjectHelper other than Ant's
- default, this task may or may not work.
- </p>
-
- <p>
- On execution it will read another Ant file into the same Project
- rewriting the included target names and depends lists. This is
- different
- from <a href="http://ant.apache.org/faq.html#xml-entity-include">Entity
- Includes as explained in the Ant FAQ</a> insofar as the target
- names get prefixed by the included project's name or the as
- attribute and do not appear as if the file was contained in the
- including file.
- </p>
- <p>
- The include task may only be used as a top-level task. This means that
- it may not be used in a target.
- </p>
- <p>
-There are two further functional aspects that pertain to this task and
-that are not possible with entity includes:</p>
-<ul>
- <li>target rewriting</li>
- <li>special properties</li>
-</ul>
-<h4>Target rewriting</h4>
-
-<p>Any target in the included file will be renamed
- to <i>prefix.name</i> where <i>name</i> is the original target's
- name and <i>prefix</i> is either the value of the <i>as</i>
- attribute or the <i>name</i> attribute of the <i>project</i> tag of
- the included file.</p>
-
-<p>The depends attribute of all included targets is rewritten so that
- all target names are prefixed as well. This makes the included file
- self-contained.</p>
-
-<p>Note that prefixes nest, so if a build file includes a file with
- prefix "a" and the included file includes another file with prefix
- "b", then the targets of that last build file will be prefixed by
- "a.b.".</p>
-
-<p><code><import></code> contribute to the prefix as well, but
- only if their <code>as</code> attribute has been specified.
-
-<h4>Special Properties</h4>
-
-<p>Included files are treated as they are present in the main
-buildfile. This makes it easy to understand, but it makes it impossible
-for them to reference files and resources relative to their path.
-Because of this, for every included file, Ant adds a property that
-contains the path to the included buildfile. With this path, the
-included buildfile can keep resources and be able to reference them
-relative to its position.</p>
-
-<p>So if I include for example a <i>docsbuild.xml</i> file named <b>builddocs</b>,
-I can get its path as <b>ant.file.builddocs</b>, similarly to the <b>ant.file</b>
-property of the main buildfile.</p>
-
-<p>Note that "builddocs" is not the filename, but the name attribute
-present in the included project tag.</p>
- <p>
- If the included file does not have a name attribute, the ant.file.projectname
- property will not be set.
- </p>
-
-<p>If you need to know whether the current build file's source has
- been a file or an URL you can consult the
- property <b>ant.file.type.<em>projectname</em></b> (using the same
- example as above <b>ant.file.type.builddocs</b>) which either have
- the value "file" or "url".</p>
-
-<h4>Resolving files against the included file</h4>
-
-<p>Suppose your main build file called <code>including.xml</code>
-includes a build file <code>included.xml</code>, located anywhere on
-the file system, and <code>included.xml</code> reads a set of
-properties from <code>included.properties</code>:</p>
-
-<pre><!-- including.xml -->
+ <p><strong>Note</strong> this task heavily relies on the ProjectHelper implementation and doesn't
+ really perform any work of its own. If you have configured Ant to use a ProjectHelper other
+ than Ant's default, this task may or may not work.</p>
+
+ <p>On execution it will read another Ant file into the same project rewriting the included
+ target <var>name</var>s and <var>depends</var> lists. This is different
+ from <a href="https://ant.apache.org/faq.html#xml-entity-include">Entity Includes as explained
+ in the Ant FAQ</a> insofar as the target names get prefixed by the included
+ project's <var>name</var> or <var>as</var> attribute and do not appear as if the file was
+ contained in the including file.</p>
+ <p>The <code>include</code> task may only be used as a top-level task. This means that
+ it may not be used in a target.</p>
+ <p>There are two further functional aspects that pertain to this task and that are not possible
+ with entity includes:</p>
+ <ul>
+ <li>target rewriting</li>
+ <li>special properties</li>
+ </ul>
+ <h4>Target rewriting</h4>
+
+ <p>Any target in the included file will be renamed to <q>prefix.name</q> where <q>name</q> is the
+ original target's name and <q>prefix</q> is either the value of the <var>as</var> attribute or
+ the <var>name</var> attribute of the <code>project</code> tag of the included file.</p>
+
+ <p>The <var>depends</var> attribute of all included targets is rewritten so that all target names
+ are prefixed as well. This makes the included file self-contained.</p>
+
+ <p>Note that prefixes nest, so if a build file includes a file with prefix <q>q</q> and the
+ included file includes another file with prefix <q>b</q>, then the targets of that last build
+ file will be prefixed by <q>a.b.</q>.</p>
+
+ <p><code><import></code> contribute to the prefix as well, but only if their <var>as</var>
+ attribute has been specified.
+
+ <h4>Special Properties</h4>
+
+ <p>Included files are treated as they are present in the main buildfile. This makes it easy to
+ understand, but it makes it impossible for them to reference files and resources relative to
+ their path. Because of this, for every included file, Ant adds a property that contains the
+ path to the included buildfile. With this path, the included buildfile can keep resources and be
+ able to reference them relative to its position.</p>
+
+ <p>So if I include for example a <samp>docsbuild.xml</samp> file named <q>builddocs</q>, I can get
+ its path as <code>ant.file.builddocs</code>, similarly to the <code>ant.file</code> property of
+ the main buildfile.</p>
+
+ <p>Note that <q>builddocs</q> is not the filename, but the <var>name</var> attribute present in
+ the included <code>project</code> tag.</p>
+ <p>If the included file does not have a <var>name</var> attribute,
+ the <code>ant.file.<i>projectname</i></code> property will not be set.</p>
+
+ <p>If you need to know whether the current build file's source has been a file or an URL you can
+ consult the property <code>ant.file.type.<i>projectname</i></code> (using the same example as
+ above <code>ant.file.type.builddocs</code>) which either have the value <q>file</q>
+ or <q>url</q>.</p>
+
+ <h4>Resolving files against the included file</h4>
+
+ <p>Suppose your main build file called <samp>including.xml</samp> includes a build
+ file <samp>included.xml</samp>, located anywhere on the file system,
+ and <samp>included.xml</samp> reads a set of properties
+ from <samp>included.properties</samp>:</p>
+
+ <pre>
+<!-- including.xml -->
<project name="including" basedir="." default="...">
<include file="${path_to_included}/included.xml"/>
</project>
@@ -119,156 +99,121 @@ properties from <code>included.properties</code>:</p>
<!-- included.xml -->
<project name="included" basedir="." default="...">
<property file="included.properties"/>
-</project>
-</pre>
+</project></pre>
-<p>This snippet however will resolve <code>included.properties</code>
-against the basedir of <code>including.xml</code>, because the basedir
-of <code>included.xml</code> is ignored by Ant. The right way to use
-<code>included.properties</code> is:</p>
+ <p>This snippet however will resolve <samp>included.properties</samp> against
+ the <var>basedir</var> of <samp>including.xml</samp>, because the <var>basedir</var>
+ of <samp>included.xml</samp> is ignored by Ant. The right way to
+ use <samp>included.properties</samp> is:</p>
-<pre>
+ <pre>
<!-- included.xml -->
<project name="included" basedir="." default="...">
<dirname property="included.basedir" file="${ant.file.included}"/>
<property file="${included.basedir}/included.properties"/>
-</project>
-</pre>
+</project></pre>
-<p>As explained above <code>${ant.file.included}</code> stores the
-path of the build script, that defines the project called
-<code>included</code>, (in short it stores the path to
-<code>included.xml</code>) and <a
-href="dirname.html"><code><dirname></code></a> takes its
-directory. This technique also allows <code>included.xml</code> to be
-used as a standalone file (without being included in other
-project).</p>
-
-<p>The above description only works for included files that actually
- are included from files and not from URLs. For files included from
- URLs using resources relative to the included file requires you to
- use tasks that can work on non-file resources in the first place.
- To create a relative resource you'd use something like:</p>
+ <p>As explained above <code>ant.file.included</code> stores the path of the build script, that
+ defines the project called <q>included</q>, (in short it stores the path
+ to <samp>included.xml</samp>) and <a href="dirname.html"><code><dirname></code></a> takes
+ its directory. This technique also allows <samp>included.xml</samp> to be used as a standalone
+ file (without being included in other project).</p>
-<pre>
- <loadproperties>
- <url baseUrl="${ant.file.included}"
- relativePath="included.properties"/>
- </loadproperties>
-</pre>
+ <p>The above description only works for included files that actually are included from files and
+ not from URLs. For files included from URLs using resources relative to the included file
+ requires you to use tasks that can work on non-file resources in the first place. To create a
+ relative resource you'd use something like:</p>
+
+ <pre>
+<loadproperties>
+ <url baseUrl="${ant.file.included}"
+ relativePath="included.properties"/>
+</loadproperties></pre>
<h3>Parameters</h3>
-<table>
+<table class="attr">
<tbody>
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr>
- <td valign="top">
- file
- </td>
- <td valign="top">
- The file to include. If this is a relative file name, the file name will be resolved
- relative to the <i>including</i> file. <strong>Note</strong>, this is unlike most other
- ant file attributes, where relative files are resolved relative to ${basedir}.
- </td>
- <td valign="top" align="center">Yes or a nested resource collection</td>
+ <td>file</td>
+ <td>The file to include. If this is a relative file name, the file name will be resolved
+ relative to the <em>including</em> file. <strong>Note</strong>, this is unlike most other
+ ant file attributes, where relative files are resolved relative to ${basedir}.</td>
+ <td>Yes or a nested resource collection</td>
</tr>
<tr>
- <td valign="top">
- optional
- </td>
- <td valign="top">
- If true, do not stop the build if the file does not exist,
- default is false.
- </td>
- <td valign="top" align="center">No</td>
+ <td>optional</td>
+ <td>If <q>true</q>, do not stop the build if the file does not exist.</td>
+ <td>No; default is <q>false</q></td>
</tr>
<tr>
- <td valign="top">
- as
- </td>
- <td valign="top">
- Specifies the prefix prepended to the target names. If
- omitted, the name attribute of the project tag of the
- included file will be used.
- </td>
- <td valign="top" align="center">Yes, if the included file's
- project tag doesn't specify a name attribute.</td>
+ <td>as</td>
+ <td>Specifies the prefix prepended to the target names.</td>
+ <td>Yes, if the included file's <code>project</code> tag doesn't specify a <var>name</var>
+ attribute (which is otherwise taken as default)</td>
</tr>
<tr>
- <td valign="top">
- prefixSeparator
- </td>
- <td valign="top">
- Specifies the separator to be used between the prefix and the
- target name. Defaults to ".".
- </td>
- <td valign="top" align="center">No</td>
+ <td>prefixSeparator</td>
+ <td>Specifies the separator to be used between the prefix and the target name.</td>
+ <td>No; defaults to <q>.</q></td>
</tr>
</tbody>
</table>
<h3>Parameters specified as nested elements</h3>
-<h4>any <a href="../Types/resources.html">resource</a> or resource
-collection</h4>
+<h4>any <a href="../Types/resources.html">resource</a> or resource collection</h4>
<p>The specified resources will be included.</p>
<h3>Examples</h3>
-<pre> <include file="../common-targets.xml"/></pre>
+<pre><include file="../common-targets.xml"/></pre>
-<p>Includes targets from the common-targets.xml file that is in a parent
-directory.</p>
+<p>Includes targets from the <samp>common-targets.xml</samp> file that is in a parent directory.</p>
-<pre> <include file="${deploy-platform}.xml"/></pre>
+<pre><include file="${deploy-platform}.xml"/></pre>
<p>Includes the project defined by the property deploy-platform</p>
<pre>
- <include>
- <javaresource name="common/targets.xml">
- <classpath location="common.jar"/>
- </javaresource>
- </include>
-</pre>
+<include>
+ <javaresource name="common/targets.xml">
+ <classpath location="common.jar"/>
+ </javaresource>
+</include></pre>
-<p>Includes targets from the targets.xml file that is inside the
- directory common inside the jar file common.jar.</p>
+<p>Includes targets from the <samp>targets.xml</samp> file that is inside the
+directory <samp>common</samp> inside the jar file <samp>common.jar</samp>.</p>
-<h3>How is <a href="import.html"><import></a> different
- from <include>?</h3>
+<h3>How is <a href="import.html"><import></a> different from <include>?</h3>
-<p>The short version: Use import if you intend to override a target,
- otherwise use include.</p>
+<p>The short version: Use <code>import</code> if you intend to override a target, otherwise
+use <code>include</code>.</p>
-<p>When using import the imported targets are available by up to two
- names. Their "normal" name without any prefix and potentially with
- a prefixed name (the value of the as attribute or the imported
- project's name attribute, if any).</p>
+<p>When using <code>import</code> the imported targets are available by up to two names. Their
+"normal" name without any prefix and potentially with a prefixed name (the value of
+the <var>as</var> attribute or the imported project's <var>name</var> attribute, if any).</p>
-<p>When using include the included targets are only available in the
- prefixed form.</p>
+<p>When using <code>include</code> the included targets are only available in the prefixed form.</p>
-<p>When using import, the imported target's depends attribute
- remains unchanged, i.e. it uses "normal" names and allows you to
- override targets in the dependency list.</p>
+<p>When using <code>import</code>, the imported target's <var>depends</var> attribute remains
+unchanged, i.e. it uses "normal" names and allows you to override targets in the dependency
+list.</p>
-<p>When using include, the included targets cannot be overridden and
- their depends attributes are rewritten so that prefixed names are
- used. This allows writers of the included file to control which
- target is invoked as part of the dependencies.</p>
+<p>When using <code>include</code>, the included targets cannot be overridden and
+their <var>depends</var> attributes are rewritten so that prefixed names are used. This allows
+writers of the included file to control which target is invoked as part of the dependencies.</p>
-<p>It is possible to include the same file more than once by using
- different prefixes, it is not possible to import the same file more
- than once.</p>
+<p>It is possible to <code>include</code> the same file more than once by using different prefixes,
+it is not possible to <code>import</code> the same file more than once.</p>
<h4>Examples</h4>
-<p><i>nested.xml</i> shall be:</p>
+<p><samp>nested.xml</samp> shall be:</p>
<pre>
<project>
@@ -279,10 +224,9 @@ directory.</p>
<target name="echo" depends="setUp">
<echo>prop has the value ${prop}</echo>
</target>
-</project>
-</pre>
+</project></pre>
-<p>When using import like in</p>
+<p>When using <code>import</code> like in</p>
<pre>
<project default="test">
@@ -293,10 +237,9 @@ directory.</p>
<import file="nested.xml" as="nested"/>
<target name="test" depends="nested.echo"/>
-</project>
-</pre>
+</project></pre>
-<p>Running the build file will emit:
+<p>Running the build file will emit:</p>
<pre>
setUp:
@@ -308,7 +251,7 @@ test:
</pre>
-<p>When using include like in</p>
+<p>When using <code>include</code> like in</p>
<pre>
<project default="test">
@@ -319,10 +262,9 @@ test:
<include file="nested.xml" as="nested"/>
<target name="test" depends="nested.echo"/>
-</project>
-</pre>
+</project></pre>
-<p>Running the target build file will emit:
+<p>Running the target build file will emit:</p>
<pre>
nested.setUp:
@@ -334,7 +276,7 @@ test:
</pre>
-<p>and there won't be any target named "echo" on the including build file.</p>
+<p>and there won't be any target named <q>echo</q> on the including build file.</p>
</body>
</html>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/Tasks/input.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/input.html b/manual/Tasks/input.html
index b40fc01..a2829f2 100644
--- a/manual/Tasks/input.html
+++ b/manual/Tasks/input.html
@@ -27,167 +27,150 @@
<h2 id="input">Input</h2>
<h3>Description</h3>
-<p>Allows user interaction during the build process by prompting for
-input. To do so, it uses the configured
-<a href="../inputhandler.html">InputHandler</a>.</p>
-
-<p>The prompt can be set via the message attribute or as character
-data nested into the element.</p>
-
-<p>Optionally a set of valid input arguments can be defined via the
-validargs attribute. Input task will not accept a value that doesn't match
-one of the predefined.</p>
-
-<p>Optionally a property can be created from the value entered by the
-user. This property can then be used during the following build
-run. Input behaves according to <a href="property.html">property
-task</a> which means that existing properties cannot be overridden.
-<em>Since Apache Ant 1.6</em>, <code><input></code> will not prompt for input if
-a property should be set by the task that has already been set in the
-project (and the task wouldn't have any effect).</p>
-
-<p>Historically, a regular complaint about this task has been that it echoes
-characters to the console, this is a critical security defect, we must fix it
-immediately, etc, etc. This problem was due to the lack in early versions of
-Java of a (fully functional) facility for handling secure console input.
-In Java 6 that shortcoming in Java's API was addressed and Ant versions 1.7.1
-and 1.8 have added support for Java 6 secure console input feature
-(see <a href="#handler.type">handler type</a>).</p>
-
-<p>
-IDE behaviour depends upon the IDE: some hang waiting for input, some let you
-type it in. For this situation, place the password in a (secured) property
-file and load in before the input task.</p>
+<p>Allows user interaction during the build process by prompting for input. To do so, it uses the
+configured <a href="../inputhandler.html">InputHandler</a>.</p>
+
+<p>The prompt can be set via the <var>message</var> attribute or as character data nested into the
+element.</p>
+
+<p>Optionally a set of valid input arguments can be defined via the <var>validargs</var>
+attribute. <code>Input</code> task will not accept a value that doesn't match one of the
+predefined.</p>
+
+<p>Optionally a property can be created from the value entered by the user. This property can then
+be used during the following build run. <code>Input</code> then behaves
+as <a href="property.html">property task</a> which means that existing properties cannot be
+overridden. <em>Since Apache Ant 1.6</em>, <code><input></code> will not prompt for input if
+a property should be set by the task that has already been set in the project (and the task wouldn't
+have any effect).</p>
+
+<p>Historically, a regular complaint about this task has been that it echoes characters to the
+console, this is a critical security defect, we must fix it immediately, etc, etc. This problem was
+due to the lack in early versions of Java of a (fully functional) facility for handling secure
+console input. In Java 6 that shortcoming in Java's API was addressed and Ant versions 1.7.1 and
+1.8 have added support for Java 6 secure console input feature (see <a href="#handler.type">handler
+type</a>).</p>
+
+<p>IDE behaviour depends upon the IDE: some hang waiting for input, some let you type it in. For
+this situation, place the password in a (secured) property file and load in before
+the <code>input</code> task.</p>
<h3>Parameters</h3>
-<table>
+<table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr>
- <td valign="top">message</td>
- <td valign="top">the Message which gets displayed to the user
- during the build run.</td>
- <td valign="top" align="center">No</td>
+ <td>message</td>
+ <td>the Message which gets displayed to the user during the build run.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">validargs</td>
- <td valign="top">comma separated String containing valid input
- arguments. If set, input task will reject any input not defined
- here. Validargs are compared case sensitive. If you want 'a' and
- 'A' to be accepted you will need to define both arguments within
- validargs.</td>
- <td valign="top" align="center">No</td>
+ <td>validargs</td>
+ <td>comma separated String containing valid input arguments. If set, <code>input</code> task
+ will reject any input not defined here. Comparison of input to <var>validargs</var> is case
+ sensitive. If you want <q>a</q> and
+ <q>A</q> to be accepted you will need to define both arguments within <var>validargs</var>.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">addproperty</td>
- <td valign="top">the name of a property to be created from
- input. Behaviour is equal to <a href="property.html">property
- task</a> which means that existing properties cannot be
- overridden.</td>
- <td valign="top" align="center">No</td>
+ <td>addproperty</td>
+ <td>the name of a property to be created from input. Behaviour is equal
+ to <a href="property.html">property task</a> which means that existing properties cannot be
+ overridden.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">defaultvalue</td>
- <td valign="top">Defines the default value of the property to be
- created from input. Property value will be set to default if no
- input is received.</td>
- <td valign="top" align="center">No</td>
+ <td>defaultvalue</td>
+ <td>Defines the default value of the property to be created from input. Property value will be
+ set to default if no input is received.</td>
+ <td>No</td>
</tr>
</table>
<h3>Parameters Specified as Nested Elements</h3>
<h4>Handler</h4>
-<p><em>Since Ant 1.7</em>, a nested <handler> element can be used to
-specify an InputHandler, so that different InputHandlers may be used
-among different Input tasks.</p>
+<p><em>Since Ant 1.7</em>, a nested <code><handler></code> element can be used to specify
+an <code>InputHandler</code>, so that different <code>InputHandler</code>s may be used among
+different <code>Input</code> tasks.</p>
-<table>
+<table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr id="handler.type">
- <td valign="top">type</td>
- <td valign="top">one of "default","propertyfile", "greedy", or "secure" (<em>since Ant 1.8</em>).
- </td>
- <td align="center" valign="top" rowspan="3">One of these</td>
+ <td>type</td>
+ <td>one of <q>default</q>, <q>propertyfile</q>, <q>greedy</q>, or <q>secure</q> (<em>since Ant
+ 1.8</em>).</td>
+ <td rowspan="3">One of these</td>
</tr>
<tr>
- <td valign="top">refid</td>
- <td valign="top">Reference to an <code>InputHandler</code>
- defined elsewhere in the project.
- </td>
+ <td>refid</td>
+ <td class="left">Reference to an <code>InputHandler</code> defined elsewhere in the
+ project.</td>
</tr>
<tr>
- <td valign="top">classname</td>
- <td valign="top">The name of an <code>InputHandler</code> subclass.</td>
+ <td>classname</td>
+ <td class="left">The name of an <code>InputHandler</code> subclass.</td>
</tr>
<tr>
- <td valign="top">classpath</td>
- <td valign="top">The classpath to use with <i>classname</i>.</td>
- <td valign="top">No</td>
+ <td>classpath</td>
+ <td>The classpath to use with <var>classname</var>.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">classpathref</td>
- <td valign="top">The refid of a classpath to use with <i>classname</i>.</td>
- <td valign="top">No</td>
+ <td>classpathref</td>
+ <td>The refid of a classpath to use with <var>classname</var>.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">loaderref</td>
- <td valign="top">The refid of a classloader to use with <i>classname</i>.
+ <td>loaderref</td>
+ <td>The refid of a classloader to use with <var>classname</var>.
</td>
- <td valign="top">No</td>
+ <td>No</td>
</tr>
</table>
-<p>
-The classpath can also be specified by means of one or more nested
-<classpath> elements.</p>
+<p>The classpath can also be specified by means of one or more nested <code><classpath></code>
+elements.</p>
<h3>Examples</h3>
-<pre> <input/></pre>
-<p>Will pause the build run until return key is pressed when using the
-<a href="../inputhandler.html#defaulthandler">default
-InputHandler</a>, the concrete behavior is defined by the InputHandler
-implementation you use.</p>
-<pre> <input>Press Return key to continue...</input></pre>
-<p>Will display the message "Press Return key to
-continue..." and pause the build run until return key is pressed
-(again, the concrete behavior is implementation dependent).</p>
-<pre> <input
- message="Press Return key to continue..."/></pre>
-<p>Will display the message "Press Return key to
-continue..." and pause the build run until return key is pressed
-(see above).</p>
+<pre><input/></pre>
+<p>Will pause the build run until return key is pressed when using
+the <a href="../inputhandler.html#defaulthandler">default InputHandler</a>, the concrete behavior is
+defined by the <code>InputHandler</code> implementation you use.</p>
+<pre><input>Press Return key to continue...</input></pre>
+<p>Will display the message <q>Press Return key to continue...</q> and pause the build run until
+return key is pressed (again, the concrete behavior is implementation dependent).</p>
+<pre><input message="Press Return key to continue..."/></pre>
+<p>Will display the message <q>Press Return key to continue...</q> and pause the build run until
+return key is pressed (see above).</p>
<pre>
- <input
- message="All data is going to be deleted from DB continue (y/n)?"
- validargs="y,n"
- addproperty="do.delete"/>
- <condition property="do.abort">
- <equals arg1="n" arg2="${do.delete}"/>
- </condition>
- <fail if="do.abort">Build aborted by user.</fail>
+<input message="All data is going to be deleted from DB continue (y/n)?"
+ validargs="y,n"
+ addproperty="do.delete"/>
+<condition property="do.abort">
+ <equals arg1="n" arg2="${do.delete}"/>
+</condition>
+<fail if="do.abort">Build aborted by user.</fail>
</pre>
-<p>Will display the message "All data is going to be deleted from
-DB continue (y/n)?" and require 'y' to continue build or 'n' to
-exit build with following message "Build aborted by
-user.".</p>
-<pre> <input
- message="Please enter db-username:"
- addproperty="db.user"/></pre>
-<p>Will display the message "Please enter db-username:" and set the
+<p>Will display the message <q>All data is going to be deleted from DB continue (y/n)?</q> and
+require <q>y</q> to continue build or <q>n</q> to exit build with following message <q>Build aborted
+by user.</q>.</p>
+<pre>
+<input message="Please enter db-username:"
+ addproperty="db.user"/></pre>
+<p>Will display the message <q>Please enter db-username:</q> and set the
property <code>db.user</code> to the value entered by the user.</p>
-<pre> <input
- message="Please enter db-username:"
- addproperty="db.user"
- defaultvalue="Scott-Tiger"/></pre>
-<p>Same as above, but will set <code>db.user</code> to the value
-<i>Scott- Tiger</i> if the user enters no value (simply types
-<return>).</p>
+<pre>
+<input message="Please enter db-username:"
+ addproperty="db.user"
+ defaultvalue="Scott-Tiger"/></pre>
+<p>Same as above, but will set <code>db.user</code> to the value <q>Scott-Tiger</q> if the user
+enters no value (simply presses <q>return</q>).</p>
</body>
</html>