1 files changed, 153 insertions, 0 deletions
diff --git a/doc/user/help.xml b/doc/user/help.xml
new file mode 100644
index 0000000..ca44a40
--- /dev/null
+++ b/doc/user/help.xml
@@ -0,0 +1,153 @@
+<!--
+
+  __COPYRIGHT__
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+   <para>
+
+   It's often very useful to be able to give
+   users some help that describes the
+   specific targets, build options, etc.,
+   that can be used for your build.
+   &SCons; provides the &Help; function
+   to allow you to specify this help text:
+
+   </para>
+
+   <programlisting>
+      Help("""
+      Type: 'scons program' to build the production program,
+            'scons debug' to build the debug version.
+      """)
+   </programlisting>
+
+   <para>
+
+   (Note the above use of the Python triple-quote syntax,
+   which comes in very handy for
+   specifying multi-line strings like help text.)
+
+   </para>
+
+   <para>
+
+   When the &SConstruct; or &SConscript; files
+   contain such a call to the &Help; function,
+   the specified help text will be displayed in response to
+   the &SCons; <literal>-h</literal> option:
+
+   </para>
+
+   <screen>
+      % <userinput>scons -h</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      
+      Type: 'scons program' to build the production program,
+            'scons debug' to build the debug version.
+      
+      Use scons -H for help about command-line options.
+   </screen>
+
+   <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>
+
+   <programlisting>
+      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")
+   </programlisting>
+
+   <para>
+
+   Will display the completely help text on Windows:
+
+   </para>
+
+   <screen>
+      C:\><userinput>scons -h</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      
+      Type: 'scons program' to build the production program.
+      
+      Type: 'scons windebug' to build the Windows debug version.
+      
+      Use scons -H for help about command-line options.
+   </screen>
+
+   <para>
+
+   But only show the relevant option on a Linux or UNIX system:
+
+   </para>
+
+   <screen>
+      % <userinput>scons -h</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      
+      Type: 'scons program' to build the production program.
+      
+      Use scons -H for help about command-line options.
+   </screen>
+
+   <para>
+
+   If there is no &Help; text in the &SConstruct; or
+   &SConscript; files,
+   &SCons; will revert to displaying its
+   standard list that describes the &SCons; command-line
+   options.
+   This list is also always displayed whenever
+   the <literal>-H</literal> option is used.
+
+   </para>