[groff] 14/14: src/roff/groff/groff.cpp: Revise usage message.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 89648fb4dcce64fa7fba230088c6e6cd931a4c0b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jun 5 05:37:00 2021 +1000

    src/roff/groff/groff.cpp: Revise usage message.
    
    * src/roff/groff/groff.cpp: Revise usage message.
    
      (synopsis): Set primary synopsis on a single output line, for
      convenience of parsing and also because we have no control over the
      width of the program name in character cells; it comes from argv[0]
      and is under user control.  There is thus no point in trying to get
      pretty formatting.  Also include separate synopsis lines for short and
      long help options.  Use opposite case from option flags for option
      arguments.
    
      (help): Collate option flags in English lexicographic order.  Include
      space after flag letters for options that take arguments.
      Consistently use capitals for options arguments because they are
      space-separated here.  Illustrate longer forms of -d and -r options.
      Update language (some, like "tmac.name", was very old).  Add reference
      to groff(1) man page at end.
    
      (usage): Drop appendnment of notice regarding -h option; this is now
      covered in `synopsis()` unconditionally.
---
 ChangeLog                | 19 ++++++++++++
 src/roff/groff/groff.cpp | 80 +++++++++++++++++++++++++-----------------------
 2 files changed, 61 insertions(+), 38 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 59a6ac1..7c1669b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,24 @@
 2021-06-05  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       * src/roff/groff/groff.cpp: Revise usage message.
+       (synopsis): Set primary synopsis on a single output line, for
+       convenience of parsing and also because we have no control over
+       the width of the program name in character cells; it comes from
+       argv[0] and is under user control.  There is thus no point in
+       trying to get pretty formatting.  Also include separate synopsis
+       lines for short and long help options.  Use opposite case from
+       option flags for option arguments.
+       (help): Collate option flags in English lexicographic order.
+       Include space after flag letters for options that take
+       arguments.  Consistently use capitals for options arguments
+       because they are space-separated here.  Illustrate longer forms
+       of -d and -r options.  Update language (some, like "tmac.name",
+       was very old).  Add reference to groff(1) man page at end.
+       (usage): Drop appendnment of notice regarding -h option; this is
+       now covered in `synopsis()` unconditionally.
+
+2021-06-05  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        Eliminate "groff_opts_no_arg.txt" and "groff_opts_with_arg.txt"
        files from distribution.  They are not needed by any live code
        in the tree; possibly only groffer ever used them.
diff --git a/src/roff/groff/groff.cpp b/src/roff/groff/groff.cpp
index 2ad4107..702eca4 100644
--- a/src/roff/groff/groff.cpp
+++ b/src/roff/groff/groff.cpp
@@ -781,9 +781,11 @@ char **possible_command::get_argv()
 void synopsis(FILE *stream)
 {
   fprintf(stream,
-"usage: %s [-abceghijklpstvzCEGNRSUVXZ] [-dcs] [-ffam] [-mname] [-nnum]\n"
-"       [-olist] [-rcn] [-wname] [-Darg] [-Fdir] [-Idir] [-Karg] [-Larg]\n"
-"       [-Mdir] [-Parg] [-Tdev] [-Wname] [files...]\n",
+"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",
          program_name);
 }
 
@@ -791,49 +793,52 @@ void help()
 {
   synopsis(stdout);
   fputs("\n"
-"-h\tprint this message\n"
-"-v\tprint version number\n"
+"-a\tproduce approximate description of output\n"
+"-b\tprint backtraces with errors or warnings\n"
+"-c\tdisable color output\n"
+"-C\tenable compatibility mode\n"
+"-d CS\tdefine string C as S\n"
+"-d C=S\tdefine string C as S; C can be multiple characters\n"
+"-D ENC\tfall back to ENC as default input encoding; implies -k\n"
 "-e\tpreprocess with eqn\n"
+"-E\tsuppress error diagnostics\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"
-"-j\tpreprocess with chem\n"
-"-k\tpreprocess with preconv\n"
-"-p\tpreprocess with pic\n"
-"-s\tpreprocess with soelim\n"
-"-t\tpreprocess with tbl\n"
 "-G\tpreprocess with grap\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\n"
 "-J\tpreprocess with gideal\n"
-"-R\tpreprocess with refer\n"
-"-a\tproduce ASCII description of output\n"
-"-b\tprint backtraces with errors or warnings\n"
-"-c\tdisable color output\n"
-"-dcs\tdefine a string c as s\n"
-"-ffam\tuse fam as the default font family\n"
-"-i\tread standard input after named input files\n"
+"-k\tpreprocess with preconv\n"
+"-K ENC\tuse ENC as input encoding; implies -k\n"
 "-l\tspool the output\n"
-"-mname\tread macros tmac.name\n"
-"-nnum\tnumber first page n\n"
-"-olist\toutput only pages in list\n"
-"-rcn\tdefine a number register c as n\n"
-"-wname\tenable warning name\n"
-"-z\tsuppress formatted output\n"
-"-C\tenable compatibility mode\n"
-"-Darg\tuse arg as default input encoding.  Implies -k\n"
-"-E\tinhibit all errors\n"
-"-Fdir\tsearch dir for device directories\n"
-"-Idir\tsearch dir for soelim, troff, and grops.  Implies -s\n"
-"-Karg\tuse arg as input encoding.  Implies -k\n"
-"-Larg\tpass arg to the spooler\n"
-"-Mdir\tsearch dir for macro files\n"
+"-L ARG\tpass ARG to the 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"
-"-Parg\tpass arg to the postprocessor\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\tdefine register C as N\n"
+"-r C=N\tdefine register C as N; C can be multiple characters\n"
+"-R\tpreprocess with refer\n"
+"-s\tpreprocess with soelim\n"
 "-S\tenable safer mode (the default)\n"
-"-Tdev\tuse device dev\n"
+"-t\tpreprocess with tbl\n"
+"-T DEV\tprepare output for device DEV\n"
 "-U\tenable unsafe mode\n"
-"-V\tprint commands on stdout instead of running them\n"
-"-Wname\tinhibit warning name\n"
-"-X\tuse X11 previewer rather than usual postprocessor\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\tdon't postprocess\n"
-"\n",
+"\n"
+"See groff(1) for details.\n",
        stdout);
   exit(0);
 }
@@ -841,7 +846,6 @@ void help()
 void usage(FILE *stream)
 {
   synopsis(stream);
-  fprintf(stream, "%s -h gives more help\n", program_name);
 }
 
 extern "C" {