[groff] 34/72: [groff]: Update usage message.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 477ff64882df13e11fff6b11c1de79880dd7b9ac
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Oct 21 22:20:05 2022 -0500

    [groff]: Update usage message.
    
    * src/roff/groff/groff.cpp (synopsis, help): Update usage message.
      Present different modes of operation on separate output lines.  Sort
      options in English lexicographic order.  Revise metasyntactic variable
      names for clarity.
      - name -> string
      The former is not wrong but is too general.  In practice there is no
      way to populate a macro or diversion from a command-line argument.
      - reg -> register
        expr -> numeric-expression
      Use complete words and the exact terminology from our documentation.
---
 ChangeLog                |   7 +--
 src/roff/groff/groff.cpp | 113 ++++++++++++++++++++++++++---------------------
 2 files changed, 67 insertions(+), 53 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ca0269a92..a6c0bb848 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -7,9 +7,10 @@
        * src/preproc/grn/main.cpp (usage):
        * src/preproc/pic/main.cpp (usage):
        * src/preproc/preconv/preconv.cpp (usage):
-       * src/preproc/soelim/soelim.cpp (usage): Update usage message.
-       Present different modes of operation on separate output lines.
-       Sort options in English lexicographic order.
+       * src/preproc/soelim/soelim.cpp (usage):
+       * src/roff/groff/groff.cpp (synopsis, help): Update usage
+       message.  Present different modes of operation on separate
+       output lines.  Sort options in English lexicographic order.
 
 2022-10-21  G. Branden Robinson <g.branden.robinson@gmail.com>
 
diff --git a/src/roff/groff/groff.cpp b/src/roff/groff/groff.cpp
index 1991f5a02..1e0a7dd48 100644
--- a/src/roff/groff/groff.cpp
+++ b/src/roff/groff/groff.cpp
@@ -821,64 +821,77 @@ void synopsis(FILE *stream)
 {
   // Add `J` to the cluster if we ever get ideal(1) support.
   fprintf(stream,
-"usage: %s [-abcCeEgGijklNpRsStUVXzZ] [-dCS] [-dNAME=STRING] [-Denc]"
-" [-fFAM] [-Fdir] [-Idir] [-Kenc] [-Larg] [-mNAME] [-Mdir] [-nNUM]"
-" [-oLIST] [-Parg] [-rCN] [-rREG=EXPR] [-Tdev] [-wNAME] [-Wname]"
+"usage: %s [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text]"
+" [-D fallback-encoding] [-f font-family] [-F font-directory]"
+" [-I inclusion-directory] [-K input-encoding] [-L spooler-argument]"
+" [-m macro-package] [-M macro-directory] [-n page-number]"
+" [-o page-list] [-P postprocessor-argument] [-r cnumeric-expression]"
+" [-r register=numeric-expression] [-T output-device]"
+" [-w warning-category] [-W warning-category]"
 " [file ...]\n"
-"usage: %s {-h | --help | -v | --version}\n",
-         program_name, program_name);
+"usage: %s {-v | --version}\n"
+"usage: %s {-h | --help}\n",
+         program_name, program_name, program_name);
 }
 
 void help()
 {
   synopsis(stdout);
-  fputs("\n"
-"-a\tproduce approximate description of output\n"
-"-b\treport backtraces with errors or warnings\n"
-"-c\tstart with color output disabled\n"
-"-C\tstart with AT&T troff compatibility mode enabled\n"
-"-d ST\tstore text T to string S (one character)\n"
-"-d STRING=TEXT\n\tstore TEXT to string STRING\n"
-"-D ENC\tfall back to ENC as default input encoding; implies -k\n"
-"-e\tpreprocess with eqn\n"
-"-E\tsuppress error diagnostics; implies -Ww\n"
-"-f FAM\tuse FAM as the default font family\n"
-"-F DIR\tsearch DIR for device and font description files\n"
-"-g\tpreprocess with grn\n"
-"-G\tpreprocess with grap; implies -p\n"
-"-h\toutput this usage message and exit\n"
-"-i\tread standard input after all FILEs\n"
-"-I DIR\tsearch DIR for input files; implies -s\n"
-"-j\tpreprocess with chem; implies -p\n"
+  fputs(
+"\n"
+"groff (GNU roff) is a typesetting system that reads plain text input\n"
+"files that include formatting commands to produce output in\n"
+"PostScript, PDF, HTML, or DVI formats or for display to a terminal.\n"
+"\n"
+"Options:\n"
+"  -a\tproduce approximate description of output\n"
+"  -b\treport backtraces with errors or warnings\n"
+"  -c\tstart with color output disabled\n"
+"  -C\tstart with AT&T troff compatibility mode enabled; implies -c\n"
+"  -d CT\tstore text T to string C (one character)\n"
+"  -d NAME=TEXT\n\tstore TEXT to string NAME\n"
+"  -D ENC\tfall back to ENC as default input encoding; implies -k\n"
+"  -e\tpreprocess with eqn\n"
+"  -E\tsuppress error diagnostics; implies -Ww\n"
+"  -f FAM\tuse FAM as the default font family\n"
+"  -F DIR\tsearch DIR for device and font description files\n"
+"  -g\tpreprocess with grn\n"
+"  -G\tpreprocess with grap; implies -p\n"
+"  --help\n"
+"  -h\toutput this usage message and exit\n"
+"  -i\tread standard input after all FILEs\n"
+"  -I DIR\tsearch DIR for input files; implies -s\n"
+"  -j\tpreprocess with chem; implies -p\n"
 // "-J\tpreprocess with gideal\n"
-"-k\tpreprocess with preconv\n"
-"-K ENC\tuse ENC as input encoding; implies -k\n"
-"-l\tsend postprocessed output to print spooler\n"
-"-L ARG\tpass ARG to print spooler\n"
-"-m NAME\tread macro file NAME.tmac\n"
-"-M DIR\tsearch DIR for macro files\n"
-"-N\tdon't allow newlines within eqn delimiters\n"
-"-n NUM\tnumber first page NUM\n"
-"-o LIST\toutput only page in LIST (\"1\"; \"2,4\"; \"3,7-11\")\n"
-"-p\tpreprocess with pic\n"
-"-P ARG\tpass ARG to the postprocessor\n"
-"-r CN\tstore numeric expression N in register C (one character)\n"
-"-r REG=EXPR\n\tstore numeric expression EXPR in register REG\n"
-"-R\tpreprocess with refer\n"
-"-s\tpreprocess with soelim\n"
-"-S\tenable safer mode (default)\n"
-"-t\tpreprocess with tbl\n"
-"-T DEV\tprepare output for device DEV\n"
-"-U\taccept unsafe input (disable safer mode)\n"
-"-v\toutput version information and pass -v to commands to be run\n"
-"-V\twrite commands to standard output instead of running them\n"
-"-w NAME\tenable warning type NAME\n"
-"-W NAME\tinhibit warning type NAME\n"
-"-X\trun gxditview previewer instead of normal postprocessor\n"
-"-z\tsuppress formatted output\n"
-"-Z\tdo not run postprocessor\n"
+"  -k\tpreprocess with preconv\n"
+"  -K ENC\tuse ENC as input encoding; implies -k\n"
+"  -l\tsend postprocessed output to print spooler\n"
+"  -L ARG\tpass ARG to print spooler\n"
+"  -m MAC\tread macro file MAC.tmac\n"
+"  -M DIR\tsearch DIR for macro files\n"
+"  -N\tdon't allow newlines within eqn delimiters\n"
+"  -n NUM\tnumber first page NUM\n"
+"  -o LIST\n\toutput only pages in LIST (\"1\"; \"2,4\"; \"3,7-11\")\n"
+"  -p\tpreprocess with pic\n"
+"  -P ARG\tpass ARG to the postprocessor\n"
+"  -r CN\tstore numeric expression N in register C (one character)\n"
+"  -r REG=EXPR\n\tstore numeric expression EXPR in register REG\n"
+"  -R\tpreprocess with refer\n"
+"  -s\tpreprocess with soelim\n"
+"  -S\tenable safer mode (default)\n"
+"  -t\tpreprocess with tbl\n"
+"  -T DEV\tprepare output for device DEV\n"
+"  -U\taccept unsafe input (disable safer mode)\n"
+"  --version\n"
+"  -v\toutput version information and pass -v to commands to be run\n"
+"  -V\twrite commands to standard output instead of running them\n"
+"  -w CAT\tenable warning category CAT\n"
+"  -W CAT\tinhibit warning category CAT\n"
+"  -X\trun gxditview previewer instead of normal postprocessor\n"
+"  -z\tsuppress formatted output\n"
+"  -Z\tdo not run postprocessor\n"
 "\n"
-"See groff(1) for details.\n",
+"See the groff(1) manual page.\n",
        stdout);
   exit(EXIT_SUCCESS);
 }