Commits

Steven Knight  committed c871046

Merged revisions 3057-3059,3061-3264 via svnmerge from
http://scons.tigris.org/svn/scons/branches/core

........
r3061 | stevenknight | 2008-06-10 10:06:24 -0700 (Tue, 10 Jun 2008) | 3 lines

Issue 2085: Fix man page indentation under Debian systems.
Also add escape characters to the beginnings of some necessary lines.
........
r3063 | GregNoel | 2008-06-10 17:50:28 -0700 (Tue, 10 Jun 2008) | 1 line

Add David as a member; parametize input file
........
r3064 | stevenknight | 2008-06-11 07:22:23 -0700 (Wed, 11 Jun 2008) | 3 lines

Issue 1973: Clarify the man page description of the SConscript(src_dir)
argument.
........
r3065 | stevenknight | 2008-06-11 11:25:00 -0700 (Wed, 11 Jun 2008) | 3 lines

Issues 1974, 1999: document {Add,Get,Set}Option(). Reorganize the
section a little bit, other minor edits.
........
r3066 | garyo | 2008-06-12 19:53:51 -0700 (Thu, 12 Jun 2008) | 1 line

Document GetBuildFailures in Users Guide. Closes issue #1989.
........
r3067 | stevenknight | 2008-06-14 06:42:07 -0700 (Sat, 14 Jun 2008) | 2 lines

Fix build errors from undefined &GetBuildFailures; entity in doc.
........
r3073 | garyo | 2008-06-14 18:40:20 -0700 (Sat, 14 Jun 2008) | 1 line

Fix issue #1538 (Handling of string argument in Action.Action). Includes test.
........
r3074 | garyo | 2008-06-14 19:11:30 -0700 (Sat, 14 Jun 2008) | 1 line

doc: Trivial man page typo fix.
........
r3075 | stevenknight | 2008-06-15 14:35:13 -0700 (Sun, 15 Jun 2008) | 3 lines

Add a test to make sure the env.RCS() applied to an individual file works
correctly when the checked-out copy is changed.
........
r3076 | stevenknight | 2008-06-15 23:07:17 -0700 (Sun, 15 Jun 2008) | 2 lines

Issue 2025: User's Guide updates from Randall Spangler's review.
........
r3078 | stevenknight | 2008-06-16 06:26:13 -0700 (Mon, 16 Jun 2008) | 2 lines

Issue 1990: Document the Requires() function in the Users's Guide.
........
r3082 | stevenknight | 2008-06-16 19:31:00 -0700 (Mon, 16 Jun 2008) | 3 lines

Fix the second example in the AddMethod() chapter. Show the Windows
output generating a resource file. Other copyedits.
........
r3083 | stevenknight | 2008-06-17 06:44:02 -0700 (Tue, 17 Jun 2008) | 2 lines

Fix misspelled entity: &Builders; => &Builder;s.
........
r3084 | stevenknight | 2008-06-17 08:30:13 -0700 (Tue, 17 Jun 2008) | 3 lines

Issue 1588: - Document suggested use of the Viual C/C++ /FC option to fix
the ability to double-click on file names in compilation error messages.
........
r3085 | stevenknight | 2008-06-17 08:50:33 -0700 (Tue, 17 Jun 2008) | 3 lines

Issue 1687: Document the need to use Clean() for any SideEffect()
files that must be explicitly removed when their targets are removed.
........
r3086 | stevenknight | 2008-06-17 10:59:28 -0700 (Tue, 17 Jun 2008) | 2 lines

Typo fix in the new SideEffect() paragraph. (Gary Oberbrunner)
........
r3088 | cournape | 2008-06-17 19:55:27 -0700 (Tue, 17 Jun 2008) | 3 lines

Initialized merge tracking via "svnmerge" with revisions "1-3087" from
http://scons.tigris.org/svn/scons/branches/vs_revamp
........
r3094 | stevenknight | 2008-06-19 09:52:16 -0700 (Thu, 19 Jun 2008) | 3 lines

Change the User's Guide to use the new Variables object and its
associated function for controlling command-line build variables.
........
r3115 | stevenknight | 2008-06-25 06:46:36 -0700 (Wed, 25 Jun 2008) | 2 lines

Issue 2072: end indentation after generated Builder text.
........
r3116 | stevenknight | 2008-06-25 19:07:15 -0700 (Wed, 25 Jun 2008) | 2 lines

Reorganize the command-line arguments chapter.
........
r3117 | stevenknight | 2008-06-25 19:13:58 -0700 (Wed, 25 Jun 2008) | 2 lines

Editing pass for formatting in the Glob() sections.
........
r3118 | stevenknight | 2008-06-25 19:23:09 -0700 (Wed, 25 Jun 2008) | 3 lines

Wording changing: Preventing => Controlling, because the chapter
also talks about how to clean additional targets.
........
r3119 | stevenknight | 2008-06-25 19:50:41 -0700 (Wed, 25 Jun 2008) | 2 lines

Fix missing </literal> tags, minor wording fix.
........
r3120 | stevenknight | 2008-06-25 19:58:34 -0700 (Wed, 25 Jun 2008) | 2 lines

Add "the Default Function" to the appropriate subsection title.
........
r3121 | stevenknight | 2008-06-26 08:33:43 -0700 (Thu, 26 Jun 2008) | 2 lines

Issue 1988: Document the Variables.UnknownVariables() method.
........
r3122 | stevenknight | 2008-06-26 08:35:51 -0700 (Thu, 26 Jun 2008) | 3 lines

Remove comments listing some of the variables that have been
documented recently.
........
r3123 | stevenknight | 2008-06-26 12:42:53 -0700 (Thu, 26 Jun 2008) | 2 lines

Issue 2118: Fix incorrectly swapped man page text. (Alexey Zezukin)
........
r3124 | bdbaddog | 2008-06-26 21:23:46 -0700 (Thu, 26 Jun 2008) | 2 lines

Fix bug 2108 - duplicate text in description of interactive mode
........
r3125 | stevenknight | 2008-06-27 21:54:56 -0700 (Fri, 27 Jun 2008) | 3 lines

Issue 1993: Document the $*COMSTR variables, the Progress() function,
and create a common "Controlling Build Output" chapter.
........
r3126 | garyo | 2008-06-28 05:46:44 -0700 (Sat, 28 Jun 2008) | 1 line

Fix issue 2105; temporarily omit doc saying that SetOption can override user-created Options (until that is implemented).
........
r3127 | stevenknight | 2008-06-28 07:29:18 -0700 (Sat, 28 Jun 2008) | 2 lines

Issue 1747: Explicitly document use of Node lists as input to Depends().
........
r3128 | stevenknight | 2008-06-28 07:48:32 -0700 (Sat, 28 Jun 2008) | 6 lines

White space change: indent the construction environment sections
further to make way for combining this chapter with others to make
one big "Controlling Environments" chapter.
Also, get rid of some now-unnecessary doc from the old Cons classic
POD, that was taking up space here waiting to be documented.
........
r3129 | cournape | 2008-06-29 01:56:30 -0700 (Sun, 29 Jun 2008) | 3 lines

Initialized merge tracking via "svnmerge" with revisions "1-3128" from
http://scons.tigris.org/svn/scons/branches/trygrep
........
r3143 | stevenknight | 2008-07-02 10:29:39 -0700 (Wed, 02 Jul 2008) | 3 lines

Initialized merge tracking via "svnmerge" with revisions "1-3142" from
http://scons.tigris.org/svn/scons/branches/sgk_lookup
........
r3181 | stevenknight | 2008-07-08 07:17:27 -0700 (Tue, 08 Jul 2008) | 4 lines

Reorganize the discussion of different environments into one chapter.
Document the SetDefault(), PrependUnique(), AppendUnique(),
PrependENVPath() and AppendENVPath() functions.
........
r3182 | stevenknight | 2008-07-08 08:47:55 -0700 (Tue, 08 Jul 2008) | 2 lines

Issue 1998: Docment the ARGLIST variable in the User's Guide.
........
r3194 | GregNoel | 2008-07-09 23:16:51 -0700 (Wed, 09 Jul 2008) | 1 line

remove unnecessary trailing spaces on lines
........
r3204 | stevenknight | 2008-07-11 08:29:18 -0700 (Fri, 11 Jul 2008) | 2 lines

Issue 1853: Remove referenc to SCons.Util.CLVar from a doc example.
........
r3206 | GregNoel | 2008-07-12 02:08:19 -0700 (Sat, 12 Jul 2008) | 1 line

Another go at describing VariantDir()
........
r3213 | stevenknight | 2008-07-13 08:57:57 -0700 (Sun, 13 Jul 2008) | 3 lines

Set /branches/comments in svnmerge-integrated property to allow
merging changes in both directions.
........
r3217 | stevenknight | 2008-07-16 06:52:44 -0700 (Wed, 16 Jul 2008) | 2 lines

Update the copyright year in the User's Guide.
........
r3218 | stevenknight | 2008-07-16 07:08:52 -0700 (Wed, 16 Jul 2008) | 3 lines

Issue 1881: Add man page text clarifying the behavior of
Add{Pre,Post}Action() when multiple targets are specified.
........
r3223 | stevenknight | 2008-07-18 08:18:45 -0700 (Fri, 18 Jul 2008) | 3 lines

Initialized merge tracking via "svnmerge" with revisions "1-3222" from
http://scons.tigris.org/svn/scons/branches/sgk_subst
........
r3231 | stevenknight | 2008-07-22 01:58:11 -0700 (Tue, 22 Jul 2008) | 4 lines

Enhance MSVSProject() tests so they're runnable on any system, regardless
of whether Visual Studio is installed, or if it's even a Windows system
at all.
........
r3237 | GregNoel | 2008-07-26 00:07:49 -0700 (Sat, 26 Jul 2008) | 1 line

Issue 1983: Document ParseConfig, MergeFlags, and ParseFlags for the Users' Guide
........
r3238 | stevenknight | 2008-07-26 08:38:18 -0700 (Sat, 26 Jul 2008) | 3 lines

Follow-ons for building the User's Guide with Greg's recent additions
for MergeFlags() and ParseFlags().
........
r3239 | stevenknight | 2008-07-26 09:52:40 -0700 (Sat, 26 Jul 2008) | 3 lines

Re-arrange some sections talking about creating construction environments
and fetching/expanding variables.
........
r3240 | stevenknight | 2008-07-26 12:16:11 -0700 (Sat, 26 Jul 2008) | 2 lines

Stylistic editing of new {Merge,Parse}{Config,Flags} sections.
........
r3241 | GregNoel | 2008-07-26 12:42:42 -0700 (Sat, 26 Jul 2008) | 1 line

Issue 1987: Document SideEffect for Users' Guide (incomplete)
........
r3242 | stevenknight | 2008-07-26 13:27:56 -0700 (Sat, 26 Jul 2008) | 2 lines

Correct dumb XML mistakes in my last checkin.
........
r3243 | stevenknight | 2008-07-26 13:34:05 -0700 (Sat, 26 Jul 2008) | 2 lines

One-character typo. Gah.
........
r3244 | stevenknight | 2008-07-26 13:44:14 -0700 (Sat, 26 Jul 2008) | 2 lines

Issue 1977,1980: document the Exit() and Flatten() functions.
........
r3245 | stevenknight | 2008-07-27 10:24:12 -0700 (Sun, 27 Jul 2008) | 14 lines

Updates to the new SideEffect section (kudos to Greg).

While working on this, Greg discovered a bug (issue #2154) that prevents
a SideEffect() file from being used as input to another builder call; it
makes the builder target not get build when run in paralle (e.g. -j2)...
:-( So this patch comments out that section of Greg's section.

This also contains my usual editing pass. In this case I changed some
of the examples and added a bunch of text to try to help clarify some
things that seemed important. I also added a closing paragraph warning
that SideEffect() really shouldn't be used as an alternative to specifying
multiple target files in a Builder call when a command builds more than
one file that you care about.
........
r3246 | stevenknight | 2008-07-27 10:31:17 -0700 (Sun, 27 Jul 2008) | 2 lines

Proofreading edits of the MergeFlags() section. (Greg Noel)
........
r3247 | stevenknight | 2008-07-27 11:17:27 -0700 (Sun, 27 Jul 2008) | 2 lines

Issue 1976: document ensure{Python,SCons}Version() in the User's Guide.
........
r3249 | GregNoel | 2008-07-28 15:57:00 -0700 (Mon, 28 Jul 2008) | 1 line

Add svn-bisect script
........

  • Participants
  • Parent commits b9b3cbe

Comments (0)

Files changed (56)

File bin/sconsoutput.py

                  ('jar', 'JARCOM', JarCom, []),
                  ('rmic', 'RMICCOM', Cat, []),
                 ],
-    'win32' :   [('msvc', ['CCCOM', 'SHCCCOM'], CCCom, ['CCFLAGS', 'CPPDEFINES', 'COLOR', 'COLORS', 'PACKAGE']),
+    'win32' :   [('msvc', ['CCCOM', 'SHCCCOM', 'RCCOM'], CCCom, ['CCFLAGS', 'CPPDEFINES', 'COLOR', 'COLORS', 'PACKAGE']),
                  ('mslink', ['LINKCOM', 'SHLINKCOM'], Cat, []),
                  ('mslib', 'ARCOM', Cat, []),
                  ('tar', 'TARCOM', Null, []),

File bin/svn-bisect.py

+#!/usr/bin/env python
+# -*- Python -*-
+
+import sys
+from math import log, ceil
+from optparse import OptionParser
+import subprocess
+
+# crack the command line
+parser = OptionParser(
+             usage="%prog lower-revision upper-revision test_script [arg1 ...]",
+             description="Binary search for a bug in a SVN checkout")
+(options,script_args) = parser.parse_args()
+
+# make sure we have sufficient parameters
+if len(script_args) < 1:
+    parser.error("Need a lower revision")
+elif len(script_args) < 2:
+    parser.error("Need an upper revision")
+elif len(script_args) < 3:
+    parser.error("Need a script to run")
+
+# extract our starting values
+lower = int(script_args[0])
+upper = int(script_args[1])
+script = script_args[2:]
+
+# print an error message and quit
+def error(s):
+    print >>sys.stderr, "******", s, "******"
+    sys.exit(1)    
+
+# update to the specified version and run test
+def testfail(revision):
+    "Return true if test fails"
+    print "Updating to revision", revision
+    if subprocess.call(["svn","up","-qr",str(revision)]) != 0:
+        m = "SVN did not update properly to revision %d"
+        raise RuntimeError(m % revision)
+    return subprocess.call(script,shell=False) != 0
+
+# confirm that the endpoints are different
+print "****** Checking upper bracket", upper
+upperfails = testfail(upper)
+print "****** Checking lower bracket", lower
+lowerfails = testfail(lower)
+if upperfails == lowerfails:
+    error("Upper and lower revisions must bracket the failure")
+
+# binary search for transition
+msg = "****** max %d revisions to test (bug bracketed by [%d,%d])"
+while upper-lower > 1:
+    print msg % (ceil(log(upper-lower,2)), lower, upper)
+
+    mid = int((lower + upper)/2)
+    midfails = testfail(mid)
+    if midfails == lowerfails:
+        lower = mid
+        lowerfails = midfails
+    else:
+        upper = mid
+        upperfails = midfails
+
+# show which revision was first to fail
+if upperfails != lowerfails: lower = upper
+print "The error was caused by revision", lower

File bin/xmlagenda.py

 # 'issues.xml'.  Run this script to translate 'issues.xml' into a CSV
 # file named 'editlist.csv'.  Upload the CSV into a Google spreadsheet.
 
-# In the spreadsheet, select the last column and delete it (added by the
-# upload to allow for expansion; we don't need it).
+# In the spreadsheet, select the last column and pick "delete-->column" (it
+# was added by the upload to allow for expansion and we don't need it).
 # Select all the columns and pick "align-->top"
 # Select the ID and votes columns and pick "align-->right"
 # Select the priority column and pick "align-->center"
 
 # The team members
 # FIXME: These names really should be external to this script
-team = 'Bill Greg Steven Gary Ken Brandon Sohail Jim'.split()
+team = 'Bill Greg Steven Gary Ken Brandon Sohail Jim David'.split()
 team.sort()
 
 # The elements to be picked out of the issue
 	return v.nodeValue
 
 # Parse the XML issues file and produce a DOM for it
-# FIXME: parameterize the input file name
+import sys
+if len(sys.argv) > 1: xml = sys.argv[1]
+else: xml = 'issues.xml'
 from xml.dom.minidom import parse
-xml = parse('issues.xml')
+xml = parse(xml)
 
 # Go through the issues in the DOM, pick out the elements we want,
 # and put them in our list of issues.

File doc/man/scons.1

 .\"
 .\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
 .\"
+.TH SCONS 1 "__MONTH_YEAR__"
 .\" ES - Example Start - indents and turns off line fill
+.rm ES
 .de ES
 .RS
 .nf
 ..
 .\" EE - Example End - ends indent and turns line fill back on
+.rm EE
 .de EE
 .fi
 .RE
 ..
-.TH SCONS 1 "__MONTH_YEAR__"
 .SH NAME
 scons \- a software construction tool
 .SH SYNOPSIS
 ]
 .SH DESCRIPTION
 
-The 
-.B scons 
+The
+.B scons
 utility builds software (or other files) by determining which
 component pieces must be rebuilt and executing the necessary commands to
 rebuild them.
 
-By default, 
-.B scons 
-searches for a file named 
+By default,
+.B scons
+searches for a file named
 .IR SConstruct ,
 .IR Sconstruct ,
 or
 (in that order) in the current directory and reads its
 configuration from the first file found.
 An alternate file name may be
-specified via the 
+specified via the
 .B -f
 option.
 
 can scan known input files automatically for dependency
 information (for example, #include statements
 in C or C++ files) and will rebuild dependent files appropriately
-whenever any "included" input file changes. 
+whenever any "included" input file changes.
 .B scons
 supports the
 ability to define new scanners for unknown input file types.
 (along with any derived files on which they depend).
 
 Specifying "cleanup" targets in SConscript files is not usually necessary.
-The 
+The
 .B -c
 flag removes all files
 necessary to build the specified target:
 function.
 
 A subset of a hierarchical tree may be built by
-remaining at the top-level directory (where the 
+remaining at the top-level directory (where the
 .I SConstruct
 file lives) and specifying the subdirectory as the target to be
 built:
 or by changing directory and invoking scons with the
 .B -u
 option, which traverses up the directory
-hierarchy until it finds the 
+hierarchy until it finds the
 .I SConstruct
 file, and then builds
 targets relatively to the current subdirectory:
 .B scons
 can maintain a cache of target (derived) files that can
 be shared between multiple builds.  When caching is enabled in a
-SConscript file, any target files built by 
+SConscript file, any target files built by
 .B scons
 will be copied
 to the cache.  If an up-to-date target file is found in the cache, it
 will be retrieved from the cache instead of being rebuilt locally.
 Caching behavior may be disabled and controlled in other ways by the
-.BR --cache-force , 
+.BR --cache-force ,
 .BR --cache-disable ,
 and
 .B --cache-show
 and the PharLap ETS compiler.
 On OS/2 systems,
 .B scons
-searches in order for the 
+searches in order for the
 OS/2 compiler,
 the GCC tool chain,
 and the Microsoft Visual C++ tools,
 Environment construction variables.
 
 .SH OPTIONS
-In general, 
-.B scons 
+In general,
+.B scons
 supports the same command-line options as GNU
-.BR make , 
-and many of those supported by 
+.BR make ,
+and many of those supported by
 .BR cons .
 
 .TP
 and a necessary test does not
 yet have any results in the cache.
 
-.TP 
+.TP
 .RI "-C" " directory" ",  --directory=" directory
-Change to the specified 
+Change to the specified
 .I directory
-before searching for the 
+before searching for the
 .IR SConstruct ,
 .IR Sconstruct ,
 or
 .I sconstruct
 file, or doing anything
-else.  Multiple 
+else.  Multiple
 .B -C
 options are interpreted
 relative to the previous one, and the right-most
 .B -C
 option wins. (This option is nearly
-equivalent to 
+equivalent to
 .BR "-f directory/SConstruct" ,
 except that it will search for
 .IR SConstruct ,
-.IR Sconstruct , 
+.IR Sconstruct ,
 or
 .I sconstruct
 in the specified directory.)
 
 .TP
 --debug=includes
-Print the include tree after each top-level target is built. 
+Print the include tree after each top-level target is built.
 This is generally used to find out what files are included by the sources
 of a given derived file:
 
 $ scons --debug=presub
 Building myprog.o with action(s):
   $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
-...
+\&...
 .EE
 
 .TP
 .TP
 .RI --duplicate= ORDER
 There are three ways to duplicate files in a build tree: hard links,
-soft (symbolic) links and copies. The default behaviour of SCons is to 
+soft (symbolic) links and copies. The default behaviour of SCons is to
 prefer hard links to soft links to copies. You can specify different
 behaviours with this option.
-.IR ORDER 
-must be one of 
+.IR ORDER
+must be one of
 .IR hard-soft-copy
 (the default),
 .IR soft-hard-copy ,
 
 .TP
 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
-Use 
-.I file 
+Use
+.I file
 as the initial SConscript file.
 
-.TP 
+.TP
 -h, --help
 Print a local help message for this build, if one is defined in
-the SConscript file(s), plus a line that describes the 
+the SConscript file(s), plus a line that describes the
 .B -H
 option for command-line option help.  If no local help message
 is defined, prints the standard help message about command-line
 -i, --ignore-errors
 Ignore all errors from commands executed to rebuild files.
 
-.TP 
+.TP
 .RI -I " directory" ", --include-dir=" directory
-Specifies a 
+Specifies a
 .I directory
 to search for
-imported Python modules.  If several 
+imported Python modules.  If several
 .B -I
 options
 are used, the directories are searched in the order specified.
 --implicit-deps-unchanged
 Force SCons to ignore changes in the implicit dependencies.
 This causes cached implicit dependencies to always be used.
-This implies 
+This implies
 .BR --implicit-cache .
 
 .TP
 -n, --no-exec, --just-print, --dry-run, --recon
 -Q
 -s, --silent, --quiet
--s, --silent, --quiet
 --taskmastertrace=FILE
 --tree=OPTIONS
 .EE
 .TP
 .RI -j " N" ", --jobs=" N
 Specifies the number of jobs (commands) to run simultaneously.
-If there is more than one 
-.B -j 
+If there is more than one
+.B -j
 option, the last one is effective.
-.\" ??? If the 
-.\" .B -j 
+.\" ??? If the
+.\" .B -j
 .\" option
 .\" is specified without an argument,
-.\" .B scons 
+.\" .B scons
 .\" will not limit the number of
 .\" simultaneous jobs.
 
 .\" .RI  -l " N" ", --load-average=" N ", --max-load=" N
 .\" No new jobs (commands) will be started if
 .\" there are other jobs running and the system load
-.\" average is at least 
+.\" average is at least
 .\" .I N
 .\" (a floating-point number).
 
 
 .TP
 .RI --max-drift= SECONDS
-Set the maximum expected drift in the modification time of files to 
+Set the maximum expected drift in the modification time of files to
 .IR SECONDS .
 This value determines how long a file must be unmodified
 before its cached content signature
 No execute.  Print the commands that would be executed to build
 any out-of-date target files, but do not execute the commands.
 
-.TP 
+.TP
 .RI --no-site-dir
 Prevents the automatic addition of the standard
 .I site_scons
 
 .\" .TP
 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
-.\" Do not rebuild 
+.\" Do not rebuild
 .\" .IR file ,
 .\" and do
 .\" not rebuild anything due to changes in the contents of
 .\" .IR file .
-.\" .TP 
+.\" .TP
 .\" .RI --override " file"
 .\" Read values to override specific build environment variables
-.\" from the specified 
+.\" from the specified
 .\" .IR file .
 .\" .TP
 .\" -p
 .\" After printing, a normal build is performed
 .\" as usual, as specified by other command-line options.
 .\" This also prints version information
-.\" printed by the 
+.\" printed by the
 .\" .B -v
 .\" option.
 .\"
 
 .TP
 -S, --no-keep-going, --stop
-Ignored for compatibility with GNU 
+Ignored for compatibility with GNU
 .BR make .
 
-.TP 
+.TP
 .RI --site-dir= dir
 Uses the named dir as the site dir rather than the default
 .I site_scons
 .TP
 .RI --stack-size= KILOBYTES
 Set the size stack used to run threads to
-.IR KILOBYTES . 
+.IR KILOBYTES .
 This value determines the stack size of the threads used to run jobs.
 These are the threads that execute the actions of the builders for the
 nodes that are out-of-date.
 .TP
 -t, --touch
 Ignored for compatibility with GNU
-.BR make .  
+.BR make .
 (Touching a file to make it
-appear up-to-date is unnecessary when using 
+appear up-to-date is unnecessary when using
 .BR scons .)
 
 .TP
 
 .TP
 -u, --up, --search-up
-Walks up the directory structure until an 
+Walks up the directory structure until an
 .I SConstruct ,
 .I Sconstruct
-or 
+or
 .I sconstruct
 file is found, and uses that
 as the top of the directory tree.
 
 .TP
 -v, --version
-Print the 
+Print the
 .B scons
 version, copyright information,
 list of authors, and any other relevant information.
 
 .TP
 --warn=duplicate-environment, --warn=no-duplicate-environment
-Enables or disables warnings about missing SConscript files.
+Enables or disables warnings about attempts to specify a build
+of a target with two different construction environments
+that use the same action.
+These warnings are enabled by default.
 
 .TP
 --warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
 
 .TP
 --warn=missing-sconscript, --warn=no-missing-sconscript
-Enables or disables warnings about attempts to specify a build
-of a target with two different construction environments
-that use the same action.
+Enables or disables warnings about missing SConscript files.
 These warnings are enabled by default.
 
 .TP
 .\"
 .\" .TP
 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
-.\" Pretend that the target 
-.\" .I file 
+.\" Pretend that the target
+.\" .I file
 .\" has been
-.\" modified.  When used with the 
+.\" modified.  When used with the
 .\" .B -n
 .\" option, this
 .\" show you what would be rebuilt if you were to modify that file.
-.\" Without 
+.\" Without
 .\" .B -n
 .\" ... what? XXX
 .\"
 .\" --warn-undefined-variables
 .\" Warn when an undefined variable is referenced.
 
-.TP 
+.TP
 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
 Search the specified repository for any input and target
 files not found in the local directory hierarchy.  Multiple
 .\" XXX Adding this in the future would be a help.
 .SS Construction Environments
 A construction environment is the basic means by which the SConscript
-files communicate build information to 
+files communicate build information to
 .BR scons .
-A new construction environment is created using the 
-.B Environment 
+A new construction environment is created using the
+.B Environment
 function:
 
 .ES
 .I construction
 .IR variables ,
 may be set in a construction environment
-either by specifyng them as keywords when the object is created
+either by specifying them as keywords when the object is created
 or by assigning them a value after the object is created:
 
 .ES
 This is so that any executed commands
 that use sockets to connect with other systems
 (such as fetching source files from
-external CVS repository specifications like 
+external CVS repository specifications like
 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
 will work on Windows systems.
 
 (that is, do not begin with
 .B /
 on POSIX systems
-or 
+or
 .B \\
 on Windows systems,
 with or without
 executable program
 .B bar
 (on POSIX systems)
-or 
+or
 .B bar.exe
 (on Windows systems)
 from the bar.c source file:
 '\" END GENERATED BUILDER DESCRIPTIONS
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
+.P
 All
 targets of builder methods automatically depend on their sources.
 An explicit dependency can
-be specified using the 
-.B Depends 
+be specified using the
+.B Depends
 method of a construction environment (see below).
 
 In addition,
 Except where otherwise noted,
 the same-named
 construction environment method
-and global function 
+and global function
 provide the exact same functionality.
 The only difference is that,
 where appropriate,
 include:
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI Action( action ", [" strfunction ", " varlist ])
 .TP
 .RI env.Action( action ", [" strfunction ", " varlist ])
 See the section "Action Objects,"
 below, for a complete explanation of the arguments and behavior.
 
-Note that the 
+Note that the
 .BR env.Action ()
 form of the invocation will expand
 construction variables in any arguments strings,
 until the Action object is actually used.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI AddMethod( object, function ", [" name ])
 .TP
 .RI env.AddMethod( function ", [" name ])
 to indicate that the specified long option(s) take(s) an
 .I optional
 argument.
-When 
+When
 .B "nargs = '?'"
 is passed to the
 .BR AddOption ()
 .BR GetOption ()
 or
 .BR env.GetOption ().
-The value may also be set, using
-.BR SetOption ()
-or
-.BR env.SetOption (),
-if conditions in a
-.B SConscript
-require overriding any default value.
-Note, however, that a
-value specified on the command line will
-.I always
-override a value set by any SConscript file.
+\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
+\" Uncomment this when that works.  See tigris issue 2105.
+\" The value may also be set, using
+\" .BR SetOption ()
+\" or
+\" .BR env.SetOption (),
+\" if conditions in a
+\" .B SConscript
+\" require overriding any default value.
+\" Note, however, that a
+\" value specified on the command line will
+\" .I always
+\" override a value set by any SConscript file.
 
 Any specified
 .B help=
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI AddPostAction( target ", " action )
 .TP
 .RI env.AddPostAction( target ", " action )
 can be converted into an Action object
 (see below).
 
+When multiple targets are supplied,
+the action may be called multiple times,
+once after each action that generates
+one or more targets in the list.
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI AddPreAction( target ", " action )
 .TP
 .RI env.AddPreAction( target ", " action )
 can be converted into an Action object
 (see below).
 
+When multiple targets are specified,
+the action(s) may be called multiple times,
+once before each action that generates
+one or more targets in the list.
+
+Note that if any of the targets are built in multiple steps,
+the action will be invoked just
+before the "final" action that specifically
+generates the specified target(s).
+For example, when building an executable program
+from a specified source
+.B .c
+file via an intermediate object file:
+
+.ES
+foo = Program('foo.c')
+AddPreAction(foo, 'pre_action')
+.EE
+
+The specified
+.B pre_action
+would be executed before
+.B scons
+calls the link command that actually
+generates the executable program binary
+.BR foo ,
+not before compiling the
+.B foo.c
+file into an object file.
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI Alias( alias ", [" targets ", [" action ]])
 (This will be officially deprecated some day.)
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI Builder( action ", [" arguments ])
-.TP 
+.TP
 .RI env.Builder( action ", [" arguments ])
 Creates a Builder object for
 the specified
 See the section "Builder Objects,"
 below, for a complete explanation of the arguments and behavior.
 
-Note that the 
+Note that the
 .BR env.Builder ()
 form of the invocation will expand
 construction variables in any arguments strings,
 until after the Builder object is actually called.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI CacheDir( cache_dir )
-.TP 
+.TP
 .RI env.CacheDir( cache_dir )
 Specifies that
 .B scons
 predict or prohibitively large.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI Clean( targets ", " files_or_dirs )
-.TP 
+.TP
 .RI env.Clean( targets ", " files_or_dirs )
 This specifies a list of files or directories which should be removed
 whenever the targets are specified with the
 Examples:
 
 The related
-.BR NoClean () 
+.BR NoClean ()
 function overrides calling
 .BR Clean ()
 for the same target,
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI Decider( function )
 .TP
 .RI env.Decider( function )
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI Default( targets )
 .TP
 .RI env.Default( targets )
 .TP
 .RI env.Depends( target ", " dependency )
 Specifies an explicit dependency;
-the target file(s) will be rebuilt
-whenever the dependency file(s) has changed.
+the
+.I target
+will be rebuilt
+whenever the
+.I dependency
+has changed.
+Both the specified
+.I target
+and
+.I dependency
+can be a string
+(usually the path name of a file or directory)
+or Node objects,
+or a list of strings or Node objects
+(such as returned by a Builder call).
 This should only be necessary
 for cases where the dependency
 is not caught by a Scanner
 
 .ES
 env.Depends('foo', 'other-input-file-for-foo')
+
+mylib = env.Library('mylib.c')
+installed_lib = env.Install('lib', mylib)
+bar = env.Program('bar.c')
+
+# Arrange for the library to be copied into the installation
+# directory before trying to build the "bar" program.
+# (Note that this is for example only.  A "real" library
+# dependency would normally be configured through the $LIBS
+# and $LIBPATH variables, not using an env.Depends() call.)
+
+env.Depends(bar, installed_lib)
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .RI env.Dir( name ", [" directory ])
 This returns a Directory Node,
 an object that represents the specified directory
-.IR name . 
+.IR name .
 .I name
-can be a relative or absolute path. 
+can be a relative or absolute path.
 .I directory
-is an optional directory that will be used as the parent directory. 
+is an optional directory that will be used as the parent directory.
 If no
 .I directory
 is specified, the current script's directory is used as the parent.
 
-If 
+If
 .I name
 is a list, SCons returns a list of Dir nodes.
 Construction variables are expanded in
 .IP
 will print:
 .ES
-'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
+\&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
 .EE
 
 .ES
 .RI EnsurePythonVersion( major ", " minor )
 .TP
 .RI env.EnsurePythonVersion( major ", " minor )
-Ensure that the Python version is at least 
-.IR major . minor . 
+Ensure that the Python version is at least
+.IR major . minor .
 This function will
 print out an error message and exit SCons with a non-zero exit code if the
 actual Python version is not late enough.
 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
 .TP
 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
-Ensure that the SCons version is at least 
+Ensure that the SCons version is at least
 .IR major.minor ,
 or
-.IR major.minor.revision . 
+.IR major.minor.revision .
 if
 .I revision
 is specified.
 pairs.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI Execute( action ", [" strfunction ", " varlist ])
 .TP
 .RI env.Execute( action ", [" strfunction ", " varlist ])
 .RI Export( vars )
 .TP
 .RI env.Export( vars )
-This tells 
+This tells
 .B scons
 to export a list of variables from the current
 SConscript file to all other SConscript files.
 The exported variables are kept in a global collection,
 so subsequent calls to
 .BR Export ()
-will over-write previous exports that have the same name. 
+will over-write previous exports that have the same name.
 Multiple variable names can be passed to
 .BR Export ()
 as separate arguments or as a list. A dictionary can be used to map
 function, below.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI File( name ", [" directory ])
-.TP 
+.TP
 .RI env.File( name ", [" directory ])
 This returns a
 File Node,
 an object that represents the specified file
-.IR name . 
+.IR name .
 .I name
-can be a relative or absolute path. 
+can be a relative or absolute path.
 .I directory
-is an optional directory that will be used as the parent directory. 
-
-If 
+is an optional directory that will be used as the parent directory.
+
+If
 .I name
 is a list, SCons returns a list of File nodes.
 Construction variables are expanded in
 .RI FindFile( file ", " dirs )
 .TP
 .RI env.FindFile( file ", " dirs )
-Search for 
-.I file 
-in the path specified by 
+Search for
+.I file
+in the path specified by
 .IR dirs .
 .I file
 may be a list of file names or a single file name. In addition to searching
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI GetBuildFailures()
 Returns a list of exceptions for the
 actions that failed while
 This function provides a way to query the value of
 SCons options set on scons command line
 (or set using the
-.IR SetOption () 
+.IR SetOption ()
 function).
 The options supported are:
 
 .RI Help( text )
 .TP
 .RI env.Help( text )
-This specifies help text to be printed if the 
-.B -h 
+This specifies help text to be printed if the
+.B -h
 argument is given to
 .BR scons .
 If
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI Import( vars )
-.TP 
+.TP
 .RI env.Import( vars )
-This tells 
+This tells
 .B scons
 to import a list of variables into the current SConscript file. This
 will import variables that were exported with
 .BR Export ()
-or in the 
+or in the
 .I exports
-argument to 
+argument to
 .BR SConscript ().
-Variables exported by 
+Variables exported by
 .BR SConscript ()
 have precedence.
-Multiple variable names can be passed to 
+Multiple variable names can be passed to
 .BR Import ()
 as separate arguments or as a list. The variable "*" can be used
 to import all variables.
 not as separate arguments to
 .BR env.MergeFlags ().
 
-By default, 
+By default,
 duplicate values are eliminated;
 you can, however, specify
 .B unique=0
 .RI env.NoCache( target ", ...)"
 Specifies a list of files which should
 .I not
-be cached whenever the 
+be cached whenever the
 .BR CacheDir ()
 method has been activated.
 The specified targets may be a list
 Builder methods.
 
 Calling
-.BR NoClean () 
+.BR NoClean ()
 for a target overrides calling
 .BR Clean ()
 for the same target,
 .BR gtk-config )
 and adds the options
 to the appropriate construction variables.
-By default, 
+By default,
 duplicate values are not
 added to any construction variables;
 you can specify
 Any other strings not associated with options
 are assumed to be the names of libraries
 and added to the
-.B LIBS 
+.B LIBS
 construction variable.
 
 Examples (all of which produce the same result):
 This is so that any executed commands
 that use sockets to connect with other systems
 (such as fetching source files from
-external CVS repository specifications like 
+external CVS repository specifications like
 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
 will work on Windows systems.
 
 .EE
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP 
+.TP
 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-.TP 
+.TP
 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
 Creates a Scanner object for
 the specified
 .RI name= script
 keyword argument.
 
-The optional 
+The optional
 .I exports
 argument provides a list of variable names or a dictionary of
 named values to export to the
 .BR Import ()
 function to import the variables.
 
-In effect, the optional
+If the optional
 .I variant_dir
-argument causes the files (and subdirectories) in the directory where
-.I script
-resides to be copied to
+argument is present, it causes an effect equivalent to
+.BR VariantDir (
+.IR variant_dir ,
+.IR src_dir ,
+.IR duplicate )
+to be executed prior to reading the
+.IR script (s).
+(If
 .I variant_dir
-and the build performed in
-.IR variant_dir .
-Thus, all of the targets (for example, object files and executables)
-that would normally be built in (or underneath) the directory containing
-.I script
-would actually be built in (or underneath)
-.IR variant_dir .
+is not present, the
+.I src_dir
+and
+.I duplicate
+arguments are ignored.)
+The
+.I variant_dir
+and
+.I src_dir
+arguments are interpreted relative to the directory
+of the calling SConscript file.
+If
+.I src_dir
+is not specified, the directory of the calling SConscript file is assumed.
 See the description of the
 .BR VariantDir ()
-function below for the details and restrictions.
-.I variant_dir
-is interpreted relative to the directory
-of the calling SConscript file.
-
-Normally, the source for the variant build is the directory containing
-.IR script .
-If the sources are not in
-.IR script 's
-directory, the optional
-.I src_dir
-argument provides the location of the sources.
-.I src_dir
-is interpreted relative to the directory
-of the calling SConscript file.
-
-By default,
-.B scons
-will link or copy (depending on the platform)
-all the source files into the variant directory tree.
-This behavior may be disabled by setting the optional
-.I duplicate
-argument to 0 (it is set to 1 by default), in which case
-.B scons
-will refer directly to the source files in their source directory
-when building target files.
-See the description for
-.BR VariantDir ()
-below for the details and restrictions.
-
-Any variables returned by 
-.I script 
-using 
+function below for additional details and restrictions.
+
+Any variables returned by
+.I script
+using
 .BR Return ()
 will be returned by the call to
-.BR SConscript (). 
+.BR SConscript ().
 
 Examples:
 
 SConscript('subdir/SConscript')
 foo = SConscript('sub/SConscript', exports='env')
 SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript('src/SConscript', variant_dir='build', duplicate=0)
-SConscript('bld/SConscript', src_dir='src', exports='env variable')
+SConscript('dir/SConscript', exports='env variable')
 SConscript(dirs=['sub1', 'sub2'])
 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
 .EE
 
+.ES
+SConscript('bld/SConscript', variant_dir='bld', duplicate=0)
+.EE
+which is equivalent to
+.ES
+VariantDir('bld', '.', duplicate=0)
+SConscript('bld/SConscript')
+.EE
+'\"TODO: SConscript('bld/SConscript', src_dir='src', exports='env variable')
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI SConscriptChdir( value )
 Declares
 .I side_effect
 as a side effect of building
-.IR target . 
-Both 
-.I side_effect 
+.IR target .
+Both
+.I side_effect
 and
 .I target
 can be a list, a file name, or a node.
-A side effect is a target that is created
+A side effect is a target file that is created or updated
 as a side effect of building other targets.
 For example, a Windows PDB
 file is created as a side effect of building the .obj
-files for a static library.
+files for a static library,
+and various log files are created updated
+as side effects of various TeX commands.
 If a target is a side effect of multiple build commands,
 .B scons
 will ensure that only one set of commands
 for side-effect targets that are built as a result of
 multiple build commands.
 
+Because multiple build commands may update
+the same side effect file,
+by default the
+.I side_effect
+target is
+.I not
+automatically removed
+when the
+.I target
+is removed by the
+.B -c
+option.
+(Note, however, that the
+.I side_effect
+might be removed as part of
+cleaning the directory in which it lives.)
+If you want to make sure the
+.I side_effect
+is cleaned whenever a specific
+.I target
+is cleaned,
+you must specify this explicitly
+with the
+.BR Clean ()
+or
+.BR env.Clean ()
+function.
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI SourceCode( entries ", " builder )
 by setting a new value.
 The optional
 .I built_value
-argument can be specified 
+argument can be specified
 when the Value Node is created
 to indicate the Node should already be considered
 "built."
     # $TARGET.
     f = open(str(target[0]), 'wb')
     f.write('prefix=' + source[0].get_contents())
-    
+
 # Fetch the prefix= argument, if any, from the command
 # line, and use /usr/local as the default.
 prefix = ARGUMENTS.get('prefix', '/usr/local')
 .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
 .TP
 .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
-In effect, the
-.I src_dir
-directory tree is copied to
-.I variant_dir
-so a build can be performed there.
+Use the
+.BR VariantDir ()
+function to create a copy of your sources in another location:
+if a name under
+.IR variant_dir
+is not found but exists under
+.IR src_dir ,
+the file or directory is copied to
+.IR variant_dir .
+Target files can be built in a different directory than the original sources
+by simply refering to the sources (and targets) within the variant tree.
+
 .BR VariantDir ()
 can be called multiple times with the same
 .I  src_dir
 to set up multiple builds with different options
 .RI ( variants ).
+The
 .I src_dir
-must be in or underneath the SConstruct file's directory, and
+location must be in or underneath the SConstruct file's directory, and
 .I variant_dir
-may not be underneath the
-.I src_dir .
+may not be underneath
+.IR src_dir .
+'\"TODO: Can the above restrictions be clarified or relaxed?
+'\"TODO: The latter restriction is clearly not completely right;
+'\"TODO: src_dir = '.' works fine with a build dir under it.
 
 The default behavior is for
 .B scons
-to duplicate the source files in the variant tree
-and then build the derived files within the variant tree.
-This guarantees correct builds regardless of
-whether intermediate source files are generated during the build,
-whether preprocessors or other scanners search for included files
+to physically duplicate the source files in the variant tree.
+Thus, a build performed in the variant tree is guaranteed to be identical
+to a build performed in the source tree even if
+intermediate source files are generated during the build,
+or preprocessors or other scanners search for included files
 relative to the source file,
-or whether individual compilers or other invoked tools are hard-coded
+or individual compilers or other invoked tools are hard-coded
 to put derived files in the same directory as source files.
 
 If possible on the platform,
 files and directories that are not used are not present in
 .IR variant_dir .
 
-Duplicating the source tree may be disabled by setting
+Duplicating the source tree may be disabled by setting the
 .I duplicate
-to 0.
+argument to 0.
 This will cause
 .B scons
 to invoke Builders using the path names of source files in
 However, you would then call the subsidiary SConscript file
 not in the source directory, but in the
 .I variant_dir ,
-regardless of the value of 
+regardless of the value of
 .IR duplicate .
 This is how you tell
 .B scons
-which variant of a source tree to build.
-For example:
-
-.ES
-VariantDir('build-variant1', 'src')
-SConscript('build-variant1/SConscript')
-VariantDir('build-variant2', 'src')
-SConscript('build-variant2/SConscript')
+which variant of a source tree to build:
+
+.ES
+# run src/SConscript in two variant directories
+VariantDir('build/variant1', 'src')
+SConscript('build/variant1/SConscript')
+VariantDir('build/variant2', 'src')
+SConscript('build/variant2/SConscript')
 .EE
 
 .IP
 for another way to specify a variant directory
 in conjunction with calling a subsidiary SConscript file.
 
+Examples:
+
+.ES
+# use names in the build directory, not the source directory
+VariantDir('build', 'src', duplicate=0)
+Program('build/prog', 'build/source.c')
+.EE
+
+.ES
+# this variant builds both the source and docs
+VariantDir('build', '.', duplicate=0)
+SConscript(dirs=['build/src','build/doc'])
+.EE
+Or, equivalently:
+.ES
+SConscript(dirs=['build/src','build/doc'],
+        variant_dir = 'build', duplicate = 0)
+.EE
+
+.ES
+SConscript('build/SConscript', variant_dir = 'build', duplicate = 0)
+.EE
+Note that in the last example, the
+.I src_dir
+is not given, so the current directory is assumed, and the
+.B SConstruct
+and the
+.B SConscript
+are actually in the same directory, even though the
+.B SConscript
+is treated as if it were in the
+.B build
+subdirectory.
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI WhereIs( program ", [" path  ", " pathext ", " reject ])
 .\" CC     The C compiler
 .\"    Example: env["CC"] = "c68x"
 .\"    Default: env["CC"] = "cc"
-.\" 
+.\"
 .\" CCCOM  The command line ...
 .\"    Example:
 .\"        To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 .LP
-Construction variables can be retrieved and set using the 
-.B Dictionary 
+Construction variables can be retrieved and set using the
+.B Dictionary
 method of the construction environment:
 
 .ES
 env = Environment(CC="cc")
 .EE
 
-or when copying a construction environment using the 
-.B Clone 
+or when copying a construction environment using the
+.B Clone
 method:
 
 .ES
 .B scons
 does not maintain an explicit cache of the tested values,
 but uses its normal dependency tracking to keep the checked values
-up to date. However, users may override this behaviour with the 
+up to date. However, users may override this behaviour with the
 .B --config
 command line option.
 
 This environment may be modified when performing checks.
 .I custom_tests
 is a dictionary containing custom tests.
-See also the section about custom tests below. 
+See also the section about custom tests below.
 By default, no custom tests are added to the configure context.
 .I conf_dir
 specifies a directory where the test cases are built.
 method,
 you may want to specify a subdirectory under your variant directory.
 .I config_h
-specifies a C header file where the results of tests 
-will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc. 
+specifies a C header file where the results of tests
+will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
 The default is to not write a
 .B config.h
 file.
 .B Configure
 instance has the following associated methods:
 
-.TP 
+.TP
 .RI Configure.Finish( self )
 This method should be called after configuration is done.
 It returns the environment as modified
 by the configuration checks performed.
 After this method is called, no further checks can be performed
 with this configuration context.
-However, you can create a new 
-.RI Configure 
+However, you can create a new
+.RI Configure
 context to perform additional checks.
 Only one context should be active at a time.
 
 
 .TP
 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
-Checks if 
+Checks if
 .I header
 is usable in the specified language.
 .I header
 .B #include
 lines should precede the
 header line being checked for.
-The optional argument 
-.I include_quotes 
+The optional argument
+.I include_quotes
 must be
 a two character string, where the first character denotes the opening
 quote and the second character denotes the closing quote.
 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
 This is a wrapper around
 .B Configure.CheckHeader
-which checks if 
+which checks if
 .I header
 is usable in the C language.
 .I header
 .B #include
 lines should precede the
 header line being checked for.
-The optional argument 
-.I include_quotes 
+The optional argument
+.I include_quotes
 must be
 a two character string, where the first character denotes the opening
 quote and the second character denotes the closing quote (both default
 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
 This is a wrapper around
 .B Configure.CheckHeader
-which checks if 
+which checks if
 .I header
 is usable in the C++ language.
 .I header
 .B #include
 lines should precede the
 header line being checked for.
-The optional argument 
-.I include_quotes 
+The optional argument
+.I include_quotes
 must be
 a two character string, where the first character denotes the opening
 quote and the second character denotes the closing quote (both default
 to \N'34').
-Returns 1 on success and 0 on failure. 
+Returns 1 on success and 0 on failure.
 
 .TP
 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
 and selects the compiler to be used for the check;
 the default is "C".
 
-.TP 
+.TP
 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
-Checks if 
-.I library 
-provides 
+Checks if
+.I library
+provides
 .IR symbol .
 If the value of
 .I autoadd
 is 1 and the library provides the specified
 .IR symbol ,
 appends the library to the LIBS construction environment variable.
-.I library 
+.I library
 may also be None (the default),
-in which case 
-.I symbol 
+in which case
+.I symbol
 is checked with the current LIBS variable,
 or a list of library names,
 in which case each library in the list
 will be checked for
 .IR symbol .
-If 
+If
 .I symbol
 is not set or is
 .BR None ,
 is 1.
 This method returns 1 on success and 0 on error.
 
-.TP 
+.TP
 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
 
-In contrast to the 
-.RI Configure.CheckLib 
+In contrast to the
+.RI Configure.CheckLib
 call, this call provides a more sophisticated way to check against libraries.
-Again, 
+Again,
 .I library
-specifies the library or a list of libraries to check. 
+specifies the library or a list of libraries to check.
 .I header
 specifies a header to check for.
 .I header
 can link against the specified
 .IR library .
 .I autoadd
-specifies whether to add the library to the environment (only if the check 
+specifies whether to add the library to the environment (only if the check
 succeeds). This method returns 1 on success and 0 on error.
 
 .TP
 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
     # do stuff for qt - usage, e.g.
     conf.env.Append( CPPFLAGS = '-DWITH_QT' )
-env = conf.Finish() 
+env = conf.Finish()
 .EE
 
 .TP
 .EE
 
 .EE
-You can define your own custom checks. 
+You can define your own custom checks.
 in addition to the predefined checks.
 These are passed in a dictionary to the Configure function.
 This dictionary maps the names of the checks
-to user defined Python callables 
+to user defined Python callables
 (either Python functions or class instances implementing the
 .I __call__
 method).
-The first argument of the call is always a 
+The first argument of the call is always a
 .I CheckContext
 instance followed by the arguments,
 which must be supplied by the user of the check.
 These CheckContext instances define the following methods:
 
-.TP 
+.TP
 .RI CheckContext.Message( self ", " text )
 
-Usually called before the check is started. 
+Usually called before the check is started.
 .I text
 will be displayed to the user, e.g. 'Checking for library X...'
 
 .TP
 .RI CheckContext.Result( self, ", " res )
 
-Usually called after the check is done. 
+Usually called after the check is done.
 .I res
-can be either an integer or a string. In the former case, 'ok' (res != 0) 
-or 'failed' (res == 0) is displayed to the user, in the latter case the 
+can be either an integer or a string. In the former case, 'ok' (res != 0)
+or 'failed' (res == 0) is displayed to the user, in the latter case the
 given string is displayed.
 
 .TP
 .RI CheckContext.TryCompile( self ", " text ", " extension )
-Checks if a file with the specified 
+Checks if a file with the specified
 .I extension
-(e.g. '.c') containing 
-.I text 
+(e.g. '.c') containing
+.I text
 can be compiled using the environment's
-.B Object 
+.B Object
 builder. Returns 1 on success and 0 on failure.
 
-.TP 
+.TP
 .RI CheckContext.TryLink( self ", " text ", " extension )
 Checks, if a file with the specified
 .I extension
-(e.g. '.c') containing 
-.I text 
+(e.g. '.c') containing
+.I text
 can be compiled using the environment's
 .B Program
 builder. Returns 1 on success and 0 on failure.
 .RI CheckContext.TryRun( self ", " text ", " extension )
 Checks, if a file with the specified
 .I extension
-(e.g. '.c') containing 
-.I text 
+(e.g. '.c') containing
+.I text
 can be compiled using the environment's
 .B Program
 builder. On success, the program is run. If the program
 .TP
 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
 Checks if the specified
-.I action 
+.I action
 with an optional source file (contents
 .I text
-, extension 
+, extension
 .I extension
 = ''
-) can be executed. 
-.I action 
-may be anything which can be converted to a 
+) can be executed.
+.I action
+may be anything which can be converted to a
 .B scons
 .RI Action.
 On success,
 the methods above are based on this method.
 Given the Builder instance
 .I builder
-and the optional 
+and the optional
 .I text
 of a source file with optional
 .IR extension ,
-this method returns 1 on success and 0 on failure. In addition, 
-.I self.lastTarget 
+this method returns 1 on success and 0 on failure. In addition,
+.I self.lastTarget
 is set to the build target node, if the build was successful.
 
 .EE
     context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
     ret = context.TryLink("""
 #include <qapp.h>
-int main(int argc, char **argv) { 
+int main(int argc, char **argv) {
   QApplication qapp(argc, argv);
   return 0;
 }
 if not conf.CheckQt('/usr/lib/qt'):
     print 'We really need qt!'
     Exit(1)
-env = conf.Finish() 
+env = conf.Finish()
 .EE
 
 .SS Command-Line Construction Variables
 some variables must be specified at build time.
 For example, libraries needed for the build may be in non-standard
 locations, or site-specific compiler options may need to be passed to the
-compiler. 
+compiler.
 .B scons
 provides a
 .B Variables
 
 .TP
 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
-This adds a customizable construction variable to the Variables object. 
+This adds a customizable construction variable to the Variables object.
 .I key
-is the name of the variable. 
-.I help 
+is the name of the variable.
+.I help
 is the help text for the variable.
-.I default 
+.I default
 is the default value of the variable;
 if the default value is
 .B None
 
 .TP
 .RI Save( filename ", " env )
-This saves the currently set variables into a script file named  
+This saves the currently set variables into a script file named
 .I filename
 that can be used on the next invocation to automatically load the current
 settings.  This method combined with the Variables method can be used to
 .TP
 .RI GenerateHelpText( env ", [" sort ])
 This generates help text documenting the customizable construction
-variables suitable to passing in to the Help() function. 
+variables suitable to passing in to the Help() function.
 .I env
 is the construction environment that will be used to get the actual values
-of customizable variables. Calling with 
+of customizable variables. Calling with
 an optional
 .I sort
 function
 to set up an option
 whose value is a path name
 of a package that may be
-enabled, disabled or 
+enabled, disabled or
 given an explicit path name.
 The option will use
 the specified name
 .I File
 or
 .IR Dir .
-The 
+The
 
 .ES
 # Get the current build dir's path, relative to top.
 
 Builder objects are created
 using the
-.B Builder 
+.B Builder
 function.
 The
 .B Builder
 function accepts the following arguments:
 
 .IP action
-The command line string used to build the target from the source. 
+The command line string used to build the target from the source.
 .B action
 can also be:
 a list of strings representing the command
 
 An action function
 takes three arguments:
-.I source 
-- a list of source nodes, 
+.I source
+- a list of source nodes,
 .I target
 - a list of target nodes,
 .I env
 - the construction environment.
 
-.IP prefix 
+.IP prefix
 The prefix that will be prepended to the target file name.
 This may be specified as a:
 
 .RS 10
 .HP 6
-* 
+*
 .IR string ,
 
 .HP 6
-* 
+*
 .I callable object
 - a function or other callable that takes
 two arguments (a construction environment and a list of sources)
 and returns a prefix,
 
 .HP 6
-* 
+*
 .I dictionary
-- specifies a mapping from a specific source suffix (of the first 
+- specifies a mapping from a specific source suffix (of the first
 source specified) to a corresponding target prefix.  Both the source
 suffix and target prefix specifications may use environment variable
 substitution, and the target prefix (the 'value' entries in the
 .EE
 
 .IP ensure_suffix
-When set to any true value, causes 
+When set to any true value, causes
 .B scons
 to add the target suffix specified by the
 .I suffix
 implicit dependencies
 based only on the target file
 and the construction environment,
-.I not 
+.I not
 for implicit
 (See the section "Scanner Objects," below,
 for information about creating Scanner objects.)
 
 An emitter function
 takes three arguments:
-.I source 
-- a list of source nodes, 
+.I source
+- a list of source nodes,
 .I target
 - a list of target nodes,
 .I env
 builder multiple times for the same target simply adds additional source
 files to the target; it is not allowed to change the environment associated
 with the target, specify addition environment overrides, or associate a different
-builder with the target. 
+builder with the target.
 
 .IP env
 A construction environment that can be used
 
 The generator function
 takes four arguments:
-.I source 
-- a list of source nodes, 
+.I source
+- a list of source nodes,
 .I target
 - a list of target nodes,
 .I env
 
 .ES
 def g(source, target, env, for_signature):
-    return [["gcc", "-c", "-o"] + target + source] 
+    return [["gcc", "-c", "-o"] + target + source]
 
 b = Builder(generator=g)
 .EE
 
 .IP
-The 
+The
 .I generator
 and
 .I action
 .IP single_source
 Specifies that this builder expects exactly one source file per call. Giving
 more than one source files without target files results in implicitely calling
-the builder multiple times (once for each source given). Giving multiple 
+the builder multiple times (once for each source given). Giving multiple
 source files together with target files results in a UserError exception.
 
 .RE
 .IP
-The 
+The
 .I generator
 and
 .I action
 the setting of
 .B source_ext_match
 prevents
-.B scons 
+.B scons
 from exiting with an error
 due to the mismatched suffixes of
 .B foo.in
 will be set in the executing construction
 environment when the Builder object is called.
 The canonical example here would be
-to set a construction variable to 
+to set a construction variable to
 the repository of a source code system.
 
 Any additional keyword arguments supplied
 def build_it(target = None, source = None, env = None):
     # build the target from the source
     return 0
- 
+
 a = Action(build_it)
 .EE
 
 that arrange for various common
 file and directory manipulations
 to be performed.
-These are similar in concept to "tasks" in the 
+These are similar in concept to "tasks" in the
 Ant build tool,
 although the implementation is slightly different.
 These functions do not actually
 without relying
 on platform-specific
 external commands:
-that 
+that
 .ES
 env = Environment(TMPBUILD = '/tmp/builddir')
 env.Command('foo.out', 'foo.in',
 variables for each command execution:
 
 .IP TARGET
-The file name of the target being built, or the file name of the first 
+The file name of the target being built, or the file name of the first
 target if multiple targets are being built.
 
 .IP TARGETS
 (Note that the above variables are reserved
 and may not be set in a construction environment.)
 
-.LP 
+.LP
 For example, given the construction variable CC='cc', targets=['foo'], and
 sources=['foo.c', 'bar.c']:
 
 take four arguments:
 .I target
 - a list of target nodes,
-.I source 
-- a list of source nodes, 
+.I source
+- a list of source nodes,
 .I env
 - the construction environment,
 .I for_signature
 
 .IP String
 When the value is a string it is interpreted as a space delimited list of