Imported Upstream version 2.3.1upstream/2.3.1

1 files changed, 334 insertions, 306 deletions

diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index b0a7498..64625f4 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -1,6 +1,28 @@
+<?xml version='1.0'?>
+<!DOCTYPE sconsdoc [
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+    
+    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
+    %builders-mod;
+    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
+    %functions-mod;
+    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
+    %tools-mod;
+    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
+    %variables-mod;
+
+]>
+
+<chapter id="chap-environments"
+         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/scons.xsd scons.xsd">
+<title>Environments</title>
+
 <!--
 
-     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
 
      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
@@ -466,9 +488,14 @@ environment, of directory names, suffixes, etc.
 
   </para>
 
-   <programlisting>
-     import os
-   </programlisting>
+   <scons_example name="environments_ex1">
+     <file name="SConstruct" printme="1">
+import os
+     </file>
+     <file name="foo.c">
+int main() { }
+     </file>
+   </scons_example>
 
   <para>
 
@@ -518,9 +545,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-       <programlisting>
-         env = Environment()
-       </programlisting>
+       <sconstruct>
+env = Environment()
+       </sconstruct>
 
       <para>
 
@@ -550,14 +577,17 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-       <programlisting>
-     import os
-
-         env = Environment(CC = 'gcc',
-                           CCFLAGS = '-O2')
+       <scons_example name="environments_ex1">
+         <file name="SConstruct" printme="1">
+ env = Environment(CC = 'gcc',
+                   CCFLAGS = '-O2')
 
-         env.Program('foo.c')
-       </programlisting>
+ env.Program('foo.c')
+         </file>
+         <file name="foo.c">
+int main() { }
+         </file>
+       </scons_example>
 
       <para>
 
@@ -577,11 +607,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         gcc -o foo.o -c -O2 foo.c
-         gcc -o foo foo.o
-      </screen>
+      <scons_output example="environments_ex1" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
     </section>
 
@@ -596,10 +624,12 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         print "CC is:", env['CC']
-      </programlisting>
+      <scons_example name="environments_ex6">
+        <file name="SConstruct" printme="1">
+env = Environment()
+print "CC is:", env['CC']
+        </file>
+      </scons_example>
 
       <para>
 
@@ -609,11 +639,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         CC is: cc
-         scons: `.' is up to date.
-      </screen>
+      <scons_output example="environments_ex6" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -625,12 +653,14 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment(FOO = 'foo', BAR = 'bar')
-         dict = env.Dictionary()
-         for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
-             print "key = %s, value = %s" % (key, dict[key])
-      </programlisting>
+      <scons_example name="environments_ex6b">
+         <file name="SConstruct" printme="1">
+env = Environment(FOO = 'foo', BAR = 'bar')
+dict = env.Dictionary()
+for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
+    print "key = %s, value = %s" % (key, dict[key])
+         </file>
+      </scons_example>
 
       <para>
 
@@ -640,13 +670,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         key = OBJSUFFIX, value = .o
-         key = LIBSUFFIX, value = .a
-         key = PROGSUFFIX, value = 
-         scons: `.' is up to date.
-      </screen>
+      <scons_output example="environments_ex6b" os="posix" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -654,13 +680,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         C:\><userinput>scons -Q</userinput>
-         key = OBJSUFFIX, value = .obj
-         key = LIBSUFFIX, value = .lib
-         key = PROGSUFFIX, value = .exe
-         scons: `.' is up to date.
-      </screen>
+      <scons_output example="environments_ex6b" os="win32" suffix="2">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -670,11 +692,11 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         for item in sorted(env.Dictionary().items()):
-             print "construction variable = '%s', value = '%s'" % item
-      </programlisting>
+      <sconstruct>
+env = Environment()
+for item in sorted(env.Dictionary().items()):
+    print "construction variable = '%s', value = '%s'" % item
+      </sconstruct>
 
     </section>
 
@@ -697,10 +719,10 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-        env = Environment()
-        print "CC is:", env.subst('$CC')
-      </programlisting>
+      <sconstruct>
+env = Environment()
+print "CC is:", env.subst('$CC')
+      </sconstruct>
 
       <para>
 
@@ -714,10 +736,10 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-        env = Environment(CCFLAGS = '-DFOO')
-        print "CCCOM is:", env['CCCOM']
-      </programlisting>
+      <sconstruct>
+env = Environment(CCFLAGS = '-DFOO')
+print "CCCOM is:", env['CCCOM']
+      </sconstruct>
 
       <para>
 
@@ -728,9 +750,9 @@ environment, of directory names, suffixes, etc.
       </para>
 
       <screen>
-        % <userinput>scons -Q</userinput>
-        CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
-        scons: `.' is up to date.
+% <userinput>scons -Q</userinput>
+CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
+scons: `.' is up to date.
       </screen>
 
       <para>
@@ -740,10 +762,10 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-        env = Environment(CCFLAGS = '-DFOO')
-        print "CCCOM is:", env.subst('$CCCOM')
-      </programlisting>
+      <sconstruct>
+env = Environment(CCFLAGS = '-DFOO')
+print "CCCOM is:", env.subst('$CCCOM')
+      </sconstruct>
 
       <para>
 
@@ -755,9 +777,9 @@ environment, of directory names, suffixes, etc.
       </para>
 
       <screen>
-        % <userinput>scons -Q</userinput>
-        CCCOM is: gcc -DFOO -c -o
-        scons: `.' is up to date.
+% <userinput>scons -Q</userinput>
+CCCOM is: gcc -DFOO -c -o
+scons: `.' is up to date.
       </screen>
 
       <para>
@@ -781,16 +803,16 @@ environment, of directory names, suffixes, etc.
       (a null string), and will not cause scons to fail. 
       </para>
 
-       <programlisting>
-          env = Environment()
-          print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
-      </programlisting>
+       <scons_example name="environments_missing1">
+         <file name="SConstruct" printme="1">
+env = Environment()
+print "value is:", env.subst( '->$MISSING&lt;-' )
+        </file>
+      </scons_example>
 
-       <screen>
-          % <userinput>scons -Q</userinput>
-          value is: -&gt;&lt;-
-          scons: `.' is up to date.
-       </screen>
+       <scons_output example="environments_missing1" suffix="1">
+          <scons_output_command>scons -Q</scons_output_command>
+       </scons_output>
 
       <para>
       This default behaviour can be changed using the &AllowSubstExceptions;
@@ -808,18 +830,17 @@ environment, of directory names, suffixes, etc.
       with no extra arguments.
       </para>
 
-       <programlisting>
-          AllowSubstExceptions()
-          env = Environment()
-          print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
-      </programlisting>
+       <scons_example name="environments_missing2">
+         <file name="SConstruct" printme="1">
+AllowSubstExceptions()
+env = Environment()
+print "value is:", env.subst( '->$MISSING&lt;-' )
+        </file>
+      </scons_example>
 
-       <screen>
-          % <userinput>scons -Q</userinput>
-          value is:
-          scons: *** NameError `MISSING' trying to evaluate `$MISSING'
-          File "/home/my/project/SConstruct", line 3, in &lt;module&gt;
-       </screen>
+       <scons_output example="environments_missing2" suffix="1">
+          <scons_output_command>scons -Q</scons_output_command>
+       </scons_output>
 
       <para>
       This can also be used to allow other exceptions that might occur,
@@ -829,19 +850,17 @@ environment, of directory names, suffixes, etc.
       allowed
       </para>
 
-       <programlisting>
-          AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
-          env = Environment()
-          print "value is:", env.subst( '-&gt;${1 / 0}&lt;-' )
-      </programlisting>
+       <scons_example name="environments_missing3">
+         <file name="SConstruct" printme="1">
+AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
+env = Environment()
+print "value is:", env.subst( '->${1 / 0}&lt;-' )
+        </file>
+      </scons_example>
 
-       <screen>
-          % <userinput>scons -Q</userinput>
-          value is: -&gt;&lt;-
-          scons: `.' is up to date.
-       </screen>
-      <programlisting>
-      </programlisting>
+       <scons_output example="environments_missing3" suffix="1">
+          <scons_output_command>scons -Q</scons_output_command>
+       </scons_output>
 
       <para>
       If &AllowSubstExceptions; is called multiple times, each call
@@ -881,11 +900,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-
-      DefaultEnvironment(CC = '/usr/local/bin/gcc')
-
-      </programlisting>
+      <sconstruct>
+DefaultEnvironment(CC = '/usr/local/bin/gcc')
+      </sconstruct>
 
       <para>
 
@@ -915,12 +932,10 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-
-      env = DefaultEnvironment()
-      env['CC'] = '/usr/local/bin/gcc'
-
-      </programlisting>
+      <sconstruct>
+env = DefaultEnvironment()
+env['CC'] = '/usr/local/bin/gcc'
+      </sconstruct>
 
       <para>
 
@@ -944,12 +959,10 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-
-      env = DefaultEnvironment(tools = ['gcc', 'gnulink'],
-                               CC = '/usr/local/bin/gcc')
-
-      </programlisting>
+      <sconstruct>
+env = DefaultEnvironment(tools = ['gcc', 'gnulink'],
+                         CC = '/usr/local/bin/gcc')
+      </sconstruct>
 
       <para>
 
@@ -982,22 +995,26 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         opt = Environment(CCFLAGS = '-O2')
-         dbg = Environment(CCFLAGS = '-g')
+      <scons_example name="environments_ex2">
+        <file name="SConstruct" printme="1">
+opt = Environment(CCFLAGS = '-O2')
+dbg = Environment(CCFLAGS = '-g')
 
-         opt.Program('foo', 'foo.c')
+opt.Program('foo', 'foo.c')
 
-         dbg.Program('bar', 'bar.c')
-      </programlisting>
+dbg.Program('bar', 'bar.c')
+        </file>
+        <file name="foo.c">
+int main() { }
+        </file>
+        <file name="bar.c">
+int main() { }
+        </file>
+      </scons_example>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         cc -o bar.o -c -g bar.c
-         cc -o bar bar.o
-         cc -o foo.o -c -O2 foo.c
-         cc -o foo foo.o
-      </screen>
+      <scons_output example="environments_ex2" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1009,14 +1026,19 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         opt = Environment(CCFLAGS = '-O2')
-         dbg = Environment(CCFLAGS = '-g')
+      <scons_example name="environments_ex3">
+        <file name="SConstruct" printme="1">
+opt = Environment(CCFLAGS = '-O2')
+dbg = Environment(CCFLAGS = '-g')
 
-         opt.Program('foo', 'foo.c')
+opt.Program('foo', 'foo.c')
 
-         dbg.Program('foo', 'foo.c')
-      </programlisting>
+dbg.Program('foo', 'foo.c')
+        </file>
+        <file name="foo.c">
+int main() { }
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1024,12 +1046,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         
-         scons: *** Two environments with different actions were specified for the same target: foo.o
-         File "/home/my/project/SConstruct", line 6, in &lt;module&gt;
-      </screen>
+      <scons_output example="environments_ex3" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1052,16 +1071,21 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         opt = Environment(CCFLAGS = '-O2')
-         dbg = Environment(CCFLAGS = '-g')
+      <scons_example name="environments_ex4">
+        <file name="SConstruct" printme="1">
+opt = Environment(CCFLAGS = '-O2')
+dbg = Environment(CCFLAGS = '-g')
 
-         o = opt.Object('foo-opt', 'foo.c')
-         opt.Program(o)
+o = opt.Object('foo-opt', 'foo.c')
+opt.Program(o)
 
-         d = dbg.Object('foo-dbg', 'foo.c')
-         dbg.Program(d)
-      </programlisting>
+d = dbg.Object('foo-dbg', 'foo.c')
+dbg.Program(d)
+        </file>
+        <file name="foo.c">
+int main() { }
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1079,13 +1103,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         cc -o foo-dbg.o -c -g foo.c
-         cc -o foo-dbg foo-dbg.o
-         cc -o foo-opt.o -c -O2 foo.c
-         cc -o foo-opt foo-opt.o
-      </screen>
+      <scons_output example="environments_ex4" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
     </section>
 
@@ -1119,19 +1139,24 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment(CC = 'gcc')
-         opt = env.Clone(CCFLAGS = '-O2')
-         dbg = env.Clone(CCFLAGS = '-g')
+      <scons_example name="environments_ex5">
+        <file name="SConstruct" printme="1">
+env = Environment(CC = 'gcc')
+opt = env.Clone(CCFLAGS = '-O2')
+dbg = env.Clone(CCFLAGS = '-g')
 
-         env.Program('foo', 'foo.c')
+env.Program('foo', 'foo.c')
 
-         o = opt.Object('foo-opt', 'foo.c')
-         opt.Program(o)
+o = opt.Object('foo-opt', 'foo.c')
+opt.Program(o)
 
-         d = dbg.Object('foo-dbg', 'foo.c')
-         dbg.Program(d)
-      </programlisting>
+d = dbg.Object('foo-dbg', 'foo.c')
+dbg.Program(d)
+        </file>
+        <file name="foo.c">
+int main() { }
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1139,15 +1164,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         gcc -o foo.o -c foo.c
-         gcc -o foo foo.o
-         gcc -o foo-dbg.o -c -g foo.c
-         gcc -o foo-dbg foo-dbg.o
-         gcc -o foo-opt.o -c -O2 foo.c
-         gcc -o foo-opt foo-opt.o
-      </screen>
+      <scons_output example="environments_ex5" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
     </section>
 
@@ -1161,11 +1180,16 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment(CCFLAGS = '-DDEFINE1')
-         env.Replace(CCFLAGS = '-DDEFINE2')
-         env.Program('foo.c')
-      </programlisting>
+      <scons_example name="environments_Replace1">
+        <file name="SConstruct" printme="1">
+env = Environment(CCFLAGS = '-DDEFINE1')
+env.Replace(CCFLAGS = '-DDEFINE2')
+env.Program('foo.c')
+        </file>
+        <file name="foo.c">
+int main() { }
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1176,11 +1200,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         cc -o foo.o -c -DDEFINE2 foo.c
-         cc -o foo foo.o
-      </screen>
+      <scons_output example="environments_Replace1" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1190,11 +1212,13 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         env.Replace(NEW_VARIABLE = 'xyzzy')
-         print "NEW_VARIABLE =", env['NEW_VARIABLE']
-      </programlisting>
+      <scons_example name="environments_Replace-nonexistent">
+        <file name="SConstruct" printme="1">
+env = Environment()
+env.Replace(NEW_VARIABLE = 'xyzzy')
+print "NEW_VARIABLE =", env['NEW_VARIABLE']
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1204,11 +1228,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         NEW_VARIABLE = xyzzy
-         scons: `.' is up to date.
-      </screen>
+      <scons_output example="environments_Replace-nonexistent" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1226,15 +1248,23 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment(CCFLAGS = '-DDEFINE1')
-         print "CCFLAGS =", env['CCFLAGS']
-         env.Program('foo.c')
-
-         env.Replace(CCFLAGS = '-DDEFINE2')
-         print "CCFLAGS =", env['CCFLAGS']
-         env.Program('bar.c')
-      </programlisting>
+      <scons_example name="environments_Replace2">
+        <file name="SConstruct" printme="1">
+env = Environment(CCFLAGS = '-DDEFINE1')
+print "CCFLAGS =", env['CCFLAGS']
+env.Program('foo.c')
+
+env.Replace(CCFLAGS = '-DDEFINE2')
+print "CCFLAGS =", env['CCFLAGS']
+env.Program('bar.c')
+        </file>
+        <file name="foo.c">
+int main() { }
+        </file>
+        <file name="bar.c">
+int main() { }
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1247,19 +1277,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons</userinput>
-         scons: Reading SConscript files ...
-         CCFLAGS = -DDEFINE1
-         CCFLAGS = -DDEFINE2
-         scons: done reading SConscript files.
-         scons: Building targets ...
-         cc -o bar.o -c -DDEFINE2 bar.c
-         cc -o bar bar.o
-         cc -o foo.o -c -DDEFINE2 foo.c
-         cc -o foo foo.o
-         scons: done building targets.
-      </screen>
+      <scons_output example="environments_Replace2" suffix="1">
+         <scons_output_command>scons</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1292,9 +1312,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-      env.SetDefault(SPECIAL_FLAG = '-extra-option')
-      </programlisting>
+      <sconstruct>
+env.SetDefault(SPECIAL_FLAG = '-extra-option')
+      </sconstruct>
 
       <para>
 
@@ -1322,11 +1342,16 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment(CCFLAGS = ['-DMY_VALUE'])
-         env.Append(CCFLAGS = ['-DLAST'])
-         env.Program('foo.c')
-      </programlisting>
+      <scons_example name="environments_ex8">
+        <file name="SConstruct" printme="1">
+env = Environment(CCFLAGS = ['-DMY_VALUE'])
+env.Append(CCFLAGS = ['-DLAST'])
+env.Program('foo.c')
+        </file>
+        <file name="foo.c">
+int main() { }
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1335,11 +1360,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         cc -o foo.o -c -DMY_VALUE -DLAST foo.c
-         cc -o foo foo.o
-      </screen>
+      <scons_output example="environments_ex8" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1348,11 +1371,13 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         env.Append(NEW_VARIABLE = 'added')
-         print "NEW_VARIABLE =", env['NEW_VARIABLE']
-      </programlisting>
+      <scons_example name="environments_Append-nonexistent">
+        <file name="SConstruct" printme="1">
+env = Environment()
+env.Append(NEW_VARIABLE = 'added')
+print "NEW_VARIABLE =", env['NEW_VARIABLE']
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1360,11 +1385,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         NEW_VARIABLE = added
-         scons: `.' is up to date.
-      </screen>
+      <scons_output example="environments_Append-nonexistent" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1393,9 +1416,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-      env.AppendUnique(CCFLAGS=['-g'])
-      </programlisting>
+      <sconstruct>
+env.AppendUnique(CCFLAGS=['-g'])
+      </sconstruct>
 
       <para>
 
@@ -1419,11 +1442,16 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment(CCFLAGS = ['-DMY_VALUE'])
-         env.Prepend(CCFLAGS = ['-DFIRST'])
-         env.Program('foo.c')
-      </programlisting>
+      <scons_example name="environments_ex9">
+        <file name="SConstruct" printme="1">
+env = Environment(CCFLAGS = ['-DMY_VALUE'])
+env.Prepend(CCFLAGS = ['-DFIRST'])
+env.Program('foo.c')
+        </file>
+        <file name="foo.c">
+int main() { }
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1432,11 +1460,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         cc -o foo.o -c -DFIRST -DMY_VALUE foo.c
-         cc -o foo foo.o
-      </screen>
+      <scons_output example="environments_ex9" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1445,11 +1471,13 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         env.Prepend(NEW_VARIABLE = 'added')
-         print "NEW_VARIABLE =", env['NEW_VARIABLE']
-      </programlisting>
+      <scons_example name="environments_Prepend-nonexistent">
+        <file name="SConstruct" printme="1">
+env = Environment()
+env.Prepend(NEW_VARIABLE = 'added')
+print "NEW_VARIABLE =", env['NEW_VARIABLE']
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1457,11 +1485,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         NEW_VARIABLE = added
-         scons: `.' is up to date.
-      </screen>
+      <scons_output example="environments_Prepend-nonexistent" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1492,9 +1518,9 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-      env.PrependUnique(CCFLAGS=['-g'])
-      </programlisting>
+      <sconstruct>
+env.PrependUnique(CCFLAGS=['-g'])
+      </sconstruct>
 
       <para>
 
@@ -1563,10 +1589,10 @@ environment, of directory names, suffixes, etc.
 
     </para>
 
-    <programlisting>
-      path = ['/usr/local/bin', '/bin', '/usr/bin']
-      env = Environment(ENV = {'PATH' : path})
-    </programlisting>
+    <sconstruct>
+path = ['/usr/local/bin', '/bin', '/usr/bin']
+env = Environment(ENV = {'PATH' : path})
+    </sconstruct>
 
     <para>
 
@@ -1583,9 +1609,9 @@ environment, of directory names, suffixes, etc.
 
     </para>
 
-    <programlisting>
-      env['ENV']['PATH'] = ['/usr/local/bin', '/bin', '/usr/bin']
-    </programlisting>
+    <sconstruct>
+env['ENV']['PATH'] = ['/usr/local/bin', '/bin', '/usr/bin']
+    </sconstruct>
 
     <para>
 
@@ -1596,9 +1622,9 @@ environment, of directory names, suffixes, etc.
 
     </para>
 
-    <programlisting>
-      env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin'
-    </programlisting>
+    <sconstruct>
+env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin'
+    </sconstruct>
 
     <para>
 
@@ -1610,21 +1636,21 @@ environment, of directory names, suffixes, etc.
 
     <!--
 
-    <scons_example name="ex1">
+    <scons_example name="environments_ex1">
       <file name="SConstruct" printme="1">
-      env = Environment()
-      env.Command('foo', [], '__ROOT__/usr/bin/printenv.py')
+env = Environment()
+env.Command('foo', [], '__ROOT__/usr/bin/printenv.py')
       </file>
       <file name="__ROOT__/usr/bin/printenv.py" chmod="0755">
-      #!/usr/bin/env python
-      import os
-      import sys
-      if len(sys.argv) &gt; 1:
-          keys = sys.argv[1:]
-      else:
-          keys = sorted(os.environ.keys())
-      for key in keys:
-          print "    " + key + "=" + os.environ[key]
+#!/usr/bin/env python
+import os
+import sys
+if len(sys.argv) &gt; 1:
+    keys = sys.argv[1:]
+else:
+    keys = sorted(os.environ.keys())
+for key in keys:
+    print "    " + key + "=" + os.environ[key]
       </file>
     </scons_example>
 
@@ -1632,7 +1658,7 @@ environment, of directory names, suffixes, etc.
 
     </para>
 
-    <scons_output example="ex1">
+    <scons_output example="environments_ex1" suffix="2">
       <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
@@ -1654,10 +1680,10 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-        import os
-        env = Environment(ENV = {'PATH' : os.environ['PATH']})
-      </programlisting>
+      <sconstruct>
+import os
+env = Environment(ENV = {'PATH' : os.environ['PATH']})
+      </sconstruct>
 
       <para>
 
@@ -1670,10 +1696,10 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-        import os
-        env = Environment(ENV = os.environ)
-      </programlisting>
+      <sconstruct>
+import os
+env = Environment(ENV = os.environ)
+      </sconstruct>
 
       <para>
 
@@ -1717,11 +1743,11 @@ environment, of directory names, suffixes, etc.
 
       </para>
 
-      <programlisting>
-        env = Environment(ENV = os.environ)
-        env.PrependENVPath('PATH', '/usr/local/bin')
-        env.AppendENVPath('LIB', '/usr/local/lib')
-      </programlisting>
+      <sconstruct>
+env = Environment(ENV = os.environ)
+env.PrependENVPath('PATH', '/usr/local/bin')
+env.AppendENVPath('LIB', '/usr/local/lib')
+      </sconstruct>
 
       <para>
 
@@ -1738,3 +1764,5 @@ environment, of directory names, suffixes, etc.
     </section>
 
   </section>
+
+</chapter>