Updated docs on Actions for output control

Manpage now mentions specifically generating your own Action object
in order to control the output string. Calls out using None as the
command-output specifier to avoid output: Action(foo, None) and
Action(foo, cmdstr=None), as well

Userguide got a mention of using the action kwarg for readability
and an example showing creating the Action for Command manually
to set the output string.

Signed-off-by: Mats Wichmann <mats@linux.com>

4 files changed, 100 insertions, 28 deletions

diff --git a/doc/generated/examples/builderscommands_ex5_1.xml b/doc/generated/examples/builderscommands_ex5_1.xml
new file mode 100644
index 0000000..3811242
--- /dev/null
+++ b/doc/generated/examples/builderscommands_ex5_1.xml
@@ -0,0 +1,3 @@
+<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
+Building foo.in
+</screen>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index fc28e2a..96b5700 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -5521,18 +5521,21 @@ and emitter functions.</para>
 function will turn its
 <parameter>action</parameter>
 keyword argument into an appropriate
-internal Action object.
+internal Action object, as will
+the &f-link-Command; function.
 You can also explicitly create Action objects
 for passing to &f-Builder;, or other functions
 that take actions as arguments,
 by calling the &f-link-Action; factory function.
-This can be used to configure
-an Action object more flexibly,
-or it may simply be more efficient
-than letting each separate Builder object
-create a separate Action
-when multiple
-Builder objects need to do the same thing.</para>
+This may more efficient when multiple
+Builder objects need to do the same thing
+rather than letting each of those Builder objects
+create a separate Action object.
+It also allows more flexible configuration
+of an Action object. For example, to control
+the message printed when the action is taken
+you need to create the action object using &f-Action;.
+</para>
 
 <para>The
 &Action; factory function
@@ -5652,23 +5655,22 @@ it was called. The global function form &f-link-Action;
 the Action object is actually used.
 </para>
 
-<para>The second argument to &f-Action;
-is optional and is used to define the output
+<para>The optional second argument to &f-Action;
+is used to control the output
 which is printed when the Action is actually performed.
-In the absence of this parameter,
-or if it's an empty string,
+If this parameter is omitted,
+or if the value is an empty string,
 a default output depending on the type of the action is used.
 For example, a command-line action will print the executed command.
-The argument must be either a Python function or a string:</para>
+The following argument types are accepted:
+</para>
 
 <itemizedlist>
   <listitem>
 <para>If the output argument is a function,
-it must return a string
+the function will be called to obtain a string
 describing the action being executed.
-A function may also be specified using the
-<parameter>strfunction</parameter>
-keyword argument. The function
+The function
 must accept these three keyword arguments:</para>
 
   <simplelist type="vert">
@@ -5689,18 +5691,29 @@ more than one target file or source file.</para>
 
   <listitem>
 <para>If the output argument is a string,
-substitution is performed on it before it is printed.
-The output string may also be specified using the
-<parameter>cmdstr</parameter>
-keyword argument.
+substitution is performed on the string before it is printed.
 The string typically contains variables, notably
 <literal>$TARGET(S)</literal> and <literal>$SOURCE(S)</literal>,
 or consists of just a single
 variable, which is optionally defined somewhere else.
-SCons itself heavily uses the latter variant.</para>
+&SCons; itself heavily uses the latter variant.</para>
+  </listitem>
+
+  <listitem>
+<para>If the argument is <constant>None</constant>,
+output is suppressed entirely.</para>
   </listitem>
 </itemizedlist>
 
+<para>
+Instead of using a positional argument,
+the <parameter>cmdstr</parameter>
+keyword argument may be used to specify the output string,
+or the <parameter>strfunction</parameter> keyword argument
+may be used to specify a function to return the output string,
+Use <literal>cmdstr=None</literal> to suppress output.
+</para>
+
 <para>Examples:</para>
 
 <programlisting language="python">
diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml
index 5d378b3..9bbd962 100644
--- a/doc/user/builders-commands.xml
+++ b/doc/user/builders-commands.xml
@@ -81,7 +81,7 @@
   if you only need to execute one specific command
   to build a single file (or group of files).
   For these situations, &SCons; supports a
-  &Command; &Builder; that arranges
+  &f-link-Command; builder that arranges
   for a specific action to be executed
   to build a specific file or files.
   This looks a lot like the other builders
@@ -119,7 +119,7 @@ foo.in
   This is often more convenient than
   creating a &Builder; object
   and adding it to the &cv-link-BUILDERS; variable
-  of a &consenv;
+  of a &consenv;.
 
   </para>
 
@@ -134,9 +134,11 @@ foo.in
   <scons_example name="builderscommands_ex2">
      <file name="SConstruct" printme="1">
 env = Environment()
+
 def build(target, source, env):
     # Whatever it takes to build
     return None
+
 env.Command('foo.out', 'foo.in', build)
      </file>
      <file name="foo.in">
@@ -157,8 +159,7 @@ foo.in
   <para>
 
   Note that &cv-link-SOURCE; and &cv-link-TARGET; are expanded 
-  in the source and target as well as of SCons 1.1,
-  so you can write:
+  in the source and target as well, so you can write:
 
   </para>
 
@@ -168,7 +169,6 @@ env.Command('${SOURCE.basename}.out', 'foo.in', build)
      </file>
   </scons_example>
 
-
   <para>
 
   which does the same thing as the previous example, but allows you
@@ -176,5 +176,61 @@ env.Command('${SOURCE.basename}.out', 'foo.in', build)
 
   </para>
 
+  <para>
+
+  It may be helpful to use the <parameter>action</parameter>
+  keyword to specify the action, is this makes things more clear
+  to the reader:
+
+  </para>
+
+  <scons_example name="builderscommands_ex4">
+     <file name="SConstruct" printme="1">
+env.Command('${SOURCE.basename}.out', 'foo.in', action=build)
+     </file>
+  </scons_example>
+
+  <para>
+
+  The method described in
+  <xref linkend="sect-controlling-build-output"/> for controlling
+  build output works well when used with pre-defined builders which
+  have pre-defined <literal>*COMSTR</literal> variables for that purpose,
+  but that is not the case when calling &f-Command;,
+  where &SCons; has no specific knowledge of the action ahead of time.
+  If the action argument to &f-Command is not already an &Action; object,
+  it will construct one for you with suitable defaults,
+  which include a message based on the type of action.
+  However, you can also construct the &Action; object yourself
+  and pass that, which gives you much more control.
+  Here's an evolution of the example from above showing this approach:
+
+  </para>
+
+  <scons_example name="builderscommands_ex5">
+     <file name="SConstruct" printme="1">
+env = Environment()
+
+def build(target, source, env):
+    # Whatever it takes to build
+    return None
+
+act = Action(build, cmdstr="Building ${SOURCE}")
+env.Command('foo.out', 'foo.in', action=act)
+     </file>
+     <file name="foo.in">
+foo.in
+     </file>
+  </scons_example>
+
+  <para>
+
+  Which executes as follows:
+
+  </para>
+
+  <scons_output example="builderscommands_ex5" suffix="1">
+    <scons_output_command>scons -Q</scons_output_command>
+  </scons_output>
 
 </chapter>
diff --git a/doc/user/output.xml b/doc/user/output.xml
index bae018a..cf6571c 100644
--- a/doc/user/output.xml
+++ b/doc/user/output.xml
@@ -197,7 +197,7 @@ if env['PLATFORM'] == 'win32':
 
   </section>
 
-  <section>
+  <section id="sect-controlling-build-output">
   <title>Controlling How &SCons; Prints Build Commands:  the <envar>$*COMSTR</envar> Variables</title>
 
     <para>