From 8f93348cbd542b5a90d736d6b13d4b795a162d8e Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Thu, 26 Nov 2020 09:53:22 -0700
Subject: 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>
---
 SCons/Environment.xml | 98 ++++++++++++++++++++++++++++++---------------------
 SCons/__init__.py     | 10 +++---
 2 files changed, 62 insertions(+), 46 deletions(-)

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index a1fd8ec..93c9278 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
diff --git a/SCons/__init__.py b/SCons/__init__.py
index fcd665e..f9d2085 100644
--- a/SCons/__init__.py
+++ b/SCons/__init__.py
@@ -1,9 +1,9 @@
 __version__="4.0.1.9998"
 __copyright__="Copyright (c) 2001 - 2020 The SCons Foundation"
-__developer__="bdbaddog"
-__date__="2020-10-09 19:00:35"
-__buildsys__="ProDog2020"
-__revision__="93525bed88d19a00f5de400086c0046011d3b833"
-__build__="93525bed88d19a00f5de400086c0046011d3b833"
+__developer__="mats"
+__date__="2020-11-26 16:47:04"
+__buildsys__="boulder"
+__revision__="64a80e530b0caef9763eb67bd770dd9c8925ea18"
+__build__="64a80e530b0caef9763eb67bd770dd9c8925ea18"
 # make sure compatibility is always in place
 import SCons.compat # noqa
\ No newline at end of file
-- 
cgit v0.12