From ba4425ab5227fd9597fccd368bffff6bf1032149 Mon Sep 17 00:00:00 2001
From: Luca Falavigna <dktrkranz@debian.org>
Date: Sat, 10 Sep 2011 11:25:53 +0200
Subject: Imported Upstream version 2.1.0

---
 doc/user/MANIFEST              |  1 +
 doc/user/README                |  2 +-
 doc/user/actions.in            |  2 +-
 doc/user/actions.xml           |  2 +-
 doc/user/add-method.in         |  2 +-
 doc/user/add-method.xml        |  3 +-
 doc/user/alias.in              |  2 +-
 doc/user/alias.xml             |  2 +-
 doc/user/ant.in                |  2 +-
 doc/user/ant.xml               |  2 +-
 doc/user/build-install.in      | 25 +++++++++--------
 doc/user/build-install.xml     | 25 +++++++++--------
 doc/user/builders-built-in.in  |  2 +-
 doc/user/builders-built-in.xml |  3 +-
 doc/user/builders-commands.in  |  4 +--
 doc/user/builders-commands.xml |  2 +-
 doc/user/builders-writing.in   | 63 +++++++++++++++++++++++++++---------------
 doc/user/builders-writing.xml  | 59 +++++++++++++++++++++++++--------------
 doc/user/builders.in           |  2 +-
 doc/user/builders.xml          |  2 +-
 doc/user/caching.in            |  2 +-
 doc/user/caching.xml           |  2 +-
 doc/user/command-line.in       |  6 ++--
 doc/user/command-line.xml      | 17 +++++++-----
 doc/user/copyright.in          |  2 +-
 doc/user/copyright.xml         |  2 +-
 doc/user/depends.in            | 61 +++++++++++++++++++++++++++++++++++++---
 doc/user/depends.xml           | 60 ++++++++++++++++++++++++++++++++++++++--
 doc/user/environments.in       | 22 ++++++++-------
 doc/user/environments.xml      | 10 ++++---
 doc/user/errors.in             |  2 +-
 doc/user/errors.xml            |  2 +-
 doc/user/example.in            |  2 +-
 doc/user/example.xml           |  2 +-
 doc/user/factories.in          |  4 +--
 doc/user/factories.xml         |  2 +-
 doc/user/file-removal.in       |  2 +-
 doc/user/file-removal.xml      |  2 +-
 doc/user/functions.in          | 38 +++++++++++++++++++++++++
 doc/user/functions.xml         | 38 +++++++++++++++++++++++++
 doc/user/hierarchy.in          |  6 ++--
 doc/user/hierarchy.xml         |  4 +--
 doc/user/install.in            |  2 +-
 doc/user/install.xml           |  2 +-
 doc/user/java.in               |  6 ++--
 doc/user/java.xml              |  2 +-
 doc/user/less-simple.in        |  2 +-
 doc/user/less-simple.xml       |  4 ++-
 doc/user/libraries.in          |  2 +-
 doc/user/libraries.xml         |  5 +++-
 doc/user/main.in               | 53 ++++++++++++++++++++++++++---------
 doc/user/main.xml              | 53 ++++++++++++++++++++++++++---------
 doc/user/make.in               |  2 +-
 doc/user/make.xml              |  2 +-
 doc/user/mergeflags.in         |  2 +-
 doc/user/mergeflags.xml        |  2 +-
 doc/user/misc.in               | 12 ++++----
 doc/user/misc.xml              |  6 ++--
 doc/user/nodes.in              |  2 +-
 doc/user/nodes.xml             |  4 ++-
 doc/user/output.in             |  4 +--
 doc/user/output.xml            |  2 +-
 doc/user/parseconfig.in        |  2 +-
 doc/user/parseconfig.xml       |  2 +-
 doc/user/parseflags.in         |  2 +-
 doc/user/parseflags.xml        |  3 +-
 doc/user/preface.in            |  6 ++--
 doc/user/preface.xml           |  2 +-
 doc/user/python.in             |  2 +-
 doc/user/python.xml            |  2 +-
 doc/user/repositories.in       |  6 ++--
 doc/user/repositories.xml      |  6 ++--
 doc/user/run.in                |  2 +-
 doc/user/run.xml               |  2 +-
 doc/user/scanners.in           | 17 ++++++++++--
 doc/user/scanners.xml          | 17 ++++++++++--
 doc/user/sconf.in              |  6 ++--
 doc/user/sconf.xml             |  4 +--
 doc/user/separate.in           |  2 +-
 doc/user/separate.xml          |  2 +-
 doc/user/sideeffect.in         |  2 +-
 doc/user/sideeffect.xml        |  2 +-
 doc/user/simple.in             | 10 +++----
 doc/user/simple.xml            | 10 +++++--
 doc/user/sourcecode.in         |  2 +-
 doc/user/sourcecode.xml        |  2 +-
 doc/user/tasks.in              |  6 ++--
 doc/user/tasks.xml             |  2 +-
 doc/user/tools.in              |  2 +-
 doc/user/tools.xml             |  2 +-
 doc/user/troubleshoot.in       | 49 ++++++++++++++++++++++++++++----
 doc/user/troubleshoot.xml      | 57 ++++++++++++++++++++++++++++++++------
 doc/user/variables.in          |  2 +-
 doc/user/variables.xml         |  2 +-
 doc/user/variants.in           |  2 +-
 doc/user/variants.xml          |  3 +-
 96 files changed, 651 insertions(+), 253 deletions(-)
 create mode 100644 doc/user/functions.in
 create mode 100644 doc/user/functions.xml

(limited to 'doc/user')

diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index ef273d3..0994f2b 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -17,6 +17,7 @@ errors.xml
 example.xml
 factories.xml
 file-removal.xml
+functions.xml
 hierarchy.xml
 install.xml
 java.xml
diff --git a/doc/user/README b/doc/user/README
index 773fbc2..7ebdb93 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -1,4 +1,4 @@
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
 When adding a new file, add it to main.xml and MANIFEST.
 
diff --git a/doc/user/actions.in b/doc/user/actions.in
index 06dcd63..6634a0d 100644
--- a/doc/user/actions.in
+++ b/doc/user/actions.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 7231a70..a3cce98 100644
--- a/doc/user/actions.xml
+++ b/doc/user/actions.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/add-method.in
index a9595a9..815e0a7 100644
--- a/doc/user/add-method.in
+++ b/doc/user/add-method.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 46f858d..6cb1a93 100644
--- a/doc/user/add-method.xml
+++ b/doc/user/add-method.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -113,6 +113,7 @@
     rc /fores.res res.rc
     cl /Fotest_stuff.obj /c test_stuff.c /nologo
     link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res
+    embedManifestExeCheck(target, source, env)
   </screen>
 
   <para>
diff --git a/doc/user/alias.in b/doc/user/alias.in
index c17d76a..1fb7e30 100644
--- a/doc/user/alias.in
+++ b/doc/user/alias.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 fed201f..8888f77 100644
--- a/doc/user/alias.xml
+++ b/doc/user/alias.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/ant.in
index d39207d..2cc83a3 100644
--- a/doc/user/ant.in
+++ b/doc/user/ant.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 d39207d..2cc83a3 100644
--- a/doc/user/ant.xml
+++ b/doc/user/ant.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/build-install.in
index 8d1c005..aad4a44 100644
--- a/doc/user/build-install.in
+++ b/doc/user/build-install.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -121,9 +121,10 @@
 
     <para>
 
-    &SCons; will work with any version of Python from 2.4 or later.
+    &SCons; will work with any 2.x version of Python from 2.4 on;
+    3.0 and later are not yet supported.
     If you need to install Python and have a choice,
-    we recommend using the most recent Python version available.
+    we recommend using the most recent 2.x Python version available.
     Newer Pythons have significant improvements
     that help speed up the performance of &SCons;.
 
@@ -198,7 +199,7 @@
       </para>
 
       <screen>
-        # <userinput>rpm -Uvh scons-2.0.1-1.noarch.rpm</userinput>
+        # <userinput>rpm -Uvh scons-2.1.0-1.noarch.rpm</userinput>
       </screen>
 
       <para>
@@ -260,7 +261,7 @@
 
       &SCons; provides a Windows installer
       that makes installation extremely easy.
-      Download the <filename>scons-2.0.1.win32.exe</filename>
+      Download the <filename>scons-2.1.0.win32.exe</filename>
       file from the &SCons; download page at
       <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>.
       Then all you need to do is execute the file
@@ -370,8 +371,8 @@
     <para>
 
     The first step is to download either the
-    <filename>scons-2.0.1.tar.gz</filename>
-    or <filename>scons-2.0.1.zip</filename>,
+    <filename>scons-2.1.0.tar.gz</filename>
+    or <filename>scons-2.1.0.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>.
 
@@ -384,7 +385,7 @@
     on Linux or UNIX,
     or <application>WinZip</application> on Windows.
     This will create a directory called
-    <filename>scons-2.0.1</filename>,
+    <filename>scons-2.1.0</filename>,
     usually in your local directory.
     Then change your working directory to that directory
     and install &SCons; by executing the following commands:
@@ -392,7 +393,7 @@
     </para>
 
     <screen>
-      # <userinput>cd scons-2.0.1</userinput>
+      # <userinput>cd scons-2.1.0</userinput>
       # <userinput>python setup.py install</userinput>
     </screen>
 
@@ -460,9 +461,9 @@
 
       This will install the &SCons; build engine
       in the
-      <filename>/usr/lib/scons-2.0.1</filename>
+      <filename>/usr/lib/scons-2.1.0</filename>
       or
-      <filename>C:\Python25\scons-2.0.1</filename>
+      <filename>C:\Python25\scons-2.1.0</filename>
       directory, for example.
 
       </para>
@@ -519,7 +520,7 @@
       relative to the specified prefix.
       Adding <option>--version-lib</option> to the
       above example would install the build engine in
-      <filename>/opt/scons/lib/scons-2.0.1</filename>.
+      <filename>/opt/scons/lib/scons-2.1.0</filename>.
 
       </para>
 
diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml
index 8d1c005..aad4a44 100644
--- a/doc/user/build-install.xml
+++ b/doc/user/build-install.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -121,9 +121,10 @@
 
     <para>
 
-    &SCons; will work with any version of Python from 2.4 or later.
+    &SCons; will work with any 2.x version of Python from 2.4 on;
+    3.0 and later are not yet supported.
     If you need to install Python and have a choice,
-    we recommend using the most recent Python version available.
+    we recommend using the most recent 2.x Python version available.
     Newer Pythons have significant improvements
     that help speed up the performance of &SCons;.
 
@@ -198,7 +199,7 @@
       </para>
 
       <screen>
-        # <userinput>rpm -Uvh scons-2.0.1-1.noarch.rpm</userinput>
+        # <userinput>rpm -Uvh scons-2.1.0-1.noarch.rpm</userinput>
       </screen>
 
       <para>
@@ -260,7 +261,7 @@
 
       &SCons; provides a Windows installer
       that makes installation extremely easy.
-      Download the <filename>scons-2.0.1.win32.exe</filename>
+      Download the <filename>scons-2.1.0.win32.exe</filename>
       file from the &SCons; download page at
       <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>.
       Then all you need to do is execute the file
@@ -370,8 +371,8 @@
     <para>
 
     The first step is to download either the
-    <filename>scons-2.0.1.tar.gz</filename>
-    or <filename>scons-2.0.1.zip</filename>,
+    <filename>scons-2.1.0.tar.gz</filename>
+    or <filename>scons-2.1.0.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>.
 
@@ -384,7 +385,7 @@
     on Linux or UNIX,
     or <application>WinZip</application> on Windows.
     This will create a directory called
-    <filename>scons-2.0.1</filename>,
+    <filename>scons-2.1.0</filename>,
     usually in your local directory.
     Then change your working directory to that directory
     and install &SCons; by executing the following commands:
@@ -392,7 +393,7 @@
     </para>
 
     <screen>
-      # <userinput>cd scons-2.0.1</userinput>
+      # <userinput>cd scons-2.1.0</userinput>
       # <userinput>python setup.py install</userinput>
     </screen>
 
@@ -460,9 +461,9 @@
 
       This will install the &SCons; build engine
       in the
-      <filename>/usr/lib/scons-2.0.1</filename>
+      <filename>/usr/lib/scons-2.1.0</filename>
       or
-      <filename>C:\Python25\scons-2.0.1</filename>
+      <filename>C:\Python25\scons-2.1.0</filename>
       directory, for example.
 
       </para>
@@ -519,7 +520,7 @@
       relative to the specified prefix.
       Adding <option>--version-lib</option> to the
       above example would install the build engine in
-      <filename>/opt/scons/lib/scons-2.0.1</filename>.
+      <filename>/opt/scons/lib/scons-2.1.0</filename>.
 
       </para>
 
diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in
index f7da806..d16e8c3 100644
--- a/doc/user/builders-built-in.in
+++ b/doc/user/builders-built-in.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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-built-in.xml b/doc/user/builders-built-in.xml
index 3d47f5c..39e0533 100644
--- a/doc/user/builders-built-in.xml
+++ b/doc/user/builders-built-in.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -160,6 +160,7 @@
       cl /Fogoodbye.obj /c goodbye.c /nologo
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj
+      embedManifestExeCheck(target, source, env)
     </screen>
 
     <para>
diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in
index af3aec8..1082058 100644
--- a/doc/user/builders-commands.in
+++ b/doc/user/builders-commands.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -72,7 +72,7 @@
   <scons_example name="ex1">
      <file name="SConstruct" printme="1">
      env = Environment()
-     env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET")
+     env.Command('foo.out', 'foo.in', "sed 's/x/y/' &lt; $SOURCE > $TARGET")
      </file>
      <file name="foo.in">
      foo.in
diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml
index 7e48660..e3066c6 100644
--- a/doc/user/builders-commands.xml
+++ b/doc/user/builders-commands.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/builders-writing.in
index 0bf6971..addc837 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -823,7 +823,6 @@ This functionality could be invoked as in the following example:
         <file name="my_command" chmod="0755">
         cat
         </file>
-      </file>
 
     </scons_example>
 
@@ -842,7 +841,6 @@ This functionality could be invoked as in the following example:
                          MY_EMITTER = modify2)
       env1.Foo('file1')
       env2.Foo('file2')
-      </file>
     </sconstruct>
 
     <para>
@@ -899,8 +897,8 @@ This functionality could be invoked as in the following example:
 
     <para>
 
-    The <filename>site_scons</filename> directory gives you a place to
-    put Python modules you can import into your &SConscript; files
+    The <filename>site_scons</filename> directories give you a place to
+    put Python modules and packages that you can import into your &SConscript; files
     (<filename>site_scons</filename>),
     add-on tools that can integrate into &SCons;
     (<filename>site_scons/site_tools</filename>),
@@ -912,11 +910,21 @@ This functionality could be invoked as in the following example:
 
     <para>
 
+    Each system type (Windows, Mac, Linux, etc.) searches a canonical
+    set of directories for site_scons; see the man page for details.
+    The top-level SConstruct's site_scons dir is always searched last,
+    and its dir is placed first in the tool path so it overrides all
+    others.
+
+    </para>
+
+    <para>
+
     If you get a tool from somewhere (the &SCons; wiki or a third party,
-    for instance) and you'd like to use it in your project, the
+    for instance) and you'd like to use it in your project, a
     <filename>site_scons</filename> dir is the simplest place to put it.
     Tools come in two flavors; either a Python function that operates on
-    an &Environment; or a Python file containing two functions,
+    an &Environment; or a Python module or package  containing two functions,
     <function>exists()</function> and <function>generate()</function>.
 
     </para>
@@ -931,7 +939,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_example name="site1">
-      <file name="site_scons/site_init.py" printme=1>
+      <file name="site_scons/site_init.py" printme="1">
         def TOOL_ADD_HEADER(env):
            """A Tool to add a header from $HEADER to the source file"""
            add_header = Builder(action=['echo "$HEADER" &gt; $TARGET',
@@ -975,16 +983,23 @@ This functionality could be invoked as in the following example:
     -->
 
     <para>
-      Similarly, a more full-fledged tool with
+      A more full-fledged tool with
       <function>exists()</function> and <function>generate()</function>
-      methods can be installed in
-      <filename>site_scons/site_tools/toolname.py</filename>.  Since
-      <filename>site_scons/site_tools</filename> is automatically added
-      to the head of the tool search path, any tool found there will be
-      available to all environments.  Furthermore, a tool found there
-      will override a built-in tool of the same name, so if you need to
-      change the behavior of a built-in tool, site_scons gives you the
-      hook you need.
+      methods can be installed either as a module in the file
+      <filename>site_scons/site_tools/toolname.py</filename> or as a
+      package in the
+      directory <filename>site_scons/site_tools/toolname</filename>.  In
+      the case of using a package, the <function>exists()</function>
+      and <function>generate()</function> are in the
+      file <filename>site_scons/site_tools/toolname/__init__.py</filename>.
+      (In all the above case <filename>toolname</filename> is replaced
+      by the name of the tool.)
+      Since <filename>site_scons/site_tools</filename> is automatically
+      added to the head of the tool search path, any tool found there
+      will be available to all environments.  Furthermore, a tool found
+      there will override a built-in tool of the same name, so if you
+      need to change the behavior of a built-in
+      tool, <filename>site_scons</filename> gives you the hook you need.
     </para>
 
     <para>
@@ -998,7 +1013,7 @@ This functionality could be invoked as in the following example:
     </para>
       
     <scons_example name="site2">
-      <file name="site_scons/my_utils.py" printme=1>
+      <file name="site_scons/my_utils.py" printme="1">
         from SCons.Script import *   # for Execute and Mkdir
         def build_id():
            """Return a build ID (stub version)"""
@@ -1047,13 +1062,15 @@ This functionality could be invoked as in the following example:
 
     <para>
 
-      If you have a machine-wide site dir you'd like to use instead of
-      <filename>./site_scons</filename>, use the
-      <literal>--site-dir</literal> option to point to your dir.
+      You can use any of the user- or machine-wide site dirs such as
+      <filename>~/.scons/site_scons</filename> instead of
+      <filename>./site_scons</filename>, or use the
+      <literal>--site-dir</literal> option to point to your own dir.
       <filename>site_init.py</filename> and
       <filename>site_tools</filename> will be located under that dir.
-      To avoid using a <filename>site_scons</filename> dir at all, even
-      if it exists, use the <literal>--no-site-dir</literal> option.
+      To avoid using a <filename>site_scons</filename> dir at all,
+      even if it exists, use the <literal>--no-site-dir</literal>
+      option.
 
     </para>
 
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index f364e27..d9bda79 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -703,7 +703,6 @@ This functionality could be invoked as in the following example:
         import os
         env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
         env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
-      
 
     </programlisting>
 
@@ -722,7 +721,6 @@ This functionality could be invoked as in the following example:
                          MY_EMITTER = modify2)
       env1.Foo('file1')
       env2.Foo('file2')
-      
     </programlisting>
 
     <para>
@@ -781,8 +779,8 @@ This functionality could be invoked as in the following example:
 
     <para>
 
-    The <filename>site_scons</filename> directory gives you a place to
-    put Python modules you can import into your &SConscript; files
+    The <filename>site_scons</filename> directories give you a place to
+    put Python modules and packages that you can import into your &SConscript; files
     (<filename>site_scons</filename>),
     add-on tools that can integrate into &SCons;
     (<filename>site_scons/site_tools</filename>),
@@ -794,11 +792,21 @@ This functionality could be invoked as in the following example:
 
     <para>
 
+    Each system type (Windows, Mac, Linux, etc.) searches a canonical
+    set of directories for site_scons; see the man page for details.
+    The top-level SConstruct's site_scons dir is always searched last,
+    and its dir is placed first in the tool path so it overrides all
+    others.
+
+    </para>
+
+    <para>
+
     If you get a tool from somewhere (the &SCons; wiki or a third party,
-    for instance) and you'd like to use it in your project, the
+    for instance) and you'd like to use it in your project, a
     <filename>site_scons</filename> dir is the simplest place to put it.
     Tools come in two flavors; either a Python function that operates on
-    an &Environment; or a Python file containing two functions,
+    an &Environment; or a Python module or package  containing two functions,
     <function>exists()</function> and <function>generate()</function>.
 
     </para>
@@ -848,16 +856,23 @@ This functionality could be invoked as in the following example:
     -->
 
     <para>
-      Similarly, a more full-fledged tool with
+      A more full-fledged tool with
       <function>exists()</function> and <function>generate()</function>
-      methods can be installed in
-      <filename>site_scons/site_tools/toolname.py</filename>.  Since
-      <filename>site_scons/site_tools</filename> is automatically added
-      to the head of the tool search path, any tool found there will be
-      available to all environments.  Furthermore, a tool found there
-      will override a built-in tool of the same name, so if you need to
-      change the behavior of a built-in tool, site_scons gives you the
-      hook you need.
+      methods can be installed either as a module in the file
+      <filename>site_scons/site_tools/toolname.py</filename> or as a
+      package in the
+      directory <filename>site_scons/site_tools/toolname</filename>.  In
+      the case of using a package, the <function>exists()</function>
+      and <function>generate()</function> are in the
+      file <filename>site_scons/site_tools/toolname/__init__.py</filename>.
+      (In all the above case <filename>toolname</filename> is replaced
+      by the name of the tool.)
+      Since <filename>site_scons/site_tools</filename> is automatically
+      added to the head of the tool search path, any tool found there
+      will be available to all environments.  Furthermore, a tool found
+      there will override a built-in tool of the same name, so if you
+      need to change the behavior of a built-in
+      tool, <filename>site_scons</filename> gives you the hook you need.
     </para>
 
     <para>
@@ -913,13 +928,15 @@ This functionality could be invoked as in the following example:
 
     <para>
 
-      If you have a machine-wide site dir you'd like to use instead of
-      <filename>./site_scons</filename>, use the
-      <literal>--site-dir</literal> option to point to your dir.
+      You can use any of the user- or machine-wide site dirs such as
+      <filename>~/.scons/site_scons</filename> instead of
+      <filename>./site_scons</filename>, or use the
+      <literal>--site-dir</literal> option to point to your own dir.
       <filename>site_init.py</filename> and
       <filename>site_tools</filename> will be located under that dir.
-      To avoid using a <filename>site_scons</filename> dir at all, even
-      if it exists, use the <literal>--no-site-dir</literal> option.
+      To avoid using a <filename>site_scons</filename> dir at all,
+      even if it exists, use the <literal>--no-site-dir</literal>
+      option.
 
     </para>
 
diff --git a/doc/user/builders.in b/doc/user/builders.in
index 9e9b647..f2bf36d 100644
--- a/doc/user/builders.in
+++ b/doc/user/builders.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.xml b/doc/user/builders.xml
index 9e9b647..f2bf36d 100644
--- a/doc/user/builders.xml
+++ b/doc/user/builders.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/caching.in
index e5e2742..d60f067 100644
--- a/doc/user/caching.in
+++ b/doc/user/caching.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 5a64e7d..c3dae0a 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/command-line.in
index cd5ead6..52a61ac 100644
--- a/doc/user/command-line.in
+++ b/doc/user/command-line.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -221,7 +221,7 @@
 
       </para>
 
-      <sconstruct)
+      <sconstruct>
         if not GetOption('help'):
             SConscript('src/SConscript', export='env')
       </sconstruct>
@@ -2195,7 +2195,7 @@
 
         Second,
         the contents of the &DEFAULT_TARGETS; list change
-        in response to calls to the &Default: function,
+        in response to calls to the &Default; function,
         as you can see from the following &SConstruct; file:
 
         </para>
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml
index 8bc72bb..f06442e 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -214,7 +214,10 @@
 
       </para>
 
-      <programlisting></programlisting>
+      <programlisting>
+        if not GetOption('help'):
+            SConscript('src/SConscript', export='env')
+      </programlisting>
 
       <para>
 
@@ -1252,7 +1255,7 @@
         <screen>
           % <userinput>scons -Q COLOR=magenta foo.o</userinput>
           
-          scons: *** Invalid value for option COLOR: magenta
+          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>
 
@@ -1308,15 +1311,15 @@
         <screen>
           % <userinput>scons -Q COLOR=Red foo.o</userinput>
           
-          scons: *** Invalid value for option COLOR: Red
+          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
+          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
+          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>
 
@@ -2107,7 +2110,7 @@
 
         Second,
         the contents of the &DEFAULT_TARGETS; list change
-        in response to calls to the &Default;: function,
+        in response to calls to the &Default; function,
         as you can see from the following &SConstruct; file:
 
         </para>
diff --git a/doc/user/copyright.in b/doc/user/copyright.in
index 8b90dbc..19689fe 100644
--- a/doc/user/copyright.in
+++ b/doc/user/copyright.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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/copyright.xml b/doc/user/copyright.xml
index 8b90dbc..19689fe 100644
--- a/doc/user/copyright.xml
+++ b/doc/user/copyright.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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/depends.in b/doc/user/depends.in
index 69bb242..190670c 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -386,7 +386,7 @@
 
       <para>
 
-      So configured, &SCons will still behave like
+      So configured, &SCons; will still behave like
       it does when using <literal>Decider('MD5')</literal>:
 
       </para>
@@ -487,7 +487,7 @@
       only its section of the input file.
       However, since the input file may contain a lot of data,
       we want to open the input file only if its timestamp has changed.
-      This could done with a custom
+      This could be done with a custom
       &Decider; function that might look something like this:
 
       </para>
@@ -591,6 +591,59 @@
 
       </para>
 
+      <para>
+
+      Another thing to look out for, is the fact that the three
+      attributes above may not be present at the time of the first run.
+      Without any prior build, no targets got created and no
+      <filename>.sconsign</filename> DB file exists yet.
+      So, it is recommended to always check whether the
+      <varname>prev_ni</varname> attribute in question is available.
+
+      </para>
+
+      <para>
+
+      We finally present a small example for a
+      <varname>csig</varname>-based decider function. Note how the
+      signature information for the <varname>dependency</varname> file
+      has to get initialized via <function>get_csig</function>
+      during each function call (this is mandatory!).
+
+      </para>
+
+      <sconstruct>
+        env = Environment()
+        
+        def config_file_decider(dependency, target, prev_ni):
+            import os.path
+        
+            # We always have to init the .csig value...
+            dep_csig = dependency.get_csig()
+            # .csig may not exist, because no target was built yet...
+            if 'csig' not in dir(prev_ni):
+                return True
+            # Target file may not exist yet
+            if not os.path.exists(str(target.abspath)):
+                return True
+            if dep_csig != prev_ni.csig:
+                # Some change on source file => update installed one
+                return True
+            return False
+        
+        def update_file():
+            f = open("test.txt","a")
+            f.write("some line\n")
+            f.close()
+            
+        update_file()
+        
+        # Activate our own decider function
+        env.Decider(config_file_decider)
+        
+        env.Install("install","test.txt")
+      </sconstruct>
+
     </section>
 
     <section>
@@ -861,7 +914,7 @@
 
   </section>
 
-  <section>
+  <section id="sect-implicit-dependencies">
   <title>Implicit Dependencies:  The &cv-CPPPATH; Construction Variable</title>
 
     <para>
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 430e64a..5b19220 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -488,7 +488,7 @@
       only its section of the input file.
       However, since the input file may contain a lot of data,
       we want to open the input file only if its timestamp has changed.
-      This could done with a custom
+      This could be done with a custom
       &Decider; function that might look something like this:
 
       </para>
@@ -587,6 +587,59 @@
 
       </para>
 
+      <para>
+
+      Another thing to look out for, is the fact that the three
+      attributes above may not be present at the time of the first run.
+      Without any prior build, no targets got created and no
+      <filename>.sconsign</filename> DB file exists yet.
+      So, it is recommended to always check whether the
+      <varname>prev_ni</varname> attribute in question is available.
+
+      </para>
+
+      <para>
+
+      We finally present a small example for a
+      <varname>csig</varname>-based decider function. Note how the
+      signature information for the <varname>dependency</varname> file
+      has to get initialized via <function>get_csig</function>
+      during each function call (this is mandatory!).
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        
+        def config_file_decider(dependency, target, prev_ni):
+            import os.path
+        
+            # We always have to init the .csig value...
+            dep_csig = dependency.get_csig()
+            # .csig may not exist, because no target was built yet...
+            if 'csig' not in dir(prev_ni):
+                return True
+            # Target file may not exist yet
+            if not os.path.exists(str(target.abspath)):
+                return True
+            if dep_csig != prev_ni.csig:
+                # Some change on source file =&gt; update installed one
+                return True
+            return False
+        
+        def update_file():
+            f = open("test.txt","a")
+            f.write("some line\n")
+            f.close()
+            
+        update_file()
+        
+        # Activate our own decider function
+        env.Decider(config_file_decider)
+        
+        env.Install("install","test.txt")
+      </programlisting>
+
     </section>
 
     <section>
@@ -850,7 +903,7 @@
 
   </section>
 
-  <section>
+  <section id="sect-implicit-dependencies">
   <title>Implicit Dependencies:  The &cv-CPPPATH; Construction Variable</title>
 
     <para>
@@ -989,6 +1042,7 @@
        C:\><userinput>scons -Q hello.exe</userinput>
        cl /Fohello.obj /c hello.c /nologo /Iinclude /I\home\project\inc
        link /nologo /OUT:hello.exe hello.obj
+       embedManifestExeCheck(target, source, env)
     </screen>
 
   </section>
diff --git a/doc/user/environments.in b/doc/user/environments.in
index 9ce5568..ecfea8a 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -1,6 +1,6 @@
 <!--
 
-     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
@@ -347,7 +347,7 @@ environment, of directory names, suffixes, etc.
 
     The <literal>external environment</literal>
     is the set of variables in the user's environment
-    at the time the user runs &SCons.
+    at the time the user runs &SCons;.
     These variables are available within the &SConscript; files
     through the Python <literal>os.environ</literal> dictionary.
     See <xref linkend="sect-external-environments"></xref>, below.
@@ -406,7 +406,7 @@ environment, of directory names, suffixes, etc.
 
   Unlike &Make;,  &SCons; does not automatically
   copy or import values between different environments
-  (with the exception of explicit clones of &consenvs,
+  (with the exception of explicit clones of &consenvs;,
   which inherit values from their parent).
   This is a deliberate design choice
   to make sure that builds are,
@@ -638,7 +638,7 @@ environment, of directory names, suffixes, etc.
          for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
              print "key = %s, value = %s" % (key, dict[key])
          </file>
-      </scons_Example>
+      </scons_example>
 
       <para>
 
@@ -779,18 +779,20 @@ environment, of directory names, suffixes, etc.
       If a problem occurs when expanding a construction variable,
       by default it is expanded to <literal>''</literal>
       (a null string), and will not cause scons to fail. 
-      
+      </para>
+
        <scons_example name="missing1">
          <file name="SConstruct" printme="1">
           env = Environment()
-          print "value is:", env.subst( '->$MISSING<-' )
+          print "value is:", env.subst( '->$MISSING&lt;-' )
         </file>
       </scons_example>
 
        <scons_output example="missing1">
           <scons_output_command>scons -Q</scons_output_command>
        </scons_output>
-      
+
+      <para>
       This default behaviour can be changed using the &AllowSubstExceptions;
       function.
       When a problem occurs with a variable expansion it generates
@@ -810,7 +812,7 @@ environment, of directory names, suffixes, etc.
          <file name="SConstruct" printme="1">
           AllowSubstExceptions()
           env = Environment()
-          print "value is:", env.subst( '->$MISSING<-' )
+          print "value is:", env.subst( '->$MISSING&lt;-' )
         </file>
       </scons_example>
 
@@ -830,7 +832,7 @@ environment, of directory names, suffixes, etc.
          <file name="SConstruct" printme="1">
           AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
           env = Environment()
-          print "value is:", env.subst( '->${1 / 0}<-' )
+          print "value is:", env.subst( '->${1 / 0}&lt;-' )
         </file>
       </scons_example>
 
@@ -1093,7 +1095,7 @@ environment, of directory names, suffixes, etc.
 
     </section>
 
-    <section>
+    <section id="sect-clone-environments">
     <title>Making Copies of &ConsEnvs;:  the &Clone; Method</title>
 
       <para>
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 5bb1089..81f43a4 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -1,6 +1,6 @@
 <!--
 
-     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
@@ -779,7 +779,8 @@ environment, of directory names, suffixes, etc.
       If a problem occurs when expanding a construction variable,
       by default it is expanded to <literal>''</literal>
       (a null string), and will not cause scons to fail. 
-      
+      </para>
+
        <programlisting>
           env = Environment()
           print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
@@ -790,7 +791,8 @@ environment, of directory names, suffixes, etc.
           value is: -&gt;&lt;-
           scons: `.' is up to date.
        </screen>
-      
+
+      <para>
       This default behaviour can be changed using the &AllowSubstExceptions;
       function.
       When a problem occurs with a variable expansion it generates
@@ -1087,7 +1089,7 @@ environment, of directory names, suffixes, etc.
 
     </section>
 
-    <section>
+    <section id="sect-clone-environments">
     <title>Making Copies of &ConsEnvs;:  the &Clone; Method</title>
 
       <para>
diff --git a/doc/user/errors.in b/doc/user/errors.in
index ad4c2ef..7e33118 100644
--- a/doc/user/errors.in
+++ b/doc/user/errors.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 ad4c2ef..7e33118 100644
--- a/doc/user/errors.xml
+++ b/doc/user/errors.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/example.in
index ad4c2ef..7e33118 100644
--- a/doc/user/example.in
+++ b/doc/user/example.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 ad4c2ef..7e33118 100644
--- a/doc/user/example.xml
+++ b/doc/user/example.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/factories.in
index c0f524d..da92082 100644
--- a/doc/user/factories.in
+++ b/doc/user/factories.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -209,7 +209,7 @@
     <para>
 
     Of course, like all of these &Action; factories,
-    the &Delete factory also expands
+    the &Delete; factory also expands
     &cv-link-TARGET; and &cv-link-SOURCE; variables appropriately.
     For example:
 
diff --git a/doc/user/factories.xml b/doc/user/factories.xml
index 6a92b0c..7f51c8d 100644
--- a/doc/user/factories.xml
+++ b/doc/user/factories.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/file-removal.in
index 1b12d35..b664ba0 100644
--- a/doc/user/file-removal.in
+++ b/doc/user/file-removal.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 92c1c0d..47b081a 100644
--- a/doc/user/file-removal.xml
+++ b/doc/user/file-removal.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/functions.in
new file mode 100644
index 0000000..7c96c54
--- /dev/null
+++ b/doc/user/functions.in
@@ -0,0 +1,38 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<para>
+
+This appendix contains descriptions of all of the
+function and construction environment methods
+in this version of &SCons;
+
+</para>
+
+<variablelist>
+
+&functions-gen;
+
+</variablelist>
diff --git a/doc/user/functions.xml b/doc/user/functions.xml
new file mode 100644
index 0000000..7c96c54
--- /dev/null
+++ b/doc/user/functions.xml
@@ -0,0 +1,38 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<para>
+
+This appendix contains descriptions of all of the
+function and construction environment methods
+in this version of &SCons;
+
+</para>
+
+<variablelist>
+
+&functions-gen;
+
+</variablelist>
diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in
index 16d9389..950bc8a 100644
--- a/doc/user/hierarchy.in
+++ b/doc/user/hierarchy.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -478,7 +478,7 @@ make no difference to the build.
 
   </section>
 
-  <section>
+  <section id="sect-sharing-environments">
   <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title>
 
     <para>
@@ -688,7 +688,7 @@ make no difference to the build.
 
       Sometimes, you would like to be able to
       use information from a subsidiary
-      &SConscript file in some way.
+      &SConscript; file in some way.
       For example,
       suppose that you want to create one
       library from source files
diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index bc4073e..6691e70 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -442,7 +442,7 @@ make no difference to the build.
 
   </section>
 
-  <section>
+  <section id="sect-sharing-environments">
   <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title>
 
     <para>
diff --git a/doc/user/install.in b/doc/user/install.in
index 8f9498e..131fc6a 100644
--- a/doc/user/install.in
+++ b/doc/user/install.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 f119b00..6b49ae8 100644
--- a/doc/user/install.xml
+++ b/doc/user/install.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/java.in
index 290cd43..bad5c34 100644
--- a/doc/user/java.in
+++ b/doc/user/java.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -390,7 +390,7 @@
     You can generate C header and source files
     for implementing native methods,
     by using the &b-link-JavaH; Builder.
-    There are several ways of using the &JavaH Builder.
+    There are several ways of using the &JavaH; Builder.
     One typical invocation might look like:
 
     </para>
@@ -636,7 +636,7 @@
     As it did with the &b-link-JavaH; Builder,
     &SCons; remembers the class directory
     and passes it as the <option>-classpath</option> option
-    to &rmic:
+    to &rmic;:
 
     </para>
 
diff --git a/doc/user/java.xml b/doc/user/java.xml
index a0544f7..f277558 100644
--- a/doc/user/java.xml
+++ b/doc/user/java.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/less-simple.in
index cccad83..d717014 100644
--- a/doc/user/less-simple.in
+++ b/doc/user/less-simple.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 24b45e6..e269490 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -102,6 +102,7 @@
        C:\><userinput>scons -Q</userinput>
        cl /Fohello.obj /c hello.c /nologo
        link /nologo /OUT:new_hello.exe hello.obj
+       embedManifestExeCheck(target, source, env)
     </screen>
 
   </section>
@@ -193,6 +194,7 @@
        cl /Fofile2.obj /c file2.c /nologo
        cl /Foprog.obj /c prog.c /nologo
        link /nologo /OUT:program.exe prog.obj file1.obj file2.obj
+       embedManifestExeCheck(target, source, env)
     </screen>
 
   </section>
diff --git a/doc/user/libraries.in b/doc/user/libraries.in
index 5b449e7..a56f2c3 100644
--- a/doc/user/libraries.in
+++ b/doc/user/libraries.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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/libraries.xml b/doc/user/libraries.xml
index 3eed3cc..6909758 100644
--- a/doc/user/libraries.xml
+++ b/doc/user/libraries.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -206,6 +206,7 @@
         cl /Fof3.obj /c f3.c /nologo
         link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
         RegServerFunc(target, source, env)
+        embedManifestDllCheck(target, source, env)
       </screen>
 
       <para>
@@ -288,6 +289,7 @@
       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
       cl /Foprog.obj /c prog.c /nologo
       link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
+      embedManifestExeCheck(target, source, env)
     </screen>
 
     <para>
@@ -412,6 +414,7 @@
       C:\><userinput>scons -Q</userinput>
       cl /Foprog.obj /c prog.c /nologo
       link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
+      embedManifestExeCheck(target, source, env)
     </screen>
     <!-- The link command is too wide in the PDF version. 
          There are some other examples of this throughout the document. -->
diff --git a/doc/user/main.in b/doc/user/main.in
index fbc28df..feb8c25 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -37,6 +37,9 @@
     <!ENTITY % builders-mod SYSTEM "builders.mod">
     %builders-mod;
 
+    <!ENTITY % functions-mod SYSTEM "functions.mod">
+    %functions-mod;
+
     <!ENTITY % tools-mod SYSTEM "tools.mod">
     %tools-mod;
 
@@ -61,6 +64,7 @@
     <!ENTITY example SYSTEM "example.xml">
     <!ENTITY factories SYSTEM "factories.xml">
     <!ENTITY file-removal SYSTEM "file-removal.xml">
+    <!ENTITY functions SYSTEM "functions.xml">
     <!ENTITY hierarchy SYSTEM "hierarchy.xml">
     <!ENTITY java SYSTEM "java.xml">
     <!ENTITY install SYSTEM "install.xml">
@@ -89,6 +93,7 @@
     <!ENTITY variants SYSTEM "variants.xml">
 
     <!ENTITY builders-gen SYSTEM "builders.gen">
+    <!ENTITY functions-gen SYSTEM "functions.gen">
     <!ENTITY tools-gen SYSTEM "tools.gen">
     <!ENTITY variables-gen SYSTEM "variables.gen">
 
@@ -177,18 +182,35 @@
     &environments;
   </chapter>
 
-  <!-- These next three sections should be combined into one chapter -->
-  <chapter id="chap-mergeflags">
-    <title>Merging Options into the Environment: the &MergeFlags; Function</title>
-    &mergeflags;
-  </chapter>
-  <chapter id="chap-parseflags">
-    <title>Separating Compile Arguments into their Variables:  the &ParseFlags; Function</title>
-    &parseflags;
-  </chapter>
-  <chapter id="chap-parseconfig">
-    <title>Finding Installed Library Information:  the &ParseConfig; Function</title>
-    &parseconfig;
+  <chapter id="chap-manip-options">
+    <title>Automatically Putting Command-line Options into their Construction Variables</title>
+    <!-- TODO:  This intro paragraph should describe at a high-level
+    what these things do.  People are likely to use the intro as a
+    (brief) overview of *what* these functions do to decide if this
+    chapter is where they should read in more detail.  -->
+    <para>
+    This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;.
+    </para>
+    <section id="sect-mergeflags">
+      <title>Merging Options into the Environment: the &MergeFlags; Function</title>
+      &mergeflags;
+    </section>
+    <section id="sect-parseflags">
+      <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title>
+      &parseflags;
+    </section>
+    <section id="sect-parseconfig">
+      <title>Finding Installed Library Information: the &ParseConfig; Function</title>
+      &parseconfig;
+    </section>
+    <!--
+    XXX parse_flags= option of Environment()
+
+    <section id="sect-env-parseflags">
+      <title>Adding Flags when Constructing Enviroment: the parse_flags Optional Argument</title>
+      &envparseflags;
+    </section>
+    -->
   </chapter>
 
   <chapter id="chap-output">
@@ -341,6 +363,11 @@
     &tools;
   </appendix>
 
+  <appendix id="app-functions">
+    <title>Functions and Environment Methods</title>
+    &functions;
+  </appendix>
+
   <appendix id="app-tasks">
     <title>Handling Common Tasks</title>
     &tasks;
diff --git a/doc/user/main.xml b/doc/user/main.xml
index fbc28df..feb8c25 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -37,6 +37,9 @@
     <!ENTITY % builders-mod SYSTEM "builders.mod">
     %builders-mod;
 
+    <!ENTITY % functions-mod SYSTEM "functions.mod">
+    %functions-mod;
+
     <!ENTITY % tools-mod SYSTEM "tools.mod">
     %tools-mod;
 
@@ -61,6 +64,7 @@
     <!ENTITY example SYSTEM "example.xml">
     <!ENTITY factories SYSTEM "factories.xml">
     <!ENTITY file-removal SYSTEM "file-removal.xml">
+    <!ENTITY functions SYSTEM "functions.xml">
     <!ENTITY hierarchy SYSTEM "hierarchy.xml">
     <!ENTITY java SYSTEM "java.xml">
     <!ENTITY install SYSTEM "install.xml">
@@ -89,6 +93,7 @@
     <!ENTITY variants SYSTEM "variants.xml">
 
     <!ENTITY builders-gen SYSTEM "builders.gen">
+    <!ENTITY functions-gen SYSTEM "functions.gen">
     <!ENTITY tools-gen SYSTEM "tools.gen">
     <!ENTITY variables-gen SYSTEM "variables.gen">
 
@@ -177,18 +182,35 @@
     &environments;
   </chapter>
 
-  <!-- These next three sections should be combined into one chapter -->
-  <chapter id="chap-mergeflags">
-    <title>Merging Options into the Environment: the &MergeFlags; Function</title>
-    &mergeflags;
-  </chapter>
-  <chapter id="chap-parseflags">
-    <title>Separating Compile Arguments into their Variables:  the &ParseFlags; Function</title>
-    &parseflags;
-  </chapter>
-  <chapter id="chap-parseconfig">
-    <title>Finding Installed Library Information:  the &ParseConfig; Function</title>
-    &parseconfig;
+  <chapter id="chap-manip-options">
+    <title>Automatically Putting Command-line Options into their Construction Variables</title>
+    <!-- TODO:  This intro paragraph should describe at a high-level
+    what these things do.  People are likely to use the intro as a
+    (brief) overview of *what* these functions do to decide if this
+    chapter is where they should read in more detail.  -->
+    <para>
+    This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;.
+    </para>
+    <section id="sect-mergeflags">
+      <title>Merging Options into the Environment: the &MergeFlags; Function</title>
+      &mergeflags;
+    </section>
+    <section id="sect-parseflags">
+      <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title>
+      &parseflags;
+    </section>
+    <section id="sect-parseconfig">
+      <title>Finding Installed Library Information: the &ParseConfig; Function</title>
+      &parseconfig;
+    </section>
+    <!--
+    XXX parse_flags= option of Environment()
+
+    <section id="sect-env-parseflags">
+      <title>Adding Flags when Constructing Enviroment: the parse_flags Optional Argument</title>
+      &envparseflags;
+    </section>
+    -->
   </chapter>
 
   <chapter id="chap-output">
@@ -341,6 +363,11 @@
     &tools;
   </appendix>
 
+  <appendix id="app-functions">
+    <title>Functions and Environment Methods</title>
+    &functions;
+  </appendix>
+
   <appendix id="app-tasks">
     <title>Handling Common Tasks</title>
     &tasks;
diff --git a/doc/user/make.in b/doc/user/make.in
index c17b047..7102557 100644
--- a/doc/user/make.in
+++ b/doc/user/make.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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/make.xml b/doc/user/make.xml
index c17b047..7102557 100644
--- a/doc/user/make.xml
+++ b/doc/user/make.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/mergeflags.in
index 58d437c..086d042 100644
--- a/doc/user/mergeflags.in
+++ b/doc/user/mergeflags.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 ab10e54..f0bc2b6 100644
--- a/doc/user/mergeflags.xml
+++ b/doc/user/mergeflags.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/misc.in
index 87b5db4..fef1b8f 100644
--- a/doc/user/misc.in
+++ b/doc/user/misc.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -36,7 +36,7 @@
     <para>
 
     Although the &SCons; code itself will run 
-    on any Python version 2.4 or later,
+    on any 2.x Python version 2.4 or later,
     you are perfectly free to make use of
     Python syntax and modules from more modern versions
     (for example, Python 2.5 or 2.6)
@@ -82,7 +82,7 @@
 
     <para>
 
-    And then &SCons will exit with the following error
+    And then &SCons; will exit with the following error
     message when a user runs it with an unsupported
     earlier version of Python:
 
@@ -151,7 +151,7 @@
 
     <para>
 
-    And then &SCons will exit with the following error
+    And then &SCons; will exit with the following error
     message when a user runs it with an unsupported
     earlier version of &SCons;:
 
@@ -274,13 +274,13 @@
       </file>
       <directory name="src"></directory>
       <directory name="src/include"></directory>
-      </file>
       <file name="src/include/private.h">
         exists
-      <directory name="include"></directory>
       </file>
+      <directory name="include"></directory>
       <file name="include/dist.h">
         exists
+      </file>
     </scons_example>
 
     <scons_output example="FindFile1b" os="posix">
diff --git a/doc/user/misc.xml b/doc/user/misc.xml
index f79f1cc..069f94b 100644
--- a/doc/user/misc.xml
+++ b/doc/user/misc.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -36,7 +36,7 @@
     <para>
 
     Although the &SCons; code itself will run 
-    on any Python version 2.4 or later,
+    on any 2.x Python version 2.4 or later,
     you are perfectly free to make use of
     Python syntax and modules from more modern versions
     (for example, Python 2.5 or 2.6)
@@ -263,7 +263,7 @@
        headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h']
        for hdr in headers:
            print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes)
-</programlisting>
+    </programlisting>
 
     <screen>
        % <userinput>scons -Q</userinput>
diff --git a/doc/user/nodes.in b/doc/user/nodes.in
index c65a2ad..7799d3f 100644
--- a/doc/user/nodes.in
+++ b/doc/user/nodes.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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/nodes.xml b/doc/user/nodes.xml
index 71ac7c1..fe8e167 100644
--- a/doc/user/nodes.xml
+++ b/doc/user/nodes.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -131,6 +131,7 @@
        cl /Fogoodbye.obj /c goodbye.c -DGOODBYE
        cl /Fohello.obj /c hello.c -DHELLO
        link /nologo /OUT:hello.exe hello.obj goodbye.obj
+       embedManifestExeCheck(target, source, env)
     </screen>
 
     <para>
@@ -275,6 +276,7 @@
       The program file is: hello.exe
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
     </screen>
 
     <para>
diff --git a/doc/user/output.in b/doc/user/output.in
index e456026..d2823d0 100644
--- a/doc/user/output.in
+++ b/doc/user/output.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -490,7 +490,7 @@
     over how to print each evaluated node
     by passing a Python function
     (or other Python callable)
-    to the &Progress function.
+    to the &Progress; function.
     Your function will be called
     for each evaluated node,
     allowing you to
diff --git a/doc/user/output.xml b/doc/user/output.xml
index 297e6f8..6910b59 100644
--- a/doc/user/output.xml
+++ b/doc/user/output.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/parseconfig.in
index 667601f..5eb990c 100644
--- a/doc/user/parseconfig.in
+++ b/doc/user/parseconfig.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 534ea3d..409abfe 100644
--- a/doc/user/parseconfig.xml
+++ b/doc/user/parseconfig.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/parseflags.in
index 2f4bea5..6e72c18 100644
--- a/doc/user/parseflags.in
+++ b/doc/user/parseflags.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 fd15de7..7350831 100644
--- a/doc/user/parseflags.xml
+++ b/doc/user/parseflags.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -91,6 +91,7 @@
     LIBS ['foo']
     cl /Fof1.obj /c f1.c /nologo /I\opt\include
     link /nologo /OUT:f1.exe /LIBPATH:\opt\lib foo.lib f1.obj
+    embedManifestExeCheck(target, source, env)
  </screen>
 
  <para>
diff --git a/doc/user/preface.in b/doc/user/preface.in
index a60beab..e82ee3b 100644
--- a/doc/user/preface.in
+++ b/doc/user/preface.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -104,7 +104,7 @@
     <para>
 
     There are a few overriding principles
-    we try to live up to in designing and implementing &SCons:
+    we try to live up to in designing and implementing &SCons;:
 
     </para>
 
@@ -418,7 +418,7 @@
 
     <para>
 
-    If you want to receive announcements about &SCons,
+    If you want to receive announcements about &SCons;,
     join the low-volume &scons-announce; mailing list.
 
     </para>
diff --git a/doc/user/preface.xml b/doc/user/preface.xml
index db2031d..e82ee3b 100644
--- a/doc/user/preface.xml
+++ b/doc/user/preface.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/python.in
index 18679e4..c3ea5fe 100644
--- a/doc/user/python.in
+++ b/doc/user/python.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 18679e4..c3ea5fe 100644
--- a/doc/user/python.xml
+++ b/doc/user/python.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/repositories.in
index 531aa8a..5ba9090 100644
--- a/doc/user/repositories.in
+++ b/doc/user/repositories.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -210,9 +210,9 @@
     in the repository trees, though,
     it will be unable to find the <literal>#include</literal> files.
     If, for example, the &hello_c; file in
-    our previous example includes the &hello.h;
+    our previous example includes the &hello_h;
     in its current directory,
-    and the &hello.h; only exists in the repository:
+    and the &hello_h; only exists in the repository:
 
     </para>
 
diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml
index 6400b23..219dbaf 100644
--- a/doc/user/repositories.xml
+++ b/doc/user/repositories.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -193,9 +193,9 @@
     in the repository trees, though,
     it will be unable to find the <literal>#include</literal> files.
     If, for example, the &hello_c; file in
-    our previous example includes the &hello;.h;
+    our previous example includes the &hello_h;
     in its current directory,
-    and the &hello;.h; only exists in the repository:
+    and the &hello_h; only exists in the repository:
 
     </para>
 
diff --git a/doc/user/run.in b/doc/user/run.in
index 761f37c..8d47b27 100644
--- a/doc/user/run.in
+++ b/doc/user/run.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 761f37c..8d47b27 100644
--- a/doc/user/run.xml
+++ b/doc/user/run.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/scanners.in
index db3170a..e8bdff7 100644
--- a/doc/user/scanners.in
+++ b/doc/user/scanners.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -171,9 +171,20 @@ over the file scanning rather than being called for each input line:
       
       def kfile_scan(node, env, path, arg):
           contents = node.get_text_contents()
-          return include_re.findall(contents)
+          return env.File(include_re.findall(contents))
     </programlisting>
 
+    <para>
+    
+      It is important to note that you
+      have to return a list of File nodes from the scanner function, simple
+      strings for the file names won't do. As in the examples we are showing here,
+      you can use the &File;
+      function of your current Environment in order to create nodes on the fly from
+      a sequence of file names with relative paths.
+      
+    </para>
+
     <para>
 
       The scanner function must
@@ -283,7 +294,7 @@ over the file scanning rather than being called for each input line:
         def kfile_scan(node, env, path):
             contents = node.get_text_contents()
             includes = include_re.findall(contents)
-            return includes
+            return env.File(includes)
 
         kscan = Scanner(function = kfile_scan,
                         skeys = ['.k'])
diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml
index 2aba7d2..7862265 100644
--- a/doc/user/scanners.xml
+++ b/doc/user/scanners.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -171,9 +171,20 @@ over the file scanning rather than being called for each input line:
       
       def kfile_scan(node, env, path, arg):
           contents = node.get_text_contents()
-          return include_re.findall(contents)
+          return env.File(include_re.findall(contents))
     </programlisting>
 
+    <para>
+    
+      It is important to note that you
+      have to return a list of File nodes from the scanner function, simple
+      strings for the file names won't do. As in the examples we are showing here,
+      you can use the &File;
+      function of your current Environment in order to create nodes on the fly from
+      a sequence of file names with relative paths.
+      
+    </para>
+
     <para>
 
       The scanner function must
@@ -282,7 +293,7 @@ over the file scanning rather than being called for each input line:
         def kfile_scan(node, env, path):
             contents = node.get_text_contents()
             includes = include_re.findall(contents)
-            return includes
+            return env.File(includes)
 
         kscan = Scanner(function = kfile_scan,
                         skeys = ['.k'])
diff --git a/doc/user/sconf.in b/doc/user/sconf.in
index 94a455e..52fe132 100644
--- a/doc/user/sconf.in
+++ b/doc/user/sconf.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -31,7 +31,7 @@
   figuring out what libraries or header files
   are available on the local system.
   This section describes how to use
-  this &SCons feature.
+  this &SCons; feature.
 
   </para>
 
@@ -446,7 +446,7 @@
     when removing targets doesn't hurt anything,
     it's usually unnecessary.
     You can avoid this by using the
-    &GetOption(); method to
+    &GetOption; method to
     check whether the <option>-c</option> (clean)
     option has been invoked on the command line:
 
diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml
index 35f4367..460c3d1 100644
--- a/doc/user/sconf.xml
+++ b/doc/user/sconf.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -446,7 +446,7 @@
     when removing targets doesn't hurt anything,
     it's usually unnecessary.
     You can avoid this by using the
-    &GetOption;(); method to
+    &GetOption; method to
     check whether the <option>-c</option> (clean)
     option has been invoked on the command line:
 
diff --git a/doc/user/separate.in b/doc/user/separate.in
index 8c08cbe..932c285 100644
--- a/doc/user/separate.in
+++ b/doc/user/separate.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 2c6f97b..7df53e9 100644
--- a/doc/user/separate.xml
+++ b/doc/user/separate.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/sideeffect.in
index 3356d6c..852f99a 100644
--- a/doc/user/sideeffect.in
+++ b/doc/user/sideeffect.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 f6055f3..35e026f 100644
--- a/doc/user/sideeffect.xml
+++ b/doc/user/sideeffect.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/simple.in
index b4802f8..0d15f12 100644
--- a/doc/user/simple.in
+++ b/doc/user/simple.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -297,7 +297,7 @@
 
  </section>
 
- <section>
+ <section id="sect-sconstruct-file">
  <title>The &SConstruct; File</title>
 
    <para>
@@ -353,14 +353,14 @@
 
    </section>
 
-   <section>
+   <section id="sect-order-independent">
    <title>&SCons; Functions Are Order-Independent</title>
 
      <para>
 
      One important way in which the &SConstruct;
      file is not exactly like a normal Python script,
-     and is more like a &Makefile,
+     and is more like a &Makefile;,
      is that the order in which
      the &SCons; functions are called in
      the &SConstruct; file
@@ -453,7 +453,7 @@
      <para>
 
      Notice also that &SCons; built the &goodbye; program first,
-     even though the "reading &SConscript" output
+     even though the "reading &SConscript;" output
      shows that we called <literal>Program('hello.c')</literal>
      first in the &SConstruct; file.
 
diff --git a/doc/user/simple.xml b/doc/user/simple.xml
index 54f6b56..49b8805 100644
--- a/doc/user/simple.xml
+++ b/doc/user/simple.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -110,6 +110,7 @@
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
       scons: done building targets.
    </screen>
 
@@ -300,6 +301,7 @@
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
       scons: done building targets.
       C:\><userinput>scons -c</userinput>
       scons: Reading SConscript files ...
@@ -320,7 +322,7 @@
 
  </section>
 
- <section>
+ <section id="sect-sconstruct-file">
  <title>The &SConstruct; File</title>
 
    <para>
@@ -376,7 +378,7 @@
 
    </section>
 
-   <section>
+   <section id="sect-order-independent">
    <title>&SCons; Functions Are Order-Independent</title>
 
      <para>
@@ -507,6 +509,7 @@
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
       scons: done building targets.
    </screen>
 
@@ -536,6 +539,7 @@
       C:\><userinput>scons -Q</userinput>
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
    </screen>
 
    <para>
diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in
index 5a9637e..e4fc5be 100644
--- a/doc/user/sourcecode.in
+++ b/doc/user/sourcecode.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 73c2490..6642d0f 100644
--- a/doc/user/sourcecode.xml
+++ b/doc/user/sourcecode.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/tasks.in
index 8842dcd..aa6a12e 100644
--- a/doc/user/tasks.in
+++ b/doc/user/tasks.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -99,14 +99,14 @@ env.Append(CPPPATH = "#")
 
 ## Header example
 env.Append(BUILDERS =
-   {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET',
+   {'Copy1' : Builder(action = 'cat &lt; $SOURCE > $TARGET',
                       suffix='.h', src_suffix='.bar')})
 env.Copy1('test.bar') # produces test.h from test.bar. 
 env.Program('app','main.cpp') # indirectly depends on test.bar
 
 ## Source file example
 env.Append(BUILDERS =
-  {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET',
+  {'Copy2' : Builder(action = 'cat &lt; $SOURCE > $TARGET',
                      suffix='.cpp', src_suffix='.bar2')})
 foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2. 
 env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2.
diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml
index 2b2eb0b..ada4de5 100644
--- a/doc/user/tasks.xml
+++ b/doc/user/tasks.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/tools.in
index 16228e7..9dd71df 100644
--- a/doc/user/tools.in
+++ b/doc/user/tools.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 16228e7..9dd71df 100644
--- a/doc/user/tools.xml
+++ b/doc/user/tools.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/troubleshoot.in
index 97df351..615d677 100644
--- a/doc/user/troubleshoot.in
+++ b/doc/user/troubleshoot.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -34,7 +34,7 @@
   &SCons; is no different.
   This appendix contains a number of
   different ways in which you can
-  get some additional insight into &SCons' behavior.
+  get some additional insight into &SCons;' behavior.
 
   </para>
 
@@ -410,12 +410,12 @@
 
     <para>
 
-    The <literaL>--tree</literal> option only prints
+    The <literal>--tree</literal> option only prints
     the dependency graph for the specified targets
     (or the default target(s) if none are specified on the command line).
     So if you specify a target like <filename>f2.o</filename>
     on the command line,
-    the <literaL>--tree</literal> option will only
+    the <literal>--tree</literal> option will only
     print the dependency graph for that file:
 
     </para>
@@ -722,7 +722,7 @@
 
     <para>
 
-    For example, the following &SConstruct file:
+    For example, the following &SConstruct; file:
 
     </para>
 
@@ -842,8 +842,47 @@
 
   </section>
 
+  <section>
+
+  <title>Watch &SCons; prepare targets for building: the &debug-prepare; Option</title>
+
+    <para>
+
+    Sometimes SCons doesn't build the target you want
+    and it's difficult to figure out why.  You can use
+    the <literal>--debug=prepare</literal> option
+    to see all the targets &SCons; is considering, whether
+    they are already up-to-date or not. The message is
+    printed before &SCons; decides whether to build the target.
+    </para>
+
+  </section>
+
+  <section>
+
+  <title>Why is a file disappearing?  the --debug=duplicate Option</title>
+
+    <para>
+
+    When using the &Duplicate; option to create variant dirs,
+    sometimes you may find files not getting copied to where you
+    expect (or not at all), or files mysteriously disappearing.  These
+    are usually because of a misconfiguration of some kind in the
+    SConstruct/SConscript, but they can be tricky to debug.  The
+    --debug=duplicate option shows each time a variant file is
+    unlinked and relinked from its source (or copied, depending on
+    settings), and also shows a message for removing "stale"
+    variant-dir files that no longer have a corresponding source file.
+    It also prints a line for each target that's removed just before
+    building, since that can also be mistaken for the same thing.
+
+    </para>
+
+  </section>
+
   <!--
 
+
   <section>
 
   <title>Where Are My Build Bottlenecks?  the &profile; Option</title>
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml
index 468af92..1f32a35 100644
--- a/doc/user/troubleshoot.xml
+++ b/doc/user/troubleshoot.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -282,7 +282,8 @@
                          '.mm',
                          '.S',
                          '.spp',
-                         '.SPP'],
+                         '.SPP',
+                         '.sx'],
         'DSUFFIXES': ['.d'],
         'Dir': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&gt;,
         'Dirs': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&gt;,
@@ -345,7 +346,7 @@
         'CC': 'cl',
         'CCCOM': &lt;SCons.Action.FunctionAction object at 0x700000&gt;,
         'CCFLAGS': ['/nologo'],
-        'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'],
+        'CCPCHFLAGS': ['${(PCH and "/Yu%s \\"/Fp%s\\""%(PCHSTOP or "",File(PCH))) or ""}'],
         'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'],
         'CFILESUFFIX': '.c',
         'CFLAGS': [],
@@ -371,9 +372,10 @@
                          '.mm',
                          '.S',
                          '.spp',
-                         '.SPP'],
+                         '.SPP',
+                         '.sx'],
         'CXX': '$CC',
-        'CXXCOM': '$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM',
+        'CXXCOM': '${TEMPFILE("$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM")}',
         'CXXFILESUFFIX': '.cc',
         'CXXFLAGS': ['$(', '/TP', '$)'],
         'DSUFFIXES': ['.d'],
@@ -415,7 +417,7 @@
         'SHCCFLAGS': ['$CCFLAGS'],
         'SHCFLAGS': ['$CFLAGS'],
         'SHCXX': '$CXX',
-        'SHCXXCOM': '$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM',
+        'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM")}',
         'SHCXXFLAGS': ['$CXXFLAGS'],
         'SHELL': None,
         'SHLIBPREFIX': '',
@@ -1120,9 +1122,9 @@
       scons: internal stack trace:
         File "bootstrap/src/engine/SCons/Job.py", line 199, in start
           task.prepare()
-        File "bootstrap/src/engine/SCons/Script/Main.py", line 167, in prepare
+        File "bootstrap/src/engine/SCons/Script/Main.py", line 168, in prepare
           return SCons.Taskmaster.OutOfDateTask.prepare(self)
-        File "bootstrap/src/engine/SCons/Taskmaster.py", line 187, in prepare
+        File "bootstrap/src/engine/SCons/Taskmaster.py", line 189, in prepare
           executor.prepare()
         File "bootstrap/src/engine/SCons/Executor.py", line 392, in prepare
           raise SCons.Errors.StopError(msg % (s, self.batches[0].targets[0]))
@@ -1260,8 +1262,47 @@
 
   </section>
 
+  <section>
+
+  <title>Watch &SCons; prepare targets for building: the &debug-prepare; Option</title>
+
+    <para>
+
+    Sometimes SCons doesn't build the target you want
+    and it's difficult to figure out why.  You can use
+    the <literal>--debug=prepare</literal> option
+    to see all the targets &SCons; is considering, whether
+    they are already up-to-date or not. The message is
+    printed before &SCons; decides whether to build the target.
+    </para>
+
+  </section>
+
+  <section>
+
+  <title>Why is a file disappearing?  the --debug=duplicate Option</title>
+
+    <para>
+
+    When using the &Duplicate; option to create variant dirs,
+    sometimes you may find files not getting copied to where you
+    expect (or not at all), or files mysteriously disappearing.  These
+    are usually because of a misconfiguration of some kind in the
+    SConstruct/SConscript, but they can be tricky to debug.  The
+    --debug=duplicate option shows each time a variant file is
+    unlinked and relinked from its source (or copied, depending on
+    settings), and also shows a message for removing "stale"
+    variant-dir files that no longer have a corresponding source file.
+    It also prints a line for each target that's removed just before
+    building, since that can also be mistaken for the same thing.
+
+    </para>
+
+  </section>
+
   <!--
 
+
   <section>
 
   <title>Where Are My Build Bottlenecks?  the &profile; Option</title>
diff --git a/doc/user/variables.in b/doc/user/variables.in
index bf8be1b..9b8afc1 100644
--- a/doc/user/variables.in
+++ b/doc/user/variables.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 bf8be1b..9b8afc1 100644
--- a/doc/user/variables.xml
+++ b/doc/user/variables.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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.in b/doc/user/variants.in
index d94e3f3..5050306 100644
--- a/doc/user/variants.in
+++ b/doc/user/variants.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 bca84c8..e096eed 100644
--- a/doc/user/variants.xml
+++ b/doc/user/variants.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -114,6 +114,7 @@ is pretty smart about rebuilding things when you change options.
     lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj
     Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib"
     link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj
+    embedManifestExeCheck(target, source, env)
     Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe"
   </screen>
 
-- 
cgit v1.2.3