Updated sconsign/SConsignFile docs [skip appveyor]

The sconsign manpage had some considerably out of date claims,
updated to current usage and defaults.

The SConsignFile manpage/userguide entry was reworded, mainly
to clarify that there's one setting (the presence of env.SConsignFile
*might* suggest there could be per-env settings), but also fiddled
the wording a fair bit.  Use the same arg names as the actual
function, since those are usable as kwargs (manpage used to use
"file", function accepts "name").

Signed-off-by: Mats Wichmann <mats@linux.com>

1 files changed, 57 insertions, 41 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index a1fd8ece7..93c927819 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -2740,59 +2740,74 @@ SConscript('bar/SConscript')	# will chdir to bar
 
 <scons_function name="SConsignFile">
 <arguments>
-([file, dbm_module])
+([name, dbm_module])
 </arguments>
 <summary>
 <para>
-This tells
-&scons;
-to store all file signatures
-in the specified database
-<parameter>file</parameter>.
-If the
-<parameter>file</parameter>
-name is omitted,
-<filename>.sconsign</filename>
-is used by default.
-(The actual file name(s) stored on disk
-may have an appropriated suffix appended
-by the
-<parameter>dbm_module</parameter>.)
-If
-<parameter>file</parameter>
-is not an absolute path name,
-the file is placed in the same directory as the top-level
-&SConstruct;
-file.
+Store the &SCons; file signature database in
+the file <parameter>name</parameter>,
+using <parameter>dbm_module</parameter>
+as the file format.
+This may be useful to specify alternate
+database files and/or file locations for different types of builds.
 </para>
-
 <para>
-If
-<parameter>file</parameter>
-is
-<constant>None</constant>,
-then
-&scons;
-will store file signatures
-in a separate
-<filename>.sconsign</filename>
-file in each directory,
-not in one global database file.
-(This was the default behavior
-prior to SCons 0.96.91 and 0.97.)
+If the optional first argument (or
+<parameter>name</parameter> keyword argument)
+is not an absolute path name,
+the file is placed relative to the directory containing the
+top-level &SConstruct; file.
+The default is
+<filename>.sconsign</filename>.
+The actual file name stored on disk
+may have an appropriate suffix appended
+by the chosen
+<parameter>dbm_module</parameter>
 </para>
-
 <para>
-The optional
+The optional second argument (or
 <parameter>dbm_module</parameter>
-argument can be used to specify
-which Python database module
+keyword argument) can be used to specify
+which Python database module to use
+for reading/writing the file.
 The default is to use a custom
 <filename>SCons.dblite</filename>
 module that uses pickled
 Python data structures,
 and which works on all Python versions.
 </para>
+<para>
+If called with no arguments, 
+the filename will default to
+<filename>.sconsign.dblite</filename>
+in the top directory of the project. 
+This also the default if
+if &f-SConsignFile; is not called.
+</para>
+<para>
+The setting is global, so the only difference
+between the global function and the environment method form
+is variable expansion. There should only be
+one call to this function/method in a given build setup.
+</para>
+<para>
+If 
+<parameter>name</parameter>
+is set to
+<constant>None</constant>,
+then
+&scons;
+will store file signatures
+in a separate
+<filename>.sconsign</filename>
+file in each directory,
+not in a single combined database file.
+This is a backwards-compatibility meaure to support
+what was the default behavior
+prior to &SCons; 0.97 (i.e. before 2008).
+Use of this mode is discouraged and may be 
+deprecated in a future &SCons; release.
+</para>
 
 <para>
 Examples:
@@ -2800,15 +2815,16 @@ Examples:
 
 <example_commands>
 # Explicitly stores signatures in ".sconsign.dblite"
-# in the top-level SConstruct directory (the
-# default behavior).
+# in the top-level SConstruct directory (the default behavior).
 SConsignFile()
 
 # Stores signatures in the file "etc/scons-signatures"
 # relative to the top-level SConstruct directory.
+# SCons will add a database suffix to this name.
 SConsignFile("etc/scons-signatures")
 
 # Stores signatures in the specified absolute file name.
+# SCons will add a database suffix to this name.
 SConsignFile("/home/me/SCons/signatures")
 
 # Stores signatures in a separate .sconsign file