From 697e33ed224b539a42ff68121f7497f5bbf941b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= <debian@jff-webhosting.net>
Date: Sun, 14 Jul 2019 08:35:24 +0200
Subject: New upstream version 3.0.5

---
 doc/user/README                |   2 +-
 doc/user/SConstruct            |   2 +-
 doc/user/actions.xml           |   2 +-
 doc/user/add-method.xml        |   2 +-
 doc/user/alias.xml             |   2 +-
 doc/user/ant.xml               |   2 +-
 doc/user/build-install.xml     | 292 +++++++----------------------------------
 doc/user/builders-built-in.xml |   2 +-
 doc/user/builders-commands.xml |   2 +-
 doc/user/builders-writing.xml  |  24 +---
 doc/user/builders.xml          |   2 +-
 doc/user/caching.xml           |   2 +-
 doc/user/chtml.xsl             |   2 +-
 doc/user/command-line.xml      |  37 +++---
 doc/user/copyright.xml         |  55 ++++----
 doc/user/depends.xml           |  10 +-
 doc/user/environments.xml      |  32 ++---
 doc/user/epub.xsl              |   2 +-
 doc/user/errors.xml            |   2 +-
 doc/user/example.xml           |   2 +-
 doc/user/factories.xml         |   2 +-
 doc/user/file-removal.xml      |   2 +-
 doc/user/functions.xml         |   2 +-
 doc/user/gettext.xml           |   2 +-
 doc/user/hierarchy.xml         |   2 +-
 doc/user/html.xsl              |   2 +-
 doc/user/install.xml           |   2 +-
 doc/user/java.xml              |   2 +-
 doc/user/less-simple.xml       |  61 ++++++++-
 doc/user/libraries.xml         |   2 +-
 doc/user/main.xml              |   6 +-
 doc/user/make.xml              |   2 +-
 doc/user/mergeflags.xml        |   2 +-
 doc/user/misc.xml              |  57 +++++++-
 doc/user/nodes.xml             |   8 +-
 doc/user/output.xml            |   2 +-
 doc/user/parseconfig.xml       |   2 +-
 doc/user/parseflags.xml        |   4 +-
 doc/user/pdf.xsl               |   2 +-
 doc/user/preface.xml           |   2 +-
 doc/user/python.xml            |   2 +-
 doc/user/repositories.xml      |   2 +-
 doc/user/run.xml               |   2 +-
 doc/user/scanners.xml          |  57 +++++++-
 doc/user/sconf.xml             |   2 +-
 doc/user/scons_title.xsl       |   2 +-
 doc/user/separate.xml          |   2 +-
 doc/user/sideeffect.xml        |   2 +-
 doc/user/simple.xml            |   2 +-
 doc/user/sourcecode.xml        |   2 +-
 doc/user/tasks.xml             |   2 +-
 doc/user/tools.xml             |   2 +-
 doc/user/troubleshoot.xml      |   2 +-
 doc/user/variables.xml         |   2 +-
 doc/user/variants.xml          |   2 +-
 55 files changed, 338 insertions(+), 391 deletions(-)

(limited to 'doc/user')

diff --git a/doc/user/README b/doc/user/README
index 1718f0e..5433ea2 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -1,4 +1,4 @@
-# Copyright (c) 2001 - 2017 The SCons Foundation
+# Copyright (c) 2001 - 2019 The SCons Foundation
 
 When adding a new file, add it to main.xml and MANIFEST.
 
diff --git a/doc/user/SConstruct b/doc/user/SConstruct
index 96d6677..67a3fd5 100644
--- a/doc/user/SConstruct
+++ b/doc/user/SConstruct
@@ -3,7 +3,7 @@
 #
 
 #
-# Copyright (c) 2001 - 2017 The SCons Foundation
+# Copyright (c) 2001 - 2019 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
diff --git a/doc/user/actions.xml b/doc/user/actions.xml
index 3e60a9f..24ac8cf 100644
--- a/doc/user/actions.xml
+++ b/doc/user/actions.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml
index 0d30a48..0b1187c 100644
--- a/doc/user/add-method.xml
+++ b/doc/user/add-method.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/alias.xml b/doc/user/alias.xml
index fee9dd1..17a1b8f 100644
--- a/doc/user/alias.xml
+++ b/doc/user/alias.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/ant.xml b/doc/user/ant.xml
index bd35671..ed1aac6 100644
--- a/doc/user/ant.xml
+++ b/doc/user/ant.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml
index 845b9e6..07d5397 100644
--- a/doc/user/build-install.xml
+++ b/doc/user/build-install.xml
@@ -26,7 +26,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -90,9 +90,8 @@
   <title>Installing Python</title>
 
     <para>
-
     Because &SCons; is written in Python,
-    you must obviously have Python installed on your system
+    you need to have Python installed on your system
     to use &SCons;.
     Before you try to install Python,
     you should check to see if Python is already
@@ -102,27 +101,25 @@
     or
     <userinput>python --version</userinput>
     at your system's command-line prompt.
-
+    For Linux/Unix/MacOS/BSD type systems this looks like:
     </para>
 
     <screen>
 $ <userinput>python -V</userinput>
-Python 2.5.1
+Python 3.7.1
     </screen>
 
     <para>
-
-    And on a Windows system with Python installed:
-
+    In a cmd shell or PowerShell on a Windows system
+    (note PoweShell needs it spelled "python.exe" rather than "python"):
     </para>
 
     <screen>
 C:\><userinput>python -V</userinput>
-Python 2.5.1
+Python 3.7.1
     </screen>
 
     <para>
-
     If Python is not installed on your system,
     you will see an error message
     stating something like "command not found"
@@ -132,254 +129,70 @@ Python 2.5.1
     (on Windows).
     In that case, you need to install Python
     before you can install &SCons;.
-
     </para>
 
     <para>
-
     The standard location for information
     about downloading and installing Python is
     <ulink url="http://www.python.org/download/">http://www.python.org/download/</ulink>.
-    See that page for information about
-    how to download and install Python on your system.
-
+    See that page and associated links to get started.
     </para>
 
     <para>
+    For Linux systems, Python is
+    almost certainly available as a supported package, possibly
+    installed by default; this is often preferred to installing
+    by other means, and is easier than installing from source code.
+    Many such systems have separate packages for
+    Python 2 and Python 3. Building from source may still be a
+    useful option if you need a version that is not offered by
+    the distribution you are using.
+    </para>
 
-    &SCons; will work with any 2.x version of Python from 2.7 on;
-    3.0 and later are not yet supported.
+    <para>
+    &SCons; will work with Python 2.7.x or with Python 3.5 or later.
     If you need to install Python and have a choice,
-    we recommend using the most recent 2.x Python version available.
+    we recommend using the most recent Python version available.
     Newer Pythons have significant improvements
     that help speed up the performance of &SCons;.
-
     </para>
 
   </section>
 
   <section>
-  <title>Installing &SCons; From Pre-Built Packages</title>
+  <title>Installing &SCons;</title>
 
     <para>
-
-    &SCons; comes pre-packaged for installation on a number of systems,
-    including Linux and Windows systems.
-    You do not need to read this entire section,
-    you should need to read only the section
-    appropriate to the type of system you're running on.
-
+    The canonical way to install &SCons; is from the Python Package
+    Index (PyPi):
     </para>
 
-    <section>
-    <title>Installing &SCons; on Red Hat (and Other RPM-based) Linux Systems</title>
-
-      <para>
-
-      &SCons; comes in RPM (Red Hat Package Manager) format,
-      pre-built and ready to install on Red Hat Linux,
-      Fedora,
-      or any other Linux distribution that uses RPM.
-      Your distribution may
-      already have an &SCons; RPM built specifically for it;
-      many do, including SUSE, Mandrake and Fedora.
-      You can check for the availability of an &SCons; RPM
-      on your distribution's download servers,
-      or by consulting an RPM search site like
-      <ulink url="http://www.rpmfind.net/">http://www.rpmfind.net/</ulink> or
-      <ulink url="http://rpm.pbone.net/">http://rpm.pbone.net/</ulink>.
-
-      </para>
-
-      <para>
-
-      If your distribution supports installation via
-      <application>yum</application>,
-      you should be able to install &SCons; by running:
-
-      </para>
-
-      <screen>
-# <userinput>yum install scons</userinput>
-      </screen>
-
-      <para>
-
-      If your Linux distribution does not already have
-      a specific &SCons; RPM file,
-      you can download and install from the
-      generic RPM provided by the &SCons; project.
-      This will install the
-      SCons script(s) in <filename>/usr/bin</filename>,
-      and the SCons library modules in
-      <filename>/usr/lib/scons</filename>.
-
-      </para>
-
-      <para>
-
-      To install from the command line, simply download the
-      appropriate <filename>.rpm</filename> file,
-      and then run:
-
-      </para>
-
-      <screen>
-# <userinput>rpm -Uvh scons-&buildversion;-1.noarch.rpm</userinput>
-      </screen>
-
-      <para>
-
-      Or, you can use a graphical RPM package manager.
-      See your package manager application's documentation
-      for specific instructions about
-      how to use it to install a downloaded RPM.
-
-      </para>
-
-    </section>
-
-    <section>
-    <title>Installing &SCons; on Debian Linux Systems</title>
-
-      <para>
-
-      Debian Linux systems use a different package management
-      format that also makes it very easy to install &SCons;.
-
-      </para>
-
-      <para>
-
-      If your system is connected to the Internet,
-      you can install the latest official Debian package
-      by running:
-
-      </para>
-
-      <screen>
-# <userinput>apt-get install scons</userinput>
-      </screen>
-
-      <!--
-
-      <para>
-
-      Alternatively,
-      you can download the Debian package built
-      by the &SCons; project
-      and install it manually by running:
-
-      </para>
-
-      <screen>
-# <userinput>db-XXX scons-*.deb</userinput>
-      </screen>
-
-      -->
-
-    </section>
-
-    <section>
-    <title>Installing &SCons; on Windows Systems</title>
-
-      <para>
-
-      &SCons; provides a Windows installer
-      that makes installation extremely easy.
-      Download the <filename>scons-&buildversion;.win32.exe</filename>
-      file from the &SCons; download page at
-      <ulink url="http://scons.org/pages/download.html">http://scons.org/pages/download.html</ulink>.
-      Then all you need to do is execute the file
-      (usually by clicking on its icon in Windows Explorer).
-      These will take you through a small
-      sequence of windows that will install
-      &SCons; on your system.
-
-      <!--
-      Things are a little more complicated
-      if you are using the Cygwin version of Python.
-      This is because Cygwin
-      tries to make a Windows system look more
-      POSIX-like (or UNIX-like or Linux-like, if you prefer)
-      by having the Cygwin utilities,
-      including Cygwin Python,
-      interpret file name arguments on the command line
-      using the forward-slash (<filename>/</filename>)
-      as the directory separator,
-      instead of the normal Windows behavior of the
-      backslash (<filename>\</filename>) as the directory separator.
-      -->
-
-      </para>
-
-      <!--
-
-      <section>
-      <title>Installing &SCons; on Windows Systems Without Cygwin Python</title>
-
-        <para>
-
-        XXX
-
-        </para>
-
-      </section>
-
-      <section>
-      <title>Installing &SCons; on Windows Systems With Cygwin Python</title>
-
-        <para>
-
-        XXX
-
-        </para>
-
-      </section>
-
-      -->
-
-      <!--
-
-      XXX - don't have the kinks worked out on how to
-      get these to display properly in all formats,
-      so comment them out for now.
-
-      <screenshot>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center">
-        </imageobject>
-      </mediaobject>
-      </screenshot>
-
-      <screenshot>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center">
-        </imageobject>
-      </mediaobject>
-      </screenshot>
-
-      <screenshot>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center">
-        </imageobject>
-      </mediaobject>
-      </screenshot>
+    <screen>
+% <userinput>python -m pip install scons</userinput>
+    </screen>
 
-      <screenshot>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center">
-        </imageobject>
-      </mediaobject>
-      </screenshot>
+    <para>
+    If you prefer not to install to the Python system location,
+    or do not have privileges to do so, you can add a flag to
+    install to a location specific to your own account:
+    </para>
 
-      -->
+    <screen>
+% <userinput>python -m pip install --user scons</userinput>
+    </screen>
 
-    </section>
+    <para>
+    &SCons; comes pre-packaged for installation on many Linux systems
+    Check your package installation system
+    to see if there is an &SCons; package available.
+    Many people prefer to install distribution-native packages if available,
+    as they provide a central point for management and updating.
+    Some distributions have two &SCons; packages available, one which
+    uses Python 2 and one which uses Python 3. If you need a specific
+    version of &SCons; that is different from the package available,
+    <filename>pip</filename> has a version option or you can follow
+    the instructions in the next section.
+    </para>
 
   </section>
 
@@ -387,25 +200,21 @@ Python 2.5.1
   <title>Building and Installing &SCons; on Any System</title>
 
     <para>
-
     If a pre-built &SCons; package is not available for your system,
+    and installing using <filename>pip</filename> is not suitable,
     then you can still easily build and install &SCons; using the native
     Python <filename>distutils</filename> package.
-
     </para>
 
     <para>
-
     The first step is to download either the
     <filename>scons-&buildversion;.tar.gz</filename>
     or <filename>scons-&buildversion;.zip</filename>,
     which are available from the SCons download page at
     <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
-
     </para>
 
     <para>
-
     Unpack the archive you downloaded,
     using a utility like <application>tar</application>
     on Linux or UNIX,
@@ -415,7 +224,6 @@ Python 2.5.1
     usually in your local directory.
     Then change your working directory to that directory
     and install &SCons; by executing the following commands:
-
     </para>
 
     <screen>
@@ -429,11 +237,11 @@ Python 2.5.1
     install the &scons; script
     in the python which is used to run the setup.py's scripts directory
     (<filename>/usr/local/bin</filename> or
-    <filename>C:\Python25\Scripts</filename>),
+    <filename>C:\Python27\Scripts</filename>),
     and will install the &SCons; build engine
     in the corresponding library directory for the python used
     (<filename>/usr/local/lib/scons</filename> or
-    <filename>C:\Python25\scons</filename>).
+    <filename>C:\Python27\scons</filename>).
     Because these are system directories,
     you may need root (on Linux or UNIX) or Administrator (on Windows)
     privileges to install &SCons; like this.
@@ -489,7 +297,7 @@ Python 2.5.1
       in the
       <filename>/usr/lib/scons-&buildversion;</filename>
       or
-      <filename>C:\Python25\scons-&buildversion;</filename>
+      <filename>C:\Python27\scons-&buildversion;</filename>
       directory, for example.
 
       </para>
diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml
index d64b63d..f059bca 100644
--- a/doc/user/builders-built-in.xml
+++ b/doc/user/builders-built-in.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml
index 8fa26f6..ccffaf0 100644
--- a/doc/user/builders-commands.xml
+++ b/doc/user/builders-commands.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index d26c4c6..c36d468 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -812,7 +812,7 @@ env.Foo('file')
     <scons_example name="builderswriting_MY_EMITTER">
 
       <file name="SConstruct" printme="1">
-bld = Builder(action = 'my_command $SOURCES &gt; $TARGET',
+bld = Builder(action = './my_command $SOURCES &gt; $TARGET',
               suffix = '.foo',
               src_suffix = '.input',
               emitter = '$MY_EMITTER')
@@ -826,9 +826,6 @@ env2 = Environment(BUILDERS = {'Foo' : bld},
                    MY_EMITTER = modify2)
 env1.Foo('file1')
 env2.Foo('file2')
-import os
-env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
-env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
         </file>
         <file name="file1.input">
 file1.input
@@ -848,23 +845,6 @@ cat
 
     </scons_example>
 
-    <sconstruct>
-bld = Builder(action = 'my_command $SOURCES &gt; $TARGET',
-              suffix = '.foo',
-              src_suffix = '.input',
-              emitter = '$MY_EMITTER')
-def modify1(target, source, env):
-    return target, source + ['modify1.in']
-def modify2(target, source, env):
-    return target, source + ['modify2.in']
-env1 = Environment(BUILDERS = {'Foo' : bld},
-                   MY_EMITTER = modify1)
-env2 = Environment(BUILDERS = {'Foo' : bld},
-                   MY_EMITTER = modify2)
-env1.Foo('file1')
-env2.Foo('file2')
-    </sconstruct>
-
     <para>
 
     In this example, the <filename>modify1.in</filename>
diff --git a/doc/user/builders.xml b/doc/user/builders.xml
index c1af202..873d677 100644
--- a/doc/user/builders.xml
+++ b/doc/user/builders.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index db2a469..bf070f9 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/chtml.xsl b/doc/user/chtml.xsl
index dafc044..a7b968c 100644
--- a/doc/user/chtml.xsl
+++ b/doc/user/chtml.xsl
@@ -1,7 +1,7 @@
 <?xml version='1.0'?>
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml
index 21c17c1..bb1d32b 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -317,7 +317,7 @@ if not GetOption('help'):
 import os
 num_cpu = int(os.environ.get('NUM_CPU', 2))
 SetOption('num_jobs', num_cpu)
-print("running with -j", GetOption('num_jobs'))
+print("running with -j %s"%GetOption('num_jobs'))
         </file>
         <file name="foo.in">
 foo.in
@@ -1863,7 +1863,7 @@ env = Environment(variables = vars,
                   CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
 unknown = vars.UnknownVariables()
 if unknown:
-    print("Unknown variables:", unknown.keys())
+    print("Unknown variables: %s"%unknown.keys())
     Exit(1)
 env.Program('foo.c')
         </file>
@@ -1987,17 +1987,16 @@ foo.c
 
       <para>
 
-      One of the most basic things you can control
-      is which targets &SCons; will build by default--that is,
+      You can control
+      which targets &SCons; will build by default - that is,
       when there are no targets specified on the command line.
       As mentioned previously,
       &SCons; will normally build every target
-      in or below the current directory
-      by default--that is, when you don't
+      in or below the current directory unless you
       explicitly specify one or more targets
       on the command line.
       Sometimes, however, you may want
-      to specify explicitly that only
+      to specify that only
       certain programs, or programs in certain directories,
       should be built by default.
       You do this with the &Default; function:
@@ -2193,16 +2192,16 @@ prog2.c
         <para>
 
         &SCons; supports a &DEFAULT_TARGETS; variable
-        that lets you get at the current list of default targets.
+        that lets you get at the current list of default targets
+        specified by calls to the &Default; function or method.
         The &DEFAULT_TARGETS; variable has
         two important differences from the &COMMAND_LINE_TARGETS; variable.
         First, the &DEFAULT_TARGETS; variable is a list of
         internal &SCons; nodes,
         so you need to convert the list elements to strings
         if you want to print them or look for a specific target name.
-        Fortunately, you can do this easily
-        by using the Python <function>map</function> function
-        to run the list through <function>str</function>:
+        You can do this easily by calling the <function>str</function>
+        on the elements in a list comprehension:
 
         </para>
 
@@ -2210,7 +2209,7 @@ prog2.c
            <file name="SConstruct" printme="1">
 prog1 = Program('prog1.c')
 Default(prog1)
-print("DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS))
+print("DEFAULT_TARGETS is %s" % [str(t) for t in DEFAULT_TARGETS])
            </file>
            <file name="prog1.c">
 prog1.c
@@ -2234,7 +2233,7 @@ prog1.c
         <para>
 
         Second,
-        the contents of the &DEFAULT_TARGETS; list change
+        the contents of the &DEFAULT_TARGETS; list changes
         in response to calls to the &Default; function,
         as you can see from the following &SConstruct; file:
 
@@ -2244,10 +2243,10 @@ prog1.c
            <file name="SConstruct" printme="1">
 prog1 = Program('prog1.c')
 Default(prog1)
-print("DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS))
+print("DEFAULT_TARGETS is now %s" % [str(t) for t in DEFAULT_TARGETS])
 prog2 = Program('prog2.c')
 Default(prog2)
-print("DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS))
+print("DEFAULT_TARGETS is now %s" % [str(t) for t in DEFAULT_TARGETS])
            </file>
            <file name="prog1.c">
 prog1.c
@@ -2338,7 +2337,7 @@ else:
 prog1 = Program('prog1.c')
 Program('prog2.c')
 Default(prog1)
-print("BUILD_TARGETS is", map(str, BUILD_TARGETS))
+print ("BUILD_TARGETS is %s" % [str(t) for t in BUILD_TARGETS])
         </file>
         <file name="prog1.c">
 prog1.c
@@ -2352,7 +2351,9 @@ prog2.c
 
       Notice how the value of &BUILD_TARGETS;
       changes depending on whether a target is
-      specified on the command line:
+      specified on the command line - &BUILD_TARGETS;
+      takes from  &DEFAULT_TARGETS;
+      only if there are no &COMMAND_LINE_TARGETS;:
 
       </para>
 
diff --git a/doc/user/copyright.xml b/doc/user/copyright.xml
index 6971581..cc9acac 100644
--- a/doc/user/copyright.xml
+++ b/doc/user/copyright.xml
@@ -1,44 +1,43 @@
 <?xml version='1.0'?>
 <!DOCTYPE sconsdoc [
-    <!ENTITY % scons SYSTEM "../scons.mod">
-    %scons;
-]>
+        <!ENTITY % scons SYSTEM "../scons.mod">
+        %scons;
+        ]>
 
 <legalnotice 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 http://www.scons.org/dbxsd/v1.0/scons.xsd">
 
-<!--
+    <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+      Copyright (c) 2001 - 2019 The SCons Foundation
 
-  Permission is hereby granted, free of charge, to any person obtaining
-  a copy of this software and associated documentation files (the
-  "Software"), to deal in the Software without restriction, including
-  without limitation the rights to use, copy, modify, merge, publish,
-  distribute, sublicense, and/or sell copies of the Software, and to
-  permit persons to whom the Software is furnished to do so, subject to
-  the following conditions:
+      Permission is hereby granted, free of charge, to any person obtaining
+      a copy of this software and associated documentation files (the
+      "Software"), to deal in the Software without restriction, including
+      without limitation the rights to use, copy, modify, merge, publish,
+      distribute, sublicense, and/or sell copies of the Software, and to
+      permit persons to whom the Software is furnished to do so, subject to
+      the following conditions:
 
-  The above copyright notice and this permission notice shall be included
-  in all copies or substantial portions of the Software.
+      The above copyright notice and this permission notice shall be included
+      in all copies or substantial portions of the Software.
 
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
-  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+      KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+      WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+      NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+      LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+      OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+      WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
--->
+    -->
 
-<blockquote>
- <para>
+    <blockquote>
+        <para>
+            SCons User's Guide Copyright (c) 2004-2019 Steven Knight
+        </para>
+    </blockquote>
 
-  SCons User's Guide Copyright (c) 2004, 2005, 2006, 2007 Steven Knight
-
- </para>
-</blockquote>
 
 </legalnotice>
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 29a79a5..35372e7 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -518,7 +518,7 @@ cc -o hello hello.o
         <file name="SConstruct" printme="1">
 Program('hello.c')
 def decide_if_changed(dependency, target, prev_ni):
-    if self.get_timestamp() != prev_ni.timestamp:
+    if dependency.get_timestamp() != prev_ni.timestamp:
         dep = str(dependency)
         tgt = str(target)
         if specific_part_of_file_has_changed(dep, tgt):
@@ -571,7 +571,7 @@ int main() { printf("Hello, world!\n"); }
         The <emphasis>content signature</emphasis>,
         or MD5 checksum, of the contents of the
         <varname>dependency</varname>
-        file the list time the &target; was built.
+        file the last time the &target; was built.
         </para>
         </listitem>
 
@@ -583,7 +583,7 @@ int main() { printf("Hello, world!\n"); }
         <listitem>
         <para>
         The size in bytes of the <varname>dependency</varname>
-        file the list time the target was built.
+        file the last time the target was built.
         </para>
         </listitem>
 
@@ -595,7 +595,7 @@ int main() { printf("Hello, world!\n"); }
         <listitem>
         <para>
         The modification time of the <varname>dependency</varname>
-        file the list time the &target; was built.
+        file the last time the &target; was built.
         </para>
         </listitem>
 
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index ea5d472..ede9bc3 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-     Copyright (c) 2001 - 2017 The SCons Foundation
+     Copyright (c) 2001 - 2019 The SCons Foundation
 
      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
@@ -385,9 +385,9 @@ environment, of directory names, suffixes, etc.
     <para>
 
     A &consenv;
-    is a distinct object creating within
+    is a distinct object created within
     a &SConscript; file and
-    and which contains values that
+    which contains values that
     affect how &SCons; decides
     what action to use to build a target,
     and even to define which targets
@@ -627,7 +627,7 @@ int main() { }
       <scons_example name="environments_ex6">
         <file name="SConstruct" printme="1">
 env = Environment()
-print("CC is:", env['CC'])
+print("CC is: %s"%env['CC'])
         </file>
       </scons_example>
 
@@ -721,7 +721,7 @@ for item in sorted(env.Dictionary().items()):
 
       <sconstruct>
 env = Environment()
-print("CC is:", env.subst('$CC'))
+print("CC is: %s"%env.subst('$CC'))
       </sconstruct>
 
       <para>
@@ -738,7 +738,7 @@ print("CC is:", env.subst('$CC'))
 
       <sconstruct>
 env = Environment(CCFLAGS = '-DFOO')
-print("CCCOM is:", env['CCCOM'])
+print("CCCOM is: %s"%env['CCCOM'])
       </sconstruct>
 
       <para>
@@ -764,7 +764,7 @@ scons: `.' is up to date.
 
       <sconstruct>
 env = Environment(CCFLAGS = '-DFOO')
-print("CCCOM is:", env.subst('$CCCOM'))
+print("CCCOM is: %s"%env.subst('$CCCOM'))
       </sconstruct>
 
       <para>
@@ -806,7 +806,7 @@ scons: `.' is up to date.
        <scons_example name="environments_missing1">
          <file name="SConstruct" printme="1">
 env = Environment()
-print("value is:", env.subst( '->$MISSING&lt;-' ))
+print("value is: %s"%env.subst( '->$MISSING&lt;-' ))
         </file>
       </scons_example>
 
@@ -834,7 +834,7 @@ print("value is:", env.subst( '->$MISSING&lt;-' ))
          <file name="SConstruct" printme="1">
 AllowSubstExceptions()
 env = Environment()
-print("value is:", env.subst( '->$MISSING&lt;-' ))
+print("value is: %s"%env.subst( '->$MISSING&lt;-' ))
         </file>
       </scons_example>
 
@@ -854,7 +854,7 @@ print("value is:", env.subst( '->$MISSING&lt;-' ))
          <file name="SConstruct" printme="1">
 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
 env = Environment()
-print("value is:", env.subst( '->${1 / 0}&lt;-' ))
+print("value is: %s"%env.subst( '->${1 / 0}&lt;-' ))
         </file>
       </scons_example>
 
@@ -1216,7 +1216,7 @@ int main() { }
         <file name="SConstruct" printme="1">
 env = Environment()
 env.Replace(NEW_VARIABLE = 'xyzzy')
-print("NEW_VARIABLE =", env['NEW_VARIABLE'])
+print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
         </file>
       </scons_example>
 
@@ -1251,11 +1251,11 @@ print("NEW_VARIABLE =", env['NEW_VARIABLE'])
       <scons_example name="environments_Replace2">
         <file name="SConstruct" printme="1">
 env = Environment(CCFLAGS = '-DDEFINE1')
-print("CCFLAGS =", env['CCFLAGS'])
+print("CCFLAGS = %s"%env['CCFLAGS'])
 env.Program('foo.c')
 
 env.Replace(CCFLAGS = '-DDEFINE2')
-print("CCFLAGS =", env['CCFLAGS'])
+print("CCFLAGS = %s"%env['CCFLAGS'])
 env.Program('bar.c')
         </file>
         <file name="foo.c">
@@ -1375,7 +1375,7 @@ int main() { }
         <file name="SConstruct" printme="1">
 env = Environment()
 env.Append(NEW_VARIABLE = 'added')
-print("NEW_VARIABLE =", env['NEW_VARIABLE'])
+print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
         </file>
       </scons_example>
 
@@ -1475,7 +1475,7 @@ int main() { }
         <file name="SConstruct" printme="1">
 env = Environment()
 env.Prepend(NEW_VARIABLE = 'added')
-print("NEW_VARIABLE =", env['NEW_VARIABLE'])
+print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
         </file>
       </scons_example>
 
@@ -1630,7 +1630,7 @@ env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin'
 
     But doing so makes your &SConscript; file less portable,
     (although in this case that may not be a huge concern
-    since the directories you list are likley system-specific, anyway).
+    since the directories you list are likely system-specific, anyway).
 
     </para>
 
diff --git a/doc/user/epub.xsl b/doc/user/epub.xsl
index fc95c60..818a874 100644
--- a/doc/user/epub.xsl
+++ b/doc/user/epub.xsl
@@ -1,7 +1,7 @@
 <?xml version='1.0'?>
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/errors.xml b/doc/user/errors.xml
index 78b4f39..e7e611e 100644
--- a/doc/user/errors.xml
+++ b/doc/user/errors.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/example.xml b/doc/user/example.xml
index b1453ab..4787595 100644
--- a/doc/user/example.xml
+++ b/doc/user/example.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/factories.xml b/doc/user/factories.xml
index 916c269..43e417b 100644
--- a/doc/user/factories.xml
+++ b/doc/user/factories.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/file-removal.xml b/doc/user/file-removal.xml
index bc2d89b..fe38cf7 100644
--- a/doc/user/file-removal.xml
+++ b/doc/user/file-removal.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/functions.xml b/doc/user/functions.xml
index 6093395..bebc7bf 100644
--- a/doc/user/functions.xml
+++ b/doc/user/functions.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/gettext.xml b/doc/user/gettext.xml
index 8daf5f9..36f0419 100644
--- a/doc/user/gettext.xml
+++ b/doc/user/gettext.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index f65a128..dc07e87 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/html.xsl b/doc/user/html.xsl
index 2df2fee..5ff8e53 100644
--- a/doc/user/html.xsl
+++ b/doc/user/html.xsl
@@ -1,7 +1,7 @@
 <?xml version='1.0'?>
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/install.xml b/doc/user/install.xml
index 7024320..b3cb9dd 100644
--- a/doc/user/install.xml
+++ b/doc/user/install.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/java.xml b/doc/user/java.xml
index 73afbc7..19b51e8 100644
--- a/doc/user/java.xml
+++ b/doc/user/java.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml
index c17bdae..6de1075 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -644,4 +644,61 @@ Program('bar', bar_files)
 
   </section>
 
-</chapter>
+  <section>
+  <title>Overriding construction variables when calling a Builder</title>
+
+    <para>
+
+    It is possible to override or add construction variables
+    when calling a builder method by passing additional keyword arguments.
+    These overridden or added variables will only be in effect when
+    building the target, so they will not affect other parts of the build.
+    For example, if you want to add additional libraries for just one program:
+
+    </para>
+
+    <programlisting>
+env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
+    </programlisting>
+
+    <para>
+
+    or generate a shared library with a non-standard suffix:
+
+    </para>
+
+    <programlisting>
+env.SharedLibrary('word', 'word.cpp',
+                  SHLIBSUFFIX='.ocx',
+                  LIBSUFFIXES=['.ocx'])
+    </programlisting>
+
+    <para>
+
+    It is also possible to use the <literal>parse_flags</literal> keyword argument in an
+    override:
+
+    </para>
+
+    <para>
+
+    This example adds 'include' to &cv-link-CPPPATH;,
+    'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;.
+
+    </para>
+
+    <programlisting>
+env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
+    </programlisting>
+
+    <para>
+
+    Within the call to the builder action the environment is not cloned,
+    instead an OverrideEnvironment() is created which is more
+    light weight than a whole Environment()
+
+    </para>
+
+  </section>
+
+</chapter>
\ No newline at end of file
diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml
index b905923..c6b8069 100644
--- a/doc/user/libraries.xml
+++ b/doc/user/libraries.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/main.xml b/doc/user/main.xml
index ad2ffe8..01470cc 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -74,10 +74,10 @@
 
     <corpauthor>Steven Knight and the SCons Development Team</corpauthor>
 
-    <pubdate>2004 - 2017</pubdate>
+    <pubdate>2004 - 2019</pubdate>
 
     <copyright>
-      <year>2004 - 2017</year>
+      <year>2004 - 2019</year>
       <holder>The SCons Foundation</holder>
     </copyright>
 
diff --git a/doc/user/make.xml b/doc/user/make.xml
index 4f1199d..ac6db2b 100644
--- a/doc/user/make.xml
+++ b/doc/user/make.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml
index 36bb061..d802125 100644
--- a/doc/user/mergeflags.xml
+++ b/doc/user/mergeflags.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/misc.xml b/doc/user/misc.xml
index ed96625..5ade6d3 100644
--- a/doc/user/misc.xml
+++ b/doc/user/misc.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -268,9 +268,9 @@ hello.c
     <scons_example name="misc_FindFile1a">
       <file name="SConstruct" printme="1">
 # one directory
-print(FindFile('missing', '.'))
+print("%s"%FindFile('missing', '.'))
 t = FindFile('exists', '.')
-print(t.__class__, t)
+print("%s %s"%(t.__class__, t))
       </file>
       <file name="exists">
  exists
@@ -287,7 +287,7 @@ print(t.__class__, t)
 includes = [ '.', 'include', 'src/include']
 headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h']
 for hdr in headers:
-    print('%-12s' % ('%s:' % hdr), FindFile(hdr, includes))
+    print('%-12s: %s'%(hdr, FindFile(hdr, includes)))
       </file>
       <file name="config.h">
 exists
@@ -625,4 +625,53 @@ env.Command('directory_build_info',
 
   </section>
 
+  <section>
+  <title>Virtual environments (virtualenvs)</title>
+
+    <para>
+
+      Virtualenv is a tool to create isolated Python environments.
+      A python application (such as SCons) may be executed within
+      an activated virtualenv. The activation of virtualenv modifies
+      current environment by defining some virtualenv-specific variables
+      and modifying search PATH, such that executables installed within
+      virtualenv's home directory are preferred over the ones installed
+      outside of it.
+
+    </para>
+
+    <para>
+
+      Normally, SCons uses hard-coded PATH when searching for external
+      executables, so it always picks-up executables from these pre-defined
+      locations. This applies also to python interpreter, which is invoked
+      by some custom SCons tools or test suites. This means, when running
+      SCons in a virtualenv, an eventual invocation of python interpreter from
+      SCons script will most probably jump out of virtualenv and execute
+      python executable found in hard-coded SCons PATH, not the one which is
+      executing SCons. Some users may consider this as an inconsistency.
+
+    </para>
+
+    <para>
+      This issue may be overcome by using <literal>--enable-virtualenv</literal>
+      option. The option automatically imports virtualenv-related environment
+      variables to all created construction environment <literal>env['ENV']</literal>,
+      and modifies SCons PATH appropriately to prefer virtualenv's executables.
+      Setting environment variable <literal>SCONS_ENABLE_VIRTUALENV=1</literal>
+      will have same effect. If virtualenv support is enabled system-vide
+      by the environment variable, it may be suppressed with
+      <literal>--ignore-virtualenv</literal> option.
+    </para>
+
+    <para>
+      Inside of SConscript, a global function <literal>Virtualenv</literal> is
+      available. It returns a path to virtualenv's home directory, or
+      <literal>None</literal> if SCons is not running from virtualenv. Note,
+      that this function returns a path even if SCons is run from an
+      unactivated virtualenv.
+    </para>
+
+  </section>
+
 </chapter>
diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml
index e627bba..da1d158 100644
--- a/doc/user/nodes.xml
+++ b/doc/user/nodes.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -265,8 +265,8 @@ xyzzy = Entry('xyzzy')
       <file name="SConstruct" printme="1">
 object_list = Object('hello.c')
 program_list = Program(object_list)
-print("The object file is:", object_list[0])
-print("The program file is:", program_list[0])
+print("The object file is: %s"%object_list[0])
+print("The program file is: %s"%program_list[0])
       </file>
       <file name="hello.c">
 int main() { printf("Hello, world!\n"); }
@@ -334,7 +334,7 @@ import os.path
 program_list = Program('hello.c')
 program_name = str(program_list[0])
 if not os.path.exists(program_name):
-    print(program_name, "does not exist!")
+    print("%s does not exist!"%program_name)
       </file>
       <file name="hello.c">
 int main() { printf("Hello, world!\n"); }
diff --git a/doc/user/output.xml b/doc/user/output.xml
index cf5776d..db16393 100644
--- a/doc/user/output.xml
+++ b/doc/user/output.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml
index 2367857..096d236 100644
--- a/doc/user/parseconfig.xml
+++ b/doc/user/parseconfig.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml
index 52cbdd7..26313ce 100644
--- a/doc/user/parseflags.xml
+++ b/doc/user/parseflags.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -57,7 +57,7 @@
 
  &SCons; construction environments have a &ParseFlags; method
  that takes a set of typical command-line options
- and distrbutes them into the appropriate construction variables.
+ and distributes them into the appropriate construction variables.
  Historically, it was created to support the &ParseConfig; method,
  so it focuses on options used by the GNU Compiler Collection (GCC)
  for the C and C++ toolchains.
diff --git a/doc/user/pdf.xsl b/doc/user/pdf.xsl
index 4a81d56..0f797d3 100644
--- a/doc/user/pdf.xsl
+++ b/doc/user/pdf.xsl
@@ -1,7 +1,7 @@
 <?xml version='1.0'?>
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/preface.xml b/doc/user/preface.xml
index 443bf38..62cd47b 100644
--- a/doc/user/preface.xml
+++ b/doc/user/preface.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/python.xml b/doc/user/python.xml
index 82443f9..177cb5c 100644
--- a/doc/user/python.xml
+++ b/doc/user/python.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml
index 6aae2e3..189a8cd 100644
--- a/doc/user/repositories.xml
+++ b/doc/user/repositories.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/run.xml b/doc/user/run.xml
index af28868..c9c5c6a 100644
--- a/doc/user/run.xml
+++ b/doc/user/run.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml
index 9e3ce99..e1b2249 100644
--- a/doc/user/scanners.xml
+++ b/doc/user/scanners.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -410,6 +410,59 @@ kscan = Scanner(function = kfile_scan,
     This is important since many files get scanned in a typical build.
     
     </para>
-    </section>
+  </section>
+
+  <section>
+  <title>Using scanners with Builders</title>
+
+    <para>
+
+	One approach for the use of scanners is with builders.
+    There are two optional parameters we can use with a builder
+    <literal>source_scanner</literal> and <literal>target_scanner</literal>.
+
+    </para>
+
+    <scons_example name="scanners_builders">
+      <file name="SConstruct" printme="1">
+
+def kfile_scan(node, env, path, arg):
+    contents = node.get_text_contents()
+    return env.File(include_re.findall(contents))
+
+kscan = Scanner(function = kfile_scan,
+            skeys = ['.k'],
+            path_function = FindPathDirs('KPATH'))
+
+def build_function(target, source, env):
+    # Code to build "target" from "source"
+    return None
+
+bld = Builder(action = build_function,
+            suffix = '.foo',
+            source_scanner = kscan
+            src_suffix = '.input')
+env = Environment(BUILDERS = {'Foo' : bld})
+env.Foo('file')
+
+      </file>
+    </scons_example>
+
+    <para>
+
+    An emitter function can modify the list of sources or targets
+    passed to the action function when the builder is triggered.
+
+    </para>
+
+	<para>
+
+    A scanner function will not affect the list of sources or targets
+    seen by the builder during the build action. The scanner function
+    will however affect if the builder should be rebuilt (if any of
+    the files sourced by the scanner have changed for example).
+
+    </para>
+  </section>
 
 </chapter>
diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml
index d0537cb..b8a903d 100644
--- a/doc/user/sconf.xml
+++ b/doc/user/sconf.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/scons_title.xsl b/doc/user/scons_title.xsl
index 130c6a5..21c56da 100644
--- a/doc/user/scons_title.xsl
+++ b/doc/user/scons_title.xsl
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/separate.xml b/doc/user/separate.xml
index bac7e4d..26500d6 100644
--- a/doc/user/separate.xml
+++ b/doc/user/separate.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/sideeffect.xml b/doc/user/sideeffect.xml
index 16dbd08..e630e4f 100644
--- a/doc/user/sideeffect.xml
+++ b/doc/user/sideeffect.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/simple.xml b/doc/user/simple.xml
index af7868b..43121c0 100644
--- a/doc/user/simple.xml
+++ b/doc/user/simple.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/sourcecode.xml b/doc/user/sourcecode.xml
index b3c51e4..f7cd492 100644
--- a/doc/user/sourcecode.xml
+++ b/doc/user/sourcecode.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml
index 248dcd3..32e575a 100644
--- a/doc/user/tasks.xml
+++ b/doc/user/tasks.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/tools.xml b/doc/user/tools.xml
index 0c56603..bc9f6b9 100644
--- a/doc/user/tools.xml
+++ b/doc/user/tools.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml
index aecac57..606c727 100644
--- a/doc/user/troubleshoot.xml
+++ b/doc/user/troubleshoot.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/variables.xml b/doc/user/variables.xml
index e0d1d32..b7b8d4e 100644
--- a/doc/user/variables.xml
+++ b/doc/user/variables.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/variants.xml b/doc/user/variants.xml
index 1944201..8b78c2b 100644
--- a/doc/user/variants.xml
+++ b/doc/user/variants.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
-- 
cgit v1.2.3


From efdf3fdbcd2f7654cb8d1209a8b040914437bacd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= <debian@jff-webhosting.net>
Date: Tue, 23 Jul 2019 16:54:06 +0200
Subject: New upstream version 3.1.0

---
 doc/user/depends.xml     | 11 +++++++++--
 doc/user/less-simple.xml | 18 ++++++++++--------
 2 files changed, 19 insertions(+), 10 deletions(-)

(limited to 'doc/user')

diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 35372e7..bb0a142 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -517,7 +517,7 @@ cc -o hello hello.o
       <scons_example name="depends_function">
         <file name="SConstruct" printme="1">
 Program('hello.c')
-def decide_if_changed(dependency, target, prev_ni):
+def decide_if_changed(dependency, target, prev_ni, repo_node=None):
     if dependency.get_timestamp() != prev_ni.timestamp:
         dep = str(dependency)
         tgt = str(target)
@@ -561,6 +561,13 @@ int main() { printf("Hello, world!\n"); }
 
       </para>
 
+        <para>
+            The fourth argument <varname>repo_node</varname>,
+            is the &Node; to use if it is not None when comparing &BuildInfo;.
+            This is typically only set when the target node only exists in a
+            &Repository;
+        </para>
+
       <variablelist>
 
         <varlistentry>
@@ -637,7 +644,7 @@ int main() { printf("Hello, world!\n"); }
       <sconstruct>
 env = Environment()
 
-def config_file_decider(dependency, target, prev_ni):
+def config_file_decider(dependency, target, prev_ni, repo_node=None):
     import os.path
 
     # We always have to init the .csig value...
diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml
index 6de1075..e8ff44a 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.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">
@@ -257,7 +257,7 @@ Program('program', Glob('*.c'))
     (see <xref linkend="chap-variants"></xref>, below)
     and repositories
     (see <xref linkend="chap-repositories"></xref>, below),
-    excluding some files 
+    excluding some files
     and returning strings rather than Nodes.
 
     </para>
@@ -311,7 +311,7 @@ Program('hello', ['hello.c'])
     </para>
 
     <important>
-    
+
     <para>
 
     Although &SCons; functions
@@ -359,7 +359,7 @@ Program('program2', common_sources + ['program2.c'])
     <para>
 
     One drawback to the use of a Python list
-    for source files is that 
+    for source files is that
     each file name must be enclosed in quotes
     (either single quotes or double quotes).
     This can get cumbersome and difficult to read
@@ -675,8 +675,10 @@ env.SharedLibrary('word', 'word.cpp',
 
     <para>
 
-    It is also possible to use the <literal>parse_flags</literal> keyword argument in an
-    override:
+    It is also possible to use the <literal>parse_flags</literal>
+    keyword argument in an override to merge command-line
+    style arguments into the appropriate construction
+    variables (see &f-link-env-MergeFlags;).
 
     </para>
 
@@ -688,7 +690,7 @@ env.SharedLibrary('word', 'word.cpp',
     </para>
 
     <programlisting>
-env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
+env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
     </programlisting>
 
     <para>
@@ -701,4 +703,4 @@ env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
 
   </section>
 
-</chapter>
\ No newline at end of file
+</chapter>
-- 
cgit v1.2.3