From 4fc13f6468e4625ae931f11127e19d7f6c3ed8b3 Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Mon, 29 Jan 2024 09:25:26 -0700
Subject: Adjust sconsign manpage

Following review comments, restored more descriptive names and
reworded some things.

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

diff --git a/doc/man/sconsign.xml b/doc/man/sconsign.xml
index b5b01ca..9ece78a 100644
--- a/doc/man/sconsign.xml
+++ b/doc/man/sconsign.xml
@@ -43,6 +43,9 @@ Displays the contents of one or more
 <firstterm>sconsign</firstterm> files,
 the signature/dependency database
 used by the &SCons; build tool.
+The database contains all Nodes that are known to the build,
+either by declaration in the build configuration,
+produced as side effects, or detected by inspection.
 </para>
 
 <para>By default,
@@ -53,33 +56,39 @@ Without options,
 individual dependency entries are printed in the following format:</para>
 
 <screen>
-depfile: csig timestamp length
-        implicit_dependency_1: csig timestamp length
-        implicit_dependency_2: csig timestamp length
+depfile: content-signature timestamp length
+        implicit-dependency-1: content-signature timestamp length
+        implicit-dependency-2: content-signature timestamp length
         ...
-        bactsig [action string]
+        build-signature [action-string]
 </screen>
 
 <para>
-<emphasis role="bold">csig</emphasis>
-is the <firstterm>content signature</firstterm>,
-a hash of the file's contents.
-<emphasis role="bold">bactsig</emphasis>
-is the <firstterm>build action signature</firstterm>,
-a hash of the command line or other build action
-used to build a target.
+<emphasis role="bold">content-signature</emphasis>
+is the hash of the file's contents (<firstterm>csig</firstterm>)
+and <emphasis role="bold">build-signature</emphasis>
+is the hash of the command line or other build action
+used to build a target (<firstterm>bactsig</firstterm>).
+If provided,
+<emphasis role="bold">action-string</emphasis>
+is the unexpanded string action or the function called.
 <emphasis role="bold">None</emphasis>
 is printed in place of any missing timestamp,
 <emphasis role="bold">csig</emphasis>,
 or <emphasis role="bold">bactsig</emphasis>
-values for any entry
-or any of its dependencies.
+values for any entry or any of its dependencies.
 If the entry has no implicit dependencies,
 or no build action,
 the corresponding lines are omitted.
 </para>
 
 <para>
+An indicator line is printed for each directory,
+as directories do not have signatures in the database
+and so would not otherwise be shown.
+</para>
+
+<para>
 By default,
 <command>sconsign</command>
 assumes that any
-- 
cgit v0.12