dirkbaechle avatar dirkbaechle committed bcd5738

- removed *.in files from the user guide

Comments (0)

Files changed (82)

doc/user/actions.in

-<!--
-
-  __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.
-
--->
-
-<!--
-
-=head1 Build actions
-
-Cons supports several types of B<build actions> that can be performed
-to construct one or more target files.  Usually, a build action is
-a construction command, that is, a command-line string that invokes
-an external command.  Cons can also execute Perl code embedded in a
-command-line string, and even supports an experimental ability to build
-a target file by executing a Perl code reference directly.
-
-A build action is usually specified as the value of a construction
-variable:
-
-  $env = new cons(
-	CCCOM         => '%CC %CFLAGS %_IFLAGS -c %< -o %>',
-	LINKCOM       => '[perl] &link_executable("%>", "%<")',
-	ARCOM         => sub { my($env, $target, @sources) = @_;
-				 # code to create an archive
-				}
-  );
-
-A build action may be associated directly with one or more target files
-via the C<Command> method; see below.
-
-=head2 Construction commands
-
-A construction command goes through expansion of construction variables
-and C<%-> pseudo-variables, as described above, to create the actual
-command line that Cons will execute to generate the target file or
-files.
-
-After substitution occurs, strings of white space are converted into
-single blanks, and leading and trailing white space is eliminated. It
-is therefore currently not possible to introduce variable length white
-space in strings passed into a command.
-
-If a multi-line command string is provided, the commands are executed
-sequentially. If any of the commands fails, then none of the rest are
-executed, and the target is not marked as updated, i.e. a new signature is
-not stored for the target.
-
-Normally, if all the commands succeed, and return a zero status (or whatever
-platform-specific indication of success is required), then a new signature
-is stored for the target. If a command erroneously reports success even
-after a failure, then Cons will assume that the target file created by that
-command is accurate and up-to-date.
-
-The first word of each command string, after expansion, is assumed to be an
-executable command looked up on the C<PATH> environment variable (which is,
-in turn, specified by the C<ENV> construction variable). If this command is
-found on the path, then the target will depend upon it: the command will
-therefore be automatically built, as necessary. It's possible to write
-multi-part commands to some shells, separated by semi-colons. Only the first
-command word will be depended upon, however, so if you write your command
-strings this way, you must either explicitly set up a dependency (with the
-C<Depends> method), or be sure that the command you are using is a system
-command which is expected to be available. If it isn't available, you will,
-of course, get an error.
-
-Cons normally prints a command before executing it.  This behavior is
-suppressed if the first character of the command is C<@>.  Note that
-you may need to separate the C<@> from the command name or escape it to
-prevent C<@cmd> from looking like an array to Perl quote operators that
-perform interpolation:
-
-  # The first command line is incorrect,
-  # because "@cp" looks like an array
-  # to the Perl qq// function.
-  # Use the second form instead.
-  Command $env 'foo', 'foo.in', qq(
-	@cp %< tempfile
-	@ cp tempfile %>
-  );
-
-If there are shell meta characters anywhere in the expanded command line,
-such as C<E<lt>>, C<E<gt>>, quotes, or semi-colon, then the command
-will actually be executed by invoking a shell. This means that a command
-such as:
-
-  cd foo
-
-alone will typically fail, since there is no command C<cd> on the path. But
-the command string:
-
-  cd $<:d; tar cf $>:f $<:f
-
-when expanded will still contain the shell meta character semi-colon, and a
-shell will be invoked to interpret the command. Since C<cd> is interpreted
-by this sub-shell, the command will execute as expected.
-
-=head2 Perl expressions
-
-If any command (even one within a multi-line command) begins with
-C<[perl]>, the remainder of that command line will be evaluated by the
-running Perl instead of being forked by the shell.  If an error occurs
-in parsing the Perl code, or if the Perl expression returns 0 or undef,
-the command will be considered to have failed.  For example, here is a
-simple command which creates a file C<foo> directly from Perl:
-
-  $env = new cons();
-  Command $env 'foo',
-    qq([perl] open(FOO,'>foo');print FOO "hi\\n"; close(FOO); 1);
-
-Note that when the command is executed, you are in the same package as
-when the F<Construct> or F<Conscript> file was read, so you can call
-Perl functions you've defined in the same F<Construct> or F<Conscript>
-file in which the C<Command> appears:
-
-  $env = new cons();
-  sub create_file {
-	my $file = shift;
-	open(FILE, ">$file");
-	print FILE "hi\n";
-	close(FILE);
-	return 1;
-  }
-  Command $env 'foo', "[perl] &create_file('%>')";
-
-The Perl string will be used to generate the signature for the derived
-file, so if you change the string, the file will be rebuilt.  The contents
-of any subroutines you call, however, are not part of the signature,
-so if you modify a called subroutine such as C<create_file> above,
-the target will I<not> be rebuilt.  Caveat user.
-
-=head2 Perl code references [EXPERIMENTAL]
-
-Cons supports the ability to create a derived file by directly executing
-a Perl code reference.  This feature is considered EXPERIMENTAL and
-subject to change in the future.
-
-A code reference may either be a named subroutine referenced by the
-usual C<\&> syntax:
-
-  sub build_output {
-	my($env, $target, @sources) = @_;
-	print "build_output building $target\n";
-	open(OUT, ">$target");
-	foreach $src (@sources) {
-	    if (! open(IN, "<$src")) {
-		print STDERR "cannot open '$src': $!\n";
-		return undef;
-	    }
-	    print OUT, <IN>;
-	}
-	close(OUT);
-	return 1;
-  }
-  Command $env 'output', \&build_output;
-
-or the code reference may be an anonymous subroutine:
-
-  Command $env 'output', sub {
-	my($env, $target, @sources) = @_;
-	print "building $target\n";
-	open(FILE, ">$target");
-	print FILE "hello\n";
-	close(FILE);
-	return 1;
-  };
-
-To build the target file, the referenced subroutine is passed, in order:
-the construction environment used to generate the target; the path
-name of the target itself; and the path names of all the source files
-necessary to build the target file.
-
-The code reference is expected to generate the target file, of course,
-but may manipulate the source and target files in any way it chooses.
-The code reference must return a false value (C<undef> or C<0>) if
-the build of the file failed.  Any true value indicates a successful
-build of the target.
-
-Building target files using code references is considered EXPERIMENTAL
-due to the following current limitations:
-
-=over 4
-
-Cons does I<not> print anything to indicate the code reference is being
-called to build the file.  The only way to give the user any indication
-is to have the code reference explicitly print some sort of "building"
-message, as in the above examples.
-
-Cons does not generate any signatures for code references, so if the
-code in the reference changes, the target will I<not> be rebuilt.
-
-Cons has no public method to allow a code reference to extract
-construction variables.  This would be good to allow generalization of
-code references based on the current construction environment, but would
-also complicate the problem of generating meaningful signatures for code
-references.
-
-=back
-
-Support for building targets via code references has been released in
-this version to encourage experimentation and the seeking of possible
-solutions to the above limitations.
-
--->
-
-  <para>
-
-  &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>
-
-  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:
-
-  </para>
-
-  <sconstruct>
-    b = Builder(action = 'build &lt; $SOURCE &gt; $TARGET')
-  </sconstruct>
-
-  <para>
-
-  Is equivalent to:
-
-  </para>
-
-  <sconstruct>
-    b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
-  </sconstruct>
-
-  <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>
-
-  -->

doc/user/actions.xml

 
   </para>
 
-  <programlisting>
+  <sconstruct>
     b = Builder(action = 'build &lt; $SOURCE &gt; $TARGET')
-  </programlisting>
+  </sconstruct>
 
   <para>
 
 
   </para>
 
-  <programlisting>
+  <sconstruct>
     b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
-  </programlisting>
+  </sconstruct>
 
   <para>
 

doc/user/add-method.in

-<!--
-
-  __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>
-
-  The &AddMethod; function is used to add a method
-  to an environment.  It's typically used to add a "pseudo-builder,"
-  a function that looks like a &Builder; but
-  wraps up calls to multiple other &Builder;s
-  or otherwise processes its arguments
-  before calling one or more &Builder;s.
-  In the following example,
-  we want to install the program into the standard
-  <filename>/usr/bin</filename> directory hierarchy,
-  but also copy it into a local <filename>install/bin</filename>
-  directory from which a package might be built:
-
-  </para>
-
-  <scons_example name="ex1">
-     <file name="SConstruct" printme="1">
-     def install_in_bin_dirs(env, source):
-         """Install source in both bin dirs"""
-         i1 = env.Install("$BIN", source)
-         i2 = env.Install("$LOCALBIN", source)
-         return [i1[0], i2[0]] # Return a list, like a normal builder
-     env = Environment(BIN='__ROOT__/usr/bin', LOCALBIN='#install/bin')
-     env.AddMethod(install_in_bin_dirs, "InstallInBinDirs")
-     env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs     
-     </file>
-     <file name="hello.c">
-     int main() { printf("Hello, world!\n"); }
-     </file>
-  </scons_example>
-
-  <para>
-  This produces the following:
-  </para>
-
-  <scons_output example="ex1">
-    <scons_output_command>scons -Q /</scons_output_command>
-  </scons_output>
-
-  <para>
-
-  As mentioned, a pseudo-builder also provides more flexibility
-  in parsing arguments than you can get with a &Builder;.
-  The next example shows a pseudo-builder with a
-  named argument that modifies the filename, and a separate argument
-  for the resource file (rather than having the builder figure it out
-  by file extension).  This example also demonstrates using the global
-  &AddMethod; function to add a method to the global Environment class,
-  so it will be used in all subsequently created environments.
-
-  </para>
-
-  <scons_example name="ex2">
-     <file name="SConstruct" printme="1">
-     def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
-         """Build the test program;
-         prepends "test_" to src and target,
-         and puts target into testdir."""
-         srcfile = "test_%s.c" % testfile
-         target = "%s/test_%s" % (testdir, testfile)
-         if env['PLATFORM'] == 'win32':
-             resfile = env.RES(resourcefile)
-             p = env.Program(target, [srcfile, resfile])
-         else:
-             p = env.Program(target, srcfile)
-         return p
-     AddMethod(Environment, BuildTestProg)
-
-     env = Environment()
-     env.BuildTestProg('stuff', resourcefile='res.rc')
-     </file>
-     <file name="test_stuff.c">
-     int main() { printf("Hello, world!\n"); }
-     </file>
-     <file name="res.rc">
-     res.rc
-     </file>
-  </scons_example>
-
-  <para>
-  This produces the following on Linux:
-  </para>
-
-  <scons_output example="ex2">
-    <scons_output_command>scons -Q</scons_output_command>
-  </scons_output>
-
-  <para>
-  And the following on Windows:
-  </para>
-
-  <scons_output example="ex2" os="win32">
-    <scons_output_command>scons -Q</scons_output_command>
-  </scons_output>
-
-  <para>
-  Using &AddMethod; is better than just adding an instance method
-  to a &consenv; because it gets called as a proper method,
-  and because &AddMethod; provides for copying the method
-  to any clones of the &consenv; instance.
-  </para>

doc/user/add-method.xml

 
   </para>
 
-  <programlisting>
+  <scons_example name="ex1">
+     <file name="SConstruct" printme="1">
      def install_in_bin_dirs(env, source):
          """Install source in both bin dirs"""
          i1 = env.Install("$BIN", source)
          i2 = env.Install("$LOCALBIN", source)
          return [i1[0], i2[0]] # Return a list, like a normal builder
-     env = Environment(BIN='/usr/bin', LOCALBIN='#install/bin')
+     env = Environment(BIN='__ROOT__/usr/bin', LOCALBIN='#install/bin')
      env.AddMethod(install_in_bin_dirs, "InstallInBinDirs")
      env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs     
-  </programlisting>
+     </file>
+     <file name="hello.c">
+     int main() { printf("Hello, world!\n"); }
+     </file>
+  </scons_example>
 
   <para>
   This produces the following:
   </para>
 
-  <screen>
-    % <userinput>scons -Q /</userinput>
-    cc -o hello.o -c hello.c
-    cc -o hello hello.o
-    Install file: "hello" as "/usr/bin/hello"
-    Install file: "hello" as "install/bin/hello"
-  </screen>
+  <scons_output example="ex1">
+    <scons_output_command>scons -Q /</scons_output_command>
+  </scons_output>
 
   <para>
 
 
   </para>
 
-  <programlisting>
+  <scons_example name="ex2">
+     <file name="SConstruct" printme="1">
      def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
          """Build the test program;
          prepends "test_" to src and target,
 
      env = Environment()
      env.BuildTestProg('stuff', resourcefile='res.rc')
-  </programlisting>
+     </file>
+     <file name="test_stuff.c">
+     int main() { printf("Hello, world!\n"); }
+     </file>
+     <file name="res.rc">
+     res.rc
+     </file>
+  </scons_example>
 
   <para>
   This produces the following on Linux:
   </para>
 
-  <screen>
-    % <userinput>scons -Q</userinput>
-    cc -o test_stuff.o -c test_stuff.c
-    cc -o tests/test_stuff test_stuff.o
-  </screen>
+  <scons_output example="ex2">
+    <scons_output_command>scons -Q</scons_output_command>
+  </scons_output>
 
   <para>
   And the following on Windows:
   </para>
 
-  <screen>
-    C:\><userinput>scons -Q</userinput>
-    rc /fores.res res.rc
-    cl /Fotest_stuff.obj /c test_stuff.c /nologo
-    link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res
-    embedManifestExeCheck(target, source, env)
-  </screen>
+  <scons_output example="ex2" os="win32">
+    <scons_output_command>scons -Q</scons_output_command>
+  </scons_output>
 
   <para>
   Using &AddMethod; is better than just adding an instance method

doc/user/alias.in

-<!--
-
-  __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>
-
-  We've already seen how you can use the &Alias;
-  function to create a target named <literal>install</literal>:
-
-  </para>
-
-  <scons_example name="ex1">
-     <file name="SConstruct" printme="1">
-     env = Environment()
-     hello = env.Program('hello.c')
-     env.Install('__ROOT__/usr/bin', hello)
-     env.Alias('install', '__ROOT__/usr/bin')
-     </file>
-     <file name="hello.c">
-     int main() { printf("Hello, world!\n"); }
-     </file>
-  </scons_example>
-
-  <para>
-
-  You can then use this alias on the command line
-  to tell &SCons; more naturally that you want to install files:
-
-  </para>
-
-  <scons_output example="ex1" os="posix">
-     <scons_output_command>scons -Q install</scons_output_command>
-  </scons_output>
-
-  <para>
-
-  Like other &Builder; methods, though,
-  the &Alias; method returns an object
-  representing the alias being built.
-  You can then use this object as input to anothother &Builder;.
-  This is especially useful if you use such an object
-  as input to another call to the &Alias; &Builder;,
-  allowing you to create a hierarchy
-  of nested aliases:
-
-  </para>
-
-  <scons_example name="ex2">
-     <file name="SConstruct" printme="1">
-     env = Environment()
-     p = env.Program('foo.c')
-     l = env.Library('bar.c')
-     env.Install('__ROOT__/usr/bin', p)
-     env.Install('__ROOT__/usr/lib', l)
-     ib = env.Alias('install-bin', '__ROOT__/usr/bin')
-     il = env.Alias('install-lib', '__ROOT__/usr/lib')
-     env.Alias('install', [ib, il])
-     </file>
-     <file name="foo.c">
-     int main() { printf("foo.c\n"); }
-     </file>
-     <file name="bar.c">
-     void bar() { printf("bar.c\n"); }
-     </file>
-  </scons_example>
-
-  <para>
-
-  This example defines separate <literal>install</literal>,
-  <literal>install-bin</literal>,
-  and <literal>install-lib</literal> aliases,
-  allowing you finer control over what gets installed:
-
-  </para>
-
-  <scons_output example="ex2" os="posix">
-     <scons_output_command>scons -Q install-bin</scons_output_command>
-     <scons_output_command>scons -Q install-lib</scons_output_command>
-     <scons_output_command>scons -Q -c __ROOT__/</scons_output_command>
-     <scons_output_command>scons -Q install</scons_output_command>
-  </scons_output>

doc/user/alias.xml

 
   </para>
 
-  <programlisting>
+  <scons_example name="ex1">
+     <file name="SConstruct" printme="1">
      env = Environment()
      hello = env.Program('hello.c')
-     env.Install('/usr/bin', hello)
-     env.Alias('install', '/usr/bin')
-  </programlisting>
+     env.Install('__ROOT__/usr/bin', hello)
+     env.Alias('install', '__ROOT__/usr/bin')
+     </file>
+     <file name="hello.c">
+     int main() { printf("Hello, world!\n"); }
+     </file>
+  </scons_example>
 
   <para>
 
 
   </para>
 
-  <screen>
-     % <userinput>scons -Q install</userinput>
-     cc -o hello.o -c hello.c
-     cc -o hello hello.o
-     Install file: "hello" as "/usr/bin/hello"
-  </screen>
+  <scons_output example="ex1" os="posix">
+     <scons_output_command>scons -Q install</scons_output_command>
+  </scons_output>
 
   <para>
 
 
   </para>
 
-  <programlisting>
+  <scons_example name="ex2">
+     <file name="SConstruct" printme="1">
      env = Environment()
      p = env.Program('foo.c')
      l = env.Library('bar.c')
-     env.Install('/usr/bin', p)
-     env.Install('/usr/lib', l)
-     ib = env.Alias('install-bin', '/usr/bin')
-     il = env.Alias('install-lib', '/usr/lib')
+     env.Install('__ROOT__/usr/bin', p)
+     env.Install('__ROOT__/usr/lib', l)
+     ib = env.Alias('install-bin', '__ROOT__/usr/bin')
+     il = env.Alias('install-lib', '__ROOT__/usr/lib')
      env.Alias('install', [ib, il])
-  </programlisting>
+     </file>
+     <file name="foo.c">
+     int main() { printf("foo.c\n"); }
+     </file>
+     <file name="bar.c">
+     void bar() { printf("bar.c\n"); }
+     </file>
+  </scons_example>
 
   <para>
 
 
   </para>
 
-  <screen>
-     % <userinput>scons -Q install-bin</userinput>
-     cc -o foo.o -c foo.c
-     cc -o foo foo.o
-     Install file: "foo" as "/usr/bin/foo"
-     % <userinput>scons -Q install-lib</userinput>
-     cc -o bar.o -c bar.c
-     ar rc libbar.a bar.o
-     ranlib libbar.a
-     Install file: "libbar.a" as "/usr/lib/libbar.a"
-     % <userinput>scons -Q -c /</userinput>
-     Removed foo.o
-     Removed foo
-     Removed /usr/bin/foo
-     Removed bar.o
-     Removed libbar.a
-     Removed /usr/lib/libbar.a
-     % <userinput>scons -Q install</userinput>
-     cc -o foo.o -c foo.c
-     cc -o foo foo.o
-     Install file: "foo" as "/usr/bin/foo"
-     cc -o bar.o -c bar.c
-     ar rc libbar.a bar.o
-     ranlib libbar.a
-     Install file: "libbar.a" as "/usr/lib/libbar.a"
-  </screen>
+  <scons_output example="ex2" os="posix">
+     <scons_output_command>scons -Q install-bin</scons_output_command>
+     <scons_output_command>scons -Q install-lib</scons_output_command>
+     <scons_output_command>scons -Q -c __ROOT__/</scons_output_command>
+     <scons_output_command>scons -Q install</scons_output_command>
+  </scons_output>

doc/user/ant.in

-<!--
-
-  __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>
-
-   XXX
-
- </para>
-
- <section>
- <title>Differences Between &Ant; and &SCons;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>
-
- <section>
- <title>Advantages of &SCons; Over &Ant;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>

doc/user/build-install.in

-<!--
-
-  __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>
-
-  This chapter will take you through the basic steps
-  of installing &SCons; on your system,
-  and building &SCons; if you don't have a
-  pre-built package available
-  (or simply prefer the flexibility of building it yourself).
-  Before that, however, this chapter will also describe the basic steps
-  involved in installing Python on your system,
-  in case that is necessary.
-  Fortunately, both &SCons; and Python
-  are very easy to install on almost any system,
-  and Python already comes installed on many systems.
-
-  </para>
-
-  <!--
-
-  <para>
-
-  Lastly, this chapter also contains a section that
-  provides a brief overview of the Python programming language,
-  which is the language used to implement &SCons;,
-  and which forms the basis of the &SCons; configuration files.
-  Becoming familiar with some Python concepts will make it easier
-  to understand many of the examples in this User's Guide.
-  Nevertheless, it <emphasis>is</emphasis> possible
-  to configure simple &SCons; builds without knowing Python,
-  so you can skip this section if you
-  want to dive in and pick up things
-  by example- -or, of course, if you are 
-  already familiar with Python.
-
-  </para>
-
-  -->
-
-  <section>
-  <title>Installing Python</title>
-
-    <para>
-
-    Because &SCons; is written in Python,
-    you must obviously have Python installed on your system
-    to use &SCons;.
-    Before you try to install Python,
-    you should check to see if Python is already
-    available on your system  by typing
-    <userinput>python -V</userinput>
-    (capital 'V')
-    or
-    <userinput>python --version</userinput>
-    at your system's command-line prompt.
-
-    </para>
-
-    <screen>
-       $ <userinput>python -V</userinput>
-       Python 2.5.1
-    </screen>
-
-    <para>
-
-    And on a Windows system with Python installed:
-
-    </para>
-
-    <screen>
-       C:\><userinput>python -V</userinput>
-       Python 2.5.1
-    </screen>
-
-    <para>
-
-    If Python is not installed on your system,
-    you will see an error message
-    stating something like "command not found"
-    (on UNIX or Linux)
-    or "'python' is not recognized
-    as an internal or external command, operable progam or batch file"
-    (on Windows).
-    In that case, you need to install Python
-    before you can install &SCons;.
-
-    </para>
-
-    <para>
-
-    The standard location for information
-    about downloading and installing Python is
-    <ulink url="http://www.python.org/download/">http://www.python.org/download/</ulink>.
-    See that page for information about
-    how to download and install Python on your system.
-
-    </para>
-
-    <para>
-
-    &SCons; will work with any 2.x version of Python from 2.4 on;
-    3.0 and later are not yet supported.
-    If you need to install Python and have a choice,
-    we recommend using the most recent 2.x Python version available.
-    Newer Pythons have significant improvements
-    that help speed up the performance of &SCons;.
-
-    </para>
-
-  </section>
-
-  <section>
-  <title>Installing &SCons; From Pre-Built Packages</title>
-
-    <para>
-
-    &SCons; comes pre-packaged for installation on a number of systems,
-    including Linux and Windows systems.
-    You do not need to read this entire section,
-    you should need to read only the section
-    appropriate to the type of system you're running on.
-
-    </para>
-
-    <section>
-    <title>Installing &SCons; on Red Hat (and Other RPM-based) Linux Systems</title>
-
-      <para>
-
-      &SCons; comes in RPM (Red Hat Package Manager) format,
-      pre-built and ready to install on Red Hat Linux,
-      Fedora,
-      or any other Linux distribution that uses RPM.
-      Your distribution may
-      already have an &SCons; RPM built specifically for it;
-      many do, including SUSE, Mandrake and Fedora.
-      You can check for the availability of an &SCons; RPM
-      on your distribution's download servers,
-      or by consulting an RPM search site like
-      <ulink url="http://www.rpmfind.net/">http://www.rpmfind.net/</ulink> or
-      <ulink url="http://rpm.pbone.net/">http://rpm.pbone.net/</ulink>.
-
-      </para>
-
-      <para>
-
-      If your distribution supports installation via
-      <application>yum</application>,
-      you should be able to install &SCons; by running:
-
-      </para>
-
-      <screen>
-        # <userinput>yum install scons</userinput>
-      </screen>
-
-      <para>
-
-      If your Linux distribution does not already have
-      a specific &SCons; RPM file,
-      you can download and install from the
-      generic RPM provided by the &SCons; project.
-      This will install the 
-      SCons script(s) in <filename>/usr/bin</filename>,
-      and the SCons library modules in
-      <filename>/usr/lib/scons</filename>.
-
-      </para>
-
-      <para>
-
-      To install from the command line, simply download the
-      appropriate <filename>.rpm</filename> file,
-      and then run:
-
-      </para>
-
-      <screen>
-        # <userinput>rpm -Uvh scons-__VERSION__-1.noarch.rpm</userinput>
-      </screen>
-
-      <para>
-
-      Or, you can use a graphical RPM package manager.
-      See your package manager application's documention
-      for specific instructions about
-      how to use it to install a downloaded RPM.
-
-      </para>
-
-    </section>
-
-    <section>
-    <title>Installing &SCons; on Debian Linux Systems</title>
-
-      <para>
-
-      Debian Linux systems use a different package management
-      format that also makes it very easy to install &SCons;.
-
-      </para>
-
-      <para>
-
-      If your system is connected to the Internet,
-      you can install the latest official Debian package
-      by running:
-
-      </para>
-
-      <screen>
-        # <userinput>apt-get install scons</userinput>
-      </screen>
-
-      <!--
-
-      <para>
-
-      Alternatively,
-      you can download the Debian package built
-      by the &SCons; project
-      and install it manually by running:
-
-      </para>
-
-      <screen>
-        # <userinput>db-XXX scons-*.deb</userinput>
-      </screen>
-
-      -->
-
-    </section>
-
-    <section>
-    <title>Installing &SCons; on Windows Systems</title>
-
-      <para>
-
-      &SCons; provides a Windows installer
-      that makes installation extremely easy.
-      Download the <filename>scons-__VERSION__.win32.exe</filename>
-      file from the &SCons; download page at
-      <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>.
-      Then all you need to do is execute the file
-      (usually by clicking on its icon in Windows Explorer).
-      These will take you through a small
-      sequence of windows that will install
-      &SCons; on your system.
-
-      <!--
-      Things are a little more complicated
-      if you are using the Cygwin version of Python.
-      This is because Cygwin
-      tries to make a Windows system look more
-      POSIX-like (or UNIX-like or Linux-like, if you prefer)
-      by having the Cygwin utilities,
-      including Cygwin Python,
-      interpret file name arguments on the command line
-      using the forward-slash (<filename>/</filename>)
-      as the directory separator,
-      instead of the normal Windows behavior of the
-      backslash (<filename>\</filename>) as the directory separator.
-      -->
-
-      </para>
-
-      <!--
-
-      <section>
-      <title>Installing &SCons; on Windows Systems Without Cygwin Python</title>
-
-        <para>
-
-        XXX
-
-        </para>
-
-      </section>
-
-      <section>
-      <title>Installing &SCons; on Windows Systems With Cygwin Python</title>
-
-        <para>
-
-        XXX
-
-        </para>
-
-      </section>
-
-      -->
-
-      <!--
-
-      XXX - don't have the kinks worked out on how to
-      get these to display properly in all formats,
-      so comment them out for now.
-
-      <screenshot>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center">
-        </imageobject>
-      </mediaobject>
-      </screenshot>
-
-      <screenshot>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center">
-        </imageobject>
-      </mediaobject>
-      </screenshot>
-
-      <screenshot>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center">
-        </imageobject>
-      </mediaobject>
-      </screenshot>
-
-      <screenshot>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
-        </imageobject>
-      </mediaobject>
-      </screenshot>
-
-      -->
-
-    </section>
-
-  </section>
-
-  <section>
-  <title>Building and Installing &SCons; on Any System</title>
-
-    <para>
-
-    If a pre-built &SCons; package is not available for your system,
-    then you can still easily build and install &SCons; using the native
-    Python <filename>distutils</filename> package.
-
-    </para>
-
-    <para>
-
-    The first step is to download either the
-    <filename>scons-__VERSION__.tar.gz</filename>
-    or <filename>scons-__VERSION__.zip</filename>,
-    which are available from the SCons download page at
-    <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
-
-    </para>
-
-    <para>
-
-    Unpack the archive you downloaded,
-    using a utility like <application>tar</application>
-    on Linux or UNIX,
-    or <application>WinZip</application> on Windows.
-    This will create a directory called
-    <filename>scons-__VERSION__</filename>,
-    usually in your local directory.
-    Then change your working directory to that directory
-    and install &SCons; by executing the following commands:
-
-    </para>
-
-    <screen>
-      # <userinput>cd scons-__VERSION__</userinput>
-      # <userinput>python setup.py install</userinput>
-    </screen>
-
-    <para>
-
-    This will build &SCons;,
-    install the &scons; script
-    in the python which is used to run the setup.py's scripts directory
-    (<filename>/usr/local/bin</filename> or
-    <filename>C:\Python25\Scripts</filename>),
-    and will install the &SCons; build engine
-    in the corresponding library directory for the python used
-    (<filename>/usr/local/lib/scons</filename> or
-    <filename>C:\Python25\scons</filename>).
-    Because these are system directories,
-    you may need root (on Linux or UNIX) or Administrator (on Windows)
-    privileges to install &SCons; like this.
-
-    </para>
-
-    <!--
-
-    <section>
-    <title>Building and Installing &SCons; in the Standard Python Library Directories</title>
-
-      <para>
-
-      XXX
-
-      </para>
-
-    </section>
-
-    -->
-
-    <section>
-    <title>Building and Installing Multiple Versions of &SCons; Side-by-Side</title>
-
-      <para>
-
-      The &SCons; <filename>setup.py</filename> script
-      has some extensions that support
-      easy installation of multiple versions of &SCons;
-      in side-by-side locations.
-      This makes it easier to download and
-      experiment with different versions of &SCons;
-      before moving your official build process to a new version,
-      for example.
-
-      </para>
-
-      <para>
-
-      To install &SCons; in a version-specific location,
-      add the <option>--version-lib</option> option
-      when you call <filename>setup.py</filename>:
-
-      </para>
-
-      <screen>
-        # <userinput>python setup.py install --version-lib</userinput>
-      </screen>
-
-      <para>
-
-      This will install the &SCons; build engine
-      in the
-      <filename>/usr/lib/scons-__VERSION__</filename>
-      or
-      <filename>C:\Python25\scons-__VERSION__</filename>
-      directory, for example.
-
-      </para>
-
-      <para>
-
-      If you use the <option>--version-lib</option> option
-      the first time you install &SCons;,
-      you do not need to specify it each time you install
-      a new version.
-      The &SCons; <filename>setup.py</filename> script
-      will detect the version-specific directory name(s)
-      and assume you want to install all versions
-      in version-specific directories.
-      You can override that assumption in the future
-      by explicitly specifying the <option>--standalone-lib</option> option.
-
-      </para>
-
-    </section>
-
-    <section>
-    <title>Installing &SCons; in Other Locations</title>
-
-      <para>
-
-      You can install &SCons; in locations other than
-      the default by specifying the <option>--prefix=</option> option:
-
-      </para>
-
-      <screen>
-        # <userinput>python setup.py install --prefix=/opt/scons</userinput>
-      </screen>
-
-      <para>
-
-      This would
-      install the <application>scons</application> script in
-      <filename>/opt/scons/bin</filename>
-      and the build engine in 
-      <filename>/opt/scons/lib/scons</filename>,
-
-      </para>
-
-      <para>
-
-      Note that you can specify both the <option>--prefix=</option>
-      and the <option>--version-lib</option> options
-      at the same type,
-      in which case <filename>setup.py</filename>
-      will install the build engine
-      in a version-specific directory
-      relative to the specified prefix.
-      Adding <option>--version-lib</option> to the
-      above example would install the build engine in
-      <filename>/opt/scons/lib/scons-__VERSION__</filename>.
-
-      </para>
-
-    </section>
-
-    <section>
-    <title>Building and Installing &SCons; Without Administrative Privileges</title>
-
-      <para>
-
-      If you don't have the right privileges to install &SCons;
-      in a system location,
-      simply use the <literal>--prefix=</literal> option
-      to install it in a location of your choosing.
-      For example,
-      to install &SCons; in appropriate locations
-      relative to the user's <literal>$HOME</literal> directory,
-      the &scons; script in
-      <filename>$HOME/bin</filename>
-      and the build engine in 
-      <filename>$HOME/lib/scons</filename>,
-      simply type:
-
-      </para>
-
-      <screen>
-        $ <userinput>python setup.py install --prefix=$HOME</userinput>
-      </screen>
-
-      <para>
-
-      You may, of course, specify any other location you prefer,
-      and may use the <option>--version-lib</option> option
-      if you would like to install version-specific directories
-      relative to the specified prefix.
-
-      </para>
-
-      <para>
-
-      This can also be used to experiment with a newer
-      version of &SCons; than the one installed
-      in your system locations.
-      Of course, the location in which you install the
-      newer version of the &scons; script
-      (<filename>$HOME/bin</filename> in the above example)
-      must be configured in your &PATH; variable
-      before the directory containing
-      the system-installed version
-      of the &scons; script.
-
-      </para>
-
-    </section>
-
-  </section>
-
-  <!--
-
-  <section>
-  <title>Python Basics</title>
-
-    <para>
-
-    This section will provide a brief overview of
-    the Python programming language.
-    Skip this section if you are already familiar with Python
-    (or you're really intent on diving into &SCons;
-    and just picking up things as you go).
-
-    </para>
-
-    <para>
-
-    Python has a lot of good
-    documentation freely available on-line
-    to help you get started.
-    The standard tutorial is available at XXX.
-
-
-    </para>
-
-    <para>
-
-    Python is very easy to pick up.
-
-    </para>
-
-    <para>
-
-    Python variables must be assigned to before they can be referenced.
-
-    </para>
-
-    <para>
-
-    Assignment is like most programming languages:
-
-    x = 1 + 2
-    z = 3 * x
-
-    </para>
-
-    <para>
-
-    Function calls look like most language function calls:
-
-    a = f(g)
-
-    </para>
-
-    <para>
-
-    Define functions like so:
-
-        def func(arg1, arg2):
-            return arg1 * arg 2
-
-    The number of parameters
-
-    </para>
-
-    <para>
-
-    Strings can be enclosed in single quotes or double quotes,
-    backslashes are used to escape characters,
-    triple-quote syntax lets you include quotes and newlines,
-    raw strings begin with 'r'.
-
-    </para>
-
-    <para>
-
-    Lists are enclosed in square brackets,
-    list items are separated by commas.
-    List references use square brackets and integer index values,
-    slice notation lets you select, delete or replace a range.
-
-    </para>
-
-    <para>
-
-    Dictionaries (hashes) are enclosed in curly brackets,
-    : separates keys from values,
-    , separates items.
-    Dictionary values are referenced using square brackets.
-
-    </para>
-
-    <para>
-
-    Access class attributes (including methods) using a '.'.
-
-    </para>
-
-    <para>
-
-    if: statements look like
-
-    elif: statements look like
-
-    else: statements look like
-
-    </para>
-
-    <para>
-
-    for: statements look like
-
-    while: statements look like
-
-    break statements look like
-    
-    continue statements look like
-
-    </para>
-
-    <para>
-
-    pass
-
-    </para>
-
-  </section>
-
-  -->

doc/user/builders-built-in.in

-<!--
-
-  __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>
-
-  &SCons; provides the ability to build a lot of different
-  types of files right "out of the box."
-  So far, we've been using &SCons;' ability to build
-  programs, objects and libraries to
-  illustrate much of the underlying functionality of &SCons;
-  This section will describe all of the different
-  types of files that you can build with &SCons;,
-  and the built-in &Builder; objects used to build them.
-  By default, all of the  &Builder; objects in this section
-  can be built either with or without an explicit
-  construction environment.
-
-  </para>
-
-  <section>
-  <title>Programs:  the &Program; Builder</title>
-
-    <para>
-
-    As we've seen, the &b-link-Program; Builder
-    is used to build an executable program.
-    The &source; argument is one or more
-    source-code files or object files,
-    and the &target; argument is the
-    name of the executable program name to be created.
-    For example:
-
-    </para>
-
-    <programlisting>
-      Program('prog', 'file1.o')
-    </programlisting>
-
-    <para>
-
-    Will create the &prog;
-    executable on a POSIX system,
-    the &prog_exe; executable on a Windows system.
-
-    </para>
-
-    <para>
-
-    The target file's prefix and suffix may be omitted,
-    and the values from the
-    &cv-link-PROGPREFIX;
-    and
-    &cv-link-PROGSUFFIX;
-    construction variables
-    will be appended appropriately.
-    For example:
-
-    </para>
-
-    <programlisting>
-      env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx')
-      env.Program('prog', ['file1.o', 'file2.o'])
-    </programlisting>
-
-    <para>
-
-    Will create a program named
-    <filename>myprog.xxx</filename>
-    regardless of the system on which it is run.
-
-    </para>
-
-    <para>
-
-    If you omit the &target;,
-    the base of the first input
-    file name specified
-    becomes the base of the target
-    program created.
-    For example:
-
-    </para>
-
-    <programlisting>
-      Program(['hello.c', 'goodbye.c'])
-    </programlisting>
-
-    <para>
-
-    Will create the &hello;
-    executable on a POSIX system,
-    the &hello_exe; executable on a Windows system.
-
-    </para>
-
-    <para>
-
-    Two construction variables control what libraries
-    will be linked with the resulting program.
-    The &cv-link-LIBS; variable is a list of the names of
-    libraries that will be linked into any programs,
-    and the &cv-link-LIBPATH; variables is a list of
-    directories that will be searched for
-    the specified libraries.
-    &SCons; will construct the right command-line
-    options for the running system.
-    For example:
-
-    </para>
-
-    <scons_example name="libs">
-      <file name="SConstruct" printme="1">
-      env = Environment(LIBS = ['foo1', 'foo2'],
-                        LIBPATH = ['/usr/dir1', 'dir2'])
-      env.Program(['hello.c', 'goodbye.c'])
-      </file>
-      <file name="hello.c">
-      int hello() { printf("Hello, world!\n"); }
-      </file>
-      <file name="goodbye.c">
-      int goodbye() { printf("Goodbye, world!\n"); }
-      </file>
-    </scons_example>
-
-    <para>
-
-    Will execute as follows on a POSIX system:
-
-    </para>
-
-    <scons_output example="libs" os="posix">
-      <scons_output_command>scons -Q</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    And execute as follows on a Windows system:
-
-    </para>
-
-    <scons_output example="libs" os="win32">
-      <scons_output_command>scons -Q</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    The &cv-LIBS; construction variable
-    is turned into command line options
-    by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX;
-    construction variables to the beginning and end,
-    respectively, of each specified library.
-
-    </para>
-
-    <para>
-
-    The &cv-LIBPATH; construction variable
-    is turned into command line options
-    by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX;
-    construction variables to the beginning and end,
-    respectively, of each specified library.
-
-    </para>
-
-    <para>
-
-    Other relevant construction variables
-    include those used by the &b-link-Object;
-    builders to affect how the
-    source files specified as input to the &t-Program;
-    builders are turned into object files;
-    see the next section.
-
-    </para>
-
-    <para>
-
-    The command line used to control how a program is linked
-    is specified by the &cv-link-LINKCOM; construction variable.
-    By default, it uses the
-    &cv-link-LINK; construction variable
-    and the &cv-link-LINKFLAGS; construction variable.
-
-    </para>
-
-  </section>
-
-  <section>
-  <title>Object-File Builders</title>
-
-    <para>
-
-    &SCons; provides separate Builder objects
-    to create static and shared object files.
-    The distinction becomes especially important when
-    archiving object files into different types of libraries.
-
-    </para>
-
-    <section>
-    <title>The &StaticObject; Builder</title>
-
-      <para>
-
-      The &b-link-StaticObject; Builder
-      is used to build an object file
-      suitable for static linking into a program,
-      or for inclusion in a static library.
-      The &source; argument is a single source-code file,
-      and the &target; argument is the
-      name of the static object file to be created.
-      For example:
-
-      </para>
-
-      <programlisting>
-        StaticObject('file', 'file.c')
-      </programlisting>
-
-      <para>
-
-      Will create the &file_o;
-      object file on a POSIX system,
-      the &file_obj; executable on a Windows system.
-
-      </para>
-
-      <para>
-
-      The target file's prefix and suffix may be omitted,
-      and the values from the
-      &cv-link-OBJPREFIX;
-      and
-      &cv-link-OBJSUFFIX;
-      construction variables
-      will be appended appropriately.
-      For example:
-
-      </para>
-
-      <programlisting>
-        env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx')
-        env.StaticObject('file', 'file.c')
-      </programlisting>
-
-      <para>
-
-      Will create an object file named
-      <filename>myfile.xxx</filename>
-      regardless of the system on which it is run.
-
-      </para>
-
-      <para>
-
-      If you omit the &target;,
-      the base of the first input
-      file name specified
-      beomces the base of the name
-      of the static object file to be created.
-      For example:
-
-      </para>
-
-      <programlisting>
-        StaticObject('file.c')
-      </programlisting>
-
-      <para>
-
-      Will create the &file_o;
-      executable on a POSIX system,
-      the &file_obj; executable on a Windows system.
-
-      </para>
-
-    </section>
-
-    <section>
-    <title>The &SharedObject; Builder</title>
-
-      <para>
-
-      The &b-link-SharedObject; Builder
-      is used to build an object file
-      suitable for shared linking into a program,
-      or for inclusion in a shared library.
-      The &source; argument is a single source-code file,
-      and the &target; argument is the
-      name of the shared object file to be created.
-      For example:
-
-      </para>
-
-      <programlisting>
-        SharedObject('file', 'file.c')
-      </programlisting>
-
-      <para>
-
-      Will create the &file_o;
-      object file on a POSIX system,
-      the &file_obj; executable on a Windows system.
-
-      </para>
-
-      <para>
-
-      The target file's prefix and suffix may be omitted,
-      and the values from the
-      &cv-link-SHOBJPREFIX;
-      and
-      &cv-link-SHOBJSUFFIX;
-      construction variables
-      will be appended appropriately.
-      For example:
-
-      </para>
-
-      <programlisting>
-        env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx')
-        env.SharedObject('file', 'file.c')
-      </programlisting>
-
-      <para>
-
-      Will create an object file named
-      <filename>myfile.xxx</filename>
-      regardless of the system on which it is run.
-
-      </para>
-
-      <para>
-
-      If you omit the &target;,
-      the base of the first input
-      file name specified
-      becomes the base of the name
-      of the shared object file to be created.
-      For example:
-
-      </para>
-
-      <programlisting>
-        SharedObject('file.c')
-      </programlisting>
-
-      <para>
-
-      Will create the &file_o;
-      executable on a POSIX system,
-      the &file_obj; executable on a Windows system.
-
-      </para>
-
-    </section>
-
-    <section>
-    <title>The &Object; Builder</title>
-
-      <para>
-
-      The &b-link-Object; Builder is a synonym for &b-link-StaticObject;
-      and is completely equivalent.
-
-      </para>
-
-    </section>
-
-  </section>
-
-  <section>
-  <title>Library Builders</title>
-
-    <para>
-
-    &SCons; provides separate Builder objects
-    to create static and shared libraries.
-
-    </para>
-
-    <section>
-    <title>The &StaticLibrary; Builder</title>
-
-      <para>
-
-      The &b-link-StaticLibrary; Builder
-      is used to create a library
-      suitable for static linking into a program.
-      The &source; argument is one or more
-      source-code files or object files,
-      and the &target; argument is the
-      name of the static library to be created.
-      For example:
-
-      </para>
-
-      <programlisting>
-        StaticLibrary('foo', ['file1.c', 'file2.c'])
-      </programlisting>
-
-      <para>
-
-      The target file's prefix and suffix may be omitted,
-      and the values from the
-      &cv-link-LIBPREFIX;
-      and
-      &cv-link-LIBSUFFIX;
-      construction variables
-      will be appended appropriately.
-      For example:
-
-      </para>
-
-      <programlisting>
-        env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx')
-        env.StaticLibrary('lib', ['file1.o', 'file2.o'])
-      </programlisting>
-
-      <para>
-
-      Will create an object file named
-      <filename>mylib.xxx</filename>
-      regardless of the system on which it is run.
-
-      </para>
-
-      <programlisting>
-        StaticLibrary('foo', ['file1.c', 'file2.c'])
-      </programlisting>
-
-      <para>
-
-      If you omit the &target;,
-      the base of the first input
-      file name specified
-      becomes the base of the name of the static object file to be created.
-      For example:
-
-      </para>
-
-      <programlisting>
-        StaticLibrary(['file.c', 'another.c'])
-      </programlisting>
-
-      <para>
-
-      Will create the &libfile_a;
-      library on a POSIX system,
-      the &file_lib; library on a Windows system.
-
-      </para>
-
-    </section>
-
-    <section>
-    <title>The &SharedLibrary; Builder</title>
-
-      <para>
-
-      The &b-link-SharedLibrary; Builder
-      is used to create a shared library
-      suitable for linking with a program.
-      The &source; argument is one or more
-      source-code files or object files,
-      and the &target; argument is the
-      name of the shared library to be created.
-      For example:
-
-      </para>
-
-      <programlisting>
-        SharedLibrary('foo', ['file1.c', 'file2.c'])
-      </programlisting>
-
-      <para>
-
-      The target file's prefix and suffix may be omitted,
-      and the values from the
-      &cv-link-SHLIBPREFIX;
-      and
-      &cv-link-SHLIBSUFFIX;
-      construction variables
-      will be appended appropriately.
-      For example:
-
-      </para>
-
-      <programlisting>
-        env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx')
-        env.SharedLibrary('shared', ['file1.o', 'file2.o'])
-      </programlisting>
-
-      <para>
-
-      Will create an object file named
-      <filename>myshared.xxx</filename>
-      regardless of the system on which it is run.
-
-      </para>
-
-      <programlisting>
-        SharedLibrary('foo', ['file1.c', 'file2.c'])
-      </programlisting>
-
-      <para>
-
-      If you omit the &target;,
-      the base of the first input
-      file name specified
-      becomes the base of the name of the shared library to be created.
-      For example:
-
-      </para>
-
-      <programlisting>
-        SharedLibrary(['file.c', 'another.c'])
-      </programlisting>
-
-      <para>