Issue 1086: add support for generic batch build actions, and

specific support for batched compilation for Microsoft Visual C/C++.

Merged revisions 3819-3851,3854-3869,3871-3877,3880 via svnmerge from
http://scons.tigris.org/svn/scons/branches/sgk_batch

........
  r3820 | stevenknight | 2008-12-09 23:59:14 -0800 (Tue, 09 Dec 2008) | 6 lines

  Issue 1086:  Batch compilation support:
  * $MSVC_BATCH to control Visual C/C++ batch compilation.
  * New $CHANGED_SOURCES, $CHANGED_TARGETS, $UNCHANGED_SOURCES and
    $UNCHANGED_TARGETS construction variables.
  * New Action(batch_key=, targets=) keyword arguments.
........
  r3880 | stevenknight | 2009-01-07 20:50:41 -0800 (Wed, 07 Jan 2009) | 3 lines

  Use UniqueList objects to collect the all_children(), all_prerequisites()
  and all_sources() lists instead of calling uniquer_hashables() by hand.
........

1 files changed, 173 insertions, 9 deletions

diff --git a/doc/user/actions.xml b/doc/user/actions.xml
index 928b7ea..04178b0 100644
--- a/doc/user/actions.xml
+++ b/doc/user/actions.xml
@@ -222,19 +222,183 @@ solutions to the above limitations.
 
 -->
 
- <para>
+  <para>
 
-   XXX
+  &SCons; supports several types of &build_actions;
+  that can be performed to build one or more target files.
+  Usually, a &build_action; is a command-line string
+  that invokes an external command.
+  A build action can also be an external  command
+  specified as a list of arguments,
+  or even a Python function.
 
- </para>
+  </para>
 
- <section>
- <title>XXX</title>
+  <para>
 
-   <para>
+  Build action objects are created by the &Action; function.
+  This function is, in fact, what &SCons; uses
+  to interpret the &action;
+  keyword argument when you call the &Builder; function.
+  So the following line that creates a simple Builder:
 
-   XXX
+  </para>
 
-   </para>
+  <programlisting>
+    b = Builder(action = 'build < $SOURCE > $TARGET')
+  </programlisting>
 
- </section>
+  <para>
+
+  Is equivalent to:
+
+  </para>
+
+  <programlisting>
+    b = Builder(action = Action('build < $SOURCE > $TARGET'))
+  </programlisting>
+
+  <para>
+
+  The advantage of using the &Action; function directly
+  is that it can take a number of additional options
+  to modify the action's behavior in many useful ways.
+
+  </para>
+
+  <section>
+  <title>Command Strings as Actions</title>
+
+    <section>
+    <title>Suppressing Command-Line Printing</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+    </section>
+
+    <section>
+    <title>Ignoring Exit Status</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Argument Lists as Actions</title>
+
+  <para>
+
+  XXX
+
+  </para>
+
+  </section>
+
+  <section>
+  <title>Python Functions as Actions</title>
+
+  <para>
+
+  XXX
+
+  </para>
+
+  </section>
+
+  <section>
+  <title>Modifying How an Action is Printed</title>
+
+    <section>
+    <title>XXX:  the &strfunction; keyword argument</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+    </section>
+
+    <section>
+    <title>XXX:  the &cmdstr; keyword argument</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Making an Action Depend on Variable Contents:  the &varlist; keyword argument</title>
+
+  <para>
+
+  XXX
+
+  </para>
+
+  </section>
+
+  <section>
+  <title>chdir=1</title>
+
+  <para>
+
+  XXX
+
+  </para>
+
+  </section>
+
+  <section>
+  <title>Batch Building of Multiple Targets from Separate Sources:  the &batch_key; keyword argument</title>
+
+  <para>
+
+  XXX
+
+  </para>
+
+  </section>
+
+  <section>
+  <title>Manipulating the Exit Status of an Action:  the &exitstatfunc; keyword argument</title>
+
+  <para>
+
+  XXX
+
+  </para>
+
+  </section>
+
+  <!--
+
+  ???
+
+  <section>
+  <title>presub=</title>
+
+  <para>
+
+  XXX
+
+  </para>
+
+  </section>
+
+  -->