some notes on running Ant as a background process. PR 34461.

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

docs/manual/CoreTasks/apply.html

@@ -52,6 +52,15 @@ and you must not specify more than one mapper.</p>
 <p>Note that you cannot interact with the forked program, the only way
 to send input to it is via the input and inputstring attributes.</p>
 
+<h4><a name="background">Running Ant as a background process on
+    Unix(-like) systems</a></h4>
+
+<p>If you run Ant as a background process (like <code>ant &</code>)
+  and use the <code>&lt;apply&gt;</code> task with <code>spawn</code>
+  set to <code>false</code>, you must provide explicit input to the
+  forked process or Ant will be suspended because it tries to read
+  from the standard input.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>

docs/manual/CoreTasks/exec.html

@@ -131,6 +131,15 @@ or the task will fail as follows:
 </blockquote>
 </p>
 
+<h4><a name="background">Running Ant as a background process on
+    Unix(-like) systems</a></h4>
+
+<p>If you run Ant as a background process (like <code>ant &</code>)
+  and use the <code>&lt;exec&gt;</code> task with <code>spawn</code>
+  set to <code>false</code>, you must provide explicit input to the
+  forked process or Ant will be suspended because it tries to read
+  from the standard input.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>

docs/manual/CoreTasks/java.html

@@ -36,6 +36,16 @@ JVM.
 sending input to it via the <code>input</code> and <code>inputstring</code>
 attributes.</p>
 
+<h4><a name="background">Running Ant as a background process on
+    Unix(-like) systems</a></h4>
+
+<p>If you run Ant as a background process (like <code>ant &</code>)
+  and use the <code>&lt;java&gt;</code> task with <code>spawn</code>
+  set to <code>false</code> and <code>fork</code>
+  to <code>true</code>, you must provide explicit input to the forked
+  process or Ant will be suspended because it tries to read from the
+  standard input.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>

docs/manual/running.html

@@ -520,6 +520,22 @@ shell (of course unless called automatically from <code>ant.cmd</code>). It is t
 <p>Scripts <code>envset.cmd</code> and <code>runrc.cmd</code> perform auxiliary tasks. All scripts
 have some documentation inside.</p>
 
+<h2><a name="background">Running Ant as a background process on
+    Unix(-like) systems</a></h2>
+
+<p>If you start Ant as a background process (like in <code>ant
+    &</code>) and the build process creates another process, Ant will
+    immediately try to read from standard input, which in turn will
+    most likely suspend the process.  In order to avoid this, you must
+    redirect Ant's standard input or explicitly provide input to each
+    spawned process via the input related attributes of the
+    corresponding tasks.</p>
+
+<p>Tasks that create such new processes
+  include <code>&lt;exec&gt;</code>, <code>&lt;apply&gt;</code>
+  or <code>&lt;java&gt;</code> when the <code>fork</code> attribute is
+  <code>true</code>.</p>
+
 <h2><a name="viajava">Running Ant via Java</a></h2>
 <p>If you have installed Ant in the do-it-yourself way, Ant can be started
 from one of two entry points:</p>

docs/manual/runninglist.html

@@ -37,6 +37,7 @@
   <a href="running.html#sysprops">Java System Properties</a><br/>
   <a href="running.html#cygwin">Cygwin Users</a><br/>
   <a href="running.html#os2">OS/2 Users</a><br/>
+  <a href="running.html#background">Running "in the background"</a><br/>
 </div>
 <a href="running.html#viajava">Running Ant via Java</a><br/>