[PR #3836] add example of SConsign(dbm_modue=...) (skip appveyor)

It wasn't clear that you need to pass the module name to
SConsignFile, the expectation might be to pass a string,
so clarified and an example added to show it.

Some of the wording was simplified a bit.

Added a testcase of explicity passing dbm_module=SCons.dblite,
as this should work.

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

1 files changed, 32 insertions, 25 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 93c927819..d594bdf90 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -2744,58 +2744,61 @@ SConscript('bar/SConscript')	# will chdir to bar
 </arguments>
 <summary>
 <para>
-Store the &SCons; file signature database in
-the file <parameter>name</parameter>,
-using <parameter>dbm_module</parameter>
-as the file format.
+Specify where to store the &SCons; file signature database,
+and which database format to use.
 This may be useful to specify alternate
 database files and/or file locations for different types of builds.
 </para>
 <para>
-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
+The optional <parameter>name</parameter> argument
+is the base name of the database file(s).
+If not an absolute path name,
+these are placed relative to the directory containing the
 top-level &SConstruct; file.
 The default is
 <filename>.sconsign</filename>.
-The actual file name stored on disk
+The actual database file(s) stored on disk
 may have an appropriate suffix appended
 by the chosen
 <parameter>dbm_module</parameter>
 </para>
 <para>
-The optional second argument (or
-<parameter>dbm_module</parameter>
-keyword argument) can be used to specify
-which Python database module to use
+The optional <parameter>dbm_module</parameter>
+argument specifies which
+Python database module to use
 for reading/writing the file.
-The default is to use a custom
-<filename>SCons.dblite</filename>
+The module must be imported first;
+then the imported module name
+is passed as the argument.
+The default is a custom
+<systemitem>SCons.dblite</systemitem>
 module that uses pickled
 Python data structures,
-and which works on all Python versions.
+which works on all Python versions.
+See documentation of the Python
+<systemitem>dbm</systemitem> module
+for other available types.
 </para>
 <para>
-If called with no arguments, 
-the filename will default to
+If called with no arguments,
+the database will default to
 <filename>.sconsign.dblite</filename>
-in the top directory of the project. 
-This also the default if
+in the top directory of the project,
+which is 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.
+is variable expansion on <parameter>name</parameter>.
+There should only be one active call to this
+function/method in a given build setup.
 </para>
 <para>
-If 
+If
 <parameter>name</parameter>
 is set to
 <constant>None</constant>,
-then
 &scons;
 will store file signatures
 in a separate
@@ -2805,7 +2808,7 @@ 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 
+Use of this mode is discouraged and may be
 deprecated in a future &SCons; release.
 </para>
 
@@ -2830,6 +2833,10 @@ SConsignFile("/home/me/SCons/signatures")
 # Stores signatures in a separate .sconsign file
 # in each directory.
 SConsignFile(None)
+
+# Stores signatures in a GNU dbm format .sconsign file
+import dbm.gnu
+SConsignFile(dbm_module=dbm.gnu)
 </example_commands>
 </summary>
 </scons_function>