New upstream version 3.1.2upstream/3.1.2upstream

15 files changed, 205 insertions, 264 deletions

diff --git a/doc/user/README b/doc/user/README
index 5433ea2..a66d20b 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -12,7 +12,7 @@ Writing examples: here's a simple template.
  <scons_example name="Foo">
    <file name="SConstruct">
     env = Environment()
-    print env.Dump("CC")
+    print(env.Dump("CC"))
    </file>
  </scons_example>
 
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 2fcb11b..a408479 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -196,7 +196,7 @@ env.Foo('file.foo', 'file.input')
        <file name="file.input">
 file.input
        </file>
-       <file name="foobuild" chmod="0755">
+       <file name="foobuild" chmod="0o755">
 cat
        </file>
     </scons_example>
@@ -309,7 +309,7 @@ file.input
        <file name="hello.c">
 hello.c
        </file>
-       <file name="foobuild" chmod="0755">
+       <file name="foobuild" chmod="0o755">
 cat
        </file>
     </scons_example>
@@ -389,7 +389,7 @@ file1.input
        <file name="file2.input">
 file2.input
        </file>
-       <file name="foobuild" chmod="0755">
+       <file name="foobuild" chmod="0o755">
 cat
        </file>
     </scons_example>
@@ -682,7 +682,7 @@ env.Foo('file')
        <file name="file.input">
 file.input
        </file>
-       <file name="foobuild" chmod="0755">
+       <file name="foobuild" chmod="0o755">
 cat
        </file>
     </scons_example>
@@ -766,7 +766,7 @@ file.input
        <file name="new_source">
 new_source
        </file>
-       <file name="foobuild" chmod="0755">
+       <file name="foobuild" chmod="0o755">
 cat
        </file>
     </scons_example>
@@ -840,7 +840,7 @@ modify1.input
         <file name="modify2.in">
 modify2.input
         </file>
-        <file name="my_command" chmod="0755">
+        <file name="my_command" chmod="0o755">
 cat
         </file>
 
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml
index bb1d32b..e14ed07 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE sconsdoc [
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
-    
+
     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
     %builders-mod;
     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
@@ -89,7 +89,7 @@
     all of the command-line variable settings,
     the ability to apply command-line variable settings
     to construction environments,
-    and functions for configuring 
+    and functions for configuring
     specific types of variables
     (Boolean values, path names, etc.)
     with automatic validation of the user's specified values.
@@ -599,24 +599,30 @@ foo.in
       &SCons; also allows you to define your own
       command-line options with the &AddOption; function.
       The &AddOption; function takes the same arguments
-      as the <function>optparse.add_option</function> function
-      from the standard Python library.
+      as the <function>add_option</function> method
+      from the standard Python library module <emphasis>optparse</emphasis>.
       <footnote>
       <para>
       The &AddOption; function is,
       in fact, implemented using a subclass
-      of the <classname>optparse.OptionParser</classname>.
+      of <classname>optparse.OptionParser</classname>.
       </para>
       </footnote>
+      </para>
+
+      <para>
       Once you have added a custom command-line option
       with the &AddOption; function,
       the value of the option (if any) is immediately available
       using the standard &GetOption; function.
+      <!--
       (The value can also be set using &SetOption;,
       although that's not very useful in practice
       because a default value can be specified in
       directly in the &AddOption; call.)
-
+      -->
+      &SetOption; is not currently supported for
+      options added with &AddOption;.
       </para>
 
       <para>
@@ -678,6 +684,47 @@ foo.in
         <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command>
       </scons_output>
 
+      <note>
+      <para>
+      Option-arguments separated from long options by whitespace,
+      rather than by an <literal>=</literal>, cannot be correctly
+      resolved by <command>scons</command>.
+      While <literal>--input=ARG</literal>
+      is clearly opt followed by arg, for <literal>--input ARG</literal>
+      it is not possible to tell without instructions whether
+      <parameter>ARG</parameter> is an argument belonging to the
+      <parameter>input</parameter> option or a positional argument.
+      <command>scons</command> treats positional arguments as either
+      command-line build options or command-line targets
+      which are made available for use in an &SConscript;
+      (see the immediately following sections for details).
+      Thus, they must be collected before &SConscript; processing
+      takes place. Since &AddOption; calls, which provide
+      the processing instructions to resolve any ambiguity,
+      happen in an &SConscript;,
+      <command>scons</command> does not know in time
+      for options added this way, and unexpected things will happen,
+      such as option-arguments assigned as targets and/or exceptions
+      due to missing option-arguments.
+      </para>
+      <para>
+      As a result, this usage style should be avoided when invoking
+      <command>scons</command>.  For single-argument
+      options, use the <literal>--input=ARG</literal> form on the
+      command line. For multiple-argument options
+      (<parameter>nargs</parameter> greater than one),
+      set <parameter>nargs</parameter> to one in
+      &AddOption; calls and either: combine the option-arguments into one word
+      with a separator, and parse the result in your own code
+      (see the built-in <parameter>--debug</parameter> option, which
+      allows specifying multiple arguments as a single comma-separated
+      word, for an example of such usage); or allow the option to
+      be specified multiple times by setting
+      <literal>action='append'</literal>. Both methods can be
+      supported at the same time.
+      </para>
+      </note>
+
     </section>
 
   </section>
@@ -1132,12 +1179,12 @@ vars = Variables('custom.py', ARGUMENTS)
       </screen>
 
       <para>
-      
+
       where values in the option file &custom_py; get overwritten
       by the ones specified on the command line.
 
       </para>
-      
+
     </section>
 
     <section>
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index bb0a142..96a8685 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -764,185 +764,8 @@ int main() { printf("Hello, world!\n"); }
     encounter them in older &SConscript; files.
 
     </para>
-  
-    <section>
-    <title>The &SourceSignatures; Function</title>
-
-      <para>
-
-      The &SourceSignatures; function is fairly straightforward,
-      and supports two different argument values
-      to configure whether source file changes should be decided
-      using MD5 signatures:
-
-      </para>
-
-      <sconstruct>
-Program('hello.c')
-SourceSignatures('MD5')
-      </sconstruct>
-
-      <para>
-
-      Or using time stamps:
-
-      </para>
-
-      <sconstruct>
-Program('hello.c')
-SourceSignatures('timestamp')
-      </sconstruct>
-
-      <para>
-
-      These are roughly equivalent to specifying
-      <function>Decider('MD5')</function>
-      or
-      <function>Decider('timestamp-match')</function>,
-      respectively,
-      although it only affects how SCons makes
-      decisions about dependencies on
-      <emphasis>source</emphasis> files--that is,
-      files that are not built from any other files.
-
-      </para>
-
-    </section>
-
-    <section>
-    <title>The &TargetSignatures; Function</title>
-
-      <para>
-
-      The &TargetSignatures; function
-      specifies how &SCons; decides
-      when a target file has changed
-      <emphasis>when it is used as a
-      dependency of (input to) another target</emphasis>--that is,
-      the &TargetSignatures; function configures
-      how the signatures of "intermediate" target files
-      are used when deciding if a "downstream" target file
-      must be rebuilt.
-      <footnote><para>
-      This easily-overlooked distinction between
-      how &SCons; decides if the target itself must be rebuilt
-      and how the target is then used to decide if a different
-      target must be rebuilt is one of the confusing
-      things that has led to the &TargetSignatures;
-      and &SourceSignatures; functions being
-      replaced by the simpler &Decider; function.
-      </para></footnote>
-
-      </para>
-
-      <para>
-
-      The &TargetSignatures; function supports the same
-      <literal>'MD5'</literal> and <literal>'timestamp'</literal>
-      argument values that are supported by the &SourceSignatures;,
-      with the same meanings, but applied to target files.
-      That is, in the example:
-
-      </para>
-
-      <sconstruct>
-Program('hello.c')
-TargetSignatures('MD5')
-      </sconstruct>
-
-      <para>
-
-      The MD5 checksum of the &hello_o; target file
-      will be used to decide if it has changed since the last
-      time the "downstream" &hello; target file was built.
-      And in the example:
-      
-      </para>
-
-      <sconstruct>
-Program('hello.c')
-TargetSignatures('timestamp')
-      </sconstruct>
-
-      <para>
-
-      The modification time of the &hello_o; target file
-      will be used to decide if it has changed since the last
-      time the "downstream" &hello; target file was built.
-
-      </para>
-
-      <para>
-
-      The &TargetSignatures; function supports
-      two additional argument values:
-      <literal>'source'</literal> and <literal>'build'</literal>.
-      The <literal>'source'</literal> argument
-      specifies that decisions involving
-      whether target files have changed
-      since a previous build
-      should use the same behavior
-      for the decisions configured for source files
-      (using the &SourceSignatures; function).
-      So in the example:
-
-      </para>
-
-      <sconstruct>
-Program('hello.c')
-TargetSignatures('source')
-SourceSignatures('timestamp')
-      </sconstruct>
-
-      <para>
-
-      All files, both targets and sources,
-      will use modification times
-      when deciding if an input file
-      has changed since the last
-      time a target was built.
-
-      </para>
-
-      <para>
-
-      Lastly, the <literal>'build'</literal> argument
-      specifies that &SCons; should examine
-      the build status of a target file
-      and always rebuild a "downstream" target
-      if the target file was itself rebuilt,
-      without re-examining the contents or timestamp
-      of the newly-built target file.
-      If the target file was not rebuilt during
-      this &scons; invocation,
-      then the target file will be examined
-      the same way as configured by
-      the &SourceSignature; call
-      to decide if it has changed.
-
-      </para>
-
-      <para>
-
-      This mimics the behavior of
-      <literal>build signatures</literal>
-      in earlier versions of &SCons;.
-      A &buildsignature; re-combined
-      signatures of all the input files
-      that went into making the target file,
-      so that the target file itself
-      did not need to have its contents read
-      to compute an MD5 signature.
-      This can improve performance for some configurations,
-      but is generally not as effective as using
-      <literal>Decider('MD5-timestamp')</literal>.
-
-      </para>
-
-    </section>
-
   </section>
-
+  
   <section>
   <title>Implicit Dependencies:  The &cv-CPPPATH; Construction Variable</title>
 
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index ede9bc3..5df58c5 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -618,7 +618,7 @@ int main() { }
 
       <para>
 
-      You can fetch individual construction variables
+      You can fetch individual &consvars;
       using the normal syntax
       for accessing individual named items in a Python dictionary:
 
@@ -645,20 +645,21 @@ print("CC is: %s"%env['CC'])
 
       <para>
 
-      A construction environment, however,
-      is actually an object with associated methods, etc.
+      A &consenv;
+      is actually an object with associated methods and
+      attributes.
       If you want to have direct access to only the
-      dictionary of construction variables,
+      dictionary of &consvars;
       you can fetch this using the &Dictionary; method:
 
       </para>
 
       <scons_example name="environments_ex6b">
          <file name="SConstruct" printme="1">
-env = Environment(FOO = 'foo', BAR = 'bar')
-dict = env.Dictionary()
+env = Environment(FOO='foo', BAR='bar')
+cvars = env.Dictionary()
 for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
-    print("key = %s, value = %s" % (key, dict[key]))
+    print("key = %s, value = %s" % (key, cvars[key]))
          </file>
       </scons_example>
 
@@ -687,7 +688,7 @@ for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
       <para>
 
       If you want to loop and print the values of
-      all of the construction variables in a construction environment,
+      all of the &consvars; in a &consenv;,
       the Python code to do that in sorted order might look something like:
 
       </para>
@@ -698,6 +699,16 @@ for item in sorted(env.Dictionary().items()):
     print("construction variable = '%s', value = '%s'" % item)
       </sconstruct>
 
+      <para>
+      It should be noted that for the previous example, there is actually
+      a &consenv; method that does the same thing more simply,
+      and tries to format the output nicely as well:
+      </para>
+      <sconstruct>
+env = Environment()
+print(env.Dump())
+      </sconstruct>
+
     </section>
 
     <section>
@@ -706,10 +717,10 @@ for item in sorted(env.Dictionary().items()):
       <para>
 
       Another way to get information from
-      a construction environment
+      a &consenv;
       is to use the &subst; method
       on a string containing <literal>$</literal> expansions
-      of construction variable names.
+      of &consvar; names.
       As a simple example,
       the example from the previous
       section that used
@@ -728,7 +739,7 @@ print("CC is: %s"%env.subst('$CC'))
 
       One advantage of using
       &subst; to expand strings is
-      that construction variables
+      that &consvars;
       in the result get re-expanded until
       there are no expansions left in the string.
       So a simple fetch of a value like
@@ -875,33 +886,30 @@ print("value is: %s"%env.subst( '->${1 / 0}&lt;-' ))
       <para>
 
       All of the &Builder; functions that we've introduced so far,
-      like &Program; and &Library;,
-      actually use a default &consenv;
-      that contains settings
-      for the various compilers
-      and other tools that
-      &SCons; configures by default,
-      or otherwise knows about
-      and has discovered on your system.
-      The goal of the default construction environment
-      is to make many configurations to "just work"
-      to build software using
-      readily available tools
+      like &Program; and &Library;, use a &consenv;
+      that contains settings for the various compilers
+      and other tools that &SCons; configures by default,
+      or otherwise knows about and has discovered on your system.
+      If not invoked as methods of a specific &consenv;,
+      they use the default &consenv;
+      The goal of the default &consenv;
+      is to make many configurations "just work"
+      to build software using readily available tools
       with a minimum of configuration changes.
 
       </para>
 
       <para>
 
-      You can, however, control the settings
-      in the default construction environment
+      If needed, you can control the default &consenv;
       by using the &DefaultEnvironment; function
-      to initialize various settings:
+      to initialize various settings by passing
+      them as keyword arguments:
 
       </para>
 
       <sconstruct>
-DefaultEnvironment(CC = '/usr/local/bin/gcc')
+DefaultEnvironment(CC='/usr/local/bin/gcc')
       </sconstruct>
 
       <para>
@@ -917,15 +925,15 @@ DefaultEnvironment(CC = '/usr/local/bin/gcc')
 
       <para>
 
-      Note that the &DefaultEnvironment; function
-      returns the initialized
-      default construction environment object,
-      which can then be manipulated like any
-      other construction environment.
-      So the following
-      would be equivalent to the
-      previous example,
-      setting the &cv-CC;
+      The &DefaultEnvironment; function
+      returns the initialized default &consenv; object,
+      which can then be manipulated like any other &consenv;
+      (note that the default environment works like a singleton -
+      it can have only one instance - so the keyword arguments
+      are processed only on the first call. On any subsequent
+      call the existing object is returned).
+      So the following would be equivalent to the
+      previous example, setting the &cv-CC;
       variable to <filename>/usr/local/bin/gcc</filename>
       but as a separate step after
       the default construction environment has been initialized:
@@ -960,8 +968,8 @@ env['CC'] = '/usr/local/bin/gcc'
       </para>
 
       <sconstruct>
-env = DefaultEnvironment(tools = ['gcc', 'gnulink'],
-                         CC = '/usr/local/bin/gcc')
+env = DefaultEnvironment(tools=['gcc', 'gnulink'],
+                         CC='/usr/local/bin/gcc')
       </sconstruct>
 
       <para>
@@ -983,9 +991,8 @@ env = DefaultEnvironment(tools = ['gcc', 'gnulink'],
 
       <para>
 
-      The real advantage of construction environments
-      is that you can create as many different construction
-      environments as you need,
+      The real advantage of &consenvs;
+      is that you can create as many different ones as you need,
       each tailored to a different way to build
       some piece of software or other file.
       If, for example, we need to build
@@ -1018,7 +1025,7 @@ int main() { }
 
       <para>
 
-      We can even use multiple construction environments to build
+      We can even use multiple &consenvs; to build
       multiple versions of a single program.
       If you do this by simply trying to use the
       &b-link-Program; builder with both environments, though,
@@ -1641,7 +1648,7 @@ env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin'
 env = Environment()
 env.Command('foo', [], '__ROOT__/usr/bin/printenv.py')
       </file>
-      <file name="__ROOT__/usr/bin/printenv.py" chmod="0755">
+      <file name="__ROOT__/usr/bin/printenv.py" chmod="0o755">
 #!/usr/bin/env python
 import os
 import sys
diff --git a/doc/user/factories.xml b/doc/user/factories.xml
index 43e417b..0756ad0 100644
--- a/doc/user/factories.xml
+++ b/doc/user/factories.xml
@@ -161,7 +161,7 @@ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
 SConscript('S')
       </file>
       <file name="file.in">file.in</file>
-      <file name="modify" chmod="0755">
+      <file name="modify" chmod="0o755">
 touch $*
       </file>
     </scons_example>
@@ -231,7 +231,7 @@ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
 SConscript('S')
       </file>
       <file name="file.in">file.in</file>
-      <file name="modify" chmod="0755">
+      <file name="modify" chmod="0o755">
 touch $*
       </file>
     </scons_example>
@@ -325,7 +325,7 @@ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
 SConscript('S')
       </file>
       <file name="file.in">file.in</file>
-      <file name="modify" chmod="0755">
+      <file name="modify" chmod="0o755">
 touch $*
       </file>
     </scons_example>
@@ -416,7 +416,7 @@ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
 SConscript('S')
       </file>
       <file name="file.in">file.in</file>
-      <file name="process" chmod="0755">
+      <file name="process" chmod="0o755">
 touch $*
       </file>
     </scons_example>
@@ -452,7 +452,7 @@ touch $*
 Command("file.out", "file.in",
         [
           Copy("$TARGET", "$SOURCE"),
-          Chmod("$TARGET", 0755),
+          Chmod("$TARGET", 0o755),
         ])
       </file>
       <file name="file.in">file.in</file>
diff --git a/doc/user/file-removal.xml b/doc/user/file-removal.xml
index fe38cf7..e772eeb 100644
--- a/doc/user/file-removal.xml
+++ b/doc/user/file-removal.xml
@@ -214,7 +214,7 @@ foo.in
       <file name="foo.log">
 foo.log
       </file>
-      <file name="build" chmod="0755">
+      <file name="build" chmod="0o755">
 cat $3 > $2
       </file>
     </scons_example>
diff --git a/doc/user/install.xml b/doc/user/install.xml
index b3cb9dd..d977e6b 100644
--- a/doc/user/install.xml
+++ b/doc/user/install.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE sconsdoc [
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
-    
+
     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
     %builders-mod;
     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
@@ -11,7 +11,7 @@
     %tools-mod;
     <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
     %variables-mod;
-    
+
 ]>
 
 <chapter id="chap-install"
@@ -50,7 +50,7 @@
   Once a program is built,
   it is often appropriate to install it in another
   directory for public use.
-  You use the &Install; method 
+  You use the &Install; method
   to arrange for a program, or any other file,
   to be copied into a destination directory:
 
@@ -226,7 +226,7 @@ int main() { printf("Hello, world!\n"); }
 
     <para>
 
-    Lastly, if you have multiple files that all
+    If you have multiple files that all
     need to be installed with different file names,
     you can either call the &InstallAs; function
     multiple times, or as a shorthand,
@@ -268,4 +268,66 @@ int main() { printf("Goodbye, world!\n"); }
 
   </section>
 
+  <section>
+  <title>Installing a Shared Library</title>
+
+    <para>
+    If a shared library is created with the
+    &cv-link-SHLIBVERSION; variable set,
+    &scons; will create symbolic links as needed based on that
+    variable.  To properly install such a library including the
+    symbolic links, use the &InstallVersionedLib; function.
+    </para>
+
+    <para>
+    For example, on a Linux system, this instruction:
+    </para>
+
+    <sconstruct>
+foo =  env.SharedLibrary(target="foo", source="foo.c", SHLIBVERSION="1.2.3")
+    </sconstruct>
+
+    <para>
+    Will produce a shared library
+    <filename>libfoo.so.1.2.3</filename>
+    and symbolic links
+    <filename>libfoo.so</filename> and
+    <filename>libfoo.so.1</filename>
+    which point to
+    <filename>libfoo.so.1.2.3</filename>.
+    You can use the Node returned by the &SharedLibrary;
+    builder in order to install the library and its
+    symbolic links in one go without having to list
+    them individually:
+    </para>
+
+    <sconstruct>
+env.InstallVersionedLib(target="lib", source=foo)
+    </sconstruct>
+
+<!-- didn't get this to illustrate what I expected: example reports
+     installing lib without version, while manual effort has it:
+
+    <scons_example name="install_ex6">
+      <file name="SConstruct" printme="1">
+env = Environment()
+foo =  env.SharedLibrary(target="foo", source="foo.c", SHLIBVERSION="1.2.3")
+ins = env.InstallVersionedLib(target="lib", source=foo)
+env.Alias('install', ins)
+      </file>
+      <file name="foo.c">
+int call_foo() {
+    printf("Hello world");
+    return(0);
+}
+      </file>
+    </scons_example>
+
+    <scons_output example="install_ex6" suffix="1">
+       <scons_output_command>scons -Q install</scons_output_command>
+    </scons_output>
+-->
+
+  </section>
+
 </chapter>
diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml
index d802125..f4438f8 100644
--- a/doc/user/mergeflags.xml
+++ b/doc/user/mergeflags.xml
@@ -77,7 +77,7 @@ env = Environment()
 env.Append(CCFLAGS = '-option -O3 -O1')
 flags = { 'CCFLAGS' : '-whatever -O3' }
 env.MergeFlags(flags)
-print env['CCFLAGS']
+print(env['CCFLAGS'])
    </file>
  </scons_example>
 
@@ -104,7 +104,7 @@ env = Environment()
 env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include'])
 flags = { 'CPPPATH' : ['/usr/opt/include', '/usr/local/include'] }
 env.MergeFlags(flags)
-print env['CPPPATH']
+print(env['CPPPATH'])
    </file>
  </scons_example>
 
@@ -138,8 +138,8 @@ env = Environment()
 env.Append(CCFLAGS = '-option -O3 -O1')
 env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include'])
 env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include')
-print env['CCFLAGS']
-print env['CPPPATH']
+print(env['CCFLAGS'])
+print(env['CPPPATH'])
    </file>
  </scons_example>
 
diff --git a/doc/user/output.xml b/doc/user/output.xml
index db16393..c0edbca 100644
--- a/doc/user/output.xml
+++ b/doc/user/output.xml
@@ -309,7 +309,7 @@ Linking foo
     <scons_example name="output_COMSTR-VERBOSE">
        <file name="SConstruct" printme="1">
 env = Environment()
-if ARGUMENTS.get('VERBOSE') != "1':
+if ARGUMENTS.get('VERBOSE') != '1':
     env['CCCOMSTR'] = "Compiling $TARGET"
     env['LINKCOMSTR'] = "Linking $TARGET"
 env.Program('foo.c')
diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml
index 096d236..4adb20f 100644
--- a/doc/user/parseconfig.xml
+++ b/doc/user/parseconfig.xml
@@ -87,7 +87,7 @@
 env = Environment()
 env['CPPPATH'] = ['/lib/compat']
 env.ParseConfig("pkg-config x11 --cflags --libs")
-print env['CPPPATH']
+print(env['CPPPATH'])
    </file>
  </scons_example>
 
@@ -139,7 +139,7 @@ scons: `.' is up to date.
 env = Environment()
 env.ParseConfig("pkg-config x11 --cflags --libs")
 env.ParseConfig("pkg-config x11 --cflags --libs")
-print env['CPPPATH']
+print(env['CPPPATH'])
    </file>
  </scons_example>
 
diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml
index 26313ce..cc31b3b 100644
--- a/doc/user/parseflags.xml
+++ b/doc/user/parseflags.xml
@@ -80,11 +80,12 @@
 
  <scons_example name="parseflags_ex1">
    <file name="SConstruct" printme="1">
+from __future__ import print_function
 env = Environment()
 d = env.ParseFlags("-I/opt/include -L/opt/lib -lfoo")
 for k,v in sorted(d.items()):
     if v:
-        print k, v
+        print(k, v)
 env.MergeFlags(d)
 env.Program('f1.c')
    </file>
@@ -119,11 +120,12 @@ int main() { return 0; }
 
  <scons_example name="parseflags_ex2">
    <file name="SConstruct" printme="1">
+from __future__ import print_function
 env = Environment()
 d = env.ParseFlags("-whatever")
 for k,v in sorted(d.items()):
     if v:
-        print k, v
+        print(k, v)
 env.MergeFlags(d)
 env.Program('f1.c')
    </file>
@@ -145,11 +147,12 @@ env.Program('f1.c')
 
  <scons_example name="parseflags_ex3">
    <file name="SConstruct" printme="1">
+from __future__ import print_function
 env = Environment()
 d = env.ParseFlags(["-I/opt/include", ["-L/opt/lib", "-lfoo"]])
 for k,v in sorted(d.items()):
     if v:
-        print k, v
+        print(k, v)
 env.MergeFlags(d)
 env.Program('f1.c')
    </file>
@@ -172,11 +175,12 @@ int main() { return 0; }
 
  <scons_example name="parseflags_ex4">
    <file name="SConstruct" printme="1">
+from __future__ import print_function
 env = Environment()
 d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"])
 for k,v in sorted(d.items()):
     if v:
-        print k, v
+        print(k, v)
 env.MergeFlags(d)
 env.Program('f1.c')
    </file>
diff --git a/doc/user/separate.xml b/doc/user/separate.xml
index 26500d6..3640fef 100644
--- a/doc/user/separate.xml
+++ b/doc/user/separate.xml
@@ -149,10 +149,8 @@ program using the F<build/foo.c> path name.
   <para>
 
   One historical note:  the &VariantDir; function
-  used to be called &BuildDir;.
-  That name is still supported
-  but has been deprecated
-  because the &SCons; functionality
+  used to be called &BuildDir;, a name which was
+  removed because the &SCons; functionality
   differs from the model of a "build directory"
   implemented by other build systems like the GNU Autotools.
 
diff --git a/doc/user/sideeffect.xml b/doc/user/sideeffect.xml
index e630e4f..e8f0614 100644
--- a/doc/user/sideeffect.xml
+++ b/doc/user/sideeffect.xml
@@ -164,7 +164,7 @@ env.SideEffect('logfile.txt', f1 + f2)
    </file>
    <file name="file1.in">file1.in</file>
    <file name="file2.in">file2.in</file>
-   <file name="build" chmod="0755">
+   <file name="build" chmod="0o755">
 cat
    </file>
  </scons_example>
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml
index 606c727..a9da534 100644
--- a/doc/user/troubleshoot.xml
+++ b/doc/user/troubleshoot.xml
@@ -289,7 +289,7 @@ file3.c
     <scons_example name="troubleshoot_Dump">
       <file name="SConstruct" printme="1">
 env = Environment()
-print env.Dump()
+print(env.Dump())
       </file>
     </scons_example>
 
@@ -349,7 +349,7 @@ print env.Dump()
     <scons_example name="troubleshoot_Dump_ENV">
       <file name="SConstruct" printme="1">
 env = Environment()
-print env.Dump('ENV')
+print(env.Dump('ENV'))
       </file>
     </scons_example>