Merged revisions 1784-1824 via svnmerge from

http://scons.tigris.org/svn/scons/branches/core ........ r1786 | stevenknight | 2007-01-25 15:29:15 -0600 (Thu, 25 Jan 2007) | 1 line 0.96.D555 - Doc string updates for TaskMaster to better describe the architecture. Get rid of some no-longer-used code. ........ r1787 | stevenknight | 2007-01-25 23:24:31 -0600 (Thu, 25 Jan 2007) | 1 line 0.96.D556 - Packaging changes to support building packages in an arbitrary directory. ........ r1788 | stevenknight | 2007-01-30 20:35:39 -0600 (Tue, 30 Jan 2007) | 1 line 0.96.D557 - Make the Scanner.Base class able to handle Scanner.Selector functionality (i.e., a dictionary to select other scanners) and prepare to deprecate Scanner.Selector and Scanner.Scanner() in the future. ........ r1789 | stevenknight | 2007-01-30 20:45:23 -0600 (Tue, 30 Jan 2007) | 1 line 0.96.D558 - Add support for a site-scons subdirectory. (Gary Oberbrunner) ........ r1790 | stevenknight | 2007-01-31 00:36:20 -0600 (Wed, 31 Jan 2007) | 1 line 0.96.D559 - Clean up various module imports and other pychecker-detected problems. ........ r1791 | stevenknight | 2007-01-31 11:51:04 -0600 (Wed, 31 Jan 2007) | 1 line 0.96.D560 - Fix detection of Java anonymous classes if a newline precedes the opening brace. (Leanid Nazdrynau) ........ r1792 | stevenknight | 2007-02-02 11:57:59 -0600 (Fri, 02 Feb 2007) | 1 line 0.96.D561 - Add a --bootstrap_src option to bootstrap.py; search the bootstrap.py directory by default. (Greg Noel) ........ r1793 | stevenknight | 2007-02-02 18:04:52 -0600 (Fri, 02 Feb 2007) | 1 line 0.96.D562 - Don't check the build/*/gentoo directories for copyright strings. ........ r1794 | stevenknight | 2007-02-02 18:12:43 -0600 (Fri, 02 Feb 2007) | 1 line 0.96.D563 - Fix pychecker clean-ups on later Python versions. ........ r1795 | stevenknight | 2007-02-02 18:38:47 -0600 (Fri, 02 Feb 2007) | 1 line 0.96.D564 - Add a NoCache() function to allow marking targets as not being suitable for propagating/ to (or retrieving from) CacheDir(). (Dave Vitek) ........ r1796 | stevenknight | 2007-02-02 20:08:33 -0600 (Fri, 02 Feb 2007) | 1 line 0.96.D565 - Add a --tree= option, to make the interface to dumping dependency graphs a little clearner, and give it a 'prune' option to avoid repeating the dependency walk for Nodes we've already visited. ........ r1797 | stevenknight | 2007-02-03 20:37:25 -0600 (Sat, 03 Feb 2007) | 1 line 0.96.D566 - Packaging fix: don't add '#' to the beginning of a build_dir name if it's already an absolute path. ........ r1798 | stevenknight | 2007-02-03 20:53:42 -0600 (Sat, 03 Feb 2007) | 1 line 0.96.D567 - Add backwards-compatibility for set() types, and restore the line that used them in the compatibility _subprocess.py module. ........ r1799 | stevenknight | 2007-02-05 10:30:28 -0600 (Mon, 05 Feb 2007) | 1 line 0.96.D568 - Capture outline and build configuration for a possible future Developer's Guide. ........ r1800 | stevenknight | 2007-02-05 11:03:37 -0600 (Mon, 05 Feb 2007) | 1 line 0.96.D569 - Exclude the new developer guide MANIFEST from Copyright string checks. ........ r1801 | stevenknight | 2007-02-05 11:16:04 -0600 (Mon, 05 Feb 2007) | 1 line 0.96.D570 - Track fix in upstream subprocess.py. (Ralf W. Grosse-Kunstleve) ........ r1802 | stevenknight | 2007-02-05 20:05:59 -0600 (Mon, 05 Feb 2007) | 1 line 0.96.D571 - Change the Windows installer to register scons.bat as an 'App Path', so the directory doesn't need to be added to %PATH%. ........ r1803 | stevenknight | 2007-02-05 21:33:01 -0600 (Mon, 05 Feb 2007) | 1 line 0.96.D572 - Prepare SConf for use with the subprocess module by refactoring the Unbuffered class. ........ r1804 | stevenknight | 2007-02-05 22:37:09 -0600 (Mon, 05 Feb 2007) | 1 line 0.96.D573 - Get rid of left-over Node.Node.{pre,post}_actions attributes. ........ r1805 | stevenknight | 2007-02-06 12:04:14 -0600 (Tue, 06 Feb 2007) | 1 line 0.96.D574 - Remove leftover print in the test/CacheDir/NoCache.py test. ........ r1806 | stevenknight | 2007-02-06 17:11:03 -0600 (Tue, 06 Feb 2007) | 1 line 0.96.D575 - Support the ability to evaluate a ${} construction variable to select the spawner function. ........ r1809 | stevenknight | 2007-02-07 00:30:10 -0600 (Wed, 07 Feb 2007) | 1 line 0.96.D576 - Documentation fixes and updates. ........ r1810 | stevenknight | 2007-02-07 15:51:20 -0600 (Wed, 07 Feb 2007) | 1 line 0.96.D577 - Don't expect a bootstrap.py runtest.py file to be generated when swig -noproxy is used. ........ r1811 | stevenknight | 2007-02-07 16:55:06 -0600 (Wed, 07 Feb 2007) | 1 line 0.96.D578 - Make --srcdir a synonym for -Y/--repository. ........ r1812 | stevenknight | 2007-02-07 23:46:22 -0600 (Wed, 07 Feb 2007) | 1 line 0.96.D579 - More doc updates: PathAccept, #include+Repository double-quote limitation. ........ r1817 | stevenknight | 2007-02-08 12:46:42 -0600 (Thu, 08 Feb 2007) | 1 line 0.96.D580 - Fix use of toolpath with BuildDir. ........ r1818 | stevenknight | 2007-02-08 12:59:23 -0600 (Thu, 08 Feb 2007) | 1 line 0.96.D581 - Enable build of the text version of the User's Guide. ........ r1819 | stevenknight | 2007-02-08 14:21:31 -0600 (Thu, 08 Feb 2007) | 1 line 0.96.D582 - Fix handling of Java inner classes with JARCHDIR. ........ r1820 | stevenknight | 2007-02-08 14:39:33 -0600 (Thu, 08 Feb 2007) | 1 line 0.96.D583 - Add linking with -lm to the dmd.py Tool smart linker. (Anonymous) ........ r1821 | stevenknight | 2007-02-08 17:26:29 -0600 (Thu, 08 Feb 2007) | 1 line 0.96.D584 - Fix ParseConfig() when *FLAGS variables have been replaced with strings. ........ r1822 | stevenknight | 2007-02-09 12:21:17 -0600 (Fri, 09 Feb 2007) | 1 line 0.96.D585 - Fix installation of file names beginning with #. (Dave Weber) ........ r1823 | stevenknight | 2007-02-09 14:14:47 -0600 (Fri, 09 Feb 2007) | 1 line 0.96.D586 - Post-review improvements to recent toolpath and MergeFlags() changes. (Gary Oberbrunner, Greg Noel) ........ r1824 | stevenknight | 2007-02-10 00:53:13 -0600 (Sat, 10 Feb 2007) | 1 line 0.96.D587 - Commonize flags initialization between the c and c++ Tools. ........
author: Steven Knight <knight@baldmt.com> 2007-02-11 05:02:05 (GMT)
committer: Steven Knight <knight@baldmt.com> 2007-02-11 05:02:05 (GMT)
commit: 895bf33464c921fecdee7ac5e770ce1009bd2c57 (patch)
tree: 107c065697f6b6bb61356d82f4876df7f0eb378c /doc
parent: 79248be790aa3e46ee7b0a2dc080f211dcca9aa7 (diff)
download: SCons-895bf33464c921fecdee7ac5e770ce1009bd2c57.zip
SCons-895bf33464c921fecdee7ac5e770ce1009bd2c57.tar.gz
SCons-895bf33464c921fecdee7ac5e770ce1009bd2c57.tar.bz2
34 files changed, 1581 insertions, 508 deletions
diff --git a/doc/SConscript b/doc/SConscript
index 43d3403..bf62024 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -29,18 +29,18 @@ import os.path
 import re
 import string
 
-Import('env', 'whereis')
+Import('build_dir', 'env', 'whereis')
 
 env = env.Clone()
 
 env.TargetSignatures('content')
 
-build = os.path.join('#build', 'doc')
+build = os.path.join(build_dir, 'doc')
 
 #
 #
 #
-doc_tar_gz = os.path.join('#build',
+doc_tar_gz = os.path.join(build_dir,
                           'dist',
                           'scons-doc-%s.tar.gz' % env.Dictionary('VERSION'))
 
@@ -210,12 +210,21 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
                 'pdf'       : 1,
                 'text'      : 0,
         },
+        # For whenever (if ever?) we start putting developer guide
+        # information in a printable document instead of the wiki.
+        #'developer' : {
+        #        'htmlindex' : 'book1.html',
+        #        'html'      : 1,
+        #        'ps'        : 1,
+        #        'pdf'       : 1,
+        #        'text'      : 0,
+        #},
         'user' : {
                 'htmlindex' : 'book1.html',
                 'html'      : 1,
                 'ps'        : 1,
                 'pdf'       : 1,
-                'text'      : 0,
+                'text'      : 1,
                 'graphics'  : [
                                 'SCons-win32-install-1.jpg',
                                 'SCons-win32-install-2.jpg',
@@ -268,7 +277,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 
         # Hard-coding the scons-src path is a bit of a hack.  This can
         # be reworked when a better solution presents itself.
-        scons_src_main = os.path.join('#build', 'scons-src', 'doc', main)
+        scons_src_main = os.path.join(build_dir, 'scons-src', 'doc', main)
         env.Ignore(scons_src_main, version_sgml)
 
         htmldir = os.path.join(build, 'HTML', 'scons-%s' % doc)
@@ -379,7 +388,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 man_page_list = ['scons.1', 'sconsign.1', 'scons-time.1']
 
 for m in man_page_list:
-    orig_env.SCons_revision(os.path.join(build, 'man', m),
+    x = orig_env.SCons_revision(os.path.join(build, 'man', m),
                             os.path.join('man', m))
 
 man_i_files = ['builders.man', 'tools.man', 'variables.man']
@@ -425,7 +434,7 @@ for man_1 in man_page_list:
             return 0
 
         cmds = [
-            "( cd build/doc/man && cp %s .. )" % string.join(man_i_files),
+            "( cd %s/man && cp %s .. )" % (build, string.join(man_i_files)),
             "( cd ${SOURCE.dir} && man2html ${SOURCE.file} ) > $TARGET",
             Action(strip_to_first_html_tag),
         ]
diff --git a/doc/developer/MANIFEST b/doc/developer/MANIFEST
new file mode 100644
index 0000000..12a4de0
--- /dev/null
+++ b/doc/developer/MANIFEST
@@ -0,0 +1,9 @@
+architecture.sgml
+branches.sgml
+copyright.sgml
+cycle.sgml
+main.sgml
+packaging.sgml
+preface.sgml
+sourcetree.sgml
+testing.sgml
diff --git a/doc/developer/architecture.sgml b/doc/developer/architecture.sgml
new file mode 100644
index 0000000..0fc357f
--- /dev/null
+++ b/doc/developer/architecture.sgml
@@ -0,0 +1,40 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  XXX
+
+  </para>
+
+  <section>
+  <title>Architecture</title>
+
+    <para>
+
+    XXX
+    </para>
+
+  </section>
diff --git a/doc/developer/branches.sgml b/doc/developer/branches.sgml
new file mode 100644
index 0000000..abba398
--- /dev/null
+++ b/doc/developer/branches.sgml
@@ -0,0 +1,40 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  XXX
+
+  </para>
+
+  <section>
+  <title>&SCons; Branches</title>
+
+    <para>
+
+    XXX
+    </para>
+
+  </section>
diff --git a/doc/developer/copyright.sgml b/doc/developer/copyright.sgml
new file mode 100644
index 0000000..d926f5b
--- /dev/null
+++ b/doc/developer/copyright.sgml
@@ -0,0 +1,32 @@
+<!--
+
+  __COPYRIGHT__
+
+  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.
+
+-->
+
+<blockquote>
+ <para>
+
+  SCons Developer's Guide Copyright (c) 2007 Steven Knight
+
+ </para>
+</blockquote>
diff --git a/doc/developer/cycle.sgml b/doc/developer/cycle.sgml
new file mode 100644
index 0000000..629a1a8
--- /dev/null
+++ b/doc/developer/cycle.sgml
@@ -0,0 +1,40 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  XXX
+
+  </para>
+
+  <section>
+  <title>Development Cycle</title>
+
+    <para>
+
+    XXX
+    </para>
+
+  </section>
diff --git a/doc/developer/main.sgml b/doc/developer/main.sgml
new file mode 100644
index 0000000..949287a
--- /dev/null
+++ b/doc/developer/main.sgml
@@ -0,0 +1,107 @@
+<!--
+
+  __COPYRIGHT__
+
+  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.
+
+-->
+
+<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+[
+
+    <!ENTITY % version SYSTEM "../version.sgml">
+    %version;
+
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+
+    <!ENTITY architecture SYSTEM "architecture.sgml">
+    <!ENTITY branches SYSTEM "branches.sgml">
+    <!ENTITY copyright SYSTEM "copyright.sgml">
+    <!ENTITY cycle SYSTEM "cycle.sgml">
+    <!ENTITY packaging SYSTEM "packaging.sgml">
+    <!ENTITY preface SYSTEM "preface.sgml">
+    <!ENTITY sourcetree SYSTEM "sourcetree.sgml">
+    <!ENTITY testing SYSTEM "testing.sgml">
+
+]>
+
+<book>
+  <bookinfo>
+    <title>SCons Developer's Guide &buildversion;</title>
+
+    <author>
+      <firstname>Steven</firstname>
+      <surname>Knight</surname>
+    </author>
+
+    <edition>Revision &buildrevision; (&builddate;)</edition>
+
+    <pubdate>2007</pubdate>
+
+    <copyright>
+      <year>2007</year>
+      <holder>Steven Knight</holder>
+    </copyright>
+
+    <legalnotice>
+      &copyright;
+    </legalnotice>
+
+    <releaseinfo>version &buildversion;</releaseinfo>
+
+  </bookinfo>
+
+  <preface id="chap-preface">
+    <title>Preface</title>
+    &preface;
+  </preface>
+
+  <chapter id="chap-development-cycle">
+    <title>Development Cycle</title>
+    &cycle;
+  </chapter>
+
+  <chapter id="chap-source-tree">
+    <title>Source Tree</title>
+    &sourcetree;
+  </chapter>
+
+  <chapter id="chap-testing">
+    <title>Testing</title>
+    &testing;
+  </chapter>
+
+  <chapter id="chap-branches">
+    <title>Branches</title>
+    &branches;
+  </chapter>
+
+  <chapter id="chap-packaging">
+    <title>Packaging</title>
+    &packaging;
+  </chapter>
+
+  <chapter id="chap-architecture">
+    <title>Architecture</title>
+    &architecture;
+  </chapter>
+
+</book>
diff --git a/doc/developer/packaging.sgml b/doc/developer/packaging.sgml
new file mode 100644
index 0000000..3860ee7
--- /dev/null
+++ b/doc/developer/packaging.sgml
@@ -0,0 +1,40 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  XXX
+
+  </para>
+
+  <section>
+  <title>Packaging</title>
+
+    <para>
+
+    XXX
+    </para>
+
+  </section>
diff --git a/doc/developer/preface.sgml b/doc/developer/preface.sgml
new file mode 100644
index 0000000..5784cee
--- /dev/null
+++ b/doc/developer/preface.sgml
@@ -0,0 +1,175 @@
+<!--
+
+  __COPYRIGHT__
+
+  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 document assumes that you already know how &SCons;
+  and that you want to learn how to work on the code.
+
+  </para>
+
+  <section>
+  <title>&SCons; Principles</title>
+
+    <para>
+
+    There are a few overriding principles
+    we try to live up to in designing and implementing &SCons:
+
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+      <term>Correctness</term>
+
+      <listitem>
+      <para>
+
+      First and foremost,
+      by default, &SCons; guarantees a correct build
+      even if it means sacrificing performance a little.
+      We strive to guarantee the build is correct
+      regardless of how the software being built is structured,
+      how it may have been written,
+      or how unusual the tools are that build it.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>Performance</term>
+
+      <listitem>
+      <para>
+
+      Given that the build is correct,
+      we try to make &SCons; build software
+      as quickly as possible.
+      In particular, wherever we may have needed to slow
+      down the default &SCons; behavior to guarantee a correct build,
+      we also try to make it easy to speed up &SCons;
+      through optimization options that let you trade off
+      guaranteed correctness in all end cases for
+      a speedier build in the usual cases.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>Convenience</term>
+
+      <listitem>
+      <para>
+
+      &SCons; tries to do as much for you out of the box as reasonable,
+      including detecting the right tools on your system
+      and using them correctly to build the software.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+
+    In a nutshell, we try hard to make &SCons; just
+    "do the right thing" and build software correctly,
+    with a minimum of hassles.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Acknowledgements</title>
+
+    <para>
+
+    &SCons; would not exist without a lot of help
+    from a lot of people,
+    many of whom may not even be aware
+    that they helped or served as inspiration.
+    So in no particular order,
+    and at the risk of leaving out someone:
+
+    </para>
+
+    <para>
+
+    First and foremost,
+    &SCons; owes a tremendous debt to Bob Sidebotham,
+    the original author of the classic Perl-based &Cons; tool
+    which Bob first released to the world back around 1996.
+    Bob's work on Cons classic provided the underlying architecture
+    and model of specifying a build configuration
+    using a real scripting language.
+    My real-world experience working on Cons
+    informed many of the design decisions in SCons,
+    including the improved parallel build support,
+    making Builder objects easily definable by users,
+    and separating the build engine from the wrapping interface.
+
+    </para>
+
+    <para>
+
+    Greg Wilson was instrumental in getting
+    &SCons; started as a real project
+    when he initiated the Software Carpentry design
+    competition in February 2000.
+    Without that nudge,
+    marrying the advantages of the Cons classic
+    architecture with the readability of Python
+    might have just stayed no more than a nice idea.
+
+    </para>
+
+    <para>
+
+    Thanks to Peter Miller
+    for his splendid change management system, &Aegis;,
+    which has provided the &SCons; project
+    with a robust development methodology from day one,
+    and which showed me how you could
+    integrate incremental regression tests into
+    a practical development cycle
+    (years before eXtreme Programming arrived on the scene).
+
+    </para>
+
+    <para>
+
+    And last, thanks to Guido van Rossum
+    for his elegant scripting language,
+    which is the basis not only for the &SCons; implementation,
+    but for the interface itself.
+
+    </para>
+
+  </section>
diff --git a/doc/developer/sourcetree.sgml b/doc/developer/sourcetree.sgml
new file mode 100644
index 0000000..be1c45a
--- /dev/null
+++ b/doc/developer/sourcetree.sgml
@@ -0,0 +1,40 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  XXX
+
+  </para>
+
+  <section>
+  <title>Source Tree</title>
+
+    <para>
+
+    XXX
+    </para>
+
+  </section>
diff --git a/doc/developer/testing.sgml b/doc/developer/testing.sgml
new file mode 100644
index 0000000..c577c5c
--- /dev/null
+++ b/doc/developer/testing.sgml
@@ -0,0 +1,40 @@
+<!--
+
+  __COPYRIGHT__
+
+  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>
+
+  XXX
+
+  </para>
+
+  <section>
+  <title>Testing</title>
+
+    <para>
+
+    XXX
+    </para>
+
+  </section>
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 0a76aff..862cde5 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -92,6 +92,26 @@ rules exist for building common software components (executable
 programs, object files, libraries), so that for most software
 projects, only the target and input files need be specified.
 
+Before reading the
+.I SConstruct
+file,
+.B scons
+adds looks for a dir named
+.I site_scons
+in the dir containing the
+.I SConstruct
+file; it adds that
+.I site_scons
+to sys.path, reads the file
+.IR site_scons/site_init.py ,
+and adds the directory
+.I site_scons/site_tools
+to the default toolpath, if those exist.  See the
+.I --no-site-dir
+and
+.I --site-dir
+options for more details.
+
 .B scons
 reads and executes the SConscript files as Python scripts,
 so you may use normal Python scripting capabilities
@@ -570,8 +590,11 @@ This only works when run under Python 2.1 or later.
 
 .TP
 --debug=dtree
-Print the dependency tree
-after each top-level target is built. This prints out only derived files.
+A synonym for the newer
+.B --tree=derived
+option.
+This will be deprecated in some future release
+and ultimately removed.
 
 .TP
 --debug=explain
@@ -650,9 +673,11 @@ when encountering an otherwise unexplained error.
 
 .TP
 --debug=stree
-Print the dependency tree along with status information.  This is the
-same as the debug=tree option, but additional status information is
-provided for each node in the tree.
+A synonym for the newer
+.B --tree=all,status
+option.
+This will be deprecated in some future release
+and ultimately removed.
 
 .TP
 --debug=time
@@ -663,10 +688,11 @@ SConscript files, and the total time spent executing SCons itself.
 
 .TP
 --debug=tree
-Print the dependency tree
-after each top-level target is built. This prints out the complete
-dependency tree including implicit dependencies and ignored
-dependencies.
+A synonym for the newer
+.B --tree=all
+option.
+This will be deprecated in some future release
+and ultimately removed.
 
 .TP
 .RI --diskcheck= types
@@ -748,6 +774,18 @@ imported Python modules.  If several
 options
 are used, the directories are searched in the order specified.
 
+.TP 
+.RI --no-site-dir
+Prevents the automatic addition of the standard
+.I site_scons
+dir to
+.IR sys.path .
+Also prevents loading the
+.I site_scons/site_init.py
+module if it exists, and prevents adding
+.I site_scons/site_tools
+to the toolpath.
+
 .TP
 --implicit-cache
 Cache implicit dependencies. This can cause 
@@ -939,6 +977,18 @@ Also suppresses SCons status messages.
 Ignored for compatibility with GNU 
 .BR make .
 
+.TP 
+.RI --site-dir= dir
+Uses the named dir as the site dir rather than the default
+.I site_scons
+dir.  This dir will get prepended to
+.IR sys.path ,
+the module
+.IR dir /site_init.py
+will get loaded if it exists, and
+.IR dir /site_tools
+will get added to the default toolpath.
+
 .TP
 -t, --touch
 Ignored for compatibility with GNU
@@ -958,6 +1008,56 @@ A file name of
 may be used to specify the standard output.
 
 .TP
+.RI -tree= options
+Prints a tree of the dependencies
+after each top-level target is built.
+This prints out some or all of the tree,
+in various formats,
+depending on the
+.I options
+specified:
+
+.TP
+--tree=all
+Print the entire dependency tree
+after each top-level target is built.
+This prints out the complete dependency tree,
+including implicit dependencies and ignored dependencies.
+
+.TP
+--tree=derived
+Restricts the tree output to only derived (target) files,
+not source files.
+
+.TP
+--tree=status
+Prints status information for each displayed node.
+
+.TP
+--tree=prune
+Prunes the tree to avoid repeating dependency information
+for nodes that have already been displayed.
+Any node that has already been displayed
+will have its name printed in
+.BR "[square brackets]" ,
+as an indication that the dependencies
+for that node can be found by searching
+for the relevant output higher up in the tree.
+
+.IP
+Multiple options may be specified,
+separated by commas:
+
+.ES
+# Prints only derived files, with status information:
+scons --tree=derived,status
+
+# Prints all dependencies of target, with status information
+# and pruning dependencies of already-visited Nodes:
+scons --tree=all,prune,status target
+.EE
+
+.TP
 -u, --up, --search-up
 Walks up the directory structure until an 
 .I SConstruct ,
@@ -994,6 +1094,10 @@ Print a message containing the working directory before and
 after other processing.
 
 .TP
+--no-print-directory
+Turn off -w, even if it was turned on implicitly.
+
+.TP
 .RI --warn= type ", --warn=no-" type
 Enable or disable warnings.
 .I type
@@ -1004,6 +1108,20 @@ specifies the type of warnings to be enabled or disabled:
 Enables or disables all warnings.
 
 .TP
+--warn=cache-write-error, --warn=no-cache-write-error
+Enables or disables warnings about errors trying to
+write a copy of a built file to a specified
+.BR CacheDir ().
+These warnings are disabled by default.
+
+.TP
+--warn=corrupt-sconsign, --warn=no-corrupt-sconsign
+Enables or disables warnings about unfamiliar signature data in
+.B .sconsign
+files.
+These warnings are enabled by default.
+
+.TP
 --warn=dependency, --warn=no-dependency
 Enables or disables warnings about dependencies.
 These warnings are disabled by default.
@@ -1014,13 +1132,63 @@ Enables or disables warnings about use of deprecated features.
 These warnings are enabled by default.
 
 .TP
---warn=missing-sconscript, --warn=no-missing-sconscript
+--warn=duplicate-environment, --warn=no-duplicate-environment
 Enables or disables warnings about missing SConscript files.
+
+.TP
+--warn=misleading-keywords, --warn=no-misleading-keywords
+Enables or disables warnings about use of the misspelled keywords
+.B targets
+and
+.B sources
+when calling Builders.
+(Note the last
+.B s
+characters, the correct spellings are
+.B target
+and
+.B source.)
 These warnings are enabled by default.
 
 .TP
---no-print-directory
-Turn off -w, even if it was turned on implicitly.
+--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.
+These warnings are enabled by default.
+
+.TP
+--warn=no-md5-module, --warn=no-no-md5-module
+Enables or disables warnings about the version of Python
+not having an MD5 checksum module available.
+These warnings are enabled by default.
+
+.TP
+--warn=no-metaclass-support, --warn=no-no-metaclass-support
+Enables or disables warnings about the version of Python
+not supporting metaclasses when the
+.B --debug=memoizer
+option is used.
+These warnings are enabled by default.
+
+.TP
+--warn=no-parallel-support, --warn=no-no-parallel-support
+Enables or disables warnings about the version of Python
+not being able to support parallel builds when the
+.B -j
+option is used.
+These warnings are enabled by default.
+
+.TP
+--warn=reserved-variable, --warn=no-reserved-variable
+Enables or disables warnings about attempts to set the
+reserved construction variable names
+.BR TARGET ,
+.BR TARGETS ,
+.BR SOURCE
+or
+.BR SOURCES .
+These warnings are disabled by default.
 
 .\" .TP
 .\" .RI --write-filenames= file
@@ -1045,7 +1213,7 @@ Turn off -w, even if it was turned on implicitly.
 .\" Warn when an undefined variable is referenced.
 
 .TP 
-.RI -Y " repository" ", --repository=" repository
+.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
 .B -Y
@@ -2174,6 +2342,12 @@ that are equivalent regardless of whether
 a given derived file has been built in-place
 or retrieved from the cache.
 
+The
+.BR NoCache ()
+method can be used to disable caching of specific files.  This can be
+useful if inputs and/or outputs of some tool are impossible to
+predict or prohibitively large.
+
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP 
 .RI Clean( targets ", " files_or_dirs )
@@ -2282,6 +2456,7 @@ env.Command('baz.out', 'baz.in',
 	     rename ])
 .EE
 
+.IP
 Note that the
 .BR Command ()
 function will usually assume, by default,
@@ -2304,6 +2479,7 @@ env['DISTDIR'] = 'destination/directory'
 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
 .EE
 
+.IP
 (Also note that SCons will usually
 automatically create any directory necessary to hold a target file,
 so you normally don't need to create directories by hand.)
@@ -2513,6 +2689,7 @@ This SConstruct:
 env=Environment()
 print env.Dump('CCCOM')
 .EE
+.IP
 will print:
 .ES
 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
@@ -2522,6 +2699,7 @@ will print:
 env=Environment()
 print env.Dump()
 .EE
+.IP
 will print:
 .ES
 { 'AR': 'ar',
@@ -3026,6 +3204,46 @@ env.MergeFlags(['-O3',
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
+.RI NoCache( target ", ...)"
+.TP
+.RI env.NoCache( target ", ...)"
+Specifies a list of files which should
+.I not
+be cached whenever the 
+.BR CacheDir ()
+method has been activated.
+The specified targets may be a list
+or an individual target.
+Multiple calls to
+.BR NoCache ()
+are legal,
+and prevent each specified target
+from being removed by calls to the
+.B -c
+option.
+
+Multiple files should be specified
+either as separate arguments to the
+.BR NoCache ()
+method, or as a list.
+.BR NoCache ()
+will also accept the return value of any of the construction environment
+Builder methods.
+
+Calling
+.BR NoCache ()
+on directories and other non-File Node types has no effect because
+only File Nodes are cached.
+
+Examples:
+
+.ES
+NoCache('foo.elf')
+NoCache(env.Program('hello', 'hello.c'))
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
 .RI NoClean( target ", ...)"
 .TP
 .RI env.NoClean( target ", ...)"
@@ -3214,6 +3432,7 @@ and added to the following construction variables:
 +                   CCFLAGS, LINKFLAGS
 .EE
 
+.IP
 Any other strings not associated with options
 are assumed to be the names of libraries
 and added to the
@@ -5347,10 +5566,15 @@ which verifies that the specified path exists;
 which verifies that the specified path is an existing file;
 .BR PathOption.PathIsDir ,
 which verifies that the specified path is an existing directory;
-and
 .BR PathOption.PathIsDirCreate ,
-which verifies that the specified path is a directory,
-and will create the specified directory if the path does not exist.
+which verifies that the specified path is a directory
+and will create the specified directory if the path does not exist;
+and
+.BR PathOption.PathAccept ,
+which simply accepts the specific path name argument without validation,
+and which is suitable if you want your users
+to be able to specify a directory path that will be
+created as part of the build process, for example.
 You may supply your own
 .I validator
 function,
@@ -5636,6 +5860,7 @@ env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
 env.MakeDirectory('new_directory', [])
 .EE
 
+.IP
 Note that the call to the MakeDirectory Builder
 needs to specify an empty source list
 to make the string represent the builder's target;
@@ -6739,16 +6964,23 @@ new file types for implicit dependencies.
 Scanner accepts the following arguments:
 
 .IP function
-A Python function that will process
+This can be either:
+1) a Python function that will process
 the Node (file)
 and return a list of strings (file names)
 representing the implicit
-dependencies found in the contents.
-The function takes three or four arguments:
+dependencies found in the contents;
+or:
+2) a dictionary that maps keys
+(typically the file suffix, but see below for more discussion)
+to other Scanners that should be called.
+
+If the argument is actually a Python function,
+the function must take three or four arguments:
 
     def scanner_function(node, env, path):
 
-    def scanner_function(node, env, path, arg):
+    def scanner_function(node, env, path, arg=None):
 
 The
 .B node
diff --git a/doc/user/ENV.sgml b/doc/user/ENV.sgml
index aa65ebd..d843276 100644
--- a/doc/user/ENV.sgml
+++ b/doc/user/ENV.sgml
@@ -57,7 +57,7 @@
     on a POSIX system
     is <literal>/usr/local/bin:/bin:/usr/bin</literal>.
     The default value of the &PATH; environment variable
-    on a Win32 system comes from the Windows registry
+    on a Windows system comes from the Windows registry
     value for the command interpreter.
     If you want to execute any commands--compilers, linkers, etc.--that
     are not in these default locations,
diff --git a/doc/user/alias.sgml b/doc/user/alias.sgml
index 4471605..f285d70 100644
--- a/doc/user/alias.sgml
+++ b/doc/user/alias.sgml
@@ -46,7 +46,7 @@
 
   <screen>
      % <userinput>scons -Q install</userinput>
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
      Install file: "hello" as "/usr/bin/hello"
   </screen>
@@ -86,12 +86,12 @@
 
   <screen>
      % <userinput>scons -Q install-bin</userinput>
-     cc -c -o foo.o foo.c
+     cc -o foo.o -c foo.c
      cc -o foo foo.o
      Install file: "foo" as "/usr/bin/foo"
      % <userinput>scons -Q install-lib</userinput>
-     cc -c -o bar.o bar.c
-     ar r libbar.a bar.o
+     cc -o bar.o -c bar.c
+     ar rc libbar.a bar.o
      ranlib libbar.a
      Install file: "libbar.a" as "/usr/lib/libbar.a"
      % <userinput>scons -Q -c /</userinput>
@@ -102,11 +102,11 @@
      Removed libbar.a
      Removed /usr/lib/libbar.a
      % <userinput>scons -Q install</userinput>
-     cc -c -o foo.o foo.c
+     cc -o foo.o -c foo.c
      cc -o foo foo.o
      Install file: "foo" as "/usr/bin/foo"
-     cc -c -o bar.o bar.c
-     ar r libbar.a bar.o
+     cc -o bar.o -c bar.c
+     ar rc libbar.a bar.o
      ranlib libbar.a
      Install file: "libbar.a" as "/usr/lib/libbar.a"
   </screen>
diff --git a/doc/user/builders-built-in.sgml b/doc/user/builders-built-in.sgml
index 84877a3..9c0a3b8 100644
--- a/doc/user/builders-built-in.sgml
+++ b/doc/user/builders-built-in.sgml
@@ -144,8 +144,8 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o goodbye.o goodbye.c
-      cc -c -o hello.o hello.c
+      cc -o goodbye.o -c goodbye.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o goodbye.o -L/usr/dir1 -Ldir2 -lfoo1 -lfoo2
     </screen>
 
diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml
index 9085c0e..327650a 100644
--- a/doc/user/builders-writing.sgml
+++ b/doc/user/builders-writing.sgml
@@ -266,7 +266,7 @@ This functionality could be invoked as in the following example:
     <screen>
       % <userinput>scons -Q</userinput>
       foobuild &lt; file.input &gt; file.foo
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
     </screen>
 
diff --git a/doc/user/caching.sgml b/doc/user/caching.sgml
index eac6911..d87e493 100644
--- a/doc/user/caching.sgml
+++ b/doc/user/caching.sgml
@@ -82,7 +82,7 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
       % <userinput>scons -Q -c</userinput>
       Removed hello.o
@@ -124,13 +124,13 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
       % <userinput>scons -Q -c</userinput>
       Removed hello.o
       Removed hello
       % <userinput>scons -Q --cache-show</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
     </screen>
 
@@ -177,7 +177,7 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
       % <userinput>scons -Q -c</userinput>
       Removed hello.o
@@ -189,7 +189,7 @@
       Removed hello.o
       Removed hello
       % <userinput>scons -Q --cache-disable</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
     </screen>
 
@@ -228,13 +228,13 @@
 
     <screen>
       % <userinput>scons -Q --cache-disable</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
       % <userinput>scons -Q -c</userinput>
       Removed hello.o
       Removed hello
       % <userinput>scons -Q --cache-disable</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
       % <userinput>scons -Q --cache-force</userinput>
       scons: `.' is up to date.
diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml
index 565d9f8..1953690 100644
--- a/doc/user/command-line.sgml
+++ b/doc/user/command-line.sgml
@@ -133,11 +133,11 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o foo.o foo.c
+      cc -o foo.o -c foo.c
       cc -o foo foo.o
       % <userinput>scons -Q bar</userinput>
       Don't forget to copy `bar' to the archive!
-      cc -c -o bar.o bar.c
+      cc -o bar.o -c bar.c
       cc -o bar bar.o
     </screen>
 
@@ -192,12 +192,12 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o hello.o hello.c
+       cc -o hello.o -c hello.c
        cc -o hello hello.o
        % <userinput>scons -Q</userinput>
        scons: `hello' is up to date.
        % <userinput>scons -Q goodbye</userinput>
-       cc -c -o goodbye.o goodbye.c
+       cc -o goodbye.o -c goodbye.c
        cc -o goodbye goodbye.o
     </screen>
 
@@ -214,9 +214,9 @@
 
     <screen>
        % <userinput>scons -Q .</userinput>
-       cc -c -o goodbye.o goodbye.c
+       cc -o goodbye.o -c goodbye.c
        cc -o goodbye goodbye.o
-       cc -c -o hello.o hello.c
+       cc -o hello.o -c hello.c
        cc -o hello hello.o
     </screen>
 
@@ -266,12 +266,12 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o prog1.o prog1.c
+       cc -o prog1.o -c prog1.c
        cc -o prog1 prog1.o
-       cc -c -o prog3.o prog3.c
+       cc -o prog3.o -c prog3.c
        cc -o prog3 prog3.o
        % <userinput>scons -Q .</userinput>
-       cc -c -o prog2.o prog2.c
+       cc -o prog2.o -c prog2.c
        cc -o prog2 prog2.o
     </screen>
 
@@ -298,14 +298,14 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o prog1/foo.o prog1/foo.c
-       cc -c -o prog1/main.o prog1/main.c
+       cc -o prog1/foo.o -c prog1/foo.c
+       cc -o prog1/main.o -c prog1/main.c
        cc -o prog1/main prog1/main.o prog1/foo.o
        % <userinput>scons -Q</userinput>
        scons: `prog1' is up to date.
        % <userinput>scons -Q .</userinput>
-       cc -c -o prog2/bar.o prog2/bar.c
-       cc -c -o prog2/main.o prog2/main.c
+       cc -o prog2/bar.o -c prog2/bar.c
+       cc -o prog2/main.o -c prog2/main.c
        cc -o prog2/main prog2/main.o prog2/bar.o
     </screen>
 
@@ -335,9 +335,9 @@
        % <userinput>scons -Q</userinput>
        scons: *** No targets specified and no Default() targets found.  Stop.
        % <userinput>scons -Q .</userinput>
-       cc -c -o prog1.o prog1.c
+       cc -o prog1.o -c prog1.c
        cc -o prog1 prog1.o
-       cc -c -o prog2.o prog2.c
+       cc -o prog2.o -c prog2.c
        cc -o prog2 prog2.o
     </screen>
 
@@ -382,7 +382,7 @@
          DEFAULT_TARGETS is ['prog1']
          scons: done reading SConscript files.
          scons: Building targets ...
-         cc -c -o prog1.o prog1.c
+         cc -o prog1.o -c prog1.c
          cc -o prog1 prog1.o
          scons: done building targets.
       </screen>
@@ -418,9 +418,9 @@
          DEFAULT_TARGETS is now ['prog1', 'prog2']
          scons: done reading SConscript files.
          scons: Building targets ...
-         cc -c -o prog1.o prog1.c
+         cc -o prog1.o -c prog1.c
          cc -o prog1 prog1.o
-         cc -c -o prog2.o prog2.c
+         cc -o prog2.o -c prog2.c
          cc -o prog2 prog2.o
          scons: done building targets.
       </screen>
@@ -509,11 +509,11 @@
     <screen>
       % <userinput>scons -Q</userinput>
       BUILD_TARGETS is ['prog1']
-      cc -c -o prog1.o prog1.c
+      cc -o prog1.o -c prog1.c
       cc -o prog1 prog1.o
       % <userinput>scons -Q prog2</userinput>
       BUILD_TARGETS is ['prog2']
-      cc -c -o prog2.o prog2.c
+      cc -o prog2.o -c prog2.c
       cc -o prog2 prog2.o
       % <userinput>scons -Q -c .</userinput>
       BUILD_TARGETS is ['.']
@@ -593,12 +593,12 @@
 
     <screen>
        % <userinput>scons -Q debug=0</userinput>
-       cc -c -o prog.o prog.c
+       cc -o prog.o -c prog.c
        cc -o prog prog.o
        % <userinput>scons -Q debug=0</userinput>
        scons: `.' is up to date.
        % <userinput>scons -Q debug=1</userinput>
-       cc -g -c -o prog.o prog.c
+       cc -o prog.o -c -g prog.c
        cc -o prog prog.o
        % <userinput>scons -Q debug=1</userinput>
        scons: `.' is up to date.
@@ -693,8 +693,8 @@
 
     <screen>
       % <userinput>scons -Q RELEASE=1</userinput>
-      cc -DRELEASE_BUILD=1 -c -o bar.o bar.c
-      cc -DRELEASE_BUILD=1 -c -o foo.o foo.c
+      cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
+      cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
       cc -o foo foo.o bar.o
     </screen>
 
@@ -808,8 +808,8 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -DRELEASE_BUILD=1 -c -o bar.o bar.c
-      cc -DRELEASE_BUILD=1 -c -o foo.o foo.c
+      cc -o bar.o -c -D['RELEASE_BUILD=', 1] bar.c
+      cc -o foo.o -c -D['RELEASE_BUILD=', 1] foo.c
       cc -o foo foo.o bar.o
     </screen>
 
@@ -832,8 +832,8 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -DRELEASE_BUILD=0 -c -o bar.o bar.c
-      cc -DRELEASE_BUILD=0 -c -o foo.o foo.c
+      cc -o bar.o -c -D['RELEASE_BUILD=', 0] bar.c
+      cc -o foo.o -c -D['RELEASE_BUILD=', 0] foo.c
       cc -o foo foo.o bar.o
     </screen>
 
@@ -898,12 +898,12 @@
 
       <screen>
         % <userinput>scons -Q RELEASE=yes foo.o</userinput>
-        cc -DRELEASE_BUILD=1 -c -o foo.o foo.c
+        cc -o foo.o -c -D['RELEASE_BUILD=', True] foo.c
       </screen>
 
       <screen>
         % <userinput>scons -Q RELEASE=t foo.o</userinput>
-        cc -DRELEASE_BUILD=1 -c -o foo.o foo.c
+        cc -o foo.o -c -D['RELEASE_BUILD=', True] foo.c
       </screen>
 
       <para>
@@ -929,12 +929,12 @@
 
       <screen>
         % <userinput>scons -Q RELEASE=no foo.o</userinput>
-        cc -DRELEASE_BUILD=0 -c -o foo.o foo.c
+        cc -o foo.o -c -D['RELEASE_BUILD=', False] foo.c
       </screen>
 
       <screen>
         % <userinput>scons -Q RELEASE=f foo.o</userinput>
-        cc -DRELEASE_BUILD=0 -c -o foo.o foo.c
+        cc -o foo.o -c -D['RELEASE_BUILD=', False] foo.c
       </screen>
 
       <para>
@@ -961,7 +961,7 @@
         
         scons: *** Error converting option: RELEASE
         Invalid value for boolean option: bad_value
-        File "SConstruct", line 4, in ?
+        File "/home/my/project/SConstruct", line 4, in ?
       </screen>
 
     </section>
@@ -1004,11 +1004,11 @@
 
       <screen>
         % <userinput>scons -Q COLOR=red foo.o</userinput>
-        cc -DCOLOR="red" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="red" foo.c
         % <userinput>scons -Q COLOR=blue foo.o</userinput>
-        cc -DCOLOR="blue" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="blue" foo.c
         % <userinput>scons -Q COLOR=green foo.o</userinput>
-        cc -DCOLOR="green" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="green" foo.c
       </screen>
 
       <para>
@@ -1024,7 +1024,7 @@
         % <userinput>scons -Q COLOR=magenta foo.o</userinput>
         
         scons: *** Invalid value for option COLOR: magenta
-        File "SConstruct", line 5, in ?
+        File "/home/my/project/SConstruct", line 5, in ?
       </screen>
 
       <para>
@@ -1063,7 +1063,7 @@
 
       <screen>
         % <userinput>scons -Q COLOR=navy foo.o</userinput>
-        cc -DCOLOR="blue" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="blue" foo.c
       </screen>
 
       <para>
@@ -1080,15 +1080,15 @@
         % <userinput>scons -Q COLOR=Red foo.o</userinput>
         
         scons: *** Invalid value for option COLOR: Red
-        File "SConstruct", line 5, in ?
+        File "/home/my/project/SConstruct", line 5, in ?
         % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
         
         scons: *** Invalid value for option COLOR: BLUE
-        File "SConstruct", line 5, in ?
+        File "/home/my/project/SConstruct", line 5, in ?
         % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
         
         scons: *** Invalid value for option COLOR: nAvY
-        File "SConstruct", line 5, in ?
+        File "/home/my/project/SConstruct", line 5, in ?
       </screen>
 
       <para>
@@ -1120,13 +1120,13 @@
 
       <screen>
         % <userinput>scons -Q COLOR=Red foo.o</userinput>
-        cc -DCOLOR="Red" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="Red" foo.c
         % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
-        cc -DCOLOR="BLUE" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="BLUE" foo.c
         % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
-        cc -DCOLOR="blue" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="blue" foo.c
         % <userinput>scons -Q COLOR=green foo.o</userinput>
-        cc -DCOLOR="green" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="green" foo.c
       </screen>
 
       <para>
@@ -1164,11 +1164,11 @@
 
       <screen>
         % <userinput>scons -Q COLOR=Red foo.o</userinput>
-        cc -DCOLOR="red" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="red" foo.c
         % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
-        cc -DCOLOR="blue" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="blue" foo.c
         % <userinput>scons -Q COLOR=GREEN foo.o</userinput>
-        cc -DCOLOR="green" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLOR="green" foo.c
       </screen>
 
     </section>
@@ -1207,9 +1207,9 @@
 
       <screen>
         % <userinput>scons -Q COLORS=red,blue foo.o</userinput>
-        cc -DCOLORS="red blue" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLORS="red blue" foo.c
         % <userinput>scons -Q COLORS=blue,green,red foo.o</userinput>
-        cc -DCOLORS="blue green red" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLORS="blue green red" foo.c
       </screen>
 
       <para>
@@ -1224,9 +1224,9 @@
 
       <screen>
         % <userinput>scons -Q COLORS=all foo.o</userinput>
-        cc -DCOLORS="red green blue" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLORS="red green blue" foo.c
         % <userinput>scons -Q COLORS=none foo.o</userinput>
-        cc -DCOLORS="" -c -o foo.o foo.c
+        cc -o foo.o -c -DCOLORS="" foo.c
       </screen>
 
       <para>
@@ -1241,7 +1241,7 @@
         
         scons: *** Error converting option: COLORS
         Invalid value(s) for option: magenta
-        File "SConstruct", line 5, in ?
+        File "/home/my/project/SConstruct", line 5, in ?
       </screen>
 
     </section>
@@ -1281,7 +1281,7 @@
 
       <screen>
         % <userinput>scons -Q foo.o</userinput>
-        cc -DCONFIG_FILE="/etc/my_config" -c -o foo.o foo.c
+        cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c
         % <userinput>scons -Q CONFIG=/usr/local/etc/other_config foo.o</userinput>
         scons: `foo.o' is up to date.
       </screen>
@@ -1298,7 +1298,7 @@
         % <userinput>scons -Q CONFIG=/does/not/exist foo.o</userinput>
         
         scons: *** Path for option CONFIG does not exist: /does/not/exist
-        File "SConstruct", line 6, in ?
+        File "/home/my/project/SConstruct", line 6, in ?
       </screen>
 
       <para>
@@ -1426,13 +1426,13 @@
 
       <screen>
         % <userinput>scons -Q foo.o</userinput>
-        cc -DPACKAGE="/opt/location" -c -o foo.o foo.c
+        cc -o foo.o -c -DPACKAGE="/opt/location" foo.c
         % <userinput>scons -Q PACKAGE=/usr/local/location foo.o</userinput>
-        cc -DPACKAGE="/usr/local/location" -c -o foo.o foo.c
+        cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c
         % <userinput>scons -Q PACKAGE=yes foo.o</userinput>
-        cc -DPACKAGE="1" -c -o foo.o foo.c
+        cc -o foo.o -c -D['PACKAGE="', True, '"'] foo.c
         % <userinput>scons -Q PACKAGE=no foo.o</userinput>
-        cc -DPACKAGE="0" -c -o foo.o foo.c
+        cc -o foo.o -c -D['PACKAGE="', False, '"'] foo.c
       </screen>
 
     </section>
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index 3d74025..10a93b6 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -61,7 +61,7 @@ operating system on which the build is performed (as reported by C<uname
 
   <screen>
      % <userinput>scons -Q</userinput>
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
      % <userinput>scons -Q</userinput>
      scons: `.' is up to date.
@@ -80,7 +80,7 @@ operating system on which the build is performed (as reported by C<uname
 
   <screen>
      % <userinput>scons -Q hello</userinput>
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
      % <userinput>scons -Q hello</userinput>
      scons: `hello' is up to date.
@@ -132,7 +132,7 @@ operating system on which the build is performed (as reported by C<uname
 
       <screen>
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
          % <userinput>touch hello.c</userinput>
          % <userinput>scons -Q hello</userinput>
@@ -157,12 +157,12 @@ operating system on which the build is performed (as reported by C<uname
 
       <screen>
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
              [CHANGE THE CONTENTS OF hello.c]
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
       </screen>
 
@@ -212,11 +212,11 @@ operating system on which the build is performed (as reported by C<uname
 
       <screen>
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
          % <userinput>touch hello.c</userinput>
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
       </screen>
 
@@ -259,12 +259,12 @@ operating system on which the build is performed (as reported by C<uname
 
       <screen>
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
              [CHANGE THE CONTENTS OF hello.c]
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
       </screen>
 
@@ -346,12 +346,12 @@ operating system on which the build is performed (as reported by C<uname
 
       <screen>
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
            [CHANGE A COMMENT IN hello.c]
          % <userinput>scons -Q hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          scons: `hello' is up to date.
       </screen>
 
@@ -433,14 +433,14 @@ operating system on which the build is performed (as reported by C<uname
 
     <screen>
        % <userinput>scons -Q hello</userinput>
-       cc -I. -c -o hello.o hello.c
+       cc -o hello.o -c -I. hello.c
        cc -o hello hello.o
        % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
        % <userinput>edit hello.h</userinput>
            [CHANGE THE CONTENTS OF hello.h]
        % <userinput>scons -Q hello</userinput>
-       cc -I. -c -o hello.o hello.c
+       cc -o hello.o -c -I. hello.c
        cc -o hello hello.o
     </screen>
 
@@ -499,7 +499,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <screen>
        % <userinput>scons -Q hello</userinput>
-       cc -Iinclude -I/home/project/inc -c -o hello.o hello.c
+       cc -o hello.o -c -Iinclude -I/home/project/inc hello.c
        cc -o hello hello.o
     </screen>
 
@@ -567,7 +567,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <screen>
        % <userinput>scons -Q --implicit-cache hello</userinput>
-       cc -c -o hello.o hello.c
+       cc -o hello.o -c hello.c
        cc -o hello hello.o
        % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
@@ -626,7 +626,7 @@ operating system on which the build is performed (as reported by C<uname
 
       <screen>
          % <userinput>scons -Q --implicit-deps-changed hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
          % <userinput>scons -Q hello</userinput>
          scons: `hello' is up to date.
@@ -664,7 +664,7 @@ operating system on which the build is performed (as reported by C<uname
 
       <screen>
          % <userinput>scons -Q --implicit-deps-unchanged hello</userinput>
-         cc -c -o hello.o hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
          % <userinput>scons -Q hello</userinput>
          scons: `hello' is up to date.
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index 90f6e3f..9404c23 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -125,7 +125,7 @@ UNIX system are:
   ENV		=> { 'PATH' => '/bin:/usr/bin' },
 
 
-And on a Win32 system (Windows NT), the default construction variables
+And on a Windows system (Windows NT), the default construction variables
 are (unless the default rule style is set using the B<DefaultRules>
 method):
 
@@ -473,7 +473,7 @@ environment undisturbed.
 
  <screen>
     % <userinput>scons -Q</userinput>
-    gcc -O2 -c -o foo.o foo.c
+    gcc -o foo.o -c -O2 foo.c
     gcc -o foo foo.o
  </screen>
 
@@ -505,9 +505,9 @@ environment undisturbed.
 
    <screen>
       % <userinput>scons -Q</userinput>
-      cc -g -c -o bar.o bar.c
+      cc -o bar.o -c -g bar.c
       cc -o bar bar.o
-      cc -O2 -c -o foo.o foo.c
+      cc -o foo.o -c -O2 foo.c
       cc -o foo foo.o
    </screen>
 
@@ -540,7 +540,7 @@ environment undisturbed.
       % <userinput>scons -Q</userinput>
       
       scons: *** Two environments with different actions were specified for the same target: foo.o
-      File "SConstruct", line 6, in ?
+      File "/home/my/project/SConstruct", line 6, in ?
    </screen>
 
    <para>
@@ -593,9 +593,9 @@ environment undisturbed.
 
    <screen>
       % <userinput>scons -Q</userinput>
-      cc -g -c -o foo-dbg.o foo.c
+      cc -o foo-dbg.o -c -g foo.c
       cc -o foo-dbg foo-dbg.o
-      cc -O2 -c -o foo-opt.o foo.c
+      cc -o foo-opt.o -c -O2 foo.c
       cc -o foo-opt foo-opt.o
    </screen>
 
@@ -653,11 +653,11 @@ environment undisturbed.
 
    <screen>
       % <userinput>scons -Q</userinput>
-      gcc -c -o foo.o foo.c
+      gcc -o foo.o -c foo.c
       gcc -o foo foo.o
-      gcc -g -c -o foo-dbg.o foo.c
+      gcc -o foo-dbg.o -c -g foo.c
       gcc -o foo-dbg foo-dbg.o
-      gcc -O2 -c -o foo-opt.o foo.c
+      gcc -o foo-opt.o -c -O2 foo.c
       gcc -o foo-opt foo-opt.o
    </screen>
 
@@ -728,7 +728,7 @@ environment undisturbed.
 
    <para>
 
-   And on Win32:
+   And on Windows:
 
    </para>
 
@@ -889,7 +889,7 @@ environment undisturbed.
 
      <screen>
         % <userinput>scons -Q</userinput>
-        cc -DDEFINE2 -c -o foo.o foo.c
+        cc -o foo.o -c -DDEFINE2 foo.c
         cc -o foo foo.o
      </screen>
 
@@ -965,9 +965,9 @@ environment undisturbed.
         CCFLAGS = -DDEFINE2
         scons: done reading SConscript files.
         scons: Building targets ...
-        cc -DDEFINE2 -c -o bar.o bar.c
+        cc -o bar.o -c -DDEFINE2 bar.c
         cc -o bar bar.o
-        cc -DDEFINE2 -c -o foo.o foo.c
+        cc -o foo.o -c -DDEFINE2 foo.c
         cc -o foo foo.o
         scons: done building targets.
      </screen>
@@ -1014,7 +1014,7 @@ environment undisturbed.
 
      <screen>
         % <userinput>scons -Q</userinput>
-        cc -DMY_VALUE -DLAST -c -o foo.o foo.c
+        cc -o foo.o -c -DMY_VALUE -DLAST foo.c
         cc -o foo foo.o
      </screen>
 
@@ -1071,7 +1071,7 @@ environment undisturbed.
 
      <screen>
         % <userinput>scons -Q</userinput>
-        cc -DFIRST -DMY_VALUE -c -o foo.o foo.c
+        cc -o foo.o -c -DFIRST -DMY_VALUE foo.c
         cc -o foo foo.o
      </screen>
 
diff --git a/doc/user/hierarchy.sgml b/doc/user/hierarchy.sgml
index 047545d..0ce2430 100644
--- a/doc/user/hierarchy.sgml
+++ b/doc/user/hierarchy.sgml
@@ -317,13 +317,13 @@ make no difference to the build.
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o prog1/foo1.o prog1/foo1.c
-       cc -c -o prog1/foo2.o prog1/foo2.c
-       cc -c -o prog1/main.o prog1/main.c
+       cc -o prog1/foo1.o -c prog1/foo1.c
+       cc -o prog1/foo2.o -c prog1/foo2.c
+       cc -o prog1/main.o -c prog1/main.c
        cc -o prog1/prog1 prog1/main.o prog1/foo1.o prog1/foo2.o
-       cc -c -o prog2/bar1.o prog2/bar1.c
-       cc -c -o prog2/bar2.o prog2/bar2.c
-       cc -c -o prog2/main.o prog2/main.c
+       cc -o prog2/bar1.o -c prog2/bar1.c
+       cc -o prog2/bar2.o -c prog2/bar2.c
+       cc -o prog2/main.o -c prog2/main.c
        cc -o prog2/prog2 prog2/main.o prog2/bar1.o prog2/bar2.o
     </screen>
 
@@ -382,9 +382,9 @@ make no difference to the build.
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o lib/foo1.o lib/foo1.c
-       cc -c -o src/prog/foo2.o src/prog/foo2.c
-       cc -c -o src/prog/main.o src/prog/main.c
+       cc -o lib/foo1.o -c lib/foo1.c
+       cc -o src/prog/foo2.o -c src/prog/foo2.c
+       cc -o src/prog/main.o -c src/prog/main.c
        cc -o src/prog/prog src/prog/main.o lib/foo1.o src/prog/foo2.o
     </screen>
 
@@ -423,9 +423,9 @@ make no difference to the build.
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o src/prog/foo2.o src/prog/foo2.c
-       cc -c -o src/prog/main.o src/prog/main.c
-       cc -c -o /usr/joe/lib/foo1.o /usr/joe/lib/foo1.c
+       cc -o src/prog/foo2.o -c src/prog/foo2.c
+       cc -o src/prog/main.o -c src/prog/main.c
+       cc -o /usr/joe/lib/foo1.o -c /usr/joe/lib/foo1.c
        cc -o src/prog/prog src/prog/main.o /usr/joe/lib/foo1.o src/prog/foo2.o
     </screen>
 
@@ -716,9 +716,9 @@ make no difference to the build.
 
       <screen>
         % <userinput>scons -Q</userinput>
-        cc -c -o bar/bar.o bar/bar.c
-        cc -c -o foo/foo.o foo/foo.c
-        ar r libprog.a foo/foo.o bar/bar.o
+        cc -o bar/bar.o -c bar/bar.c
+        cc -o foo/foo.o -c foo/foo.c
+        ar rc libprog.a foo/foo.o bar/bar.o
         ranlib libprog.a
       </screen>
 
diff --git a/doc/user/install.sgml b/doc/user/install.sgml
index 430b336..2a6d1b8 100644
--- a/doc/user/install.sgml
+++ b/doc/user/install.sgml
@@ -58,7 +58,7 @@
 
   <screen>
      % <userinput>scons -Q</userinput>
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
      % <userinput>scons -Q /usr/bin</userinput>
      Install file: "hello" as "/usr/bin/hello"
@@ -95,7 +95,7 @@
 
   <screen>
      % <userinput>scons -Q</userinput>
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
      % <userinput>scons -Q install</userinput>
      Install file: "hello" as "/usr/bin/hello"
@@ -144,10 +144,10 @@
 
     <screen>
        % <userinput>scons -Q install</userinput>
-       cc -c -o goodbye.o goodbye.c
+       cc -o goodbye.o -c goodbye.c
        cc -o goodbye goodbye.o
        Install file: "goodbye" as "/usr/bin/goodbye"
-       cc -c -o hello.o hello.c
+       cc -o hello.o -c hello.c
        cc -o hello hello.o
        Install file: "hello" as "/usr/bin/hello"
     </screen>
@@ -184,7 +184,7 @@
 
     <screen>
        % <userinput>scons -Q install</userinput>
-       cc -c -o hello.o hello.c
+       cc -o hello.o -c hello.c
        cc -o hello hello.o
        Install file: "hello" as "/usr/bin/hello-new"
     </screen>
@@ -226,10 +226,10 @@
 
     <screen>
        % <userinput>scons -Q install</userinput>
-       cc -c -o goodbye.o goodbye.c
+       cc -o goodbye.o -c goodbye.c
        cc -o goodbye goodbye.o
        Install file: "goodbye" as "/usr/bin/goodbye-new"
-       cc -c -o hello.o hello.c
+       cc -o hello.o -c hello.c
        cc -o hello hello.o
        Install file: "hello" as "/usr/bin/hello-new"
     </screen>
diff --git a/doc/user/less-simple.sgml b/doc/user/less-simple.sgml
index 1aa993d..ad20812 100644
--- a/doc/user/less-simple.sgml
+++ b/doc/user/less-simple.sgml
@@ -87,7 +87,7 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o hello.o hello.c
+       cc -o hello.o -c hello.c
        cc -o new_hello hello.o
     </screen>
 
@@ -135,9 +135,9 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o file1.o file1.c
-       cc -c -o file2.o file2.c
-       cc -c -o main.o main.c
+       cc -o file1.o -c file1.c
+       cc -o file2.o -c file2.c
+       cc -o main.o -c main.c
        cc -o main main.o file1.o file2.o
     </screen>
 
@@ -175,9 +175,9 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o file1.o file1.c
-       cc -c -o file2.o file2.c
-       cc -c -o main.o main.c
+       cc -o file1.o -c file1.c
+       cc -o file2.o -c file2.c
+       cc -o main.o -c main.c
        cc -o program main.o file1.o file2.o
     </screen>
 
@@ -459,10 +459,10 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o bar1.o bar1.c
-       cc -c -o bar2.o bar2.c
+       cc -o bar1.o -c bar1.c
+       cc -o bar2.o -c bar2.c
        cc -o bar bar1.o bar2.o
-       cc -c -o foo.o foo.c
+       cc -o foo.o -c foo.c
        cc -o foo foo.o
     </screen>
 
@@ -522,12 +522,12 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -c -o bar1.o bar1.c
-       cc -c -o bar2.o bar2.c
-       cc -c -o common1.o common1.c
-       cc -c -o common2.o common2.c
+       cc -o bar1.o -c bar1.c
+       cc -o bar2.o -c bar2.c
+       cc -o common1.o -c common1.c
+       cc -o common2.o -c common2.c
        cc -o bar bar1.o bar2.o common1.o common2.o
-       cc -c -o foo.o foo.c
+       cc -o foo.o -c foo.c
        cc -o foo foo.o common1.o common2.o
     </screen>
 
diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml
index aab3045..ca2cb97 100644
--- a/doc/user/libraries.sgml
+++ b/doc/user/libraries.sgml
@@ -57,10 +57,10 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o f1.o f1.c
-      cc -c -o f2.o f2.c
-      cc -c -o f3.o f3.c
-      ar r libfoo.a f1.o f2.o f3.o
+      cc -o f1.o -c f1.c
+      cc -o f2.o -c f2.c
+      cc -o f3.o -c f3.c
+      ar rc libfoo.a f1.o f2.o f3.o
       ranlib libfoo.a
     </screen>
 
@@ -139,10 +139,10 @@
 
       <screen>
         % <userinput>scons -Q</userinput>
-        cc -c -o f1.os f1.c
-        cc -c -o f2.os f2.c
-        cc -c -o f3.os f3.c
-        cc -shared -o libfoo.so f1.os f2.os f3.os
+        cc -o f1.os -c f1.c
+        cc -o f2.os -c f2.c
+        cc -o f3.os -c f3.c
+        cc -o libfoo.so -shared f1.os f2.os f3.os
       </screen>
 
       <para>
@@ -212,12 +212,12 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o f1.o f1.c
-      cc -c -o f2.o f2.c
-      cc -c -o f3.o f3.c
-      ar r libfoo.a f1.o f2.o f3.o
+      cc -o f1.o -c f1.c
+      cc -o f2.o -c f2.c
+      cc -o f3.o -c f3.c
+      ar rc libfoo.a f1.o f2.o f3.o
       ranlib libfoo.a
-      cc -c -o prog.o prog.c
+      cc -o prog.o -c prog.c
       cc -o prog prog.o -L. -lfoo -lbar
     </screen>
 
@@ -345,7 +345,7 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o prog.o prog.c
+      cc -o prog.o -c prog.c
       cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
     </screen>
 
diff --git a/doc/user/nodes.in b/doc/user/nodes.in
index f5faf5a..4b8aa0f 100644
--- a/doc/user/nodes.in
+++ b/doc/user/nodes.in
@@ -310,7 +310,7 @@
 
     </para>
 
-    <scons_output example="print" os="posix">
+    <scons_output example="exists" os="posix">
       <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
@@ -328,7 +328,7 @@
 
     </para>
 
-    <scons_example name="exists">
+    <scons_example name="read">
       <file name="SConstruct" printme="1">
       hello_c = File('hello.c')
       contents = hello_c.read()
@@ -346,7 +346,7 @@
 
     </para>
 
-    <scons_output example="print" os="posix">
+    <scons_output example="read" os="posix">
       <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
diff --git a/doc/user/nodes.sgml b/doc/user/nodes.sgml
index 114e9e0..c8756c5 100644
--- a/doc/user/nodes.sgml
+++ b/doc/user/nodes.sgml
@@ -115,8 +115,8 @@
 
     <screen>
        % <userinput>scons -Q</userinput>
-       cc -DGOODBYE -c -o goodbye.o goodbye.c
-       cc -DHELLO -c -o hello.o hello.c
+       cc -o goodbye.o -c -DGOODBYE goodbye.c
+       cc -o hello.o -c -DHELLO hello.c
        cc -o hello hello.o goodbye.o
     </screen>
 
@@ -254,7 +254,7 @@
       % <userinput>scons -Q</userinput>
       The object file is: hello.o
       The program file is: hello
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
     </screen>
 
@@ -312,9 +312,8 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      The object file is: hello.o
-      The program file is: hello
-      cc -c -o hello.o hello.c
+      hello does not exist!
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
     </screen>
 
@@ -332,7 +331,7 @@
 
     </para>
 
-    <scons_example name="exists">
+    <scons_example name="read">
       <file name="SConstruct" printme="1">
       hello_c = File('hello.c')
       contents = hello_c.read()
@@ -350,7 +349,7 @@
 
     </para>
 
-    <scons_output example="print" os="posix">
+    <scons_output example="read" os="posix">
       <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml
index 47dbd98..ba5d1a3 100644
--- a/doc/user/preface.sgml
+++ b/doc/user/preface.sgml
@@ -345,12 +345,12 @@
 
     &SCons; has received contributions
     from many other people, of course:
-    Matt Balvin (extending long command-line support on Win32),
+    Matt Balvin (extending long command-line support on Windows),
     Allen Bierbaum (extensions and fixes to Options),
     Steve Christensen (help text sorting and function action signature fixes),
     Michael Cook (avoiding losing signal bits from executed commands),
     Derrick 'dman' Hudson (),
-    Alex Jacques (work on the Win32 scons.bat file),
+    Alex Jacques (work on the Windows scons.bat file),
     Stephen Kennedy (performance enhancements),
     Lachlan O'Dea (SharedObject() support for masm
     and normalized paths for the WhereIs() function),
diff --git a/doc/user/repositories.in b/doc/user/repositories.in
index d2c9236..a667a91 100644
--- a/doc/user/repositories.in
+++ b/doc/user/repositories.in
@@ -23,118 +23,6 @@
 
 -->
 
-<!--
-
-
-=head2 Repository dependency analysis
-
-Due to its built-in scanning, Cons will search the specified repository
-trees for included F<.h> files.  Unless the compiler also knows about the
-repository trees, though, it will be unable to find F<.h> files that only
-exist in a repository.  If, for example, the F<hello.c> file includes the
-F<hello.h> file in its current directory:
-
-  % cons -R /usr/all/repository hello
-  gcc -c /usr/all/repository/hello.c -o hello.o
-  /usr/all/repository/hello.c:1: hello.h: No such file or directory
-
-Solving this problem forces some requirements onto the way construction
-environments are defined and onto the way the C C<#include> preprocessor
-directive is used to include files.
-
-In order to inform the compiler about the repository trees, Cons will add
-appropriate C<-I> flags to the compilation commands.  This means that the
-C<CPPPATH> variable in the construction environment must explicitly specify
-all subdirectories which are to be searched for included files, including the
-current directory.  Consequently, we can fix the above example by changing
-the environment creation in the F<Construct> file as follows:
-
-  $env = new cons(
-	CC	=> 'gcc',
-	CPPPATH	=> '.',
-	LIBS	=> 'libworld.a',
-  );
-
-Due to the definition of the C<CPPPATH> variable, this yields, when we
-re-execute the command:
-
-  % cons -R /usr/all/repository hello
-  gcc -c -I. -I/usr/all/repository /usr/all/repository/hello.c -o hello.o
-  gcc -o hello hello.o /usr/all/repository/libworld.a
-
-The order of the C<-I> flags replicates, for the C preprocessor, the same
-repository-directory search path that Cons uses for its own dependency
-analysis.  If there are multiple repositories and multiple C<CPPPATH>
-directories, Cons will append the repository directories to the beginning of
-each C<CPPPATH> directory, rapidly multiplying the number of C<-I> flags.
-As an extreme example, a F<Construct> file containing:
-
-  Repository qw(
-	/u1
-	/u2
-  );
-
-  $env = new cons(
-	CPPPATH	=> 'a:b:c',
-  );
-
-Would yield a compilation command of:
-
-  cc -Ia -I/u1/a -I/u2/a -Ib -I/u1/b -I/u2/b -Ic -I/u1/c -I/u2/c -c hello.c -o hello.o
-
-In order to shorten the command lines as much as possible, Cons will
-remove C<-I> flags for any directories, locally or in the repositories,
-which do not actually exist.  (Note that the C<-I> flags are not included
-in the MD5 signature calculation for the target file, so the target will
-not be recompiled if the compilation command changes due to a directory
-coming into existence.)
-
-Because Cons relies on the compiler's C<-I> flags to communicate the
-order in which repository directories must be searched, Cons' handling
-of repository directories is fundamentally incompatible with using
-double-quotes on the C<#include> directives in any C source code that
-you plan to modify:
-
-  #include "file.h"	/* DON'T USE DOUBLE-QUOTES LIKE THIS */
-
-This is because most C preprocessors, when faced with such a directive, will
-always first search the directory containing the source file.  This
-undermines the elaborate C<-I> options that Cons constructs to make the
-preprocessor conform to its preferred search path.
-
-Consequently, when using repository trees in Cons, B<always> use
-angle-brackets for included files in any C source (.c or .h) files that
-you plan to modify locally:
-
-  #include <file.h>	/* USE ANGLE-BRACKETS INSTEAD */
-
-Code that will not change can still safely use double quotes on #include
-lines.
-
-
-=head2 Repository_List
-
-Cons provides a C<Repository_List> command to return a list of all
-repository directories in their current search order.  This can be used for
-debugging, or to do more complex Perl stuff:
-
-  @list = Repository_List;
-  print join(' ', @list), "\n";
-
-
-=head2 Repository interaction with other Cons features
-
-Cons' handling of repository trees interacts correctly with other Cons
-features, which is to say, it generally does what you would expect.
-
-Most notably, repository trees interact correctly, and rather powerfully,
-with the 'Link' command.  A repository tree may contain one or more
-subdirectories for version builds established via C<Link> to a source
-subdirectory.  Cons will search for derived files in the appropriate build
-subdirectories under the repository tree.
-
--->
-
   <para>
 
   Often, a software project will have
@@ -170,11 +58,13 @@ subdirectories under the repository tree.
     a directory copy of the source code tree.
     (Note that this is not the sort of repository
     maintained by a source code management system
-    like BitKeeper, CVS, or Subversion.
+    like BitKeeper, CVS, or Subversion.)
+    <!--
     For information about using &SCons;
     with these systems, see the section,
     "Fetching Files From Source Code Management Systems,"
     below.)
+    -->
     You use the &Repository; method
     to tell &SCons; to search one or more
     central code repositories (in order)
@@ -187,7 +77,7 @@ subdirectories under the repository tree.
       <file name="SConstruct" printme="1">
        env = Environment()
        env.Program('hello.c')
-       Repository('/usr/repository1', '/usr/repository2')
+       Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2')
       </file>
       <file name="hello.c">
       int main() { printf("Hello, world!\n"); }
@@ -256,17 +146,15 @@ subdirectories under the repository tree.
       <file name="SConstruct">
        env = Environment()
        env.Program('hello.c')
-       Repository('/usr/repository1', '/usr/repository2')
+       Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2')
       </file>
-      <file name="hello.c">
+      <file name="__ROOT__/usr/repository1/hello.c">
       int main() { printf("Hello, world!\n"); }
       </file>
     </scons_example>
 
     <scons_output example="ex2">
       <scons_output_command>scons -Q</scons_output_command>
-      gcc -c /usr/repository1/hello.c -o hello.o
-      gcc -o hello hello.o
     </scons_output>
 
     <para>
@@ -281,9 +169,9 @@ subdirectories under the repository tree.
       <file name="SConstruct">
        env = Environment()
        env.Program('hello.c')
-       Repository('/usr/repository1', '/usr/repository2')
+       Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2')
       </file>
-      <file name="hello.c">
+      <file name="__ROOT__/usr/repository2/hello.c">
       int main() { printf("Hello, world!\n"); }
       </file>
     </scons_example>
@@ -299,6 +187,252 @@ subdirectories under the repository tree.
   </section>
 
   <section>
+  <title>Finding <literal>#include</literal> files in repositories</title>
+
+    <para>
+
+    We've already seen that SCons will scan the contents of
+    a source file for <literal>#include</literal> file names
+    and realize that targets built from that source file
+    also depend on the <literal>#include</literal> file(s).
+    For each directory in the &cv-CPPPATH; list,
+    &SCons; will actually search the corresponding directories
+    in any repository trees and establish the
+    correct dependencies on any
+    <literal>#include</literal> files that it finds
+    in repository directory.
+
+    </para>
+
+    <para>
+
+    Unless the C compiler also knows about these directories
+    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;
+    in its current directory,
+    and the &hello.h; only exists in the repository:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      hello.c:1: hello.h: No such file or directory
+    </screen>
+
+    <para>
+
+    In order to inform the C compiler about the repositories,
+    &SCons; will add appropriate
+    <literal>-I</literal> flags to the compilation commands
+    for each directory in the &cv-CPPPATH; list.
+    So if we add the current directory to the
+    construction environment &cv-CPPPATH; like so:
+
+    </para>
+
+    <scons_example name="CPPPATH">
+      <file name="SConstruct" printme="1">
+       env = Environment(CPPPATH = ['.'])
+       env.Program('hello.c')
+       Repository('__ROOT__/usr/repository1')
+      </file>
+      <file name="hello.c">
+      int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
+
+    <para>
+
+    Then re-executing &SCons; yields:
+
+    </para>
+
+    <scons_output example="CPPPATH">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    The order of the <literal>-I</literal> options replicates,
+    for the C preprocessor,
+    the same repository-directory search path
+    that &SCons; uses for its own dependency analysis.
+    If there are multiple repositories and multiple &cv-CPPPATH;
+    directories, &SCons; will add the repository directories
+    to the beginning of each &cv-CPPPATH; directory,
+    rapidly multiplying the number of <literal>-I</literal> flags.
+    If, for example, the &cv-CPPPATH; contains three directories
+    (and shorter repository path names!):
+
+    </para>
+
+    <scons_example name="CPPPATH3">
+      <file name="SConstruct" printme="1">
+       env = Environment(CPPPATH = ['dir1', 'dir2', 'dir3'])
+       env.Program('hello.c')
+       Repository('__ROOT__/r1', '__ROOT__/r2')
+      </file>
+      <file name="hello.c">
+      int main() { printf("Hello, world!\n"); }
+      </file>
+    </scons_example>
+
+    <para>
+
+    Then we'll end up with nine <literal>-I</literal> options
+    on the command line,
+    three (for each of the &cv-CPPPATH; directories)
+    times three (for the local directory plus the two repositories):
+
+    </para>
+
+    <scons_output example="CPPPATH3">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+<!--
+
+Cons classic did the following, does SCons?
+
+In order to shorten the command lines as much as possible, Cons will
+remove C<-I> flags for any directories, locally or in the repositories,
+which do not actually exist.  (Note that the C<-I> flags are not included
+in the MD5 signature calculation for the target file, so the target will
+not be recompiled if the compilation command changes due to a directory
+coming into existence.)
+
+-->
+
+    <section>
+    <title>Limitations on <literal>#include</literal> files in repositories</title>
+
+      <para>
+
+      &SCons; relies on the C compiler's
+      <literal>-I</literal> options to control the order in which
+      the preprocessor will search the repository directories
+      for <literal>#include</literal> files.
+      This causes a problem, however, with how the C preprocessor
+      handles <literal>#include</literal> lines with
+      the file name included in double-quotes.
+
+      </para>
+
+      <para>
+
+      As we've seen,
+      &SCons; will compile the &hello_c; file from
+      the repository if it doesn't exist in
+      the local directory.
+      If, however, the &hello_c; file in the repository contains
+      a <literal>#include</literal> line with the file name in
+      double quotes:
+
+      </para>
+
+      <programlisting>
+        #include "hello.h"
+        int
+        main(int argc, char *argv[])
+        {
+            printf(HELLO_MESSAGE);
+            return (0);
+        }
+      </programlisting>
+
+      <para>
+
+      Then the C preprocessor will <emphasis>always</emphasis>
+      use a &hello_h; file from the repository directory first,
+      even if there is a &hello_h; file in the local directory,
+      despite the fact that the command line specifies
+      <literal>-I</literal> as the first option:
+
+      </para>
+
+      <scons_example name="quote1">
+        <file name="SConstruct">
+         env = Environment(CPPPATH = ['.'])
+         env.Program('hello.c')
+         Repository('__ROOT__/usr/repository1')
+        </file>
+        <file name="__ROOT__/usr/repository1/hello.c">
+        int main() { printf("Hello, world!\n"); }
+        </file>
+      </scons_example>
+
+      <scons_output example="quote1">
+        <scons_output_command>scons -Q</scons_output_command>
+      </scons_output>
+
+      <para>
+
+      This behavior of the C preprocessor--always search
+      for a <literal>#include</literal> file in double-quotes
+      first in the same directory as the source file,
+      and only then search the <literal>-I</literal>--can
+      not, in general, be changed.
+      In other words, it's a limitation
+      that must be lived with if you want to use
+      code repositories in this way.
+      There are three ways you can possibly
+      work around this C preprocessor behavior:
+
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+        <para>
+
+        Some modern versions of C compilers do have an option
+        to disable or control this behavior.
+        If so, add that option to &cv-CFLAGS;
+        (or &cv-CXXFLAGS; or both) in your construction environment(s).
+        Make sure the option is used for all construction
+        environments that use C preprocessing!
+
+        </para>
+        </listitem>
+
+        <listitem>
+        <para>
+
+        Change all occurrences of <literal>#include "file.h"</literal>
+        to <literal>#include &amp;lt;file.h&amp;gt;</literal>.
+        Use of <literal>#include</literal> with angle brackets
+        does not have the same behavior--the <literal>-I</literal>
+        directories are searched first
+        for <literal>#include</literal> files--which
+        gives &SCons; direct control over the list of
+        directories the C preprocessor will search.
+
+        </para>
+        </listitem>
+
+        <listitem>
+        <para>
+
+        Require that everyone working with compilation from
+        repositories check out and work on entire directories of files,
+        not individual files.
+        (If you use local wrapper scripts around
+        your source code control system's command,
+        you could add logic to enforce this restriction there.
+
+        </para>
+        </listitem>
+
+      </orderedlist>
+
+    </section>
+
+  </section>
+
+  <section>
   <title>Finding the &SConstruct; file in repositories</title>
 
     <para>
diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml
index 0392853..c659aa2 100644
--- a/doc/user/repositories.sgml
+++ b/doc/user/repositories.sgml
@@ -23,118 +23,6 @@
 
 -->
 
-<!--
-
-
-=head2 Repository dependency analysis
-
-Due to its built-in scanning, Cons will search the specified repository
-trees for included F<.h> files.  Unless the compiler also knows about the
-repository trees, though, it will be unable to find F<.h> files that only
-exist in a repository.  If, for example, the F<hello.c> file includes the
-F<hello.h> file in its current directory:
-
-  % cons -R /usr/all/repository hello
-  gcc -c /usr/all/repository/hello.c -o hello.o
-  /usr/all/repository/hello.c:1: hello.h: No such file or directory
-
-Solving this problem forces some requirements onto the way construction
-environments are defined and onto the way the C C<#include> preprocessor
-directive is used to include files.
-
-In order to inform the compiler about the repository trees, Cons will add
-appropriate C<-I> flags to the compilation commands.  This means that the
-C<CPPPATH> variable in the construction environment must explicitly specify
-all subdirectories which are to be searched for included files, including the
-current directory.  Consequently, we can fix the above example by changing
-the environment creation in the F<Construct> file as follows:
-
-  $env = new cons(
-	CC	=> 'gcc',
-	CPPPATH	=> '.',
-	LIBS	=> 'libworld.a',
-  );
-
-Due to the definition of the C<CPPPATH> variable, this yields, when we
-re-execute the command:
-
-  % cons -R /usr/all/repository hello
-  gcc -c -I. -I/usr/all/repository /usr/all/repository/hello.c -o hello.o
-  gcc -o hello hello.o /usr/all/repository/libworld.a
-
-The order of the C<-I> flags replicates, for the C preprocessor, the same
-repository-directory search path that Cons uses for its own dependency
-analysis.  If there are multiple repositories and multiple C<CPPPATH>
-directories, Cons will append the repository directories to the beginning of
-each C<CPPPATH> directory, rapidly multiplying the number of C<-I> flags.
-As an extreme example, a F<Construct> file containing:
-
-  Repository qw(
-	/u1
-	/u2
-  );
-
-  $env = new cons(
-	CPPPATH	=> 'a:b:c',
-  );
-
-Would yield a compilation command of:
-
-  cc -Ia -I/u1/a -I/u2/a -Ib -I/u1/b -I/u2/b -Ic -I/u1/c -I/u2/c -c hello.c -o hello.o
-
-In order to shorten the command lines as much as possible, Cons will
-remove C<-I> flags for any directories, locally or in the repositories,
-which do not actually exist.  (Note that the C<-I> flags are not included
-in the MD5 signature calculation for the target file, so the target will
-not be recompiled if the compilation command changes due to a directory
-coming into existence.)
-
-Because Cons relies on the compiler's C<-I> flags to communicate the
-order in which repository directories must be searched, Cons' handling
-of repository directories is fundamentally incompatible with using
-double-quotes on the C<#include> directives in any C source code that
-you plan to modify:
-
-  #include "file.h"	/* DON'T USE DOUBLE-QUOTES LIKE THIS */
-
-This is because most C preprocessors, when faced with such a directive, will
-always first search the directory containing the source file.  This
-undermines the elaborate C<-I> options that Cons constructs to make the
-preprocessor conform to its preferred search path.
-
-Consequently, when using repository trees in Cons, B<always> use
-angle-brackets for included files in any C source (.c or .h) files that
-you plan to modify locally:
-
-  #include <file.h>	/* USE ANGLE-BRACKETS INSTEAD */
-
-Code that will not change can still safely use double quotes on #include
-lines.
-
-
-=head2 Repository_List
-
-Cons provides a C<Repository_List> command to return a list of all
-repository directories in their current search order.  This can be used for
-debugging, or to do more complex Perl stuff:
-
-  @list = Repository_List;
-  print join(' ', @list), "\n";
-
-
-=head2 Repository interaction with other Cons features
-
-Cons' handling of repository trees interacts correctly with other Cons
-features, which is to say, it generally does what you would expect.
-
-Most notably, repository trees interact correctly, and rather powerfully,
-with the 'Link' command.  A repository tree may contain one or more
-subdirectories for version builds established via C<Link> to a source
-subdirectory.  Cons will search for derived files in the appropriate build
-subdirectories under the repository tree.
-
--->
-
   <para>
 
   Often, a software project will have
@@ -170,11 +58,13 @@ subdirectories under the repository tree.
     a directory copy of the source code tree.
     (Note that this is not the sort of repository
     maintained by a source code management system
-    like BitKeeper, CVS, or Subversion.
+    like BitKeeper, CVS, or Subversion.)
+    <!--
     For information about using &SCons;
     with these systems, see the section,
     "Fetching Files From Source Code Management Systems,"
     below.)
+    -->
     You use the &Repository; method
     to tell &SCons; to search one or more
     central code repositories (in order)
@@ -236,7 +126,7 @@ subdirectories under the repository tree.
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
     </screen>
 
@@ -253,10 +143,8 @@ subdirectories under the repository tree.
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c /usr/repository1/hello.c
       cc -o hello hello.o
-      gcc -c /usr/repository1/hello.c -o hello.o
-      gcc -o hello hello.o
     </screen>
 
     <para>
@@ -271,14 +159,247 @@ subdirectories under the repository tree.
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c /usr/repository2/hello.c
+      cc -o hello hello.o
+    </screen>
+
+    <para>
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Finding <literal>#include</literal> files in repositories</title>
+
+    <para>
+
+    We've already seen that SCons will scan the contents of
+    a source file for <literal>#include</literal> file names
+    and realize that targets built from that source file
+    also depend on the <literal>#include</literal> file(s).
+    For each directory in the &cv-CPPPATH; list,
+    &SCons; will actually search the corresponding directories
+    in any repository trees and establish the
+    correct dependencies on any
+    <literal>#include</literal> files that it finds
+    in repository directory.
+
+    </para>
+
+    <para>
+
+    Unless the C compiler also knows about these directories
+    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;
+    in its current directory,
+    and the &hello;.h; only exists in the repository:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      hello.c:1: hello.h: No such file or directory
+    </screen>
+
+    <para>
+
+    In order to inform the C compiler about the repositories,
+    &SCons; will add appropriate
+    <literal>-I</literal> flags to the compilation commands
+    for each directory in the &cv-CPPPATH; list.
+    So if we add the current directory to the
+    construction environment &cv-CPPPATH; like so:
+
+    </para>
+
+    <programlisting>
+       env = Environment(CPPPATH = ['.'])
+       env.Program('hello.c')
+       Repository('/usr/repository1')
+    </programlisting>
+
+    <para>
+
+    Then re-executing &SCons; yields:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c -I. -I/usr/repository1 hello.c
       cc -o hello hello.o
     </screen>
 
     <para>
 
+    The order of the <literal>-I</literal> options replicates,
+    for the C preprocessor,
+    the same repository-directory search path
+    that &SCons; uses for its own dependency analysis.
+    If there are multiple repositories and multiple &cv-CPPPATH;
+    directories, &SCons; will add the repository directories
+    to the beginning of each &cv-CPPPATH; directory,
+    rapidly multiplying the number of <literal>-I</literal> flags.
+    If, for example, the &cv-CPPPATH; contains three directories
+    (and shorter repository path names!):
+
     </para>
 
+    <programlisting>
+       env = Environment(CPPPATH = ['dir1', 'dir2', 'dir3'])
+       env.Program('hello.c')
+       Repository('/r1', '/r2')
+    </programlisting>
+
+    <para>
+
+    Then we'll end up with nine <literal>-I</literal> options
+    on the command line,
+    three (for each of the &cv-CPPPATH; directories)
+    times three (for the local directory plus the two repositories):
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c -Idir1 -I/r1/dir1 -I/r2/dir1 -Idir2 -I/r1/dir2 -I/r2/dir2 -Idir3 -I/r1/dir3 -I/r2/dir3 hello.c
+      cc -o hello hello.o
+    </screen>
+
+<!--
+
+Cons classic did the following, does SCons?
+
+In order to shorten the command lines as much as possible, Cons will
+remove C<-I> flags for any directories, locally or in the repositories,
+which do not actually exist.  (Note that the C<-I> flags are not included
+in the MD5 signature calculation for the target file, so the target will
+not be recompiled if the compilation command changes due to a directory
+coming into existence.)
+
+-->
+
+    <section>
+    <title>Limitations on <literal>#include</literal> files in repositories</title>
+
+      <para>
+
+      &SCons; relies on the C compiler's
+      <literal>-I</literal> options to control the order in which
+      the preprocessor will search the repository directories
+      for <literal>#include</literal> files.
+      This causes a problem, however, with how the C preprocessor
+      handles <literal>#include</literal> lines with
+      the file name included in double-quotes.
+
+      </para>
+
+      <para>
+
+      As we've seen,
+      &SCons; will compile the &hello_c; file from
+      the repository if it doesn't exist in
+      the local directory.
+      If, however, the &hello_c; file in the repository contains
+      a <literal>#include</literal> line with the file name in
+      double quotes:
+
+      </para>
+
+      <programlisting>
+        #include "hello.h"
+        int
+        main(int argc, char *argv[])
+        {
+            printf(HELLO_MESSAGE);
+            return (0);
+        }
+      </programlisting>
+
+      <para>
+
+      Then the C preprocessor will <emphasis>always</emphasis>
+      use a &hello_h; file from the repository directory first,
+      even if there is a &hello_h; file in the local directory,
+      despite the fact that the command line specifies
+      <literal>-I</literal> as the first option:
+
+      </para>
+
+      
+
+      <screen>
+        % <userinput>scons -Q</userinput>
+        cc -o hello.o -c -I. -I/usr/repository1 /usr/repository1/hello.c
+        cc -o hello hello.o
+      </screen>
+
+      <para>
+
+      This behavior of the C preprocessor--always search
+      for a <literal>#include</literal> file in double-quotes
+      first in the same directory as the source file,
+      and only then search the <literal>-I</literal>--can
+      not, in general, be changed.
+      In other words, it's a limitation
+      that must be lived with if you want to use
+      code repositories in this way.
+      There are three ways you can possibly
+      work around this C preprocessor behavior:
+
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+        <para>
+
+        Some modern versions of C compilers do have an option
+        to disable or control this behavior.
+        If so, add that option to &cv-CFLAGS;
+        (or &cv-CXXFLAGS; or both) in your construction environment(s).
+        Make sure the option is used for all construction
+        environments that use C preprocessing!
+
+        </para>
+        </listitem>
+
+        <listitem>
+        <para>
+
+        Change all occurrences of <literal>#include "file.h"</literal>
+        to <literal>#include &lt;file.h&gt;</literal>.
+        Use of <literal>#include</literal> with angle brackets
+        does not have the same behavior--the <literal>-I</literal>
+        directories are searched first
+        for <literal>#include</literal> files--which
+        gives &SCons; direct control over the list of
+        directories the C preprocessor will search.
+
+        </para>
+        </listitem>
+
+        <listitem>
+        <para>
+
+        Require that everyone working with compilation from
+        repositories check out and work on entire directories of files,
+        not individual files.
+        (If you use local wrapper scripts around
+        your source code control system's command,
+        you could add logic to enforce this restriction there.
+
+        </para>
+        </listitem>
+
+      </orderedlist>
+
+    </section>
+
   </section>
 
   <section>
@@ -346,9 +467,9 @@ subdirectories under the repository tree.
     <screen>
       % <userinput>cd /usr/repository1</userinput>
       % <userinput>scons -Q</userinput>
-      cc -c -o file1.o file1.c
-      cc -c -o file2.o file2.c
-      cc -c -o hello.o hello.c
+      cc -o file1.o -c file1.c
+      cc -o file2.o -c file2.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o file1.o file2.o
     </screen>
 
diff --git a/doc/user/separate.sgml b/doc/user/separate.sgml
index 1c04f8a..5f0341d 100644
--- a/doc/user/separate.sgml
+++ b/doc/user/separate.sgml
@@ -154,7 +154,7 @@ program using the F<build/foo.c> path name.
       % <userinput>ls src</userinput>
       SConscript  hello.c
       % <userinput>scons -Q</userinput>
-      cc -c -o build/hello.o build/hello.c
+      cc -o build/hello.o -c build/hello.c
       cc -o build/hello build/hello.o
       % <userinput>ls build</userinput>
       SConscript  hello  hello.c  hello.o
@@ -350,7 +350,7 @@ program using the F<build/foo.c> path name.
       % <userinput>ls src</userinput>
       hello.c
       % <userinput>scons -Q</userinput>
-      cc -c -o build/hello.o build/hello.c
+      cc -o build/hello.o -c build/hello.c
       cc -o build/hello build/hello.o
       % <userinput>ls build</userinput>
       hello  hello.c  hello.o
@@ -380,7 +380,7 @@ program using the F<build/foo.c> path name.
       % <userinput>ls src</userinput>
       hello.c
       % <userinput>scons -Q</userinput>
-      cc -c -o build/hello.o src/hello.c
+      cc -o build/hello.o -c src/hello.c
       cc -o build/hello build/hello.o
       % <userinput>ls build</userinput>
       hello  hello.o
@@ -429,7 +429,7 @@ program using the F<build/foo.c> path name.
       % <userinput>ls src</userinput>
       SConscript  hello.c
       % <userinput>scons -Q</userinput>
-      cc -c -o build/hello.o build/hello.c
+      cc -o build/hello.o -c build/hello.c
       cc -o build/hello build/hello.o
       % <userinput>ls build</userinput>
       SConscript  hello  hello.c  hello.o
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
index fc68d17..9d3617d 100644
--- a/doc/user/simple.sgml
+++ b/doc/user/simple.sgml
@@ -91,7 +91,7 @@
       scons: Reading SConscript files ...
       scons: done reading SConscript files.
       scons: Building targets ...
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
       scons: done building targets.
    </screen>
@@ -179,7 +179,7 @@
       scons: Reading SConscript files ...
       scons: done reading SConscript files.
       scons: Building targets ...
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       scons: done building targets.
    </screen>
 
@@ -275,7 +275,7 @@
       scons: Reading SConscript files ...
       scons: done reading SConscript files.
       scons: Building targets ...
-      cc -c -o hello.o hello.c
+      cc -o hello.o -c hello.c
       cc -o hello hello.o
       scons: done building targets.
       % <userinput>scons -c</userinput>
@@ -469,9 +469,9 @@
        Finished calling Program()
        scons: done reading SConscript files.
        scons: Building targets ...
-       cc -c -o goodbye.o goodbye.c
+       cc -o goodbye.o -c goodbye.c
        cc -o goodbye goodbye.o
-       cc -c -o hello.o hello.c
+       cc -o hello.o -c hello.c
        cc -o hello hello.o
        scons: done building targets.
      </screen>
diff --git a/doc/user/sourcecode.sgml b/doc/user/sourcecode.sgml
index 6ea0b21..6cb4162 100644
--- a/doc/user/sourcecode.sgml
+++ b/doc/user/sourcecode.sgml
@@ -52,7 +52,7 @@
      % <userinput>scons -Q</userinput>
      bk get -
      bk get hello.c
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
    </screen>
 
@@ -77,7 +77,7 @@
      % <userinput>scons -Q</userinput>
      cvs -d /usr/local/CVS co -
      cvs -d /usr/local/CVS co hello.c
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
    </screen>
 
@@ -102,7 +102,7 @@
      % <userinput>scons -Q</userinput>
      co -
      co hello.c
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
    </screen>
 
@@ -127,7 +127,7 @@
      % <userinput>scons -Q</userinput>
      sccs get -
      sccs get hello.c
-     cc -c -o hello.o hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
    </screen>
 
diff --git a/doc/user/troubleshoot.sgml b/doc/user/troubleshoot.sgml
index 5cd1c9e..f019baa 100644
--- a/doc/user/troubleshoot.sgml
+++ b/doc/user/troubleshoot.sgml
@@ -133,15 +133,15 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -c -o file1.o file1.c
-      cc -c -o file2.o file2.c
-      cc -c -o file3.o file3.c
+      cc -o file1.o -c file1.c
+      cc -o file2.o -c file2.c
+      cc -o file3.o -c file3.c
       cc -o prog file1.o file2.o file3.o
       % <userinput>edit file2.c</userinput>
           [CHANGE THE CONTENTS OF file2.c]
       % <userinput>scons -Q --debug=explain</userinput>
       scons: rebuilding `file2.o' because `file2.c' changed
-      cc -c -o file2.o file2.c
+      cc -o file2.o -c file2.c
       scons: rebuilding `prog' because `file2.o' changed
       cc -o prog file1.o file2.o file3.o
     </screen>
@@ -167,17 +167,17 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -I. -c -o file1.o file1.c
-      cc -I. -c -o file2.o file2.c
-      cc -I. -c -o file3.o file3.c
+      cc -o file1.o -c -I. file1.c
+      cc -o file2.o -c -I. file2.c
+      cc -o file3.o -c -I. file3.c
       cc -o prog file1.o file2.o file3.o
       % <userinput>edit hello.h</userinput>
           [CHANGE THE CONTENTS OF hello.h]
       % <userinput>scons -Q --debug=explain</userinput>
       scons: rebuilding `file1.o' because `hello.h' changed
-      cc -I. -c -o file1.o file1.c
+      cc -o file1.o -c -I. file1.c
       scons: rebuilding `file3.o' because `hello.h' changed
-      cc -I. -c -o file3.o file3.c
+      cc -o file3.o -c -I. file3.c
       scons: rebuilding `prog' because:
                  `file1.o' changed
                  `file3.o' changed
@@ -226,6 +226,8 @@
       % <userinput>scons</userinput>
       scons: Reading SConscript files ...
       { 'BUILDERS': {},
+        'CONFIGUREDIR': '#/.sconf_temp',
+        'CONFIGURELOG': '#/config.log',
         'CPPSUFFIXES': [ '.c',
                          '.C',
                          '.cxx',
@@ -240,48 +242,52 @@
                          '.F',
                          '.fpp',
                          '.FPP',
+                         '.m',
+                         '.mm',
                          '.S',
                          '.spp',
                          '.SPP'],
         'DSUFFIXES': ['.d'],
-        'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x829dcb4&gt;,
-        'ENV': {'PATH': '/usr/local/bin:/bin:/usr/bin'},
-        'ESCAPE': &lt;function escape at 0x837d2a4&gt;,
-        'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x829e0fc&gt;,
+        'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43bec&gt;,
+        'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c0c&gt;,
+        'ENV': {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'},
+        'ESCAPE': &lt;function escape at 0xb7b66c34&gt;,
+        'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c2c&gt;,
         'IDLSUFFIXES': ['.idl', '.IDL'],
-        'INSTALL': &lt;function copyFunc at 0x829db9c&gt;,
+        'INSTALL': &lt;function installFunc at 0xb7c41f0c&gt;,
+        'INSTALLSTR': &lt;function installStr at 0xb7c41f44&gt;,
+        'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
         'LIBPREFIX': 'lib',
         'LIBPREFIXES': '$LIBPREFIX',
         'LIBSUFFIX': '.a',
         'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'],
+        'MAXLINELENGTH': 128072,
         'OBJPREFIX': '',
         'OBJSUFFIX': '.o',
-        'PDFPREFIX': '',
-        'PDFSUFFIX': '.pdf',
         'PLATFORM': 'posix',
         'PROGPREFIX': '',
         'PROGSUFFIX': '',
-        'PSPAWN': &lt;function piped_env_spawn at 0x837d384&gt;,
-        'PSPREFIX': '',
-        'PSSUFFIX': '.ps',
-        'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x829e46c&gt;,
+        'PSPAWN': &lt;function piped_env_spawn at 0xb7b66fb4&gt;,
+        'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c4c&gt;,
         'SCANNERS': [],
         'SHELL': 'sh',
         'SHLIBPREFIX': '$LIBPREFIX',
         'SHLIBSUFFIX': '.so',
         'SHOBJPREFIX': '$OBJPREFIX',
         'SHOBJSUFFIX': '$OBJSUFFIX',
-        'SPAWN': &lt;function spawnvpe_spawn at 0x8377fdc&gt;,
-        'TEMPFILE': &lt;class SCons.Defaults.NullCmdGenerator at 0x829ddec&gt;,
+        'SPAWN': &lt;function spawnvpe_spawn at 0xb7b66a74&gt;,
+        'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7bd37ac&gt;,
+        'TEMPFILEPREFIX': '@',
         'TOOLS': [],
         '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
-        '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET)} $)',
-        '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET)} $)',
+        '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
+        '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
         '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
         '__RPATH': '$_RPATH',
-        '_concat': &lt;function _concat at 0x829dc0c&gt;,
-        '_defines': &lt;function _defines at 0x829dc7c&gt;,
-        '_stripixes': &lt;function _stripixes at 0x829dc44&gt;}
+        '_concat': &lt;function _concat at 0xb7c41fb4&gt;,
+        '_defines': &lt;function _defines at 0xb7c47064&gt;,
+        '_installStr': &lt;function installStr at 0xb7c41f44&gt;,
+        '_stripixes': &lt;function _stripixes at 0xb7c4702c&gt;}
       scons: done reading SConscript files.
       scons: Building targets ...
       scons: `.' is up to date.
@@ -298,14 +304,17 @@
     <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      { 'BUILDERS': {'Object': &lt;SCons.Memoize.MultiStepBuilder object at 0x83493e4&gt;, 'SharedObject': &lt;SCons.Memoize.MultiStepBuilder object at 0x8349fec&gt;, 'StaticObject': &lt;SCons.Memoize.MultiStepBuilder object at 0x83493e4&gt;, 'PCH': &lt;SCons.Memoize.BuilderBase object at 0x83418cc&gt;, 'RES': &lt;SCons.Memoize.BuilderBase object at 0x8367cec&gt;},
+      { 'BUILDERS': {'Object': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6024c&gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b603cc&gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6024c&gt;, 'PCH': &lt;SCons.Builder.BuilderBase instance at 0xb7bd2eac&gt;, 'RES': &lt;SCons.Builder.BuilderBase instance at 0xb7b596ec&gt;},
         'CC': 'cl',
-        'CCCOM': &lt;SCons.Memoize.FunctionAction object at 0x8340454&gt;,
+        'CCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b6086c&gt;,
         'CCCOMFLAGS': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo$TARGET $CCPCHFLAGS $CCPDBFLAGS',
         'CCFLAGS': ['/nologo'],
         'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'],
         'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'],
         'CFILESUFFIX': '.c',
+        'CFLAGS': [],
+        'CONFIGUREDIR': '#/.sconf_temp',
+        'CONFIGURELOG': '#/config.log',
         'CPPDEFPREFIX': '/D',
         'CPPDEFSUFFIX': '',
         'CPPSUFFIXES': [ '.c',
@@ -322,6 +331,8 @@
                          '.F',
                          '.fpp',
                          '.FPP',
+                         '.m',
+                         '.mm',
                          '.S',
                          '.spp',
                          '.SPP'],
@@ -330,17 +341,21 @@
         'CXXFILESUFFIX': '.cc',
         'CXXFLAGS': ['$CCFLAGS', '$(', '/TP', '$)'],
         'DSUFFIXES': ['.d'],
-        'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x829dcb4&gt;,
+        'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58bec&gt;,
+        'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c0c&gt;,
         'ENV': { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include',
                  'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib',
                  'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin',
-                 'PATHEXT': '.COM;.EXE;.BAT;.CMD'},
-        'ESCAPE': &lt;function &lt;lambda&gt; at 0x82339ec&gt;,
-        'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x829e0fc&gt;,
+                 'PATHEXT': '.COM;.EXE;.BAT;.CMD',
+                 'SystemRoot': 'C:/WINDOWS'},
+        'ESCAPE': &lt;function escape at 0xb7bc917c&gt;,
+        'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c2c&gt;,
         'IDLSUFFIXES': ['.idl', '.IDL'],
         'INCPREFIX': '/I',
         'INCSUFFIX': '',
-        'INSTALL': &lt;function copyFunc at 0x829db9c&gt;,
+        'INSTALL': &lt;function installFunc at 0xb7c56f0c&gt;,
+        'INSTALLSTR': &lt;function installStr at 0xb7c56f44&gt;,
+        'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
         'LIBPREFIX': '',
         'LIBPREFIXES': ['$LIBPREFIX'],
         'LIBSUFFIX': '.lib',
@@ -352,22 +367,19 @@
         'OBJSUFFIX': '.obj',
         'PCHCOM': '$CXX $CXXFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo${TARGETS[1]} /Yc$PCHSTOP /Fp${TARGETS[0]} $CCPDBFLAGS $PCHPDBFLAGS',
         'PCHPDBFLAGS': ['${(PDB and "/Yd") or ""}'],
-        'PDFPREFIX': '',
-        'PDFSUFFIX': '.pdf',
         'PLATFORM': 'win32',
         'PROGPREFIX': '',
         'PROGSUFFIX': '.exe',
-        'PSPAWN': &lt;function piped_spawn at 0x8372bc4&gt;,
-        'PSPREFIX': '',
-        'PSSUFFIX': '.ps',
+        'PSPAWN': &lt;function piped_spawn at 0xb7bc90d4&gt;,
         'RC': 'rc',
         'RCCOM': '$RC $_CPPDEFFLAGS $_CPPINCFLAGS $RCFLAGS /fo$TARGET $SOURCES',
         'RCFLAGS': [],
-        'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x829e46c&gt;,
+        'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c4c&gt;,
         'SCANNERS': [],
         'SHCC': '$CC',
-        'SHCCCOM': &lt;SCons.Memoize.FunctionAction object at 0x83494bc&gt;,
+        'SHCCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b608cc&gt;,
         'SHCCFLAGS': ['$CCFLAGS'],
+        'SHCFLAGS': ['$CFLAGS'],
         'SHCXX': '$CXX',
         'SHCXXCOM': '$SHCXX $SHCXXFLAGS $CCCOMFLAGS',
         'SHCXXFLAGS': ['$CXXFLAGS'],
@@ -376,17 +388,19 @@
         'SHLIBSUFFIX': '.dll',
         'SHOBJPREFIX': '$OBJPREFIX',
         'SHOBJSUFFIX': '$OBJSUFFIX',
-        'SPAWN': &lt;function spawn at 0x8374c34&gt;,
+        'SPAWN': &lt;function spawn at 0xb7bc9144&gt;,
         'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1,
-        'TEMPFILE': &lt;class SCons.Platform.win32.TempFileMunge at 0x835edc4&gt;,
+        'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7be87ac&gt;,
+        'TEMPFILEPREFIX': '@',
         'TOOLS': ['msvc'],
         '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
-        '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET)} $)',
-        '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET)} $)',
+        '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
+        '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
         '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
-        '_concat': &lt;function _concat at 0x829dc0c&gt;,
-        '_defines': &lt;function _defines at 0x829dc7c&gt;,
-        '_stripixes': &lt;function _stripixes at 0x829dc44&gt;}
+        '_concat': &lt;function _concat at 0xb7c56fb4&gt;,
+        '_defines': &lt;function _defines at 0xb7c5c064&gt;,
+        '_installStr': &lt;function installStr at 0xb7c56f44&gt;,
+        '_stripixes': &lt;function _stripixes at 0xb7c5c02c&gt;}
       scons: done reading SConscript files.
       scons: Building targets ...
       scons: `.' is up to date.
@@ -431,7 +445,7 @@
     <screen>
       % <userinput>scons</userinput>
       scons: Reading SConscript files ...
-      {'PATH': '/usr/local/bin:/bin:/usr/bin'}
+      {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}
       scons: done reading SConscript files.
       scons: Building targets ...
       scons: `.' is up to date.
@@ -450,7 +464,8 @@
       { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include',
         'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib',
         'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin',
-        'PATHEXT': '.COM;.EXE;.BAT;.CMD'}
+        'PATHEXT': '.COM;.EXE;.BAT;.CMD',
+        'SystemRoot': 'C:/WINDOWS'}
       scons: done reading SConscript files.
       scons: Building targets ...
       scons: `.' is up to date.
diff --git a/doc/user/variants.sgml b/doc/user/variants.sgml
index 57d96e0..6727859 100644
--- a/doc/user/variants.sgml
+++ b/doc/user/variants.sgml
@@ -91,9 +91,9 @@ is pretty smart about rebuilding things when you change options.
   <screen>
     % <userinput>scons -Q OS=linux</userinput>
     Install file: "build/linux/world/world.h" as "export/linux/include/world.h"
-    cc -Iexport/linux/include -c -o build/linux/hello/hello.o build/linux/hello/hello.c
-    cc -Iexport/linux/include -c -o build/linux/world/world.o build/linux/world/world.c
-    ar r build/linux/world/libworld.a build/linux/world/world.o
+    cc -o build/linux/hello/hello.o -c -Iexport/linux/include build/linux/hello/hello.c
+    cc -o build/linux/world/world.o -c -Iexport/linux/include build/linux/world/world.c
+    ar rc build/linux/world/libworld.a build/linux/world/world.o
     ranlib build/linux/world/libworld.a
     Install file: "build/linux/world/libworld.a" as "export/linux/lib/libworld.a"
     cc -o build/linux/hello/hello build/linux/hello/hello.o -Lexport/linux/lib -lworld
author	Steven Knight <knight@baldmt.com>	2007-02-11 05:02:05 (GMT)
committer	Steven Knight <knight@baldmt.com>	2007-02-11 05:02:05 (GMT)
commit	895bf33464c921fecdee7ac5e770ce1009bd2c57 (patch)
tree	107c065697f6b6bb61356d82f4876df7f0eb378c /doc
parent	79248be790aa3e46ee7b0a2dc080f211dcca9aa7 (diff)
download	SCons-895bf33464c921fecdee7ac5e770ce1009bd2c57.zip SCons-895bf33464c921fecdee7ac5e770ce1009bd2c57.tar.gz SCons-895bf33464c921fecdee7ac5e770ce1009bd2c57.tar.bz2