From 02d7ef2030eb6836b65a6f1e832344bd68ea33a4 Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Tue, 23 Aug 2022 08:50:46 -0600
Subject: Tweak --hash-format manpage entry  [skip appveyor]

Previously, there are some wording problems and one paragraph
was essentially a restatement of an earlier one.  Also corrected
the claim that --hash-format=md5 would create an unadorned
.sconsign.dblite - tested to show it is actually .sconsign_md5.dblite

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 doc/man/scons.xml | 35 +++++++++++++++++++++--------------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index e7f6db0..44bb852 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1205,26 +1205,33 @@ be appropriate for most uses.</para>
 <para>Set the hashing algorithm used by SCons to
 <replaceable>ALGORITHM</replaceable>.
 This value determines the hashing algorithm used in generating
-&contentsigs; or &CacheDir; keys.</para>
+&contentsigs;, &buildsigs; and &CacheDir; keys.</para>
 
-<para>The supported list of values are: md5, sha1, and sha256.
+<para>The supported list of values are:
+<parameter>md5</parameter>,
+<parameter>sha1</parameter>
+and <parameter>sha256</parameter>.
 However, the Python interpreter used to run SCons must have the corresponding
 support available in the <systemitem>hashlib</systemitem> module
 to use the specified algorithm.</para>
 
-<para>Specifying this value changes the name of the SConsign database.
-For example, <option>--hash-format=sha256</option> will create a SConsign
-database with name <filename>.sconsign_sha256.dblite</filename>.</para>
-
-<para>If this option is not specified, a the first supported hash format found
-is selected. Typically this is MD5, however, if you are on a FIPS-compliant system
-and using a version of Python less than 3.9, SHA1 or SHA256 will be chosen as the default.
-Python 3.9 and onwards clients will always default to MD5, even in FIPS mode, unless
-otherwise specified with the <option>--hash-format</option> option.</para>
+<para>If this option is omitted,
+the first supported hash format found is selected.
+Typically this is MD5, however, on a FIPS-compliant system
+using a version of Python less than 3.9,
+SHA1 or SHA256 will be chosen as the default.
+Python 3.9 and onwards clients will always default to MD5, even in FIPS mode.
+</para>
 
-<para>For MD5 databases (either explicitly specified with <option>--hash-format=md5</option> or
-defaulted), the SConsign database is<filename>.sconsign.dblite</filename>. The newer SHA1 and
-SHA256 selections meanwhile store their databases to <filename>.sconsign_algorithmname.dblite</filename></para>
+<para>Specifying this option changes the name of the SConsign database.
+The default database is <filename>.sconsign.dblite</filename>;
+in the presence of this option,
+<replaceable>ALGORITHM</replaceable> will
+be included in the name to indicate the difference,
+even if the argument is <parameter>md5</parameter>.
+For example, <option>--hash-format=sha256</option> will create a SConsign
+database named <filename>.sconsign_sha256.dblite</filename>.
+</para>
 
 <para><emphasis>Available since &scons; 4.2.</emphasis></para>
   </listitem>
-- 
cgit v0.12