From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001
From: Luca Falavigna <dktrkranz@debian.org>
Date: Sat, 26 Apr 2014 15:11:58 +0200
Subject: Imported Upstream version 2.3.1

---
 doc/user/command-line.xml | 1248 ++++++++++++++++++++++++---------------------
 1 file changed, 676 insertions(+), 572 deletions(-)

(limited to 'doc/user/command-line.xml')

diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml
index 1888ac0..2819d3d 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.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-command-line"
+         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>Controlling a Build From the Command Line</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
@@ -146,19 +168,26 @@
 
       </para>
 
-      
-
-      <screen>
-        % <userinput>scons</userinput>
-        scons: Reading SConscript files ...
-        scons: done reading SConscript files.
-        scons: Building targets ...
-            ... [build output] ...
-        scons: done building targets.
-        % <userinput>export SCONSFLAGS="-Q"</userinput>
-        % <userinput>scons</userinput>
-            ... [build output] ...
-      </screen>
+      <scons_example name="commandline_SCONSFLAGS">
+        <file name="SConstruct">
+def b(target, source, env):
+    pass
+def s(target, source, env):
+    return "    ... [build output] ..."
+a = Action(b, strfunction = s)
+env = Environment(BUILDERS = {'A' : Builder(action=a)})
+env.A('foo.out', 'foo.in')
+        </file>
+        <file name="foo.in">
+foo.in
+        </file>
+      </scons_example>
+
+      <scons_output example="commandline_SCONSFLAGS" suffix="1">
+        <scons_output_command>scons</scons_output_command>
+        <scons_output_command>export SCONSFLAGS="-Q"</scons_output_command>
+        <scons_output_command environment="SCONSFLAGS=-Q">scons</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -168,7 +197,7 @@
       </para>
 
       <screen>
-        $ <userinput>setenv SCONSFLAGS "-Q"</userinput>
+$ <userinput>setenv SCONSFLAGS "-Q"</userinput>
       </screen>
 
       <para>
@@ -214,10 +243,10 @@
 
       </para>
 
-      <programlisting>
-        if not GetOption('help'):
-            SConscript('src/SConscript', export='env')
-      </programlisting>
+      <sconstruct>
+if not GetOption('help'):
+    SConscript('src/SConscript', export='env')
+      </sconstruct>
 
       <para>
 
@@ -283,12 +312,17 @@
 
       </para>
 
-      <programlisting>
-        import os
-        num_cpu = int(os.environ.get('NUM_CPU', 2))
-        SetOption('num_jobs', num_cpu)
-        print "running with -j", GetOption('num_jobs')
-      </programlisting>
+      <scons_example name="commandline_SetOption">
+        <file name="SConstruct" printme="1">
+import os
+num_cpu = int(os.environ.get('NUM_CPU', 2))
+SetOption('num_jobs', num_cpu)
+print "running with -j", GetOption('num_jobs')
+        </file>
+        <file name="foo.in">
+foo.in
+        </file>
+      </scons_example>
 
       <para>
 
@@ -310,11 +344,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q</userinput>
-        running with -j 2
-        scons: `.' is up to date.
-      </screen>
+      <scons_output example="commandline_SetOption" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -324,12 +356,10 @@
 
       </para>
 
-      <screen>
-        % <userinput>export NUM_CPU="4"</userinput>
-        % <userinput>scons -Q</userinput>
-        running with -j 4
-        scons: `.' is up to date.
-      </screen>
+      <scons_output example="commandline_SetOption" suffix="2">
+        <scons_output_command>export NUM_CPU="4"</scons_output_command>
+        <scons_output_command environment="NUM_CPU=4">scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -342,15 +372,11 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q -j 7</userinput>
-        running with -j 7
-        scons: `.' is up to date.
-        % <userinput>export NUM_CPU="4"</userinput>
-        % <userinput>scons -Q -j 3</userinput>
-        running with -j 3
-        scons: `.' is up to date.
-      </screen>
+      <scons_output example="commandline_SetOption" suffix="3">
+        <scons_output_command>scons -Q -j 7</scons_output_command>
+        <scons_output_command>export NUM_CPU="4"</scons_output_command>
+        <scons_output_command environment="NUM_CPU=4">scons -Q -j 3</scons_output_command>
+      </scons_output>
 
     </section>
 
@@ -600,20 +626,25 @@
 
       </para>
 
-      <programlisting>
-        AddOption('--prefix',
-                  dest='prefix',
-                  type='string',
-                  nargs=1,
-                  action='store',
-                  metavar='DIR',
-                  help='installation prefix')
-
-        env = Environment(PREFIX = GetOption('prefix'))
-
-        installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in')
-        Default(installed_foo)
-      </programlisting>
+      <scons_example name="commandline_AddOption">
+        <file name="SConstruct" printme="1">
+AddOption('--prefix',
+          dest='prefix',
+          type='string',
+          nargs=1,
+          action='store',
+          metavar='DIR',
+          help='installation prefix')
+
+env = Environment(PREFIX = GetOption('prefix'))
+
+installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in')
+Default(installed_foo)
+        </file>
+        <file name="foo.in">
+foo.in
+        </file>
+      </scons_example>
 
       <para>
 
@@ -631,10 +662,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q -n</userinput>
-        Install file: "foo.in" as "/usr/bin/foo.in"
-      </screen>
+      <scons_output example="commandline_AddOption" suffix="1">
+        <scons_output_command>scons -Q -n</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -644,10 +674,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q -n --prefix=/tmp/install</userinput>
-        Install file: "foo.in" as "/tmp/install/usr/bin/foo.in"
-      </screen>
+      <scons_output example="commandline_AddOption" suffix="2">
+        <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command>
+      </scons_output>
 
     </section>
 
@@ -670,7 +699,7 @@
     </para>
 
     <screen>
-      % <userinput>scons -Q debug=1</userinput>
+% <userinput>scons -Q debug=1</userinput>
     </screen>
 
     <para>
@@ -702,13 +731,18 @@
 
     </para>
 
-    <programlisting>
-       env = Environment()
-       debug = ARGUMENTS.get('debug', 0)
-       if int(debug):
-           env.Append(CCFLAGS = '-g')
-       env.Program('prog.c')
-    </programlisting>
+    <scons_example name="commandline_ARGUMENTS">
+       <file name="SConstruct" printme="1">
+env = Environment()
+debug = ARGUMENTS.get('debug', 0)
+if int(debug):
+    env.Append(CCFLAGS = '-g')
+env.Program('prog.c')
+       </file>
+       <file name="prog.c">
+prog.c
+       </file>
+    </scons_example>
 
     <para>
 
@@ -719,18 +753,12 @@
 
     </para>
 
-    <screen>
-       % <userinput>scons -Q debug=0</userinput>
-       cc -o prog.o -c prog.c
-       cc -o prog prog.o
-       % <userinput>scons -Q debug=0</userinput>
-       scons: `.' is up to date.
-       % <userinput>scons -Q debug=1</userinput>
-       cc -o prog.o -c -g prog.c
-       cc -o prog prog.o
-       % <userinput>scons -Q debug=1</userinput>
-       scons: `.' is up to date.
-    </screen>
+    <scons_output example="commandline_ARGUMENTS" suffix="1">
+       <scons_output_command>scons -Q debug=0</scons_output_command>
+       <scons_output_command>scons -Q debug=0</scons_output_command>
+       <scons_output_command>scons -Q debug=1</scons_output_command>
+       <scons_output_command>scons -Q debug=1</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -792,14 +820,19 @@
 
     </para>
 
-    <programlisting>
-       cppdefines = []
-       for key, value in ARGLIST:
-           if key == 'define':
-               cppdefines.append(value)
-       env = Environment(CPPDEFINES = cppdefines)
-       env.Object('prog.c')
-    </programlisting>
+    <scons_example name="commandline_ARGLIST">
+       <file name="SConstruct" printme="1">
+cppdefines = []
+for key, value in ARGLIST:
+    if key == 'define':
+        cppdefines.append(value)
+env = Environment(CPPDEFINES = cppdefines)
+env.Object('prog.c')
+       </file>
+       <file name="prog.c">
+prog.c
+       </file>
+    </scons_example>
 
     <para>
 
@@ -807,12 +840,10 @@
 
     </para>
 
-    <screen>
-       % <userinput>scons -Q define=FOO</userinput>
-       cc -o prog.o -c -DFOO prog.c
-       % <userinput>scons -Q define=FOO define=BAR</userinput>
-       cc -o prog.o -c -DFOO -DBAR prog.c
-    </screen>
+    <scons_output example="commandline_ARGLIST" suffix="1">
+       <scons_output_command>scons -Q define=FOO</scons_output_command>
+       <scons_output_command>scons -Q define=FOO define=BAR</scons_output_command>
+    </scons_output>
 
     <para>
 
@@ -874,13 +905,21 @@
 
       </para>
 
-      <programlisting>
-           vars = Variables(None, ARGUMENTS)
-           vars.Add('RELEASE', 'Set to 1 to build for release', 0)
-           env = Environment(variables = vars,
-                             CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
-           env.Program(['foo.c', 'bar.c'])
-      </programlisting>
+      <scons_example name="commandline_Variables1">
+        <file name="SConstruct" printme="1">
+vars = Variables(None, ARGUMENTS)
+vars.Add('RELEASE', 'Set to 1 to build for release', 0)
+env = Environment(variables = vars,
+                  CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
+env.Program(['foo.c', 'bar.c'])
+        </file>
+        <file name="foo.c">
+foo.c
+        </file>
+        <file name="bar.c">
+bar.c
+        </file>
+      </scons_example>
 
       <para>
 
@@ -911,12 +950,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q RELEASE=1</userinput>
-        cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
-        cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
-        cc -o foo foo.o bar.o
-      </screen>
+      <scons_output example="commandline_Variables1" suffix="1">
+        <scons_output_command>scons -Q RELEASE=1</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -960,12 +996,14 @@
 
       </para>
 
-      <programlisting>
-           vars = Variables(None, ARGUMENTS)
-           vars.Add('RELEASE', 'Set to 1 to build for release', 0)
-           env = Environment(variables = vars)
-           Help(vars.GenerateHelpText(env))
-      </programlisting>
+      <scons_example name="commandline_Variables_Help">
+        <file name="SConstruct" printme="1">
+vars = Variables(None, ARGUMENTS)
+vars.Add('RELEASE', 'Set to 1 to build for release', 0)
+env = Environment(variables = vars)
+Help(vars.GenerateHelpText(env))
+        </file>
+      </scons_example>
 
       <para>
 
@@ -974,15 +1012,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q -h</userinput>
-        
-        RELEASE: Set to 1 to build for release
-            default: 0
-            actual: 0
-        
-        Use scons -H for help about command-line options.
-      </screen>
+      <scons_output example="commandline_Variables_Help" suffix="1">
+        <scons_output_command>scons -Q -h</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1011,14 +1043,25 @@
 
       </para>
 
-      <programlisting>
-           vars = Variables('custom.py')
-           vars.Add('RELEASE', 'Set to 1 to build for release', 0)
-           env = Environment(variables = vars,
-                             CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
-           env.Program(['foo.c', 'bar.c'])
-           Help(vars.GenerateHelpText(env))
-      </programlisting>
+      <scons_example name="commandline_Variables_custom_py_1">
+        <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add('RELEASE', 'Set to 1 to build for release', 0)
+env = Environment(variables = vars,
+                  CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
+env.Program(['foo.c', 'bar.c'])
+Help(vars.GenerateHelpText(env))
+        </file>
+        <file name="foo.c">
+foo.c
+        </file>
+        <file name="bar.c">
+bar.c
+        </file>
+        <file name="custom.py">
+RELEASE = 1
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1027,9 +1070,7 @@
 
       </para>
 
-      <programlisting>
-        RELEASE = 1
-        </programlisting>
+      <scons_example_file example="commandline_Variables_custom_py_1" name="custom.py"></scons_example_file>
 
       <para>
 
@@ -1039,12 +1080,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q</userinput>
-        cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
-        cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
-        cc -o foo foo.o bar.o
-      </screen>
+      <scons_output example="commandline_Variables_custom_py_1" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1052,9 +1090,25 @@
 
       </para>
 
-      <programlisting>
-        RELEASE = 0
-      </programlisting>
+      <scons_example name="commandline_Variables_custom_py_2">
+        <file name="SConstruct">
+   vars = Variables('custom.py')
+   vars.Add('RELEASE', 'Set to 1 to build for release', 0)
+   env = Environment(variables = vars,
+                     CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
+   env.Program(['foo.c', 'bar.c'])
+   Help(vars.GenerateHelpText(env))
+        </file>
+        <file name="foo.c">
+foo.c
+        </file>
+        <file name="bar.c">
+bar.c
+        </file>
+        <file name="custom.py" printme="1">
+RELEASE = 0
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1063,12 +1117,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q</userinput>
-        cc -o bar.o -c -DRELEASE_BUILD=0 bar.c
-        cc -o foo.o -c -DRELEASE_BUILD=0 foo.c
-        cc -o foo foo.o bar.o
-      </screen>
+      <scons_output example="commandline_Variables_custom_py_2" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1077,7 +1128,7 @@
       </para>
 
       <screen>
-        vars = Variables('custom.py', ARGUMENTS)
+vars = Variables('custom.py', ARGUMENTS)
       </screen>
 
       <para>
@@ -1129,13 +1180,18 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_BoolVariable">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0))
+env = Environment(variables = vars,
+                  CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1146,15 +1202,13 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q RELEASE=yes foo.o</userinput>
-          cc -o foo.o -c -DRELEASE_BUILD=True foo.c
-        </screen>
+        <scons_output example="commandline_BoolVariable" suffix="1">
+          <scons_output_command>scons -Q RELEASE=yes foo.o</scons_output_command>
+        </scons_output>
 
-        <screen>
-          % <userinput>scons -Q RELEASE=t foo.o</userinput>
-          cc -o foo.o -c -DRELEASE_BUILD=True foo.c
-        </screen>
+        <scons_output example="commandline_BoolVariable" suffix="2">
+          <scons_output_command>scons -Q RELEASE=t foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1177,15 +1231,13 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q RELEASE=no foo.o</userinput>
-          cc -o foo.o -c -DRELEASE_BUILD=False foo.c
-        </screen>
+        <scons_output example="commandline_BoolVariable" suffix="3">
+          <scons_output_command>scons -Q RELEASE=no foo.o</scons_output_command>
+        </scons_output>
 
-        <screen>
-          % <userinput>scons -Q RELEASE=f foo.o</userinput>
-          cc -o foo.o -c -DRELEASE_BUILD=False foo.c
-        </screen>
+        <scons_output example="commandline_BoolVariable" suffix="4">
+          <scons_output_command>scons -Q RELEASE=f foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1206,13 +1258,9 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q RELEASE=bad_value foo.o</userinput>
-          
-          scons: *** Error converting option: RELEASE
-          Invalid value for boolean option: bad_value
-          File "/home/my/project/SConstruct", line 4, in &lt;module&gt;
-        </screen>
+        <scons_output example="commandline_BoolVariable" suffix="5">
+          <scons_output_command>scons -Q RELEASE=bad_value foo.o</scons_output_command>
+        </scons_output>
 
       </section>
 
@@ -1236,14 +1284,19 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
-                                 allowed_values=('red', 'green', 'blue')))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'COLOR' : '"${COLOR}"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_EnumVariable">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
+                    allowed_values=('red', 'green', 'blue')))
+env = Environment(variables = vars,
+                  CPPDEFINES={'COLOR' : '"${COLOR}"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1252,14 +1305,11 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLOR=red foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="red" foo.c
-          % <userinput>scons -Q COLOR=blue foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="blue" foo.c
-          % <userinput>scons -Q COLOR=green foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="green" foo.c
-        </screen>
+        <scons_output example="commandline_EnumVariable" suffix="1">
+          <scons_output_command>scons -Q COLOR=red foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=blue foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1270,12 +1320,9 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLOR=magenta foo.o</userinput>
-          
-          scons: *** Invalid value for option COLOR: magenta.  Valid values are: ('red', 'green', 'blue')
-          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
-        </screen>
+        <scons_output example="commandline_EnumVariable" suffix="2">
+          <scons_output_command>scons -Q COLOR=magenta foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1291,15 +1338,20 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
-                                 allowed_values=('red', 'green', 'blue'),
-                                 map={'navy':'blue'}))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'COLOR' : '"${COLOR}"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="EnumVariable_map">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
+                    allowed_values=('red', 'green', 'blue'),
+                    map={'navy':'blue'}))
+env = Environment(variables = vars,
+                  CPPDEFINES={'COLOR' : '"${COLOR}"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1311,10 +1363,9 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLOR=navy foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="blue" foo.c
-        </screen>
+        <scons_output example="EnumVariable_map" suffix="1">
+          <scons_output_command>scons -Q COLOR=navy foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1326,20 +1377,11 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLOR=Red foo.o</userinput>
-          
-          scons: *** Invalid value for option COLOR: Red.  Valid values are: ('red', 'green', 'blue')
-          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
-          % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
-          
-          scons: *** Invalid value for option COLOR: BLUE.  Valid values are: ('red', 'green', 'blue')
-          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
-          % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
-          
-          scons: *** Invalid value for option COLOR: nAvY.  Valid values are: ('red', 'green', 'blue')
-          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
-        </screen>
+        <scons_output example="commandline_EnumVariable" suffix="3">
+          <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1351,16 +1393,21 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
-                                 allowed_values=('red', 'green', 'blue'),
-                                 map={'navy':'blue'},
-                                 ignorecase=1))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'COLOR' : '"${COLOR}"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_EnumVariable_ic1">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
+                    allowed_values=('red', 'green', 'blue'),
+                    map={'navy':'blue'},
+                    ignorecase=1))
+env = Environment(variables = vars,
+                  CPPDEFINES={'COLOR' : '"${COLOR}"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1368,16 +1415,12 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLOR=Red foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="Red" foo.c
-          % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="BLUE" foo.c
-          % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="blue" foo.c
-          % <userinput>scons -Q COLOR=green foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="green" foo.c
-        </screen>
+        <scons_output example="commandline_EnumVariable_ic1" suffix="1">
+          <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1390,16 +1433,21 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
-                                 allowed_values=('red', 'green', 'blue'),
-                                 map={'navy':'blue'},
-                                 ignorecase=2))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'COLOR' : '"${COLOR}"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_EnumVariable_ic2">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
+                    allowed_values=('red', 'green', 'blue'),
+                    map={'navy':'blue'},
+                    ignorecase=2))
+env = Environment(variables = vars,
+                  CPPDEFINES={'COLOR' : '"${COLOR}"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1412,14 +1460,11 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLOR=Red foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="red" foo.c
-          % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="blue" foo.c
-          % <userinput>scons -Q COLOR=GREEN foo.o</userinput>
-          cc -o foo.o -c -DCOLOR="green" foo.c
-        </screen>
+        <scons_output example="commandline_EnumVariable_ic2" suffix="1">
+          <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLOR=GREEN foo.o</scons_output_command>
+        </scons_output>
 
       </section>
 
@@ -1437,14 +1482,19 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(ListVariable('COLORS', 'List of colors', 0,
-                                 ['red', 'green', 'blue']))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'COLORS' : '"${COLORS}"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_ListVariable">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(ListVariable('COLORS', 'List of colors', 0,
+                    ['red', 'green', 'blue']))
+env = Environment(variables = vars,
+                  CPPDEFINES={'COLORS' : '"${COLORS}"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1455,12 +1505,10 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLORS=red,blue foo.o</userinput>
-          cc -o foo.o -c -DCOLORS="red blue" foo.c
-          % <userinput>scons -Q COLORS=blue,green,red foo.o</userinput>
-          cc -o foo.o -c -DCOLORS="blue green red" foo.c
-        </screen>
+        <scons_output example="commandline_ListVariable" suffix="1">
+          <scons_output_command>scons -Q COLORS=red,blue foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLORS=blue,green,red foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1472,12 +1520,10 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLORS=all foo.o</userinput>
-          cc -o foo.o -c -DCOLORS="red green blue" foo.c
-          % <userinput>scons -Q COLORS=none foo.o</userinput>
-          cc -o foo.o -c -DCOLORS="" foo.c
-        </screen>
+        <scons_output example="commandline_ListVariable" suffix="2">
+          <scons_output_command>scons -Q COLORS=all foo.o</scons_output_command>
+          <scons_output_command>scons -Q COLORS=none foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1486,13 +1532,9 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q COLORS=magenta foo.o</userinput>
-          
-          scons: *** Error converting option: COLORS
-          Invalid value(s) for option: magenta
-          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
-        </screen>
+        <scons_output example="commandline_ListVariable" suffix="3">
+          <scons_output_command>scons -Q COLORS=magenta foo.o</scons_output_command>
+        </scons_output>
 
       </section>
 
@@ -1511,15 +1553,26 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(PathVariable('CONFIG',
-                                 'Path to configuration file',
-                                 '/etc/my_config'))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_PathVariable">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(PathVariable('CONFIG',
+                    'Path to configuration file',
+                    '__ROOT__/etc/my_config'))
+env = Environment(variables = vars,
+                  CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+          <file name="__ROOT__/etc/my_config">
+/opt/location
+          </file>
+          <file name="__ROOT__/usr/local/etc/other_config">
+/opt/location
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1529,12 +1582,10 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q foo.o</userinput>
-          cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c
-          % <userinput>scons -Q CONFIG=/usr/local/etc/other_config foo.o</userinput>
-          scons: `foo.o' is up to date.
-        </screen>
+        <scons_output example="commandline_PathVariable" suffix="1">
+          <scons_output_command>scons -Q foo.o</scons_output_command>
+          <scons_output_command>scons -Q CONFIG=__ROOT__/usr/local/etc/other_config foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1544,12 +1595,9 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q CONFIG=/does/not/exist foo.o</userinput>
-          
-          scons: *** Path for option CONFIG does not exist: /does/not/exist
-          File "/home/my/project/SConstruct", line 6, in &lt;module&gt;
-        </screen>
+        <scons_output example="commandline_PathVariable" suffix="2">
+          <scons_output_command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -1561,16 +1609,24 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(PathVariable('CONFIG',
-                                 'Path to configuration file',
-                                 '/etc/my_config',
-                                 PathVariable.PathIsFile))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_PathIsFile">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(PathVariable('CONFIG',
+                    'Path to configuration file',
+                    '__ROOT__/etc/my_config',
+                    PathVariable.PathIsFile))
+env = Environment(variables = vars,
+                  CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+          <file name="__ROOT__/etc/my_config">
+/opt/location
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1580,16 +1636,24 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(PathVariable('DBDIR',
-                                 'Path to database directory',
-                                 '/var/my_dbdir',
-                                 PathVariable.PathIsDir))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'DBDIR' : '"$DBDIR"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_PathIsDir">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(PathVariable('DBDIR',
+                    'Path to database directory',
+                    '__ROOT__/var/my_dbdir',
+                    PathVariable.PathIsDir))
+env = Environment(variables = vars,
+                  CPPDEFINES={'DBDIR' : '"$DBDIR"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+          <file name="__ROOT__/var/my_dbdir">
+/opt/location
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1601,16 +1665,24 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(PathVariable('DBDIR',
-                                 'Path to database directory',
-                                 '/var/my_dbdir',
-                                 PathVariable.PathIsDirCreate))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'DBDIR' : '"$DBDIR"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_PathIsDirCreate">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(PathVariable('DBDIR',
+                    'Path to database directory',
+                    '__ROOT__/var/my_dbdir',
+                    PathVariable.PathIsDirCreate))
+env = Environment(variables = vars,
+                  CPPDEFINES={'DBDIR' : '"$DBDIR"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+          <file name="__ROOT__/var/my_dbdir">
+/opt/location
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1621,16 +1693,21 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(PathVariable('OUTPUT',
-                                 'Path to output file or directory',
-                                 None,
-                                 PathVariable.PathAccept))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'OUTPUT' : '"$OUTPUT"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_PathAccept">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(PathVariable('OUTPUT',
+                    'Path to output file or directory',
+                    None,
+                    PathVariable.PathAccept))
+env = Environment(variables = vars,
+                  CPPDEFINES={'OUTPUT' : '"$OUTPUT"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+        </scons_example>
 
       </section>
 
@@ -1651,15 +1728,26 @@
 
         </para>
 
-        <programlisting>
-             vars = Variables('custom.py')
-             vars.Add(PackageVariable('PACKAGE',
-                                    'Location package',
-                                    '/opt/location'))
-             env = Environment(variables = vars,
-                               CPPDEFINES={'PACKAGE' : '"$PACKAGE"'})
-             env.Program('foo.c')
-        </programlisting>
+        <scons_example name="commandline_PackageVariable">
+          <file name="SConstruct" printme="1">
+vars = Variables('custom.py')
+vars.Add(PackageVariable('PACKAGE',
+                       'Location package',
+                       '__ROOT__/opt/location'))
+env = Environment(variables = vars,
+                  CPPDEFINES={'PACKAGE' : '"$PACKAGE"'})
+env.Program('foo.c')
+          </file>
+          <file name="foo.c">
+foo.c
+          </file>
+          <file name="__ROOT__/opt/location">
+/opt/location
+          </file>
+          <file name="__ROOT__/usr/local/location">
+/opt/location
+          </file>
+        </scons_example>
 
         <para>
 
@@ -1674,16 +1762,12 @@
 
         </para>
 
-        <screen>
-          % <userinput>scons -Q foo.o</userinput>
-          cc -o foo.o -c -DPACKAGE="/opt/location" foo.c
-          % <userinput>scons -Q PACKAGE=/usr/local/location foo.o</userinput>
-          cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c
-          % <userinput>scons -Q PACKAGE=yes foo.o</userinput>
-          cc -o foo.o -c -DPACKAGE="True" foo.c
-          % <userinput>scons -Q PACKAGE=no foo.o</userinput>
-          cc -o foo.o -c -DPACKAGE="False" foo.c
-        </screen>
+        <scons_output example="commandline_PackageVariable" suffix="1">
+          <scons_output_command>scons -Q foo.o</scons_output_command>
+          <scons_output_command>scons -Q PACKAGE=__ROOT__/usr/local/location foo.o</scons_output_command>
+          <scons_output_command>scons -Q PACKAGE=yes foo.o</scons_output_command>
+          <scons_output_command>scons -Q PACKAGE=no foo.o</scons_output_command>
+        </scons_output>
 
       </section>
 
@@ -1710,25 +1794,27 @@
 
       </para>
 
-      <programlisting>
-          vars = Variables()
-          vars.AddVariables(
-              ('RELEASE', 'Set to 1 to build for release', 0),
-              ('CONFIG', 'Configuration file', '/etc/my_config'),
-              BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
-              EnumVariable('debug', 'debug output and symbols', 'no',
-                         allowed_values=('yes', 'no', 'full'),
-                         map={}, ignorecase=0),  # case sensitive
-              ListVariable('shared',
-                         'libraries to build as shared libraries',
-                         'all',
-                         names = list_of_libs),
-              PackageVariable('x11',
-                            'use X11 installed here (yes = search some places)',
-                            'yes'),
-              PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
-          )
-      </programlisting>
+      <scons_example name="commandline_AddVariables_1">
+        <file name="SConstruct" printme="1">
+vars = Variables()
+vars.AddVariables(
+    ('RELEASE', 'Set to 1 to build for release', 0),
+    ('CONFIG', 'Configuration file', '/etc/my_config'),
+    BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
+    EnumVariable('debug', 'debug output and symbols', 'no',
+               allowed_values=('yes', 'no', 'full'),
+               map={}, ignorecase=0),  # case sensitive
+    ListVariable('shared',
+               'libraries to build as shared libraries',
+               'all',
+               names = list_of_libs),
+    PackageVariable('x11',
+                  'use X11 installed here (yes = search some places)',
+                  'yes'),
+    PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
+)
+        </file>
+      </scons_example>
 
       <para>
       </para>
@@ -1769,17 +1855,22 @@
 
       </para>
 
-      <programlisting>
-           vars = Variables(None)
-           vars.Add('RELEASE', 'Set to 1 to build for release', 0)
-           env = Environment(variables = vars,
-                             CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
-           unknown = vars.UnknownVariables()
-           if unknown:
-               print "Unknown variables:", unknown.keys()
-               Exit(1)
-           env.Program('foo.c')
-      </programlisting>
+      <scons_example name="commandline_UnknownVariables">
+        <file name="SConstruct" printme="1">
+vars = Variables(None)
+vars.Add('RELEASE', 'Set to 1 to build for release', 0)
+env = Environment(variables = vars,
+                  CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
+unknown = vars.UnknownVariables()
+if unknown:
+    print "Unknown variables:", unknown.keys()
+    Exit(1)
+env.Program('foo.c')
+        </file>
+        <file name="foo.c">
+foo.c
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1800,10 +1891,9 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q NOT_KNOWN=foo</userinput>
-        Unknown variables: ['NOT_KNOWN']
-      </screen>
+      <scons_output example="commandline_UnknownVariables" suffix="1">
+        <scons_output_command>scons -Q NOT_KNOWN=foo</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1852,12 +1942,20 @@
 
       </para>
 
-      <programlisting>
-        if 'bar' in COMMAND_LINE_TARGETS:
-            print "Don't forget to copy `bar' to the archive!"
-        Default(Program('foo.c'))
-        Program('bar.c')
-      </programlisting>
+      <scons_example name="commandline_COMMAND_LINE_TARGETS">
+        <file name="SConstruct" printme="1">
+if 'bar' in COMMAND_LINE_TARGETS:
+    print "Don't forget to copy `bar' to the archive!"
+Default(Program('foo.c'))
+Program('bar.c')
+        </file>
+        <file name="foo.c">
+foo.c
+        </file>
+        <file name="bar.c">
+foo.c
+        </file>
+      </scons_example>
 
       <para>
 
@@ -1868,15 +1966,10 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q</userinput>
-        cc -o foo.o -c foo.c
-        cc -o foo foo.o
-        % <userinput>scons -Q bar</userinput>
-        Don't forget to copy `bar' to the archive!
-        cc -o bar.o -c bar.c
-        cc -o bar bar.o
-      </screen>
+      <scons_output example="commandline_COMMAND_LINE_TARGETS" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
+        <scons_output_command>scons -Q bar</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1911,12 +2004,20 @@
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         hello = env.Program('hello.c')
-         env.Program('goodbye.c')
-         Default(hello)
-      </programlisting>
+      <scons_example name="commandline_Default1">
+         <file name="SConstruct" printme="1">
+env = Environment()
+hello = env.Program('hello.c')
+env.Program('goodbye.c')
+Default(hello)
+         </file>
+         <file name="hello.c">
+hello.c
+         </file>
+         <file name="goodbye.c">
+goodbye.c
+         </file>
+      </scons_example>
 
       <para>
 
@@ -1927,16 +2028,11 @@
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         cc -o hello.o -c hello.c
-         cc -o hello hello.o
-         % <userinput>scons -Q</userinput>
-         scons: `hello' is up to date.
-         % <userinput>scons -Q goodbye</userinput>
-         cc -o goodbye.o -c goodbye.c
-         cc -o goodbye goodbye.o
-      </screen>
+      <scons_output example="commandline_Default1" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+         <scons_output_command>scons -Q</scons_output_command>
+         <scons_output_command>scons -Q goodbye</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1949,13 +2045,9 @@
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q .</userinput>
-         cc -o goodbye.o -c goodbye.c
-         cc -o goodbye goodbye.o
-         cc -o hello.o -c hello.c
-         cc -o hello hello.o
-      </screen>
+      <scons_output example="commandline_Default1" suffix="2">
+         <scons_output_command>scons -Q .</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -1966,14 +2058,25 @@
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         prog1 = env.Program('prog1.c')
-         Default(prog1)
-         prog2 = env.Program('prog2.c')
-         prog3 = env.Program('prog3.c')
-         Default(prog3)
-      </programlisting>
+      <scons_example name="commandline_Default2">
+         <file name="SConstruct" printme="1">
+env = Environment()
+prog1 = env.Program('prog1.c')
+Default(prog1)
+prog2 = env.Program('prog2.c')
+prog3 = env.Program('prog3.c')
+Default(prog3)
+         </file>
+         <file name="prog1.c">
+prog1.c
+         </file>
+         <file name="prog2.c">
+prog2.c
+         </file>
+         <file name="prog3.c">
+prog3.c
+         </file>
+      </scons_example>
 
       <para>
 
@@ -1983,11 +2086,11 @@
       </para>
 
       <programlisting>
-         env = Environment()
-         prog1 = env.Program('prog1.c')
-         prog2 = env.Program('prog2.c')
-         prog3 = env.Program('prog3.c')
-         Default(prog1, prog3)
+env = Environment()
+prog1 = env.Program('prog1.c')
+prog2 = env.Program('prog2.c')
+prog3 = env.Program('prog3.c')
+Default(prog1, prog3)
       </programlisting>
 
       <para>
@@ -2001,16 +2104,10 @@
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         cc -o prog1.o -c prog1.c
-         cc -o prog1 prog1.o
-         cc -o prog3.o -c prog3.c
-         cc -o prog3 prog3.o
-         % <userinput>scons -Q .</userinput>
-         cc -o prog2.o -c prog2.c
-         cc -o prog2 prog2.o
-      </screen>
+      <scons_output example="commandline_Default2" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+         <scons_output_command>scons -Q .</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -2019,12 +2116,28 @@
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         env.Program(['prog1/main.c', 'prog1/foo.c'])
-         env.Program(['prog2/main.c', 'prog2/bar.c'])
-         Default('prog1')
-      </programlisting>
+      <scons_example name="commandline_Default3">
+         <file name="SConstruct" printme="1">
+env = Environment()
+env.Program(['prog1/main.c', 'prog1/foo.c'])
+env.Program(['prog2/main.c', 'prog2/bar.c'])
+Default('prog1')
+         </file>
+         <directory name="prog1"></directory>
+         <directory name="prog2"></directory>
+         <file name="prog1/main.c">
+int main() { printf("prog1/main.c\n"); }
+         </file>
+         <file name="prog1/foo.c">
+int foo() { printf("prog1/foo.c\n"); }
+         </file>
+         <file name="prog2/main.c">
+int main() { printf("prog2/main.c\n"); }
+         </file>
+         <file name="prog2/bar.c">
+int bar() { printf("prog2/bar.c\n"); }
+         </file>
+      </scons_example>
 
       <para>
 
@@ -2033,18 +2146,11 @@
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         cc -o prog1/foo.o -c prog1/foo.c
-         cc -o prog1/main.o -c prog1/main.c
-         cc -o prog1/main prog1/main.o prog1/foo.o
-         % <userinput>scons -Q</userinput>
-         scons: `prog1' is up to date.
-         % <userinput>scons -Q .</userinput>
-         cc -o prog2/bar.o -c prog2/bar.c
-         cc -o prog2/main.o -c prog2/main.c
-         cc -o prog2/main prog2/main.o prog2/bar.o
-      </screen>
+      <scons_output example="commandline_Default3" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+         <scons_output_command>scons -Q</scons_output_command>
+         <scons_output_command>scons -Q .</scons_output_command>
+      </scons_output>
 
       <para>
 
@@ -2055,12 +2161,20 @@
 
       </para>
 
-      <programlisting>
-         env = Environment()
-         prog1 = env.Program('prog1.c')
-         prog2 = env.Program('prog2.c')
-         Default(None)
-      </programlisting>
+      <scons_example name="commandline_Default4">
+         <file name="SConstruct" printme="1">
+env = Environment()
+prog1 = env.Program('prog1.c')
+prog2 = env.Program('prog2.c')
+Default(None)
+         </file>
+         <file name="prog1.c">
+prog1.c
+         </file>
+         <file name="prog2.c">
+prog2.c
+         </file>
+      </scons_example>
 
       <para>
 
@@ -2068,15 +2182,10 @@
 
       </para>
 
-      <screen>
-         % <userinput>scons -Q</userinput>
-         scons: *** No targets specified and no Default() targets found.  Stop.
-         % <userinput>scons -Q .</userinput>
-         cc -o prog1.o -c prog1.c
-         cc -o prog1 prog1.o
-         cc -o prog2.o -c prog2.c
-         cc -o prog2 prog2.o
-      </screen>
+      <scons_output example="commandline_Default4" suffix="1">
+         <scons_output_command>scons -Q</scons_output_command>
+         <scons_output_command>scons -Q .</scons_output_command>
+      </scons_output>
 
       <section>
       <title>Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable</title>
@@ -2097,11 +2206,16 @@
 
         </para>
 
-        <programlisting>
-           prog1 = Program('prog1.c')
-           Default(prog1)
-           print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
-        </programlisting>
+        <scons_example name="commandline_DEFAULT_TARGETS_1">
+           <file name="SConstruct" printme="1">
+prog1 = Program('prog1.c')
+Default(prog1)
+print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
+           </file>
+           <file name="prog1.c">
+prog1.c
+           </file>
+        </scons_example>
 
         <para>
 
@@ -2113,16 +2227,9 @@
 
         </para>
 
-        <screen>
-           % <userinput>scons</userinput>
-           scons: Reading SConscript files ...
-           DEFAULT_TARGETS is ['prog1']
-           scons: done reading SConscript files.
-           scons: Building targets ...
-           cc -o prog1.o -c prog1.c
-           cc -o prog1 prog1.o
-           scons: done building targets.
-        </screen>
+        <scons_output example="commandline_DEFAULT_TARGETS_1" suffix="1">
+           <scons_output_command>scons</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -2133,14 +2240,22 @@
 
         </para>
 
-        <programlisting>
-           prog1 = Program('prog1.c')
-           Default(prog1)
-           print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
-           prog2 = Program('prog2.c')
-           Default(prog2)
-           print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
-        </programlisting>
+        <scons_example name="commandline_DEFAULT_TARGETS_2">
+           <file name="SConstruct" printme="1">
+prog1 = Program('prog1.c')
+Default(prog1)
+print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+prog2 = Program('prog2.c')
+Default(prog2)
+print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+           </file>
+           <file name="prog1.c">
+prog1.c
+           </file>
+           <file name="prog2.c">
+prog2.c
+           </file>
+        </scons_example>
 
         <para>
 
@@ -2148,19 +2263,9 @@
 
         </para>
 
-        <screen>
-           % <userinput>scons</userinput>
-           scons: Reading SConscript files ...
-           DEFAULT_TARGETS is now ['prog1']
-           DEFAULT_TARGETS is now ['prog1', 'prog2']
-           scons: done reading SConscript files.
-           scons: Building targets ...
-           cc -o prog1.o -c prog1.c
-           cc -o prog1 prog1.o
-           cc -o prog2.o -c prog2.c
-           cc -o prog2 prog2.o
-           scons: done building targets.
-        </screen>
+        <scons_output example="commandline_DEFAULT_TARGETS_2" suffix="1">
+           <scons_output_command>scons</scons_output_command>
+        </scons_output>
 
         <para>
 
@@ -2198,12 +2303,12 @@
 
       </para>
 
-      <programlisting>
-        if COMMAND_LINE_TARGETS:
-            targets = COMMAND_LINE_TARGETS
-        else:
-            targets = DEFAULT_TARGETS
-      </programlisting>
+      <sconstruct>
+if COMMAND_LINE_TARGETS:
+    targets = COMMAND_LINE_TARGETS
+else:
+    targets = DEFAULT_TARGETS
+      </sconstruct>
 
       <para>
 
@@ -2228,12 +2333,20 @@
 
       </para>
 
-      <programlisting>
-        prog1 = Program('prog1.c')
-        Program('prog2.c')
-        Default(prog1)
-        print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
-      </programlisting>
+      <scons_example name="commandline_BUILD_TARGETS_1">
+        <file name="SConstruct" printme="1">
+prog1 = Program('prog1.c')
+Program('prog2.c')
+Default(prog1)
+print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
+        </file>
+        <file name="prog1.c">
+prog1.c
+        </file>
+        <file name="prog2.c">
+prog2.c
+        </file>
+      </scons_example>
 
       <para>
 
@@ -2243,23 +2356,14 @@
 
       </para>
 
-      <screen>
-        % <userinput>scons -Q</userinput>
-        BUILD_TARGETS is ['prog1']
-        cc -o prog1.o -c prog1.c
-        cc -o prog1 prog1.o
-        % <userinput>scons -Q prog2</userinput>
-        BUILD_TARGETS is ['prog2']
-        cc -o prog2.o -c prog2.c
-        cc -o prog2 prog2.o
-        % <userinput>scons -Q -c .</userinput>
-        BUILD_TARGETS is ['.']
-        Removed prog1.o
-        Removed prog1
-        Removed prog2.o
-        Removed prog2
-      </screen>
+      <scons_output example="commandline_BUILD_TARGETS_1" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
+        <scons_output_command>scons -Q prog2</scons_output_command>
+        <scons_output_command>scons -Q -c .</scons_output_command>
+      </scons_output>
 
     </section>
 
   </section>
+
+</chapter>
-- 
cgit v1.2.3