Fix man page formatting when using Safari. (Gary Oberbrunner)

1 files changed, 1835 insertions, 1342 deletions

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 490975d..5e1e7b7 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -28,10 +28,10 @@
 ..
 .\" EE - Example End - ends indent and turns line fill back on
 .de EE
-.RE
 .fi
+.RE
 ..
-.TH SCONS 1 "September 2003"
+.TH SCONS 1 "November 2003"
 .SH NAME
 scons \- a software construction tool
 .SH SYNOPSIS
@@ -891,6 +891,7 @@ variable after the Environment is constructed will not cause the tools to
 be redetected.
 
 SCons supports the following tool specifications out of the box:
+
 .ES
 386asm
 aixc++
@@ -978,33 +979,38 @@ can lead to a lot of quoting,
 .B scons
 supplies a
 .B Split()
-function that splits a single string
+global function
+and a same-named environment method
+that split a single string
 into a list, separated on
 strings of white-space characters.
-(This is similar to the
+(These are similar to the
 string.split() method
-from the standard Python library.)
+from the standard Python library,
+but work even if the input isn't a string.)
 
 Like all Python arguments,
-the target and source arguments to a builder
+the target and source arguments to a builder method
 can be specified either with or without
 the "target" and "source" keywords.
 When the keywords are omitted,
 the target is first,
 followed by the source.
-The following are equivalent examples of calling the Program builder:
+The following are equivalent examples of calling the Program builder method:
 
 .ES
 env.Program('bar', ['bar.c', 'foo.c'])
 env.Program('bar', Split('bar.c foo.c'))
+env.Program('bar', env.Split('bar.c foo.c'))
 env.Program(source =  ['bar.c', 'foo.c'], target = 'bar')
 env.Program(target = 'bar', Split('bar.c foo.c'))
+env.Program(target = 'bar', env.Split('bar.c foo.c'))
 env.Program('bar', source = string.split('bar.c foo.c'))
 .EE
 
 When the target shares the same base name
 as the source and only the suffix varies,
-and if the builder has a suffix defined for the target file type,
+and if the builder method has a suffix defined for the target file type,
 then the target argument may be omitted completely,
 and
 .B scons
@@ -1027,7 +1033,8 @@ env.Program('bar.c')
 .EE
 
 It is possible to override or add construction variables when calling a
-builder by passing additional keyword arguments. These overridden or added
+builder method by passing additional keyword arguments.
+These overridden or added
 variables will only be in effect when building the target, so they will not
 affect other parts of the build. For example, if you want to add additional
 libraries for just one program:
@@ -1042,7 +1049,24 @@ or generate a shared library with a nonstandard suffix:
 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
 .EE
 
-All Builders return a Node or a list of Nodes,
+Although the builder methods defined by
+.B scons
+are, in fact,
+methods of a construction environment object,
+they may also be called without an explicit environment:
+
+.ES
+Program('hello', 'hello.c')
+SharedLibrary('word', 'word.cpp')
+.EE
+
+In this case,
+the methods are called internally using a default construction
+environment that consists of the tools and values that
+.B scons
+has determined are appropriate for the local system.
+
+All builder methods return a Node or a list of Nodes,
 representing the target or targets that will be built.
 A list of Nodes is returned if there is more than one target,
 and a single Node is returned if there is only one target.
@@ -1054,7 +1078,7 @@ build targets or sources.
 
 The returned Node(s)
 can be passed to other builder methods as source(s)
-or passed into to any SCons function or method
+or passed to any SCons function or method
 where a filename would normally be accepted.
 For example, if it were necessary
 to add a specific
@@ -1070,7 +1094,7 @@ Using a Node in this way
 makes for a more portable build
 by avoiding having to specify
 a platform-specific object suffix
-when calling the Program() builder.
+when calling the Program() builder method.
 
 The path name for a Node's file may be used
 by passing the Node to the Python-builtin
@@ -1083,123 +1107,213 @@ print "The path to bar_obj is:", str(bar_obj)
 .EE
 
 .B scons
-provides the following builders:
+provides the following builder methods:
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP CFile()
+.IP env.CFile()
+Builds a C source file given a lex (.l) or yacc (.y) input file.
+The suffix specified by the $CFILESUFFIX construction variable
+(.c by default)
+is automatically added to the target
+if it is not already present. Example:
 
-.IP StaticObject
-Builds a static object file
-from one or more C, C++, or Fortran source files.
-Source files must have one of the following extensions:
 .ES
-  .asm    assembly language file
-  .ASM    assembly language file
-  .c      C file
-  .C      WIN32:  C file
-          POSIX:  C++ file
-  .cc     C++ file
-  .cpp    C++ file
-  .cxx    C++ file
-  .cxx    C++ file
-  .c++    C++ file
-  .C++    C++ file
-  .f      Fortran file
-  .F      WIN32:  Fortran file
-          POSIX:  Fortran file + C pre-processor
-  .for    Fortran file
-  .FOR    Fortran file
-  .fpp    Fortran file + C pre-processor
-  .FPP    Fortran file + C pre-processor
-  .s      assembly language file
-  .S      WIN32:  assembly language file
-          POSIX:  assembly language file + C pre-processor
-  .spp    assembly language file + C pre-processor
-  .SPP    assembly language file + C pre-processor
+# builds foo.c
+env.CFile(target = 'foo.c', source = 'foo.l')
+# builds bar.c
+env.CFile(target = 'bar', source = 'bar.y')
 .EE
-.IP
-The target object file prefix
-(specified by the $OBJPREFIX construction variable; nothing by default)
-and suffix
-(specified by the $OBJSUFFIX construction variable;
-\.obj on Windows systems, .o on POSIX systems)
-are automatically added to the target if not already present.
-Examples:
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP CXXFile()
+.IP env.CXXFile()
+Builds a C++ source file given a lex (.ll), yacc (.yy)
+or uic (.ui) input file.
+The suffix specified by the $CXXFILESUFFIX construction variable
+(.cc by default)
+is automatically added to the target
+if it is not already present. Example:
 
 .ES
-env.StaticObject(target = 'aaa', source = 'aaa.c')
-env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
-env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
+# builds foo.cc
+env.CXXFile(target = 'foo.cc', source = 'foo.ll')
+# builds bar.cc
+env.CXXFile(target = 'bar', source = 'bar.yy')
 .EE
-.IP SharedObject
-Builds an object file for
-inclusion in a shared library.
-Source files must have one of the same set of extensions
-specified above for the
-.B StaticObject
-builder. On some platforms building a shared object requires additional
-compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
-normal (static) object, but on some platforms there is no difference between a
-shared object and a normal (static) one. When there is a difference, SCons
-will only allow shared objects to be linked into a shared library, and will
-use a different suffix for shared objects. On platforms where there is no
-difference, SCons will allow both normal (static)
-and shared objects to be linked into a
-shared library, and will use the same suffix for shared and normal
-(static) objects.
-The target object file prefix
-(specified by the $SHOBJPREFIX construction variable;
-by default, the same as $OBJPREFIX)
-and suffix
-(specified by the $SHOBJSUFFIX construction variable)
-are automatically added to the target if not already present. 
-Examples:
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP DVI()
+.IP env.DVI()
+Builds a .dvi file from a .tex, .ltx or .latex input file.
+If the source file suffix is .tex,
+.B scons
+will examine the contents of the file;
+if the string
+.B \\documentclass
+or
+.B \\documentstyle
+is found, the file is assumed to be a LaTeX file and
+the target is built by invoking the $LATEXCOM command line;
+otherwise, the $TEXCOM command line is used.
+If the file is a LaTeX file,
+the
+.B DVI
+builder method will also examine the contents
+of the
+.B .aux file
+and invoke the $BIBTEX command line
+if the string
+.B bibdata
+is found,
+and will examine the contents
+.B .log
+file and re-run the $LATEXCOM command
+if the log file says it is necessary.
+
+The suffix .dvi
+(hard-coded within TeX itself)
+is automatically added to the target
+if it is not already present. Examples:
 
 .ES
-env.SharedObject(target = 'ddd', source = 'ddd.c')
-env.SharedObject(target = 'eee.o', source = 'eee.cpp')
-env.SharedObject(target = 'fff.obj', source = 'fff.for')
+# builds from aaa.tex
+env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
+# builds bbb.dvi
+env.DVI(target = 'bbb', source = 'bbb.ltx')
+# builds from ccc.latex
+env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
 .EE
 
-.IP Object
-A synonym for the
-.B StaticObject
-builder.
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP Jar()
+.IP env.Jar()
+Builds a Java archive (.jar) file
+from a source tree of .class files.
+If the $JAVACHDIR value is set, the
+.B jar
+command will change to the specified directory using the
+.B \-C
+option.
+If the contents any of the source files begin with the string
+.BR Manifest-Version ,
+the file is assumed to be a manifest
+and is passed to the
+.B jar
+command with the
+.B m
+option set.
 
-.IP PCH
-Builds a Microsoft Visual C++ precompiled header. Calling this builder
-returns a list of two targets: the PCH as the first element, and the object
-file as the second element. Normally the object file is ignored. This builder is only
-provided when Microsoft Visual C++ is being used as the compiler. 
-The PCH builder is generally used in
-conjuction with the PCH construction variable to force object files to use
-the precompiled header:
+.ES
+env.Jar(target = 'foo.jar', source = 'classes')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP Java()
+.IP env.Java()
+Builds one or more Java class files
+from a source tree of .java files.
+The class files will be placed underneath
+the specified target directory.
+SCons will parse each source .java file
+to find the classes
+(including inner classes)
+defined within that file,
+and from that figure out the
+target .class files that will be created.
+SCons will also search each Java file
+for the Java package name,
+which it assumes can be found on a line
+beginning with the string
+.B package
+in the first column;
+the resulting .class files
+will be placed in a directory reflecting
+the specified package name.
+For example,
+the file
+.I Foo.java
+defining a single public
+.I Foo
+class and
+containing a package name of
+.I sub.dir
+will generate a corresponding
+.IR sub/dir/Foo.class
+class file.
+
+Example:
 
 .ES
-env['PCH'] = env.PCH('StdAfx.cpp')[0]
+env.Java(target = 'classes', source = 'src')
 .EE
 
-.IP Program
-Builds an executable given one or more object files or C, C++
-or Fortran source files.
-If any C, C++ or Fortran source files are specified,
-then they will be automatically
-compiled to object files using the
-.B Object
-builder;
-see that builder's description for
-a list of legal source file suffixes
-and how they are interpreted.
-The target executable file prefix
-(specified by the $PROGPREFIX construction variable; nothing by default)
-and suffix
-(specified by the $PROGSUFFIX construction variable;
-by default, .exe on Windows systems, nothing on POSIX systems)
-are automatically added to the target if not already present.
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP JavaH()
+.IP env.JavaH()
+Builds C header and source files for
+implementing Java native methods.
+The target can be either a directory
+in which the header files will be written,
+or a header file name which
+will contain all of the definitions.
+The source can be either the names of .class files,
+or the objects returned from the
+.B Java
+builder method.
+
+If the construction variable
+.B JAVACLASSDIR
+is set, either in the environment
+or in the call to the
+.B JavaH
+builder method itself,
+then the value of the variable
+will be stripped from the
+beginning of any .class file names.
+
+Examples:
+
+.ES
+# builds java_native.h
+classes = env.Java(target = 'classdir', source = 'src')
+env.JavaH(target = 'java_native.h', source = classes)
+
+# builds include/package_foo.h and include/package_bar.h
+env.JavaH(target = 'include',
+          source = ['package/foo.class', 'package/bar.class'])
+
+# builds export/foo.h and export/bar.h
+env.JavaH(target = 'export',
+          source = ['classes/foo.class', 'classes/bar.class'],
+          JAVACLASSDIR = 'classes')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP Library()
+.IP env.Library()
+A synonym for the
+.B StaticLibrary
+builder method.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP M4()
+.IP env.M4()
+Builds an output file from an M4 input file.
+This uses a default $M4FLAGS value of
+.BR -E ,
+which considers all warnings to be fatal
+and stops on the first warning
+when using the GNU version of m4.
 Example:
 
 .ES
-env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
+env.M4(target = 'foo.c', source = 'foo.c.m4')
 .EE
 
-.IP MSVSProject
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP MSVSProject()
+.IP env.MSVSProject()
 Builds Microsoft Visual Studio project files.
 This builds a Visual Studio project file, based on the version of
 Visual Studio that is configured (either the latest installed version,
@@ -1272,9 +1386,94 @@ Example Usage:
                           variant = 'Release')
 .EE
 
-.IP RES
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP Object()
+.IP env.Object()
+A synonym for the
+.B StaticObject
+builder method.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP PCH()
+.IP env.PCH()
+Builds a Microsoft Visual C++ precompiled header.
+Calling this builder method
+returns a list of two targets: the PCH as the first element, and the object
+file as the second element. Normally the object file is ignored.
+This builder method is only
+provided when Microsoft Visual C++ is being used as the compiler. 
+The PCH builder method is generally used in
+conjuction with the PCH construction variable to force object files to use
+the precompiled header:
+
+.ES
+env['PCH'] = env.PCH('StdAfx.cpp')[0]
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP PDF()
+.IP env.PDF()
+Builds a .pdf file from a .dvi input file
+(or, by extension, a .tex, .ltx, or .latex input file).
+The suffix specified by the $PDFSUFFIX construction variable
+(.pdf by default)
+is added automatically to the target
+if it is not already present.  Example:
+
+.ES
+# builds from aaa.tex
+env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
+# builds bbb.pdf from bbb.dvi
+env.PDF(target = 'bbb', source = 'bbb.dvi')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP PostScript()
+.IP env.PostScript()
+Builds a .ps file from a .dvi input file
+(or, by extension, a .tex, .ltx, or .latex input file).
+The suffix specified by the $PSSUFFIX construction variable
+(.ps by default)
+is added automatically to the target
+if it is not already present.  Example:
+
+.ES
+# builds from aaa.tex
+env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
+# builds bbb.ps from bbb.dvi
+env.PostScript(target = 'bbb', source = 'bbb.dvi')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP Program()
+.IP env.Program()
+Builds an executable given one or more object files or C, C++
+or Fortran source files.
+If any C, C++ or Fortran source files are specified,
+then they will be automatically
+compiled to object files using the
+.B Object
+builder method;
+see that builder method's description for
+a list of legal source file suffixes
+and how they are interpreted.
+The target executable file prefix
+(specified by the $PROGPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $PROGSUFFIX construction variable;
+by default, .exe on Windows systems, nothing on POSIX systems)
+are automatically added to the target if not already present.
+Example:
+
+.ES
+env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP RES()
+.IP env.RES()
 Builds a Microsoft Visual C++ resource file.
-This builder is only provided
+This builder method is only provided
 when Microsoft Visual C++ or MinGW is being used as the compiler. The
 .I .res
 (or 
@@ -1286,38 +1485,45 @@ file is scanned for implicit dependencies as though it were a C file. Example:
 env.RES('resource.rc')
 .EE
 
-.IP StaticLibrary
-Builds a static library given one or more object files
-or C, C++ or Fortran source files.
-If any source files are given,
-then they will be automatically
-compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the $LIBPREFIX construction variable;
-by default, lib on POSIX systems, nothing on Windows systems)
-and suffix
-(specified by the $LIBSUFFIX construction variable;
-by default, .lib on Windows systems, .a on POSIX systems)
-are automatically added to the target if not already present.
-Example:
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP RMIC()
+.IP env.RMIC()
+Builds stub and skeleton class files
+for remote objects
+from Java .class files.
+The target is a directory
+relative to which the stub
+and skeleton class files will be written.
+The source can be the names of .class files,
+or the objects return from the
+.B Java
+builder method.
+
+If the construction variable
+.B JAVACLASSDIR
+is set, either in the environment
+or in the call to the
+.B RMIC
+builder method itself,
+then the value of the variable
+will be stripped from the
+beginning of any .class file names.
 
 .ES
-env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-.EE
+classes = env.Java(target = 'classdir', source = 'src')
+env.RMIC(target = 'outdir1', source = classes)
 
-.IP
-Any object files listed in the
-.B source
-must have been built for a static library
-(that is, using the
-.B StaticObject
-builder).
-.B scons
-will raise an error if there is any mismatch.
+env.RMIC(target = 'outdir2',
+         source = ['package/foo.class', 'package/bar.class'])
 
-.IP SharedLibrary
+env.RMIC(target = 'outdir3',
+         source = ['classes/foo.class', 'classes/bar.class'],
+         JAVACLASSDIR = 'classes')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP SharedLibrary()
+.IP env.SharedLibrary()
 Builds a shared library
 (.so on a POSIX system, .dll on WIN32)
 given one or more object files
@@ -1342,7 +1548,7 @@ env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
 .IP
 On WIN32 systems, the
 .B SharedLibrary
-builder will always build an import (.lib) library
+builder method will always build an import (.lib) library
 in addition to the shared (.dll) library,
 adding a .lib library with the same basename
 if there is not already a .lib file explicitly
@@ -1353,7 +1559,7 @@ Any object files listed in the
 must have been built for a shared library
 (that is, using the
 .B SharedObject
-builder).
+builder method).
 .B scons
 will raise an error if there is any mismatch.
 .IP
@@ -1374,237 +1580,128 @@ env.SharedLibrary(target = 'bar',
 .IP
 will register "bar.dll" as a COM object when it is done linking it.
 
-.IP Library
-A synonym for the
-.B StaticLibrary
-builder.
-
-.IP CFile
-Builds a C source file given a lex (.l) or yacc (.y) input file.
-The suffix specified by the $CFILESUFFIX construction variable
-(.c by default)
-is automatically added to the target
-if it is not already present. Example:
-
-.ES
-# builds foo.c
-env.CFile(target = 'foo.c', source = 'foo.l')
-# builds bar.c
-env.CFile(target = 'bar', source = 'bar.y')
-.EE
-
-.IP CXXFile
-Builds a C++ source file given a lex (.ll), yacc (.yy)
-or uic (.ui) input file.
-The suffix specified by the $CXXFILESUFFIX construction variable
-(.cc by default)
-is automatically added to the target
-if it is not already present. Example:
-
-.ES
-# builds foo.cc
-env.CXXFile(target = 'foo.cc', source = 'foo.ll')
-# builds bar.cc
-env.CXXFile(target = 'bar', source = 'bar.yy')
-.EE
-
-.IP M4
-Builds an output file from an M4 input file.
-This uses a default $M4FLAGS value of
-.BR -E ,
-which considers all warnings to be fatal
-and stops on the first warning
-when using the GNU version of m4.
-Example:
-
-.ES
-env.M4(target = 'foo.c', source = 'foo.c.m4')
-.EE
-
-.IP Jar
-Builds a Java archive (.jar) file
-from a source tree of .class files.
-.ES
-env.Jar(target = 'foo.jar', source = 'classes')
-.EE
-
-.IP Java
-Builds one or more Java class files
-from a source tree of .java files.
-The class files will be placed underneath
-the specified target directory.
-SCons will parse each source .java file
-to find the classes
-(including inner classes)
-defined within that file,
-and from that figure out the
-target .class files that will be created.
-SCons will also search each Java file
-for the Java package name,
-which it assumes can be found on a line
-beginning with the string
-.B package
-in the first column;
-the resulting .class files
-will be placed in a directory reflecting
-the specified package name.
-For example,
-the file
-.I Foo.java
-defining a single public
-.I Foo
-class and
-containing a package name of
-.I sub.dir
-will generate a corresponding
-.IR sub/dir/Foo.class
-class file.
-
-Example:
-
-.ES
-env.Java(target = 'classes', source = 'src')
-.EE
-
-.IP JavaH
-Builds C header and source files for
-implementing Java native methods.
-The target can be either a directory
-in which the header files will be written,
-or a header file name which
-will contain all of the definitions.
-The source can be either the names of .class files,
-or the objects returned from the
-.B Java
-builder.
-
-If the construction variable
-.B JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.B JavaH
-builder itself,
-then the value of the variable
-will be stripped from the
-beginning of any .class file names.
-
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP SharedObject()
+.IP env.SharedObject()
+Builds an object file for
+inclusion in a shared library.
+Source files must have one of the same set of extensions
+specified above for the
+.B StaticObject
+builder method.
+On some platforms building a shared object requires additional
+compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
+normal (static) object, but on some platforms there is no difference between a
+shared object and a normal (static) one. When there is a difference, SCons
+will only allow shared objects to be linked into a shared library, and will
+use a different suffix for shared objects. On platforms where there is no
+difference, SCons will allow both normal (static)
+and shared objects to be linked into a
+shared library, and will use the same suffix for shared and normal
+(static) objects.
+The target object file prefix
+(specified by the $SHOBJPREFIX construction variable;
+by default, the same as $OBJPREFIX)
+and suffix
+(specified by the $SHOBJSUFFIX construction variable)
+are automatically added to the target if not already present. 
 Examples:
 
 .ES
-# builds java_native.h
-classes = env.Java(target = 'classdir', source = 'src')
-env.JavaH(target = 'java_native.h', source = classes)
-
-# builds include/package_foo.h and include/package_bar.h
-env.JavaH(target = 'include',
-          source = ['package/foo.class', 'package/bar.class'])
-
-# builds export/foo.h and export/bar.h
-env.JavaH(target = 'export',
-          source = ['classes/foo.class', 'classes/bar.class'],
-          JAVACLASSDIR = 'classes')
+env.SharedObject(target = 'ddd', source = 'ddd.c')
+env.SharedObject(target = 'eee.o', source = 'eee.cpp')
+env.SharedObject(target = 'fff.obj', source = 'fff.for')
 .EE
 
-.IP RMIC
-Builds stub and skeleton class files
-for remote objects
-from Java .class files.
-The target is a directory
-relative to which the stub
-and skeleton class files will be written.
-The source can be the names of .class files,
-or the objects return from the
-.B Java
-builder.
-
-If the construction variable
-.B JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.B RMIC
-builder itself,
-then the value of the variable
-will be stripped from the
-beginning of any .class file names.
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP StaticLibrary()
+.IP env.StaticLibrary()
+Builds a static library given one or more object files
+or C, C++ or Fortran source files.
+If any source files are given,
+then they will be automatically
+compiled to object files.
+The static library prefix and suffix (if any)
+are automatically added to the target.
+The target library file prefix
+(specified by the $LIBPREFIX construction variable;
+by default, lib on POSIX systems, nothing on Windows systems)
+and suffix
+(specified by the $LIBSUFFIX construction variable;
+by default, .lib on Windows systems, .a on POSIX systems)
+are automatically added to the target if not already present.
+Example:
 
 .ES
-classes = env.Java(target = 'classdir', source = 'src')
-env.RMIC(target = 'outdir1', source = classes)
-
-env.RMIC(target = 'outdir2',
-         source = ['package/foo.class', 'package/bar.class'])
-
-env.RMIC(target = 'outdir3',
-         source = ['classes/foo.class', 'classes/bar.class'],
-         JAVACLASSDIR = 'classes')
+env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
 .EE
 
-.IP TypeLibrary
-Builds a Windows type library (.tlb) file from and input IDL file
-(.idl).  In addition, it will build the associated inteface stub and
-proxy source files.  It names them according to the base name of the .idl file.
-.IP
-For example,
-
-.ES
-env.TypeLibrary(source="foo.idl")
-.EE
 .IP
-Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
-
-.IP DVI
-Builds a .dvi file from a .tex, .ltx or .latex input file.
-The suffix .dvi
-(hard-coded within TeX itself)
-is automatically added to the target
-if it is not already present. Example:
-
-.ES
-# builds from aaa.tex
-env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
-# builds bbb.dvi
-env.DVI(target = 'bbb', source = 'bbb.ltx')
-# builds from ccc.latex
-env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
-.EE
+Any object files listed in the
+.B source
+must have been built for a static library
+(that is, using the
+.B StaticObject
+builder method).
+.B scons
+will raise an error if there is any mismatch.
 
-.IP PDF
-Builds a .pdf file from a .dvi input file
-(or, by extension, a .tex, .ltx, or .latex input file).
-The suffix specified by the $PDFSUFFIX construction variable
-(.pdf by default)
-is added automatically to the target
-if it is not already present.  Example:
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP StaticObject()
+.IP env.StaticObject()
+Builds a static object file
+from one or more C, C++, or Fortran source files.
+Source files must have one of the following extensions:
 
 .ES
-# builds from aaa.tex
-env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
-# builds bbb.pdf from bbb.dvi
-env.PDF(target = 'bbb', source = 'bbb.dvi')
+  .asm    assembly language file
+  .ASM    assembly language file
+  .c      C file
+  .C      WIN32:  C file
+          POSIX:  C++ file
+  .cc     C++ file
+  .cpp    C++ file
+  .cxx    C++ file
+  .cxx    C++ file
+  .c++    C++ file
+  .C++    C++ file
+  .f      Fortran file
+  .F      WIN32:  Fortran file
+          POSIX:  Fortran file + C pre-processor
+  .for    Fortran file
+  .FOR    Fortran file
+  .fpp    Fortran file + C pre-processor
+  .FPP    Fortran file + C pre-processor
+  .s      assembly language file
+  .S      WIN32:  assembly language file
+          POSIX:  assembly language file + C pre-processor
+  .spp    assembly language file + C pre-processor
+  .SPP    assembly language file + C pre-processor
 .EE
-
-.IP PostScript
-Builds a .ps file from a .dvi input file
-(or, by extension, a .tex, .ltx, or .latex input file).
-The suffix specified by the $PSSUFFIX construction variable
-(.ps by default)
-is added automatically to the target
-if it is not already present.  Example:
+.IP
+The target object file prefix
+(specified by the $OBJPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $OBJSUFFIX construction variable;
+\.obj on Windows systems, .o on POSIX systems)
+are automatically added to the target if not already present.
+Examples:
 
 .ES
-# builds from aaa.tex
-env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
-# builds bbb.ps from bbb.dvi
-env.PostScript(target = 'bbb', source = 'bbb.dvi')
+env.StaticObject(target = 'aaa', source = 'aaa.c')
+env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
+env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
 .EE
 
-.IP Tar
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP Tar()
+.IP env.Tar()
 Builds a tar archive of the specified files
 and/or directories.
-Unlike most builders,
+Unlike most builder methods,
 the
 .B Tar
-builder may be called multiple times
+builder method may be called multiple times
 for a given target;
 each additional call
 adds to the list of entries
@@ -1628,13 +1725,30 @@ env = Environment(TARFLAGS = '-c -z',
 env.Tar('foo')
 .EE
 
-.IP Zip
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP TypeLibrary()
+.IP env.TypeLibrary()
+Builds a Windows type library (.tlb) file from and input IDL file
+(.idl).  In addition, it will build the associated inteface stub and
+proxy source files.  It names them according to the base name of the .idl file.
+.IP
+For example,
+
+.ES
+env.TypeLibrary(source="foo.idl")
+.EE
+.IP
+Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.IP Zip()
+.IP env.Zip()
 Builds a zip archive of the specified files
 and/or directories.
-Unlike most builders,
+Unlike most builder methods,
 the
 .B Zip
-builder may be called multiple times
+builder method may be called multiple times
 for a given target;
 each additional call
 adds to the list of entries
@@ -1668,36 +1782,168 @@ or
 files extensions
 for C preprocessor dependencies,
 so the dependencies do not need to be specified explicitly.
-In addition, all builder
-targets automatically depend on their sources.
+In addition, all
+targets of builder methods automatically depend on their sources.
 An explicit dependency can
 be specified using the 
 .B Depends 
 method of a construction environment (see below).
 
-.SS Other Construction Environment Methods
-Additional construction environment methods include:
+.SS Methods and Functions to Do Things
+In addition to Builder methods,
+.B scons
+provides a number of other construction environment methods
+and global functions to
+manipulate the build configuration.
+
+Usually, a construction environment method
+and global function with the same name both exist
+so that you don't have to remember whether
+to a specific bit of functionality
+must be called with or without a construction environment.
+In the following list,
+if you call something as a global function
+it looks like:
+.ES
+.RI Function( arguments )
+.EE
+and if you call something through a construction
+environment it looks like:
+.ES
+.RI env.Function( arguments )
+.EE
+If you can call the functionality in both ways,
+then both forms are listed.
+
+Except where otherwise noted,
+the same-named
+construction environment method
+and global function 
+provide the exact same functionality.
+The only difference is that,
+where appropriate,
+calling the functionality through a construction environment will
+substitute construction variables into
+any supplied strings.
+For example:
+.ES
+env = Environment(FOO = 'foo')
+Default('$FOO')
+env.Default('$FOO')
+.EE
+the first call to the global
+.B Default()
+function will actually add a target named
+.B $FOO
+to the list of default targets,
+while the second call to the
+.B env.Default()
+construction environment method
+will expand the value
+and add a target named
+.B foo
+to the list of default targets.
+For more on construction variable expansion,
+see the next section on
+construction variables.
+
+Construction environment methods
+and global functions supported by
+.B scons
+include:
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI Action( action ", [" strfunction ", " varlist ])
+.TP
+.RI env.Action( action ", [" strfunction ", " varlist ])
+Creates an Action object for
+the specified
+.IR action .
+See the section "Action Objects,"
+below, for a complete explanation of the arguments and behavior.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI AddPostAction( target ", " action )
+.TP
+.RI env.AddPostAction( target ", " action )
+Arranges for the specified
+.I action
+to be performed
+after the specified
+.I target
+has been built.
+The specified action(s) may be
+an Action object, or anything that
+can be converted into an Action object
+(see below).
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI AddPreAction( target ", " action )
+.TP
+.RI env.AddPreAction( target ", " action )
+Arranges for the specified
+.I action
+to be performed
+before the specified
+.I target
+is built.
+The specified action(s) may be
+an Action object, or anything that
+can be converted into an Action object
+(see below).
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Alias( alias ", [" targets ])
 .TP
-.RI Alias( alias ", " targets )
-Creates a phony target that
-expands to one or more other targets.
+.RI env.Alias( alias ", [" targets ])
+Creates one or more phony targets that
+expand to one or more other targets.
 Returns the Node object representing the alias,
 which exists outside of any file system.
 This Node object, or the alias name,
 may be used as a dependency of any other target,
-including another alias. Alias can be called multiple times for the same
-alias to add additional targets to the alias. There is also an Alias
-global function for creating or referencing an alias independently of
-any construction environment.
+including another alias.
+.B Alias
+can be called multiple times for the same
+alias to add additional targets to the alias.
 
 .ES
+Alias('install')
+Alias('install', '/usr/bin')
+Alias(['install', 'install-lib'], '/usr/local/lib')
+
 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
 env.Alias('install', ['/usr/local/man'])
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI Append( key = val ", [...])"
+.RI AlwaysBuild( target ", ...)"
+.TP
+.RI env.AlwaysBuild( target ", ...)"
+Marks each given
+.I target
+so that it is always assumed to be out of date,
+and will always be rebuilt if needed.
+Note, however, that
+.BR AlwaysBuild ()
+does not add its target(s) to the default target list,
+so the targets will only be built
+if they are specified on the command line,
+or are a dependent of a target specified on the command line--but
+they will
+.I always
+be built if so specified.
+Multiple targets can be passed in to a single call to
+.BR AlwaysBuild ().
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI env.Append( key = val ", [...])"
 Appends the specified keyword arguments
 to the end of construction variables in the environment.
 If the Environment does not have
@@ -1716,38 +1962,9 @@ and the lists are added together.
 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI PrependENVPath( name ", " newpath ", [" envname ", " sep ])
-This appends new path elements to the given path in the
-specified external environment
-.RB ( ENV
-by default).
-This will only add
-any particular path once (leaving the first one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
-.B os.path.normpath
-and
-.BR os.path.normcase ).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-Example:
-
-.ES
-print 'before:',env['ENV']['INCLUDE']
-include_path = '/foo/bar:/foo'
-env.PrependENVPath('INCLUDE', include_path)
-print 'after:',env['ENV']['INCLUDE']
-
-yields:
-before: /biz:/foo
-after: /foo/bar:/foo:/biz
-.EE
-
-.TP
-.RI AppendENVPath( name ", " newpath ", [" envname ", " sep ])
+.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
 This appends new path elements to the given path in the
 specified external environment
 .RB ( ENV
@@ -1776,8 +1993,9 @@ before: /foo:/biz
 after: /biz:/foo/bar:/foo
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-BitKeeper()
+env.BitKeeper()
 A factory function that
 returns a Builder object
 to be used to fetch source files
@@ -1786,12 +2004,232 @@ The returned Builder
 is intended to be passed to the
 .B SourceCode
 function.
+
 .ES
 env.SourceCode('.', env.BitKeeper())
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
+.TP
+.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
+This specifies a build directory
+.I build_dir
+in which to build all derived files
+that would normally be built under
+.IR src_dir .
+Multiple build directories can be set up for multiple build variants, for
+example. 
+.I src_dir
+must be underneath the SConstruct file's directory,
+and
+.I build_dir
+may not be underneath the
+.I src_dir .
+
+The default behavior is for
+.B scons
+to duplicate all of the files in the tree underneath
+.I src_dir
+into
+.IR build_dir ,
+and then build the derived files within the copied tree.
+(The duplication is performed by
+linking or copying,
+depending on the platform.)
+This guarantees correct builds
+regardless of whether intermediate source files
+are generated during the build,
+where preprocessors or other scanners search
+for included files,
+or whether individual compilers or other invoked tools
+are hard-coded to put derived files in the same directory as source files.
+
+This behavior of making a complete copy of the source tree
+may be disabled by setting
+.I duplicate
+to 0.
+This will cause
+.B scons
+to invoke Builders using the
+path names of source files in
+.I src_dir
+and the path names of derived files within
+.IR build_dir .
+This is always more efficient than
+.IR duplicate =1,
+and is usually safe for most builds.
+Specifying
+.IR duplicate =0,
+however,
+may cause build problems
+if source files are generated during the build,
+if any invoked tools are hard-coded to
+put derived files in the same directory as the source files.
+
+Note that specifying a
+.B BuildDir
+works most naturally
+with a subsidiary SConscript file
+in the source directory.
+However,
+you would then call the subsidiary SConscript file
+not in the source directory,
+but in the
+.I build_dir ,
+as if
+.B scons
+had made a virtual copy of the source tree
+regardless of the value of 
+.IR duplicate .
+This is how you tell
+.B scons
+which variant of a source tree to build.
+For example:
+
+.ES
+BuildDir('build-variant1', 'src')
+SConscript('build-variant1/SConscript')
+BuildDir('build-variant2', 'src')
+SConscript('build-variant2/SConscript')
+.EE
+
+.IP
+See also the
+.BR SConscript ()
+function, described below,
+for another way to 
+specify a build directory
+in conjunction with calling a subsidiary
+SConscript file.)
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI Builder( action ", [" multi ", " prefix ", " suffix ", " src_suffix ", " src_builder ", " emitter ])
+.TP 
+.RI env.Builder( action ", [" multi ", " prefix ", " suffix ", " src_suffix ", " src_builder ", " emitter ])
+Creates a Builder object for
+the specified
+.IR action .
+See the section "Builder Objects,"
+below, for a complete explanation of the arguments and behavior.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI CacheDir( cache_dir )
+.TP 
+.RI env.CacheDir( cache_dir )
+Specifies that
+.B scons
+will maintain a cache of derived files in
+.I cache_dir .
+The derived files in the cache will be shared
+among all the builds using the same
+.BR CacheDir ()
+call.
+
+When a
+.BR CacheDir ()
+is being used and
+.B scons
+finds a derived file that needs to be rebuilt,
+it will first look in the cache to see if a
+derived file has already been built
+from identical input files and an identical build action
+(as incorporated into the MD5 build signature).
+If so,
+.B scons
+will retrieve the file from the cache.
+If the derived file is not present in the cache,
+.B scons
+will rebuild it and
+then place a copy of the built file in the cache
+(identified by its MD5 build signature),
+so that it may be retrieved by other
+builds that need to build the same derived file
+from identical inputs.
+
+Use of a specified
+.BR CacheDir()
+may be disabled for any invocation
+by using the
+.B --cache-disable
+option.
+
+If the
+.B --cache-force
+option is used,
+.B scons
+will place a copy of
+.I all
+derived files in the cache,
+even if they already existed
+and were not built by this invocation.
+This is useful to populate a cache
+the first time
+.BR CacheDir ()
+is added to a build,
+or after using the
+.B --cache-disable
+option.
+
+When using
+.BR CacheDir (),
+.B scons
+will report,
+"Retrieved `file' from cache,"
+unless the
+.B --cache-show
+option is being used.
+When the
+.B --cache-show
+option is used,
+.B scons
+will print the action that
+.I would
+have been used to build the file,
+without any indication that
+the file was actually retrieved from the cache.
+This is useful to generate build logs
+that are equivalent regardless of whether
+a given derived file has been built in-place
+or retrieved from the cache.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI Clean( target ", " files_or_dirs )
+.TP 
+.RI env.Clean( target ", " files_or_dirs )
+This specifies a list of files or directories which should be removed
+whenever the target is specified with the
+.B -c
+command line option.
+Multiple calls to
+.BR Clean ()
+are legal,
+and create a new target or add files and directories to the
+clean list for the specified target.
+
+Multiple files or directories should be specified
+either as separate arguments to the
+.BR Clean ()
+method, or as a list.
+.BR Clean ()
+will also accept the return value of any of the construction environment
+Builder methods.
+Examples:
+
+.ES
+Clean('foo', ['bar', 'baz'])
+Clean('dist', env.Program('hello', 'hello.c'))
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI Command( target ", " source ", " commands )
+.TP
+.RI env.Command( target ", " source ", " commands )
 Executes a specific action
 (or list of actions)
 to build a target file or files.
@@ -1822,8 +2260,19 @@ env.Command('baz.out', 'baz.in',
 	     rename ])
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
+.TP
+.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
+Creates a Configure object for integrated
+functionality similar to GNU autoconf.
+See the section "Configure Contexts,"
+below, for a complete explanation of the arguments and behavior.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI Copy([ key = val ", ...])"
+.RI env.Copy([ key = val ", ...])"
 Return a separate copy of a construction environment.
 If there are any keyword arguments specified,
 they are added to the returned copy,
@@ -1834,7 +2283,7 @@ for the keywords.
 env2 = env.Copy()
 env3 = env.Copy(CCFLAGS = '-g')
 .EE
-
+.IP
 Additionally, a list of tools may be specified, as in the Environment
 constructor:
 
@@ -1843,9 +2292,9 @@ def MyTool(env): env['FOO'] = 'bar'
 env4 = env.Copy(tools = ['msvc', MyTool])
 .EE
 
-
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI CVS( repository ", " module )
+.RI env.CVS( repository ", " module )
 A factory function that
 returns a Builder object
 to be used to fetch source files
@@ -1883,8 +2332,61 @@ env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI Default( targets )
+.TP
+.RI env.Default( targets )
+This specifies a list of default targets,
+which will be built by
+.B scons
+if no explicit targets are given on the command line.
+Multiple calls to
+.BR Default ()
+are legal,
+and add to the list of default targets.
+
+Multiple targets should be specified as
+separate arguments to the
+.BR Default ()
+method, or as a list.
+.BR Default ()
+will also accept the Node returned by any
+of a construction environment's
+builder methods.
+Examples:
+
+.ES
+Default('foo', 'bar', 'baz')
+env.Default(['a', 'b', 'c'])
+hello = env.Program('hello', 'hello.c')
+env.Default(hello)
+.EE
+.IP
+An argument to
+.BR Default ()
+of
+.B None
+will clear all default targets.
+Later calls to
+.BR Default ()
+will add to the (now empty) default-target list
+like normal.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI DefaultEnvironment([ args ])
+Creates and returns a default construction environment object.
+This construction environment is used internally by SCons
+in order to execute many of the global functions in this list,
+and to fetch source files transparently
+from source code management systems.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI Depends( target ", " dependency )
+.TP
+.RI env.Depends( target ", " dependency )
 Specifies an explicit dependency;
 the target file(s) will be rebuilt
 whenever the dependency file(s) has changed.
@@ -1897,8 +2399,9 @@ for the file.
 env.Depends('foo', 'other-input-file-for-foo')
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI Dictionary([ vars ])
+.RI env.Dictionary([ vars ])
 Returns a dictionary object
 containing copies of all of the
 construction variables in the environment.
@@ -1911,8 +2414,232 @@ dict = env.Dictionary()
 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Dir( name ", [" directory ])
+.TP
+.RI env.Dir( name ", [" directory ])
+This returns an object that represents a given directory 
+.IR name . 
+.I name
+can be a relative or absolute path. 
+.I directory
+is an optional directory that will be used as the parent directory. 
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI EnsurePythonVersion( major ", " minor )
+.TP
+.RI env.EnsurePythonVersion( major ", " minor )
+Ensure that the Python version is at least 
+.IR major . minor . 
+This function will
+print out an error message and exit SCons with a non-zero exit code if the
+actual Python version is not late enough.
+
+.ES
+EnsurePythonVersion(2,2)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI EnsureSConsVersion( major ", " minor )
+.TP
+.RI env.EnsureSConsVersion( major ", " minor )
+Ensure that the SCons version is at least 
+.IR major . minor . 
+This function will
+print out an error message and exit SCons with a non-zero exit code if the
+actual SCons version is not late enough.
+
+.ES
+EnsureSConsVersion(0,9)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Environment([ key = value ", ...])"
+.TP
+.RI env.Environment([ key = value ", ...])"
+Return a new construction environment
+initialized with the specified
+.IR key = value
+pairs.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Exit([ value ])
+.TP
+.RI env.Exit([ value ])
+This tells
+.B scons
+to exit immediately
+with the specified
+.IR value .
+A default exit value of
+.B 0
+(zero)
+is used if no value is specified.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Export( vars )
+.TP
+.RI env.Export( vars )
+This tells 
+.B scons
+to export a list of variables from the current
+SConscript file to all other SConscript files.
+The exported variables are kept in a global collection,
+so subsequent calls to
+.BR Export ()
+will over-write previous exports that have the same name. 
+Multiple variable names can be passed to
+.BR Export ()
+as separate arguments or as a list. A dictionary can be used to map
+variables to a different name when exported. Both local variables and
+global variables can be exported.
+Examples:
+
+.ES
+env = Environment()
+# Make env available for all SConscript files to Import().
+Export("env")
+
+package = 'my_name'
+# Make env and package available for all SConscript files:.
+Export("env", "package")
+
+# Make env and package available for all SConscript files:
+Export(["env", "package"])
+
+# Make env available using the name debug:.
+Export({"debug":env})
+.EE
+
+.IP
+Note that the
+.BR SConscript ()
+function supports an
+.I exports
+argument that makes it easier to to export a variable or
+set of variables to a single SConscript file.
+See the description of the
+.BR SConscript ()
+function, below.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI File( name ", [" directory ])
+.TP 
+.RI env.File( name ", [" directory ])
+This returns an object that represents a given file 
+.IR name . 
+.I name
+can be a relative or absolute path. 
+.I directory
+is an optional directory that will be used as the parent directory. 
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI FindFile( file ", " dirs )
+.TP
+.RI env.FindFile( file ", " dirs )
+Search for 
+.I file 
+in the path specified by 
+.IR dirs .
+.I file
+may be a list of file names or a single file name. In addition to searching
+for files that exist in the filesytem, this function also searches for
+derived files that have not yet been built.
+
+.ES
+foo = env.FindFile('foo', ['dir1', 'dir2'])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI GetBuildPath( file ", [" ... ])
+.TP
+.RI env.GetBuildPath( file ", [" ... ])
+Returns the
+.B scons
+path name (or names) for the specified
+.I file
+(or files).
+The specified
+.I file
+or files
+may be
+.B scons
+Nodes or strings representing path names.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI GetLaunchDir()
+.TP
+.RI env.GetLaunchDir()
+Returns the absolute path name of the directory from which
+.B
+scons
+was initially invoked.
+This can be useful when using the
+.BR \-u ,
+.BR \-U
+or
+.BR \-D
+options, which internally
+change to the directory in which the
+.B SConstruct
+file is found.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI GetOption( name )
+.TP
+.RI env.GetOption( name )
+This function provides a way to query a select subset of the scons command line
+options from a SConscript file. See 
+.IR SetOption () 
+for a description of the options available.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+'\".TP
+'\".RI GlobalBuilders( flag )
+'\"When
+'\".B flag
+'\"is non-zero,
+'\"adds the names of the default builders
+'\"(Program, Library, etc.)
+'\"to the global name space
+'\"so they can be called without an explicit construction environment.
+'\"(This is the default.)
+'\"When
+'\".B
+'\"flag is zero,
+'\"the names of the default builders are removed
+'\"from the global name space
+'\"so that an explicit construction environment is required
+'\"to call all builders.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Help( text )
+.TP
+.RI env.Help( text )
+This specifies help text to be printed if the 
+.B -h 
+argument is given to
+.BR scons .
+.B scons
+will exit after printing out the help text.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI Ignore( target ", " dependency )
+.TP
+.RI env.Ignore( target ", " dependency )
 The specified dependency file(s)
 will be ignored when deciding if
 the target file(s) need to be rebuilt.
@@ -1922,8 +2649,41 @@ env.Ignore('foo', 'foo.c')
 env.Ignore('bar', ['bar1.h', 'bar2.h'])
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI Import( vars )
+.TP 
+.RI env.Import( vars )
+This tells 
+.B scons
+to import a list of variables into the current SConscript file. This
+will import variables that were exported with
+.BR Export ()
+or in the 
+.I exports
+argument to 
+.BR SConscript ().
+Variables exported by 
+.BR SConscript ()
+have precedence.
+Multiple variable names can be passed to 
+.BR Import ()
+as separate arguments or as a list. The variable "*" can be used
+to import all variables.
+Examples:
+
+.ES
+Import("env")
+Import("env", "variable")
+Import(["env", "variable"])
+Import("*")
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI Install( dir ", " source )
+.TP
+.RI env.Install( dir ", " source )
 Installs one or more files in a destination directory.
 The file names remain the same.
 
@@ -1931,8 +2691,11 @@ The file names remain the same.
 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI InstallAs( target ", " source )
+.TP
+.RI env.InstallAs( target ", " source )
 Installs one or more files as specific file names,
 allowing changing a file name as part of the
 installation.
@@ -1946,8 +2709,58 @@ env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
               source = ['libFOO.a', 'libBAR.a'])
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Literal( string )
+.TP
+.RI env.Literal( string )
+The specified
+.I string
+will be preserved as-is
+and not have construction variables expanded.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Local( targets )
+.TP
+.RI env.Local( targets )
+The specified
+.I targets
+will have copies made in the local tree,
+even if an already up-to-date copy
+exists in a repository.
+Returns a list of the target Node or Nodes.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-Perforce()
+.RI env.ParseConfig( command ", [" function ])
+Calls the specified
+.I function
+to modify the environment as specified by the output of
+.I command .
+The default
+.I function
+expects the output of a typical
+.I *-config command
+(for example,
+.BR gtk-config )
+and parses the returned
+.BR -L ,
+.BR -l ,
+.B -I
+and other options
+into the
+.BR LIBPATH ,
+.BR LIBS ,
+.B CPPPATH
+and
+.B CCFLAGS
+variables,
+respectively.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+env.Perforce()
 A factory function that
 returns a Builder object
 to be used to fetch source files
@@ -1956,6 +2769,7 @@ The returned Builder
 is intended to be passed to the
 .B SourceCode
 function:
+
 .ES
 env.SourceCode('.', env.Perforce())
 .EE
@@ -1977,26 +2791,47 @@ USER,
 and
 USERNAME.
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI AlwaysBuild( target ", ...)"
-Marks each given
-.I target
-so that it is always assumed to be out of date,
-and will always be rebuilt if needed.
-Note, however, that
-.BR AlwaysBuild ()
-does not add its target(s) to the default target list,
-so the targets will only be built
-if they are specified on the command line,
-or are a dependent of a target specified on the command line--but
-they will
-.I always
-be built if so specified.
-Multiple targets can be passed in to a single call to
-.BR AlwaysBuild ().
+.RI Platform( string )
+Returns a callable object
+that can be used to initialize
+a construction environment using the
+platform keyword of the Environment() method:
+
+.ES
+env = Environment(platform = Platform('win32'))
+.EE
+.TP
+.RI env.Platform( string )
+Applies the callable object for the specified platform
+.I string
+to the environment through which the method was called.
+
+.ES
+env.Platform('posix')
+.EE
+.IP
+Note that the
+.B win32
+platform adds the
+.B SYSTEMROOT
+variable from the user's external environment
+to the construction environment's
+.B ENV
+dictionary.
+This is so that any executed commands
+that use sockets to connect with other systems
+(such as fetching source files from
+external CVS repository specifications like 
+.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
+will work on Win32 systems.
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI Precious( target ", ...)"
+.TP
+.RI env.Precious( target ", ...)"
 Marks each given
 .I target
 as precious so it is not deleted before it is rebuilt. Normally
@@ -2005,8 +2840,9 @@ deletes a target before building it.
 Multiple targets can be passed in to a single call to
 .BR Precious ().
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI Prepend( key = val ", [...])"
+.RI env.Prepend( key = val ", [...])"
 Appends the specified keyword arguments
 to the beginning of construction variables in the environment.
 If the Environment does not have
@@ -2025,8 +2861,40 @@ and the lists are added together.
 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
+This appends new path elements to the given path in the
+specified external environment
+.RB ( ENV
+by default).
+This will only add
+any particular path once (leaving the first one it encounters and
+ignoring the rest, to preserve path order),
+and to help assure this,
+will normalize all paths (using
+.B os.path.normpath
+and
+.BR os.path.normcase ).
+This can also handle the
+case where the given old path variable is a list instead of a
+string, in which case a list will be returned instead of a string.
+Example:
+
+.ES
+print 'before:',env['ENV']['INCLUDE']
+include_path = '/foo/bar:/foo'
+env.PrependENVPath('INCLUDE', include_path)
+print 'after:',env['ENV']['INCLUDE']
+
+yields:
+before: /biz:/foo
+after: /foo/bar:/foo:/biz
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-RCS()
+env.RCS()
 A factory function that
 returns a Builder object
 to be used to fetch source files
@@ -2035,6 +2903,7 @@ The returned Builder
 is intended to be passed to the
 .B SourceCode
 function:
+
 .ES
 env.SourceCode('.', env.RCS())
 .EE
@@ -2053,8 +2922,9 @@ directory as the source files,
 or if you need to explicitly specify RCS
 for a specific subdirectory.
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI Replace( key = val ", [...])"
+.RI env.Replace( key = val ", [...])"
 Replaces construction variables in the Environment
 with the specified keyword arguments.
 
@@ -2062,8 +2932,84 @@ with the specified keyword arguments.
 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
 .EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-SCCS()
+.RI Repository( directory )
+.TP
+.RI env.Repository( directory )
+Specifies that
+.I directory
+is a repository to be searched for files.
+Multiple calls to
+.BR Repository ()
+are legal,
+and each one adds to the list of
+repositories that will be searched.
+
+To
+.BR scons ,
+a repository is a copy of the source tree,
+from the top-level directory on down,
+which may contain
+both source files and derived files
+that can be used to build targets in
+the local source tree.
+The canonical example would be an
+official source tree maintained by an integrator.
+If the repository contains derived files,
+then the derived files should have been built using
+.BR scons ,
+so that the repository contains the necessary
+signature information to allow
+.B scons
+to figure out when it is appropriate to
+use the repository copy of a derived file,
+instead of building one locally.
+
+Note that if an up-to-date derived file
+already exists in a repository,
+.B scons
+will
+.I not
+make a copy in the local directory tree.
+In order to guarantee that a local copy
+will be made,
+use the
+.B Local()
+method.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Return( vars )
+This tells
+.B scons
+what variable(s) to use as the return value(s) of the current SConscript
+file. These variables will be returned to the "calling" SConscript file
+as the return value(s) of 
+.BR SConscript ().
+Multiple variable names should be passed to 
+.BR Return ()
+as a list. Example:
+
+.ES
+Return("foo")
+Return(["foo", "bar"])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP 
+.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
+.TP 
+.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
+Creates a Scanner object for
+the specified
+.IR function .
+See the section "Scanner Objects,"
+below, for a complete explanation of the arguments and behavior.
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+env.SCCS()
 A factory function that
 returns a Builder object
 to be used to fetch source files
@@ -2072,6 +3018,7 @@ The returned Builder
 is intended to be passed to the
 .B SourceCode
 function:
+
 .ES
 env.SourceCode('.', env.SCCS())
 .EE
@@ -2090,8 +3037,229 @@ directory as the source files,
 or if you need to explicitly specify SCCS
 for a specific subdirectory.
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.TP
+.RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.TP
+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+.TP
+.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+This tells
+.B scons
+to execute
+one or more subsidiary SConscript (configuration) files.
+There are two ways to call the
+.BR SConscript ()
+function.
+
+The first way you can call
+.BR SConscript ()
+is to explicitly specify one or more
+.I scripts
+as the first argument.
+A single script may be specified as a string;
+multiple scripts must be specified as a list
+(either explicitly or as created by
+a function like
+.BR Split ()).
+
+The second way you can call
+.BR SConscript ()
+is to specify a list of (sub)directory names
+as a
+.RI dirs= subdirs
+keyword argument.
+In this case,
+.B scons
+will, by default,
+execute a subsidiary configuration file named
+.B SConscript
+in each of the specified directories.
+You may specify a name other than
+.B SConscript
+by supplying an optional
+.RI name= script
+keyword argument.
+
+The optional 
+.I exports
+argument provides a list of variable names or a dictionary of
+named values to export to the
+.IR script(s) ". "
+These variables are locally exported only to the specified
+.IR script(s) ,
+and do not affect the
+global pool of variables used by
+the
+.BR Export ()
+function.
+'\"If multiple dirs are provided,
+'\"each script gets a fresh export.
+The subsidiary
+.I script(s)
+must use the
+.BR Import ()
+function to import the variables.
+
+The optional
+.I build_dir
+argument specifies that all of the target files
+(for example, object files and executables)
+that would normally be built in the subdirectory in which
+.I script
+resides should actually
+be built in
+.IR build_dir .
+
+The optional
+.I src_dir
+argument specifies that the
+source files from which
+the target files should be built
+can be found in
+.IR src_dir .
+
+By default,
+.B scons
+will link or copy (depending on the platform)
+all the source files into the build directory.
+This behavior may be disabled by
+setting the optional
+.I duplicate
+argument to 0
+(it is set to 1 by default),
+in which case
+.B scons
+will refer directly to
+the source files in their source directory
+when building target files.
+(Setting
+.IR duplicate =0
+is usually safe, and always more efficient
+than the default of
+.IR duplicate =1,
+but it may cause build problems in certain end-cases,
+such as compiling from source files that
+are generated by the build.)
+
+Any variables returned by 
+.I script 
+using 
+.BR Return ()
+will be returned by the call to
+.BR SConscript (). 
+
+Examples:
+
+.ES
+SConscript('subdir/SConscript')
+foo = SConscript('sub/SConscript', exports='env')
+SConscript('dir/SConscript', exports=['env', 'variable'])
+SConscript('src/SConscript', build_dir='build', duplicate=0)
+SConscript('bld/SConscript', src_dir='src', exports='env variable')
+SConscript(dirs=['sub1', 'sub2'])
+SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI SConscriptChdir( value )
+.TP
+.RI env.SConscriptChdir( value )
+By default,
+.B scons
+changes its working directory
+to the directory in which each
+subsidiary SConscript file lives.
+This behavior may be disabled
+by specifying either:
+
+.ES
+SConscriptChdir(0)
+env.SConscriptChdir(0)
+.EE
+.IP
+in which case
+.B scons
+will stay in the top-level directory
+while reading all SConscript files.
+(This may be necessary when building from repositories,
+when all the directories in which SConscript files may be found
+don't necessarily exist locally.)
+
+You may enable and disable
+this ability by calling
+SConscriptChdir()
+multiple times:
+
+.ES
+env = Environment()
+SConscriptChdir(0)
+SConscript('foo/SConscript')	# will not chdir to foo
+env.SConscriptChdir(1)
+SConscript('bar/SConscript')	# will chdir to bar
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI SConsignFile([ file ])
+.TP
+.RI env.SConsignFile([ file ])
+This tells
+.B scons
+to store all file signatures
+in the specified
+.IR file .
+If the
+.I file
+is omitted,
+.B .sconsign.dbm
+is used by default.
+If
+.I file
+is not an absolute path name,
+the file is placed in the same directory as the top-level
+.B SConstruct
+file.
+Examples:
+
+.ES
+# Stores signatures in ".sconsign.dbm"
+# in the top-level SConstruct directory.
+SConsignFile()
+
+# Stores signatures in the file "etc/scons-signatures"
+# relative to the top-level SConstruct directory.
+SConsignFile("etc/scons-signatures")
+
+# Stores signatures in the specified absolute file name.
+SConsignFile("/home/me/SCons/signatures")
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI SetOption( name ", " value )
+.TP
+.RI env.SetOption( name ", " value )
+This function provides a way to set a select subset of the scons command
+line options from a SConscript file. The options supported are: clean which
+cooresponds to -c, --clean, and --remove; implicit_cache which corresponds
+to --implicit-cache; max_drift which corresponds to --max-drift; and
+num_jobs which corresponds to -j and --jobs. See the documentation for the
+corresponding command line object for information about each specific
+option. Example:
+
+.ES
+SetOption('max_drift', 1)
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI SideEffect( side_effect ", " target )
+.TP
+.RI env.SideEffect( side_effect ", " target )
 Declares
 .I side_effect
 as a side effect of building
@@ -2114,8 +3282,11 @@ Consequently, you only need to use this method
 for side-effect targets that are built as a result of
 multiple build commands.
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
 .RI SourceCode( entries ", " builder )
+.TP
+.RI env.SourceCode( entries ", " builder )
 Arrange for non-existent source files to
 be fetched from a source code management system
 using the specified
@@ -2157,6 +3328,7 @@ source code management files on disk.
 You can avoid these extra searches
 and speed up your build a little
 by disabling these searches as follows:
+
 .ES
 env.SourceCode('.', None)
 .EE
@@ -2175,6 +3347,7 @@ functions that return appropriate
 Builders for various popular
 source code management systems.
 Canonical examples of invocation include:
+
 .ES
 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
@@ -2184,6 +3357,7 @@ env.SourceCode('no_source.c', None)
 .EE
 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
 '\"
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 '\".TP
 '\".RI Subversion( repository ", " module )
 '\"A factory function that
@@ -2222,6 +3396,176 @@ env.SourceCode('no_source.c', None)
 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
 '\".EE
 
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI SourceSignatures( type )
+.TP
+.RI env.SourceSignatures( type )
+This function tells SCons what type of signature to use for source files:
+.B "MD5"
+or
+.BR "timestamp" .
+If the environment method is used,
+the specified type of source signature
+is only used when deciding whether targets
+built with that environment are up-to-date or must be rebuilt.
+If the global function is used,
+the specified type of source signature becomes the default
+used for all decisions
+about whether targets are up-to-date.
+
+"MD5" means the signature of a source file
+is the MD5 checksum of its contents.
+"timestamp" means the signature of a source file
+is its timestamp (modification time).
+When using "timestamp" signatures,
+changes in the command line will not cause files to be rebuilt.
+"MD5" signatures take longer to compute,
+but are more accurate than "timestamp" signatures.
+The default is "MD5".
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Split( arg )
+.TP
+.RI env.Split( arg )
+Returns a list of file names or other objects.
+If arg is a string,
+it will be split on strings of white-space characters
+within the string,
+making it easier to write long lists of file names.
+If arg is already a list,
+the list will be returned untouched.
+If arg is any other type of object,
+it will be returned as a list
+containing just the object.
+
+.ES
+files = Split("f1.c f2.c f3.c")
+files = env.Split("f4.c f5.c f6.c")
+files = Split("""
+	f7.c
+	f8.c
+	f9.c
+""")
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI TargetSignatures( type )
+.TP
+.RI env.TargetSignatures( type )
+This function tells SCons what type of signatures to use
+for target files:
+.B "build"
+or
+.BR "content" .
+If the environment method is used,
+the specified type of signature is only used
+for targets built with that environment.
+If the global function is used,
+the specified type of signature becomes the default
+used for all target files that
+don't have an explicit target signature type
+specified for their environments.
+
+"build" means the signature of a target file
+is made by concatenating all of the
+signatures of all its source files.
+"content" means the signature of a target
+file is an MD5 checksum of its contents.
+"build" signatures are usually faster to compute,
+but "content" signatures can prevent unnecessary rebuilds
+when a target file is rebuilt to the exact same contents
+as the previous build.
+The default is "build".
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Tool( string )
+Returns a callable object
+that can be used to initialize
+a construction environment using the
+tools keyword of the Environment() method.
+The object may be called with a construction
+environment as an argument,
+in which case the object will be
+add the necessary variables
+to the construction environment
+and the name of the tool will be added to the
+.B $TOOLS
+construction variable.
+
+.ES
+env = Environment(tools = [ Tool('msvc') ])
+
+env = Environment()
+t = Tool('msvc')
+t(env)  # adds 'msvc' to the TOOLS variable
+.EE
+.TP
+.RI env.Tool( string )
+Applies the callable object for the specified tool
+.I string
+to the environment through which the method was called.
+
+.ES
+env.Tool('gcc')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI Value( value )
+.TP
+.RI env.Value( value )
+Returns a Node object representing the specified Python value.  Value
+nodes can be used as dependencies of targets.  If the result of
+calling
+.BR str( value )
+changes between SCons runs, any targets depending on
+.BR Value( value )
+will be rebuilt.  When using timestamp source signatures, Value nodes'
+timestamps are equal to the system time when the node is created.
+
+.ES
+def create(target, source, env):
+    f = open(str(target[0]), 'wb')
+    f.write('prefix=' + source[0].get_contents())
+    
+prefix = ARGUMENTS.get('prefix', '/usr/local')
+env = Environment()
+env['BUILDERS']['Config'] = Builder(action = create)
+env.Config(target = 'package-config', source = Value(prefix))
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
+.RI WhereIs( program ", [" path  ", [" pathext ]])
+.TP
+.RI env.WhereIs( program ", [" path  ", [" pathext ]])
+
+Searches for the specified executable
+.I program,
+returning the full path name to the program
+if it is found,
+and returning None if not.
+Searches the specified
+.I path,
+the value of the calling environment's PATH
+(env['ENV']['PATH']),
+or the user's current external PATH
+(os.environ['PATH'])
+by default.
+On Win32 systems, searches for executable
+programs with any of the file extensions
+listed in the specified
+.I pathext,
+the calling environment's PATHEXT
+(env['ENV']['PATHEXT'])
+or the user's current PATHEXT
+(os.environ['PATHEXT'])
+by default.
+
 .SS Construction Variables
 .\" XXX From Gary Ruben, 23 April 2002:
 .\" I think it would be good to have an example with each construction
@@ -2278,6 +3622,19 @@ after first running the file through the C preprocessor.
 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
 are included on this command line.
 
+.IP BIBTEX
+The bibliography generator for the TeX formatter and typesetter and the
+LaTeX structured formatter and typesetter.
+
+.IP BIBTEXCOM
+The command line used to call the bibliography generator for the
+TeX formatter and typesetter and the LaTeX structured formatter and
+typesetter.
+
+.IP BIBTEXFLAGS
+General options passed to the bibliography generator for the TeX formatter
+and typesetter and the LaTeX structured formatter and typesetter.
+
 .IP BITKEEPER
 The BitKeeper executable.
 
@@ -2303,6 +3660,7 @@ Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
 are available by default.
 If you initialize this variable when an
 Environment is created:
+
 .ES
 env = Environment(BUILDERS = {'NewBuilder' : foo})
 .EE
@@ -2310,12 +3668,14 @@ env = Environment(BUILDERS = {'NewBuilder' : foo})
 the default Builders will no longer be available.
 To use a new Builder object in addition to the default Builders,
 add your new Builder object like this:
+
 .ES
 env = Environment()
 env.Append(BUILDERS = {'NewBuilder' : foo})
 .EE
 .IP
 or this:
+
 .ES
 env = Environment()
 env['BUILDERS]['NewBuilder'] = foo
@@ -2779,6 +4139,12 @@ in force for this file installation.
 .IP JAR
 The Java archive tool.
 
+.IP JARCHDIR
+The directory to which the Java archive tool should change
+(using the
+.B \-C
+option).
+
 .IP JARCOM
 The command line used to call the Java archive tool.
 
@@ -3235,6 +4601,7 @@ In addition, the construction environment
 variables CPPPATH, LIBPATH, LIBS, PROGEMITTER, SHLIBEMITTER and LIBEMITTER
 are modified. Because the build-performance is affected when using this tool,
 you have to explicitly specify it at Environment creation:
+
 .ES
 Environment(tools=['default','qt']).
 .EE
@@ -3676,7 +5043,7 @@ method:
 env2 = env.Copy(CC="cl.exe")
 .EE
 
-.SS Configure contexts
+.SS Configure Contexts
 
 .B scons
 supports
@@ -3694,6 +5061,8 @@ The following methods can be used to perform checks:
 
 .TP
 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
+.TP
+.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
 This creates a configure context, which can be used to perform checks.
 .I env
 specifies the environment for building the tests.
@@ -3743,6 +5112,15 @@ goes by and developers contribute new useful tests.)
 Checks if 
 .I header
 is usable in the specified language.
+.I header
+may be a list,
+in which case the last item in the list
+is the header file to be checked,
+and the previous list items are
+header files whose
+.B #include
+lines should precede the
+header line being checked for.
 The optional argument 
 .I include_quotes 
 must be
@@ -3764,7 +5142,17 @@ This is a wrapper around
 .B Configure.CheckHeader
 which checks if 
 .I header
-is usable in the C language. The optional argument 
+is usable in the C language.
+.I header
+may be a list,
+in which case the last item in the list
+is the header file to be checked,
+and the previous list items are
+header files whose
+.B #include
+lines should precede the
+header line being checked for.
+The optional argument 
 .I include_quotes 
 must be
 a two character string, where the first character denotes the opening
@@ -3778,7 +5166,17 @@ This is a wrapper around
 .B Configure.CheckHeader
 which checks if 
 .I header
-is usable in the C++ language. The optional argument 
+is usable in the C++ language.
+.I header
+may be a list,
+in which case the last item in the list
+is the header file to be checked,
+and the previous list items are
+header files whose
+.B #include
+lines should precede the
+header line being checked for.
+The optional argument 
 .I include_quotes 
 must be
 a two character string, where the first character denotes the opening
@@ -3848,6 +5246,15 @@ Again,
 specifies the library to check. 
 .I header
 specifies a header to check for.
+.I header
+may be a list,
+in which case the last item in the list
+is the header file to be checked,
+and the previous list items are
+header files whose
+.B #include
+lines should precede the
+header line being checked for.
 .I language
 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
 .I call
@@ -4154,906 +5561,6 @@ variables. Example:
 CC = 'my_cc'
 .EE
 
-.SS Other Functions
-
-.B scons
-also provides various additional functions,
-not associated with a construction environment,
-that SConscript files can use:
-
-.TP 
-.RI AddPostAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-after the specified
-.I target
-has been built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see below).
-
-.TP 
-.RI AddPreAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-before the specified
-.I target
-is built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see below).
-
-.TP
-.RI Alias( name )
-Creates or references an alias independent of the construction environment.
-
-.ES
-Alias('install')
-.EE
-
-.TP
-.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
-This specifies a build directory
-.I build_dir
-in which to build all derived files
-that would normally be built under
-.IR src_dir .
-Multiple build directories can be set up for multiple build variants, for
-example. 
-.I src_dir
-must be underneath the SConstruct file's directory,
-and
-.I build_dir
-may not be underneath the
-.I src_dir .
-
-The default behavior is for
-.B scons
-to duplicate all of the files in the tree underneath
-.I src_dir
-into
-.IR build_dir ,
-and then build the derived files within the copied tree.
-(The duplication is performed by
-linking or copying,
-depending on the platform.)
-This guarantees correct builds
-regardless of whether intermediate source files
-are generated during the build,
-where preprocessors or other scanners search
-for included files,
-or whether individual compilers or other invoked tools
-are hard-coded to put derived files in the same directory as source files.
-
-This behavior of making a complete copy of the source tree
-may be disabled by setting
-.I duplicate
-to 0.
-This will cause
-.B scons
-to invoke Builders using the
-path names of source files in
-.I src_dir
-and the path names of derived files within
-.IR build_dir .
-This is always more efficient than
-.IR duplicate =1,
-and is usually safe for most builds.
-Specifying
-.IR duplicate =0,
-however,
-may cause build problems
-if source files are generated during the build,
-if any invoked tools are hard-coded to
-put derived files in the same directory as the source files.
-
-Note that specifying a
-.B BuildDir
-works most naturally
-with a subsidiary SConscript file
-in the source directory.
-However,
-you would then call the subsidiary SConscript file
-not in the source directory,
-but in the
-.I build_dir ,
-as if
-.B scons
-had made a virtual copy of the source tree
-regardless of the value of 
-.IR duplicate .
-This is how you tell
-.B scons
-which variant of a source tree to build.
-For example:
-
-.ES
-BuildDir('build-variant1', 'src')
-SConscript('build-variant1/SConscript')
-BuildDir('build-variant2', 'src')
-SConscript('build-variant2/SConscript')
-.EE
-
-.IP
-See also the
-.BR SConscript ()
-function, described below,
-for another way to 
-specify a build directory
-in conjunction with calling a subsidiary
-SConscript file.)
-
-.TP 
-.RI CacheDir( cache_dir )
-Specifies that
-.B scons
-will maintain a cache of derived files in
-.I cache_dir .
-The derived files in the cache will be shared
-among all the builds using the same
-.BR CacheDir ()
-call.
-
-When a
-.BR CacheDir ()
-is being used and
-.B scons
-finds a derived file that needs to be rebuilt,
-it will first look in the cache to see if a
-derived file has already been built
-from identical input files and an identical build action
-(as incorporated into the MD5 build signature).
-If so,
-.B scons
-will retrieve the file from the cache.
-If the derived file is not present in the cache,
-.B scons
-will rebuild it and
-then place a copy of the built file in the cache
-(identified by its MD5 build signature),
-so that it may be retrieved by other
-builds that need to build the same derived file
-from identical inputs.
-
-Use of a specified
-.BR CacheDir()
-may be disabled for any invocation
-by using the
-.B --cache-disable
-option.
-
-If the
-.B --cache-force
-option is used,
-.B scons
-will place a copy of
-.I all
-derived files in the cache,
-even if they already existed
-and were not built by this invocation.
-This is useful to populate a cache
-the first time
-.BR CacheDir ()
-is added to a build,
-or after using the
-.B --cache-disable
-option.
-
-When using
-.BR CacheDir (),
-.B scons
-will report,
-"Retrieved `file' from cache,"
-unless the
-.B --cache-show
-option is being used.
-When the
-.B --cache-show
-option is used,
-.B scons
-will print the action that
-.I would
-have been used to build the file,
-without any indication that
-the file was actually retrieved from the cache.
-This is useful to generate build logs
-that are equivalent regardless of whether
-a given derived file has been built in-place
-or retrieved from the cache.
-
-.TP 
-.RI Clean( target ", " files_or_dirs )
-This specifies a list of files or directories which should be removed
-whenever the target is specified with the
-.B -c
-command line option.
-Multiple calls to
-.BR Clean ()
-are legal,
-and create a new target or add files and directories to the
-clean list for the specified target.
-
-Multiple files or directories should be specified
-either as separate arguments to the
-.BR Clean ()
-method, or as a list.
-.BR Clean ()
-will also accept the return value of any of the construction environment
-Builder methods.
-Examples:
-
-.ES
-Clean('foo', ['bar', 'baz'])
-Clean('dist', env.Program('hello', 'hello.c'))
-.EE
-
-.TP 
-.RI Default( targets )
-This specifies a list of default targets,
-which will be built by
-.B scons
-if no explicit targets are given on the command line.
-Multiple calls to
-.BR Default ()
-are legal,
-and add to the list of default targets.
-
-Multiple targets should be specified as
-separate arguments to the
-.BR Default ()
-method, or as a list.
-.BR Default ()
-will also accept the Node returned by any
-of a construction environment's
-builder methods.
-Examples:
-
-.ES
-Default('foo', 'bar', 'baz')
-Default(['a', 'b', 'c'])
-hello = env.Program('hello', 'hello.c')
-Default(hello)
-.EE
-.IP
-An argument to
-.BR Default ()
-of
-.B None
-will clear all default targets.
-Later calls to
-.BR Default ()
-will add to the (now empty) default-target list
-like normal.
-
-.TP
-.RI DefaultEnvironment([ args ])
-Creates and returns a default construction environment object.
-This construction environment is used internally by SCons
-in order to fetch source files transparently
-from source code management systems.
-
-.TP
-.RI Dir( name ", [" directory ])
-This returns an object that represents a given directory 
-.IR name . 
-.I name
-can be a relative or absolute path. 
-.I directory
-is an optional directory that will be used as the parent directory. 
-
-.TP
-.RI EnsurePythonVersion( major ", " minor )
-Ensure that the Python version is at least 
-.IR major . minor . 
-This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual Python version is not late enough.
-
-.ES
-EnsurePythonVersion(2,2)
-.EE
-
-.TP
-.RI EnsureSConsVersion( major ", " minor )
-Ensure that the SCons version is at least 
-.IR major . minor . 
-This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual SCons version is not late enough.
-
-.ES
-EnsureSConsVersion(0,9)
-.EE
-
-.TP
-.RI Exit([ value ])
-This tells
-.B scons
-to exit immediately
-with the specified
-.IR value .
-A default exit value of
-.B 0
-(zero)
-is used if no value is specified.
-
-.TP
-.RI Export( vars )
-This tells 
-.B scons
-to export a list of variables from the current
-SConscript file to all other SConscript files.
-The exported variables are kept in a global collection,
-so subsequent calls to
-.BR Export ()
-will over-write previous exports that have the same name. 
-Multiple variable names can be passed to
-.BR Export ()
-as separate arguments or as a list. A dictionary can be used to map
-variables to a different name when exported. Both local variables and
-global variables can be exported.
-Examples:
-
-.ES
-env = Environment()
-# Make env available for all SConscript files to Import().
-Export("env")
-
-package = 'my_name'
-# Make env and package available for all SConscript files:.
-Export("env", "package")
-
-# Make env and package available for all SConscript files:
-Export(["env", "package"])
-
-# Make env available using the name debug:.
-Export({"debug":env})
-.EE
-
-.IP
-Note that the
-.BR SConscript ()
-function supports an
-.I exports
-argument that makes it easier to to export a variable or
-set of variables to a single SConscript file.
-See the description of the
-.BR SConscript ()
-function, below.
-
-.TP 
-.RI File( name ", [" directory ])
-This returns an object that represents a given file 
-.IR name . 
-.I name
-can be a relative or absolute path. 
-.I directory
-is an optional directory that will be used as the parent directory. 
-
-.TP
-.RI FindFile( file ", " dirs )
-Search for 
-.I file 
-in the path specified by 
-.IR dirs .
-.I file
-may be a list of file names or a single file name. In addition to searching
-for files that exist in the filesytem, this function also searches for
-derived files that have not yet been built.
-
-.ES
-foo = FindFile('foo', ['dir1', 'dir2'])
-.EE
-.\"
-.\".TP
-.\".RI GetBuildPath( XXX )
-.\"XXX
-.\"
-.\".TP
-.\".RI GetLaunchDir( XXX )
-.\"XXX
-
-.TP
-.RI GetOption( name )
-This function provides a way to query a select subset of the scons command line
-options from a SConscript file. See 
-.IR SetOption () 
-for a description of the options available.
-
-.TP
-.RI Help( text )
-This specifies help text to be printed if the 
-.B -h 
-argument is given to
-.BR scons .
-.B scons
-will exit after printing out the help text.
-
-.TP 
-.RI Import( vars )
-This tells 
-.B scons
-to import a list of variables into the current SConscript file. This
-will import variables that were exported with
-.BR Export ()
-or in the 
-.I exports
-argument to 
-.BR SConscript ().
-Variables exported by 
-.BR SConscript ()
-have precedence.
-Multiple variable names can be passed to 
-.BR Import ()
-as separate arguments or as a list. The variable "*" can be used
-to import all variables.
-Examples:
-
-.ES
-Import("env")
-Import("env", "variable")
-Import(["env", "variable"])
-Import("*")
-.EE
-
-.TP
-.RI Literal( string )
-The specified
-.I string
-will be preserved as-is
-and not have construction variables expanded.
-
-.TP
-.RI Local( targets )
-The specified
-.I targets
-will have copies made in the local tree,
-even if an already up-to-date copy
-exists in a repository.
-
-.TP
-.RI ParseConfig( env ", " command ", [" function ])
-Calls the specified
-.I function
-to modify the specified environment
-.I env
-as specified by the output of
-.I command .
-The default
-.I function
-expects the output of a typical
-.I *-config command
-(for example,
-.BR gtk-config )
-and parses the returned
-.BR -L ,
-.BR -l ,
-.B -I
-and other options
-into the
-.BR LIBPATH ,
-.BR LIBS ,
-.B CPPPATH
-and
-.B CCFLAGS
-variables,
-respectively.
-
-.TP
-.RI Platform( string )
-Returns a callable object
-that can be used to initialize
-a construction environment using the
-platform keyword of the Environment() method.
-
-.ES
-env = Environment(platform = Platform('win32'))
-.EE
-.IP
-Note that the
-.B win32
-platform adds the
-.B SYSTEMROOT
-variable from the user's external environment
-to the construction environment's
-.B ENV
-dictionary.
-This is so that any executed commands
-that use sockets to connect with other systems
-(such as fetching source files from
-external CVS repository specifications like 
-.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Win32 systems.
-
-.TP
-.RI Repository( directory )
-Specifies that
-.I directory
-is a repository to be searched for files.
-Multiple calls to
-.BR Repository ()
-are legal,
-and each one adds to the list of
-repositories that will be searched.
-
-To
-.BR scons ,
-a repository is a copy of the source tree,
-from the top-level directory on down,
-which may contain
-both source files and derived files
-that can be used to build targets in
-the local source tree.
-The canonical example would be an
-official source tree maintained by an integrator.
-If the repository contains derived files,
-then the derived files should have been built using
-.BR scons ,
-so that the repository contains the necessary
-signature information to allow
-.B scons
-to figure out when it is appropriate to
-use the repository copy of a derived file,
-instead of building one locally.
-
-Note that if an up-to-date derived file
-already exists in a repository,
-.B scons
-will
-.I not
-make a copy in the local directory tree.
-In order to guarantee that a local copy
-will be made,
-use the
-.B Local()
-method.
-
-.TP
-.RI Return( vars )
-This tells
-.B scons
-what variable(s) to use as the return value(s) of the current SConscript
-file. These variables will be returned to the "calling" SConscript file
-as the return value(s) of 
-.BR SConscript ().
-Multiple variable names should be passed to 
-.BR Return ()
-as a list. Example:
-
-.ES
-Return("foo")
-Return(["foo", "bar"])
-.EE
-
-.TP
-.RI SConsignFile([ file ])
-This tells
-.B scons
-to store all file signatures
-in the specified
-.IR file .
-If the
-.I file
-is omitted,
-.B .sconsign.dbm
-is used by default.
-If
-.I file
-is not an absolute path name,
-the file is placed in the same directory as the top-level
-.B SConstruct
-file.
-Examples:
-
-.ES
-# Stores signatures in ".sconsign.dbm"
-# in the top-level SConstruct directory.
-SConsignFile()
-
-# Stores signatures in the file "etc/scons-signatures"
-# relative to the top-level SConstruct directory.
-SConsignFile("etc/scons-signatures")
-
-# Stores signatures in the specified absolute file name.
-SConsignFile("/home/me/SCons/signatures")
-.EE
-
-.TP
-.RI SetOption( name ", " value )
-This function provides a way to set a select subset of the scons command
-line options from a SConscript file. The options supported are: clean which
-cooresponds to -c, --clean, and --remove; implicit_cache which corresponds
-to --implicit-cache; max_drift which corresponds to --max-drift; and
-num_jobs which corresponds to -j and --jobs. See the documentation for the
-corresponding command line object for information about each specific
-option. Example:
-
-.ES
-SetOption('max_drift', 1)
-.EE
-
-.TP
-.RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
-.TP
-.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
-This tells
-.B scons
-to execute
-one or more subsidiary SConscript (configuration) files.
-There are two ways to call the
-.BR SConscript ()
-function.
-
-The first way you can call
-.BR SConscript ()
-is to explicitly specify one or more
-.I scripts
-as the first argument.
-A single script may be specified as a string;
-multiple scripts must be specified as a list
-(either explicitly or as created by
-a function like
-.BR Split ()).
-
-The second way you can call
-.BR SConscript ()
-is to specify a list of (sub)directory names
-as a
-.RI dirs= subdirs
-keyword argument.
-In this case,
-.B scons
-will, by default,
-execute a subsidiary configuration file named
-.B SConscript
-in each of the specified directories.
-You may specify a name other than
-.B SConscript
-by supplying an optional
-.RI name= script
-keyword argument.
-
-The optional 
-.I exports
-argument provides a list of variable names or a dictionary of
-named values to export to the
-.IR script(s) ". "
-These variables are locally exported only to the specified
-.IR script(s) ,
-and do not affect the
-global pool of variables used by
-the
-.BR Export ()
-function.
-'\"If multiple dirs are provided,
-'\"each script gets a fresh export.
-The subsidiary
-.I script(s)
-must use the
-.BR Import ()
-function to import the variables.
-
-The optional
-.I build_dir
-argument specifies that all of the target files
-(for example, object files and executables)
-that would normally be built in the subdirectory in which
-.I script
-resides should actually
-be built in
-.IR build_dir .
-
-The optional
-.I src_dir
-argument specifies that the
-source files from which
-the target files should be built
-can be found in
-.IR src_dir .
-
-By default,
-.B scons
-will link or copy (depending on the platform)
-all the source files into the build directory.
-This behavior may be disabled by
-setting the optional
-.I duplicate
-argument to 0
-(it is set to 1 by default),
-in which case
-.B scons
-will refer directly to
-the source files in their source directory
-when building target files.
-(Setting
-.IR duplicate =0
-is usually safe, and always more efficient
-than the default of
-.IR duplicate =1,
-but it may cause build problems in certain end-cases,
-such as compiling from source files that
-are generated by the build.)
-
-Any variables returned by 
-.I script 
-using 
-.BR Return ()
-will be returned by the call to
-.BR SConscript (). 
-
-Examples:
-
-.ES
-SConscript('subdir/SConscript')
-foo = SConscript('sub/SConscript', exports='env')
-SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript('src/SConscript', build_dir='build', duplicate=0)
-SConscript('bld/SConscript', src_dir='src', exports='env variable')
-SConscript(dirs=['sub1', 'sub2'])
-SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
-.EE
-
-.TP
-.RI SConscriptChdir( value )
-By default,
-.B scons
-changes its working directory
-to the directory in which each
-subsidiary SConscript file lives.
-This behavior may be disabled
-by specifying:
-.ES
-SConscriptChdir(0)
-.EE
-.IP
-in which case
-.B scons
-will stay in the top-level directory
-while reading all SConscript files.
-(This may be necessary when building from repositories,
-when all the directories in which SConscript files may be found
-don't necessarily exist locally.)
-
-You may enable and disable
-this ability by calling
-SConscriptChdir()
-multiple times:
-
-.ES
-SConscriptChdir(0)
-SConscript('foo/SConscript')	# will not chdir to foo
-SConscriptChdir(1)
-SConscript('bar/SConscript')	# will chdir to bar
-.EE
-
-.TP
-.RI SourceSignatures( type )
-This function tells SCons what type of signature to use for source files:
-.B "MD5"
-or
-.BR "timestamp" .
-"MD5" means the signature of a source file
-is the MD5 checksum of its contents.
-"timestamp" means the signature of a source file
-is its timestamp (modification time).
-When using "timestamp" signatures,
-changes in the command line will not cause files to be rebuilt.
-"MD5" signatures take longer to compute,
-but are more accurate than "timestamp" signatures.
-The default is "MD5".
-
-.TP
-.RI Split( arg )
-Returns a list of file names or other objects.
-If arg is a string,
-it will be split on strings of white-space characters
-within the string,
-making it easier to write long lists of file names.
-If arg is already a list,
-the list will be returned untouched.
-If arg is any other type of object,
-it will be returned as a list
-containing just the object.
-
-.ES
-files = Split("f1.c f2.c f3.c")
-files = Split("""
-	f4.c
-	f5.c
-	f6.c
-""")
-.EE
-
-.TP
-.RI TargetSignatures( type )
-This function tells SCons what type of signatures to use
-for target files:
-.B "build"
-or
-.BR "content" .
-"build" means the signature of a target file
-is made by concatenating all of the
-signatures of all its source files.
-"content" means the signature of a target
-file is an MD5 checksum of its contents.
-"build" signatures are usually faster to compute,
-but "content" signatures can prevent unnecessary rebuilds
-when a target file is rebuilt to the exact same contents as last time.
-The default is "build".
-
-.TP
-.RI Tool( string )
-Returns a callable object
-that can be used to initialize
-a construction environment using the
-tools keyword of the Environment() method.
-
-.ES
-env = Environment(tools = [ Tool('msvc') ])
-.EE
-.IP
-The object may be called with a construction
-environment as an argument,
-in which case the object will be
-add the necessary variables
-to the construction environment
-and the name of the tool will be added to the
-.B $TOOLS
-construction variable.
-
-.ES
-env = Environment()
-t = Tool('msvc')
-t(env)  # adds 'msvc' to the TOOLS variable
-.EE
-
-.TP
-.RI Value( value )
-Returns a Node object representing the specified Python value.  Value
-nodes can be used as dependencies of targets.  If the result of
-calling
-.BR str( value )
-changes between SCons runs, any targets depending on
-.BR Value( value )
-will be rebuilt.  When using timestamp source signatures, Value nodes'
-timestamps are equal to the system time when the node is created.
-
-.ES
-def create(target, source, env):
-    f = open(str(target[0]), 'wb')
-    f.write('prefix=' + source[0].get_contents())
-    
-prefix = ARGUMENTS.get('prefix', '/usr/local')
-env = Environment()
-env['BUILDERS']['Config'] = Builder(action = create)
-env.Config(target = 'package-config', source = Value(prefix))
-.EE
-
-.TP
-.RI WhereIs( program ", [" path  ", [" pathext ]])
-
-Searches for the specified executable
-.I program,
-returning the full path name to the program
-if it is found,
-and returning None if not.
-Searches the specified
-.I path,
-or the user's current PATH
-(os.environ['PATH'])
-by default.
-On Win32 systems, searches for executable
-programs with any of the file extensions
-listed in the specified
-.I pathext,
-or the user's current PATHEXT
-(os.environ['PATHEXT'])
-by default.
-
 .SH EXTENDING SCONS
 .SS Builder Objects
 .B scons
@@ -5322,6 +5829,7 @@ the command line.
 This allows white space to be enclosed
 in an argument by defining
 a command in a list within a list:
+
 .ES
 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
 .EE
@@ -5347,6 +5855,7 @@ more than one target file or source file.
 The actual target and source file name(s) may
 be retrieved from their Node objects
 via the built-in Python str() function:
+
 .ES
 target_file_name = str(target)
 source_file_names = map(lambda x: str(x), source)
@@ -5928,22 +6437,6 @@ over the MinGW tools.
 To help you get started using SCons,
 this section contains a brief overview of some common tasks.
 
-NOTE:  SCons does
-.I not
-build all of its targets by default,
-like other build tools do.
-The canonical way to invoke SCons
-is with a target of '.' (dot)
-to represent all targets in and below the current directory:
-
-.ES
-scons .
-.EE
-
-One or more default targets may be specified
-via the Default() method
-in the SConstruct file.
-
 .SS Basic Compilation From a Single Source File
 
 .ES