Accumulated documentation changes.

1 files changed, 60 insertions, 1 deletions

diff --git a/doc/user/help.in b/doc/user/help.in
index d4b2caa..4356d18 100644
--- a/doc/user/help.in
+++ b/doc/user/help.in
@@ -61,7 +61,66 @@
    </para>
 
    <scons_output example="ex1">
-      <command>scons -h</command>
+      <scons_output_command>scons -h</scons_output_command>
+   </scons_output>
+
+   <para>
+
+   The &SConscript; files may contain
+   multiple calls to the &Help; function,
+   in which case the specified text(s)
+   will be concatenated when displayed.
+   This allows you to split up the
+   help text across multiple &SConscript; files.
+   In this situation, the order in
+   which the &SConscript; files are called
+   will determine the order in which the &Help; functions are called,
+   which will determine the order in which
+   the various bits of text will get concatenated.
+
+   </para>
+
+   <para>
+
+   Another use would be to make the help text conditional
+   on some variable.
+   For example, suppose you only want to display
+   a line about building a Windows-only
+   version of a program when actually
+   run on Windows.
+   The following &SConstruct; file:
+
+   </para>
+
+   <scons_example name="ex2">
+      <file name="SConstruct" printme="1">
+      env = Environment()
+
+      Help("\nType: 'scons program' to build the production program.\n")
+
+      if env['PLATFORM'] == 'win32':
+          Help("\nType: 'scons windebug' to build the Windows debug version.\n")
+      </file>
+   </scons_example>
+
+   <para>
+
+   Will display the completely help text on Windows:
+
+   </para>
+
+   <scons_output example="ex2" os="win32">
+      <scons_output_command>scons -h</scons_output_command>
+   </scons_output>
+
+   <para>
+
+   But only show the relevant option on a Linux or UNIX system:
+
+   </para>
+
+   <scons_output example="ex2" os="posix">
+      <scons_output_command>scons -h</scons_output_command>
    </scons_output>
 
    <para>