[groff] 10/47: [indxbib]: Document --version in usage message.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit bddcd98a59d2dda8086b26890fc298620a6d5dd9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jan 5 21:14:35 2022 +1100

    [indxbib]: Document --version in usage message.
    
    * src/utils/indxbib/indxbib.cpp (usage): Document --version option.  Use
      more informative metasyntactic variable names.  Organize usage message
      consistently with our others, and stop wrapping the output lines: we
      know neither the width of the terminal nor the length of the
      `program_name` string we're interpolating.  See commit b4de44f0, 19
      July 2021.
    
    Also fix content, style, and markup nits in its man page.
    
    Content:
    * Cross-reference getcwd(2) instead of pwd(1), a more appropriate choice
      since the indxbib program is not a shell script.
    * Talk directly about what defaults are when discussing various options,
      instead of saying "initially".  The latter term reflects knowledge of
      how and when the program initializes variables and then alters them
      when parsing its command line.  That's inside baseball.  The program
      could conceivably be refactored to differently handle option arguments
      and the internal parameters they manipulate.
    * Point out that bibliographic field names are one character in length.
    
    Style:
    * Use the same metasyntactic variable names as in the usage message.
    * Sort list of options in lexicographic order.
    * Remove initial capitals and trailing periods from sentence fragments.
    * Tighten wording.
    
    Markup:
    * Protect metasyntactic variable names in synopsis from hyphenation
      (this is for clarity and not necessary IMO in running text).
---
 ChangeLog                       |  11 ++++
 src/utils/indxbib/indxbib.1.man | 127 +++++++++++++++++++---------------------
 src/utils/indxbib/indxbib.cpp   |   8 ++-
 3 files changed, 77 insertions(+), 69 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ac187689..9b237540 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2022-01-05  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [indxbib]: Document --version in usage message.
+
+       * src/utils/indxbib/indxbib.cpp (usage): Document --version
+       option.  Use more informative metasyntactic variable names.
+       Organize usage message consistently with our others, and stop
+       wrapping the output lines: we know neither the width of the
+       terminal nor the length of the `program_name` string we're
+       interpolating.  See commit b4de44f0, 19 July 2021.
+
 2022-01-05  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [libbib]: Refactor index header checking.
diff --git a/src/utils/indxbib/indxbib.1.man b/src/utils/indxbib/indxbib.1.man
index a32c730c..852d5b44 100644
--- a/src/utils/indxbib/indxbib.1.man
+++ b/src/utils/indxbib/indxbib.1.man
@@ -37,25 +37,25 @@
 .SY @g@indxbib
 .RB [ \-w ]
 .RB [ \-c\~\c
-.IR common-words-file ]
+.IR \%common-words-file ]
 .RB [ \-d\~\c
 .IR dir ]
 .RB [ \-f\~\c
-.IR list-file ]
+.IR \%list-file ]
 .RB [ \-h\~\c
-.IR n ]
+.IR \%min-hash-table-size ]
 .RB [ \-i\~\c
-.IR string ]
+.IR \%excluded-fields ]
 .RB [ \-k\~\c
-.IR n ]
+.IR \%max-keys-per-record ]
 .RB [ \-l\~\c
-.IR n ]
+.IR \%min-key-length ]
 .RB [ \-n\~\c
-.IR n ]
+.IR \%threshold ]
 .RB [ \-o\~\c
 .IR file ]
 .RB [ \-t\~\c
-.IR n ]
+.IR \%max-key-length ]
 .RI [ file\~ .\|.\|.]
 .YS
 .
@@ -118,8 +118,8 @@ character.
 .LP
 The values set by the
 .BR \-c ,
-.BR \-n ,
 .BR \-l ,
+.BR \-n ,
 and
 .B \-t
 options are stored in the index:
@@ -159,7 +159,7 @@ all exit afterward.
 .TP
 .BI \-c\~ common-words-file
 Read the list of common words from
-.I file
+.I common-words-file
 instead of
 .IR \%@COMMON_WORDS_FILE@ .
 .
@@ -168,14 +168,13 @@ instead of
 .BI \-d\~ dir
 Use
 .I dir
-as the pathname of the current working directory to store in the index,
-instead of the path printed by
-.MR pwd 1 .
+as the name of the directory to store in the index,
+instead of that returned by
+.MR getcwd 2 .
 .
-Usually
+Typically,
 .I dir
-will be a symbolic link that points to the directory printed by
-.MR pwd 1 .
+will be a symbolic link whose target is the current working directory.
 .
 .
 .TP
@@ -195,83 +194,78 @@ option can be given at most once.
 .
 .
 .TP
-.BI \-i\~ string
-Don't index the contents of fields whose names are in
-.IR string .
+.BI \-h\~ min-hash-table-size
+Use the first prime number greater than or equal to
+the argument for the size of the hash table.
 .
-Field names are one character each.
+Larger values
+will usually make searching faster,
+but will make the index file larger
+and cause
+.I \%@g@indxbib
+to use more memory.
 .
-Initially,
-.I string
-is
-.BR XYZ .
+The default hash table size is 997.
 .
 .
 .TP
-.BI \-h\~ n
-Use the first prime greater than or equal to
-.I n
-for the size of the hash table.
+.BI \-i\~ excluded-fields
+Don't index the contents of fields whose names are in
+.IR excluded-fields .
 .
-Larger values of
-.I n
-will usually make searching faster,
-but will make the index larger
-and
-.I \%@g@indxbib
-use more memory.
+Field names are one character each.
 .
-Initially,
-.I n
-is 997.
+If this option is not present,
+.I \%@g@indxbib
+excludes fields
+.BR X ,
+.BR Y ,
+and
+.BR Z .
 .
 .
 .TP
-.BI \-k\~ n
-Use at most
-.I n
-keys per input record.
+.BI \-k\~ max-keys-per-record
+Use no more keys per input record than specified in the argument.
 .
-Initially,
-.I n
-is 100.
+If this option is not present,
+the maximum is 100.
 .
 .
 .TP
-.BI \-l\~ n
-Discard keys that are shorter than
-.IR n .
+.BI \-l\~ min-key-length
+Discard any key whose length in characters is shorter than the value of
+the argument.
 .
-Initially,
-.I n
+If this option is not present,
+the minimum key length
 is 3.
 .
 .
 .TP
-.BI \-n\~ n
+.BI \-n\~ threshold
 Discard the
-.I n
-most common words.
+.I threshold
+most common words from the common words file.
 .
-Initially,
-.I n
-is 100.
+If this option is not present,
+the 100 most common words are discarded.
 .
 .
 .TP
 .BI \-o\~ basename
-The index should be named
+Name the index
 .RI basename @INDEX_SUFFIX@ .
 .
 .
 .TP
-.BI \-t\~ n
+.BI \-t\~ max-key-length
 Truncate keys to
-.IR n .
+.I max-key-length
+in characters.
 .
-Initially,
-.I n
-is 6.
+If this option is not present,
+keys are truncated to 6 characters.
 .
 .
 .TP
@@ -287,17 +281,18 @@ Each file is a separate record.
 .
 .TP
 .RI \%file @INDEX_SUFFIX@
-Index.
+index for
+.I file
 .
 .
 .TP
 .I \%@DEFAULT_INDEX_NAME@@INDEX_SUFFIX@
-Default index name.
+default index name
 .
 .
 .TP
 .I \%@COMMON_WORDS_FILE@
-List of common words.
+contains the list of common words.
 .
 The traditional name,
 .RI \[lq] eign \[rq],
@@ -306,7 +301,7 @@ is an abbreviation of \[lq]English ignored [word list]\[rq].
 .
 .TP
 .IR \%indxbib XXXXXX
-Temporary file.
+temporary file
 .
 .
 .\" ====================================================================
diff --git a/src/utils/indxbib/indxbib.cpp b/src/utils/indxbib/indxbib.cpp
index 1ccd2f0b..e06f4d40 100644
--- a/src/utils/indxbib/indxbib.cpp
+++ b/src/utils/indxbib/indxbib.cpp
@@ -327,9 +327,11 @@ int main(int argc, char **argv)
 static void usage(FILE *stream)
 {
   fprintf(stream,
-"usage: %s [-vw] [-c file] [-d dir] [-f file] [-h n] [-i XYZ] [-k n]\n"
-"       [-l n] [-n n] [-o base] [-t n] [files...]\n",
-         program_name);
+"usage: %s [-w] [-c common-words-file] [-d dir] [-f list-file]"
+" [-h min-hash-table-size] [-i excluded-fields]"
+" [-k max-keys-per-record] [-l min-key-length]"
+" [-n threshold] [-o file] [-t max-key-length] [file] ...\n"
+"usage: %s { -v | --version }\n", program_name, program_name);
 }
 
 static void check_integer_arg(char opt, const char *arg, int min, int *res)