[groff] 04/14: [[gnt]roff]: Make usage messages more accurate.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b4de44f028f18ffe369c8cd328f07cdcc523bfaa
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jul 19 11:59:10 2021 +1000

    [[gnt]roff]: Make usage messages more accurate.
    
    * src/roff/groff/groff.cpp (synopsis): Drop `-h` and `-v` from
      normal operation synopsis.  Tighten presentation of alternate usage
      forms.
    
    * src/roff/nroff/nroff.sh: Report `$prog` instead of "nroff" literal.
      Refer to `-P` option argument as "arg" instead of "opt", for
      consistency with groff usage message.  Use opposite case from option
      letter for option argument.
    
    * src/roff/troff/input.cpp (usage): Put brackets around options.  Sort
      options taking arguments in en_US lexicographic order.  Drop `-v` from
      normal operation synopsis.  Use opposite case from option letter for
      option argument.  Put operand name in capitals.  Set valid usage forms
      on one physical line each (see 89648fb4, 5 June).  Add synopsis line
      for alternate usage forms.
    
    Also:
    
    * src/roff/nroff/nroff.1.man (Description): Clarify operation of `-v`
      and `--version`.
---
 ChangeLog                  | 18 ++++++++++++++++++
 src/roff/groff/groff.cpp   |  9 ++++-----
 src/roff/nroff/nroff.1.man |  4 +++-
 src/roff/nroff/nroff.sh    |  7 ++++---
 src/roff/troff/input.cpp   |  6 ++++--
 5 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 28baec9..2c4ffbb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,23 @@
 2021-07-13  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       [[gnt]roff]: Make usage messages more accurate.
+
+       * src/roff/groff/groff.cpp (synopsis): Drop `-h` and `-v` from
+       normal operation synopsis.  Tighten presentation of alternate
+       usage forms.
+       * src/roff/nroff/nroff.sh: Report `$prog` instead of "nroff"
+       literal.  Refer to `-P` option argument as "arg" instead of
+       "opt", for consistency with groff usage message.  Use opposite
+       case from option letter for option argument.
+       * src/roff/troff/input.cpp (usage): Put brackets around options.
+       Sort options taking arguments in en_US lexicographic order.
+       Drop `-v` from normal operation synopsis.  Use opposite case
+       from option letter for option argument.  Put operand name in
+       capitals.  Set valid usage forms on one physical line each (see
+       89648fb4, 5 June).  Add synopsis line for alternate usage forms.
+
+2021-07-13  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        [troff]: Refactor environment initialization, switching, and
        copying.
 
diff --git a/src/roff/groff/groff.cpp b/src/roff/groff/groff.cpp
index 702eca4..9b2e86c 100644
--- a/src/roff/groff/groff.cpp
+++ b/src/roff/groff/groff.cpp
@@ -781,11 +781,10 @@ char **possible_command::get_argv()
 void synopsis(FILE *stream)
 {
   fprintf(stream,
-"usage: %1$s [-abceghijklpstvzCEGNRSUVXZ] [-dCS] [-Denc] [-fFAM]"
-" [-Fdir] [-Idir] [-Kenc] [-Larg] [-mNAME] [-Mdir] [-nNUM] [-oLIST]"
-" [-Parg] [-rCN] [-Tdev] [-wNAME] [-Wname] [FILE ...]\n"
-"usage: %1$s -h\n"
-"usage: %1$s --help\n",
+"usage: %1$s [-abcegijklpstzCEGNRSUVXZ] [-dCS] [-Denc] [-fFAM] [-Fdir]"
+" [-Idir] [-Kenc] [-Larg] [-mNAME] [-Mdir] [-nNUM] [-oLIST] [-Parg]"
+" [-rCN] [-Tdev] [-wNAME] [-Wname] [FILE ...]\n"
+"usage: %1$s {-h | --help | -v | --version}\n",
          program_name);
 }
 
diff --git a/src/roff/nroff/nroff.1.man b/src/roff/nroff/nroff.1.man
index 167c267..daa10e4 100644
--- a/src/roff/nroff/nroff.1.man
+++ b/src/roff/nroff/nroff.1.man
@@ -211,7 +211,9 @@ but does not execute it.
 .B \-v
 and
 .B \-\-version
-show version information,
+show version information about
+.I \%@g@nroff
+and the programs it runs,
 while
 .B \-\-help
 displays a usage message;
diff --git a/src/roff/nroff/nroff.sh b/src/roff/nroff/nroff.sh
index f5dcff0..b40bb37 100644
--- a/src/roff/nroff/nroff.sh
+++ b/src/roff/nroff/nroff.sh
@@ -93,10 +93,11 @@ do
       echo "GNU nroff (groff) version @VERSION@"
       opts="$opts $1" ;;
     --help)
-      # Wrap usage message at 80 columns.
       cat <<EOF
-usage: nroff [-bcCEhikpStUVz] [-dCS] [-Karg] [-mNAME] [-MDIR] [-nNUM] [-oLIST]
-             [-Popt ...] [-rCN] [-Tname] [-wNAME] [-WNAME] [FILE ...]
+usage: $prog [-bcCEhikpStUVz] [-dCS] [-Karg] [-mNAME] [-Mdir] [-nNUM]\
+ [-oLIST] [-Parg] [-rCN] [-Tname] [-wNAME] [-Wname] [--version]\
+ [FILE ...]
+usage: $prog {--help | -v | --version}
 EOF
       exit 0 ;;
     --)
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index dc34127..f5adcc2 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -7960,8 +7960,10 @@ static void add_string(const char *s, string_list **p)
 void usage(FILE *stream, const char *prog)
 {
   fprintf(stream,
-"usage: %s -abcivzCERU -wname -Wname -dcs -ffam -mname -nnum -olist\n"
-"       -rcn -Tname -Fdir -Idir -Mdir [files...]\n",
+"usage: %1$s [-abcizCERU] [-dCS] [-fFAM] [-Fdir] [-Idir] [-mNAME]"
+" [-Mdir] [-nNUM] [-oLIST] [-rCN] [-Tname] [-wNAME] [-Wname]"
+" [FILE ...]\n"
+"usage: %1$s {-h | --help | -v | --version}\n",
          prog);
 }