Move the authoritative source for functions from the man page to various

.xml files (some new, some updated) next to the modules that implement
them.  Generate the man page using the output generated from the .xml
file by bin/scons-proc.py.

11 files changed, 285 insertions, 13 deletions

diff --git a/src/engine/SCons/Tool/BitKeeper.xml b/src/engine/SCons/Tool/BitKeeper.xml
index d0e42d7..ec20901 100644
--- a/src/engine/SCons/Tool/BitKeeper.xml
+++ b/src/engine/SCons/Tool/BitKeeper.xml
@@ -56,3 +56,29 @@ Options that are passed to the BitKeeper
 subcommand.
 </summary>
 </cvar>
+
+<scons_function name="BitKeeper">
+<arguments signature="env">
+()
+</arguments>
+<summary>
+A factory function that
+returns a Builder object
+to be used to fetch source files
+using BitKeeper.
+The returned Builder
+is intended to be passed to the
+&f-SourceCode;
+function.
+
+This function is deprecated.  For details, see the entry for the
+&f-SourceCode;
+function.
+
+Example:
+
+<example>
+env.SourceCode('.', env.BitKeeper())
+</example>
+</summary>
+</scons_function>
diff --git a/src/engine/SCons/Tool/CVS.xml b/src/engine/SCons/Tool/CVS.xml
index 3d8c055..ccaba84 100644
--- a/src/engine/SCons/Tool/CVS.xml
+++ b/src/engine/SCons/Tool/CVS.xml
@@ -64,3 +64,53 @@ This is referenced in the default
 &cv-link-CVSFLAGS; value.
 </summary>
 </cvar>
+
+<scons_function name="CVS">
+<arguments signature="env">
+(repository, module)
+</arguments>
+<summary>
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from the specified
+CVS
+<varname>repository</varname>.
+The returned Builder
+is intended to be passed to the
+&f-link-SourceCode;
+function.
+
+This function is deprecated.  For details, see the entry for the
+&f-SourceCode;
+function.
+
+The optional specified
+<varname>module</varname>
+will be added to the beginning
+of all repository path names;
+this can be used, in essence,
+to strip initial directory names
+from the repository path names,
+so that you only have to
+replicate part of the repository
+directory hierarchy in your
+local build directory.
+
+Examples:
+
+<example>
+# Will fetch foo/bar/src.c
+# from /usr/local/CVSROOT/foo/bar/src.c.
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
+
+# Will fetch bar/src.c
+# from /usr/local/CVSROOT/foo/bar/src.c.
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
+
+# Will fetch src.c
+# from /usr/local/CVSROOT/foo/bar/src.c.
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
+</example>
+</summary>
+</scons_function>
diff --git a/src/engine/SCons/Tool/Perforce.xml b/src/engine/SCons/Tool/Perforce.xml
index bc7ffed..cb34ede 100644
--- a/src/engine/SCons/Tool/Perforce.xml
+++ b/src/engine/SCons/Tool/Perforce.xml
@@ -45,3 +45,46 @@ If this is not set, then &cv-link-P4COM; (the command line) is displayed.
 General options that are passed to Perforce.
 </summary>
 </cvar>
+
+<scons_function name="Perforce">
+<arguments signature="env">
+()
+</arguments>
+<summary>
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from the Perforce source code management system.
+The returned Builder
+is intended to be passed to the
+&f-SourceCode;
+function.
+
+This function is deprecated.  For details, see the entry for the
+&f-SourceCode;
+function.
+
+Example:
+
+<example>
+env.SourceCode('.', env.Perforce())
+</example>
+
+Perforce uses a number of external
+environment variables for its operation.
+Consequently, this function adds the
+following variables from the user's external environment
+to the construction environment's
+ENV dictionary:
+P4CHARSET,
+P4CLIENT,
+P4LANGUAGE,
+P4PASSWD,
+P4PORT,
+P4USER,
+SystemRoot,
+USER,
+and
+USERNAME.
+</summary>
+</scons_function>
diff --git a/src/engine/SCons/Tool/RCS.xml b/src/engine/SCons/Tool/RCS.xml
index c81cf94..515fc12 100644
--- a/src/engine/SCons/Tool/RCS.xml
+++ b/src/engine/SCons/Tool/RCS.xml
@@ -59,3 +59,43 @@ If this is not set, then &cv-link-RCS_COCOM;
 Options that are passed to the &cv-link-RCS_CO; command.
 </summary>
 </cvar>
+
+<scons_function name="RCS">
+<arguments signature="env">
+()
+</arguments>
+<summary>
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from RCS.
+The returned Builder
+is intended to be passed to the
+&f-SourceCode;
+function:
+
+This function is deprecated.  For details, see the entry for the
+&f-SourceCode;
+function.
+
+Examples:
+
+<example>
+env.SourceCode('.', env.RCS())
+</example>
+
+Note that
+&scons;
+will fetch source files
+from RCS subdirectories automatically,
+so configuring RCS
+as demonstrated in the above example
+should only be necessary if
+you are fetching from
+RCS,v
+files in the same
+directory as the source files,
+or if you need to explicitly specify RCS
+for a specific subdirectory.
+</summary>
+</scons_function>
diff --git a/src/engine/SCons/Tool/SCCS.xml b/src/engine/SCons/Tool/SCCS.xml
index 5a55bda..a111738 100644
--- a/src/engine/SCons/Tool/SCCS.xml
+++ b/src/engine/SCons/Tool/SCCS.xml
@@ -56,3 +56,39 @@ This can be set, for example, to
 to check out editable files from SCCS.
 </summary>
 </cvar>
+
+<scons_function name="SCCS">
+<arguments signature="env">
+()
+</arguments>
+<summary>
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from SCCS.
+The returned Builder
+is intended to be passed to the
+&f-link-SourceCode;
+function.
+
+Example:
+
+<example>
+env.SourceCode('.', env.SCCS())
+</example>
+
+Note that
+&scons;
+will fetch source files
+from SCCS subdirectories automatically,
+so configuring SCCS
+as demonstrated in the above example
+should only be necessary if
+you are fetching from
+<filename>s.SCCS</filename>
+files in the same
+directory as the source files,
+or if you need to explicitly specify SCCS
+for a specific subdirectory.
+</summary>
+</scons_function>
diff --git a/src/engine/SCons/Tool/Subversion.xml b/src/engine/SCons/Tool/Subversion.xml
index adbd2b7..ac1a9ad 100644
--- a/src/engine/SCons/Tool/Subversion.xml
+++ b/src/engine/SCons/Tool/Subversion.xml
@@ -45,3 +45,54 @@ General options that are passed to Subversion.
 </summary>
 </cvar>
 -->
+
+<!--
+<scons_function name="Subversion">
+<arguments signature="global">
+(repository, module)
+</arguments>
+<summary>
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from the specified Subversion
+<varname>repository</varname>.
+The returned Builder
+is intended to be passed to the
+&f-link-SourceCode;
+function.
+
+The optional specified
+<varname>module</varname>
+will be added to the beginning
+of all repository path names;
+this can be used, in essence,
+to strip initial directory names
+from the repository path names,
+so that you only have to
+replicate part of the repository
+directory hierarchy in your
+local build directory.
+
+This function is deprecated, see the entry for the
+&f-SourceCode;
+function.
+
+Example:
+
+<example>
+# Will fetch foo/bar/src.c
+# from /usr/local/Subversion/foo/bar/src.c.
+env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
+
+# Will fetch bar/src.c
+# from /usr/local/Subversion/foo/bar/src.c.
+env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
+
+# Will fetch src.c
+# from /usr/local/Subversion/foo/bar/src.c.
+env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
+</example>
+</summary>
+</scons_function>
+-->
diff --git a/src/engine/SCons/Tool/__init__.xml b/src/engine/SCons/Tool/__init__.xml
index 502a553..d274a95 100644
--- a/src/engine/SCons/Tool/__init__.xml
+++ b/src/engine/SCons/Tool/__init__.xml
@@ -365,3 +365,21 @@ SCons also treats
 as C++ files.
 </summary>
 </cvar>
+
+<cvar name="LIBEMITTER">
+<summary>
+TODO
+</summary>
+</cvar>
+
+<cvar name="SHLIBEMITTER">
+<summary>
+TODO
+</summary>
+</cvar>
+
+<cvar name="PROGEMITTER">
+<summary>
+TODO
+</summary>
+</cvar>
diff --git a/src/engine/SCons/Tool/mslink.xml b/src/engine/SCons/Tool/mslink.xml
index 92be026..a2105db 100644
--- a/src/engine/SCons/Tool/mslink.xml
+++ b/src/engine/SCons/Tool/mslink.xml
@@ -185,7 +185,7 @@ files generated by Microsoft Visua C/C++ 8.
 
 <cvar name="WINDOWSDEFPREFIX">
 <summary>
-The prefix used for Windows <filename>.def</filename>file names.
+The prefix used for Windows <filename>.def</filename> file names.
 </summary>
 </cvar>
 
diff --git a/src/engine/SCons/Tool/msvs.xml b/src/engine/SCons/Tool/msvs.xml
index f040f4d..9d5e2da 100644
--- a/src/engine/SCons/Tool/msvs.xml
+++ b/src/engine/SCons/Tool/msvs.xml
@@ -146,7 +146,7 @@ on the file name in compilation error messages
 displayed in the Visual Studio console output window.
 This can be remedied by adding the
 Visual C/C++
-.B /FC
+<literal>/FC</literal>
 compiler option to the &cv-link-CCFLAGS;  variable
 so that the compiler will print
 the full path name of any
diff --git a/src/engine/SCons/Tool/packaging/__init__.xml b/src/engine/SCons/Tool/packaging/__init__.xml
index beae914..6fec7bd 100644
--- a/src/engine/SCons/Tool/packaging/__init__.xml
+++ b/src/engine/SCons/Tool/packaging/__init__.xml
@@ -502,7 +502,6 @@ field in the RPM
 </cvar>
 
 
-
 <!--
 
 THE FOLLOWING AREN'T CONSTRUCTION VARIABLES,
@@ -627,24 +626,32 @@ TODO
 -->
 
 
-<!--
-<builder name="Tag">
+<scons_function name="Tag">
+<arguments signature="global">
+(node, tags)
+</arguments>
 <summary>
-Leaves hints for the Package() Builder on how specific
-files or directories should be packaged.
+Annotates file or directory Nodes with
+information about how the
+&f-link-Package;
+Builder should package those files or directories.
 All tags are optional.
 
+Examples:
+
 <example>
 # makes sure the built library will be installed with 0644 file
 # access mode
-Tag( Library( 'lib.c' ), unix-attr="0644" )
+Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
 
 # marks file2.txt to be a documentation file
-Tag( 'file2.txt', doc )
+Tag( 'file2.txt', DOC )
 </example>
 </summary>
-</builder>
+</scons_function>
+
 
+<!--
 <function name="FindSourceFiles">
 <summary>
 A convenience function which returns all leaves of the build tree.
diff --git a/src/engine/SCons/Tool/qt.xml b/src/engine/SCons/Tool/qt.xml
index fcab437..7a55dad 100644
--- a/src/engine/SCons/Tool/qt.xml
+++ b/src/engine/SCons/Tool/qt.xml
@@ -88,7 +88,7 @@ variables &cv-link-CPPPATH;,
 &cv-link-LIBPATH; and
 &cv-link-LIBS; may be modified
 and the variables
-PROGEMITTER, SHLIBEMITTER and LIBEMITTER
+&cv-link-PROGEMITTER;, &cv-link-SHLIBEMITTER; and &cv-link-LIBEMITTER;
 are modified. Because the build-performance is affected when using this tool,
 you have to explicitly specify it at Environment creation:
 
@@ -104,8 +104,9 @@ However, there are a few preconditions to do so: Your header file must have
 the same filebase as your implementation file and must stay in the same
 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
-See also the corresponding builder method
-.B Moc()
+See also the corresponding
+&b-Moc();
+builder method.
 
 <emphasis Role="strong">Automatic moc file generation from cxx files.</emphasis>
 As stated in the qt documentation, include the moc file at the end of