[groff] 06/14: [[gnt]roff]: Increase documentation of -d, -r.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a4670e5281944184cc04dccae31fb5ff5900a01c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jul 19 05:23:04 2021 +1000

    [[gnt]roff]: Increase documentation of -d, -r.
    
    * src/roff/groff/groff.cpp (synopsis, help):
    * src/roff/troff/input.cpp (usage): Explicitly document -dNAME=STRING
      and -rREG=EXPR forms (not just their versions taking one-character
      register or string names).
    
      (help): Use metasyntactic variable names consistent with man page and
      usage message.
    
    * src/roff/groff/groff.1.man (Synopsis): Add -dNAME=STRING, -rREG=EXPR.
      (Options): Rename metasyntactic variables in longer forms to `string`
      and `expr`, respectively, to cue reader that they can be or arbitrary
      length.
    
    * src/roff/nroff/nroff.sh: Explicitly document -dNAME=STRING and
      -rREG=EXPR forms (not just their versions taking one-character
      register or string names).
    
    * src/roff/troff/troff.1.man (Synopsis): Add -dNAME, -rREG.
      (Options): Rename metasyntactic variables in longer forms to `string`
      and `expr`, respectively, to cue reader that they can be or arbitrary
      length.  Clarify that roff objects are being thus defined.  Clarify
      that the name or register being assigned to in the short form is one
      _character_, not merely one "letter"; numerals, punctuation, and, if
      you quote them, even shell metacharacters are valid in roff
      identifiers and are accepted here.  Note the only exception to the
      foregoing: due to the way `getopt_long()` works, the first equals sign
      is interpreted as an assignment operator by the option parser.
        echo '.tm \*1' | groff -d1=foo=bar
      Also see <https://savannah.gnu.org/bugs/?60935>.
---
 ChangeLog                  |  1 +
 src/roff/groff/groff.1.man | 15 ++++++++--
 src/roff/groff/groff.cpp   | 15 +++++-----
 src/roff/nroff/nroff.sh    |  6 ++--
 src/roff/troff/input.cpp   |  6 ++--
 src/roff/troff/troff.1.man | 70 ++++++++++++++++++++++++++++++++++------------
 6 files changed, 79 insertions(+), 34 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d820bcb..5a798c1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -5,6 +5,7 @@
        * src/roff/groff/groff.cpp (synopsis): Drop `-h` and `-v` from
        normal operation synopsis.  Sort options in en_US lexicographic
        order.  Tighten presentation of alternate usage forms.
+       (help): Document longer forms of `-d` and `-r`.
        * 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
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 5aec754..6214002 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -37,6 +37,9 @@ groff \- front end to the GNU roff document formatting system
 .RB [ \-abcCeEgGijklNpRsStUVXzZ ]
 .RB [ \-d\~\c
 .IR cs ]
+.RB [ \-d\~\c
+.IB name =\c
+.IR string ]
 .RB [ \-D\~\c
 .IR enc ]
 .RB [ \-f\~\c
@@ -61,6 +64,9 @@ groff \- front end to the GNU roff document formatting system
 .IR arg ]
 .RB [ \-r\~\c
 .IR cn ]
+.RB [ \-r\~\c
+.IB reg =\c
+.IR expr ]
 .RB [ \-T\~\c
 .IR dev ]
 .RB [ \-w\~\c
@@ -676,12 +682,14 @@ see
 .B \-C
 Enable compatibility mode.
 .
+.
 .TP
 .BI \-d\~ cs
 .TQ
-.BI \-d\~ name = s
+.BI \-d\~ name = string
 Define string.
 .
+.
 .TP
 .B \-E
 Inhibit
@@ -745,11 +753,12 @@ Number the first page
 Output only pages in
 .IR list .
 .
+.
 .TP
 .BI \-r\~ cn
 .TQ
-.BI \-r\~ name = n
-Set number register.
+.BI \-r\~ reg = expr
+Define register.
 .
 .
 .TP
diff --git a/src/roff/groff/groff.cpp b/src/roff/groff/groff.cpp
index c5365ff..698f0ac 100644
--- a/src/roff/groff/groff.cpp
+++ b/src/roff/groff/groff.cpp
@@ -781,9 +781,10 @@ char **possible_command::get_argv()
 void synopsis(FILE *stream)
 {
   fprintf(stream,
-"usage: %1$s [-abcCeEgGijklNpRsStUVXzZ] [-dCS] [-Denc] [-fFAM] [-Fdir]"
-" [-Idir] [-Kenc] [-Larg] [-mNAME] [-Mdir] [-nNUM] [-oLIST] [-Parg]"
-" [-rCN] [-Tdev] [-wNAME] [-Wname] [FILE ...]\n"
+"usage: %1$s [-abcCeEgGijklNpRsStUVXzZ] [-dCS] [-dNAME=STRING] [-Denc]"
+" [-fFAM] [-Fdir] [-Idir] [-Kenc] [-Larg] [-mNAME] [-Mdir] [-nNUM]"
+" [-oLIST] [-Parg] [-rCN] [-rREG=EXPR] [-Tdev] [-wNAME] [-Wname]"
+" [FILE ...]\n"
 "usage: %1$s {-h | --help | -v | --version}\n",
          program_name);
 }
@@ -796,8 +797,8 @@ void help()
 "-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 CS\tdefine one-character string name C as string S\n"
+"-d NAME=STRING\n\tdefine string NAME as STRING\n"
 "-D ENC\tfall back to ENC as default input encoding; implies -k\n"
 "-e\tpreprocess with eqn\n"
 "-E\tsuppress error diagnostics\n"
@@ -821,8 +822,8 @@ void help()
 "-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 CN\tdefine one-character register name C as numeric expression N\n"
+"-r REG=EXPR\n\tdefine register REG as numeric expression EXPR\n"
 "-R\tpreprocess with refer\n"
 "-s\tpreprocess with soelim\n"
 "-S\tenable safer mode (the default)\n"
diff --git a/src/roff/nroff/nroff.sh b/src/roff/nroff/nroff.sh
index b40bb37..9ab2939 100644
--- a/src/roff/nroff/nroff.sh
+++ b/src/roff/nroff/nroff.sh
@@ -94,9 +94,9 @@ do
       opts="$opts $1" ;;
     --help)
       cat <<EOF
-usage: $prog [-bcCEhikpStUVz] [-dCS] [-Karg] [-mNAME] [-Mdir] [-nNUM]\
- [-oLIST] [-Parg] [-rCN] [-Tname] [-wNAME] [-Wname] [--version]\
- [FILE ...]
+usage: $prog [-bcCEhikpStUVz] [-dCS] [-dNAME=STRING] [-Karg] [-mNAME]\
+ [-Mdir] [-nNUM] [-oLIST] [-Parg] [-rCN] [-rREG=EXPR] [-Tname] [-wNAME]\
+ [-Wname] [FILE ...]
 usage: $prog {--help | -v | --version}
 EOF
       exit 0 ;;
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index 7ec5e4e..390bff2 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -7960,9 +7960,9 @@ static void add_string(const char *s, string_list **p)
 void usage(FILE *stream, const char *prog)
 {
   fprintf(stream,
-"usage: %1$s [-abcCEiRUz] [-dCS] [-fFAM] [-Fdir] [-Idir] [-mNAME]"
-" [-Mdir] [-nNUM] [-oLIST] [-rCN] [-Tname] [-wNAME] [-Wname]"
-" [FILE ...]\n"
+"usage: %1$s [-abcCEiRUz] [-dCS] [-dNAME=STRING] [-fFAM] [-Fdir]"
+" [-Idir] [-mNAME] [-Mdir] [-nNUM] [-oLIST] [-rCN] [-rREG=EXPR]"
+" [-Tname] [-wNAME] [-Wname] [FILE ...]\n"
 "usage: %1$s {-h | --help | -v | --version}\n",
          prog);
 }
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index 0a735df..17eac59 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -35,6 +35,9 @@
 .RB [ \-abcCEiRUz ]
 .RB [ \-d\~\c
 .IR cs ]
+.RB [ \-d\~\c
+.IB name =\c
+.IR string ]
 .RB [ \-f\~\c
 .IR  fam ]
 .RB [ \-F\~\c
@@ -51,6 +54,9 @@
 .IR  list ]
 .RB [ \-r\~\c
 .IR  cn ]
+.RB [ \-r\~\c
+.IB reg =\c
+.IR expr ]
 .RB [ \-T\~\c
 .IR  dev ]
 .RB [ \-w\~\c
@@ -183,17 +189,31 @@ implies \-c.
 .
 .
 .TP
-.BI \-d cs
+.BI \-d\~ cs
 .TQ
-.BI \-d name = s
+.BI \-d\~ name = string
 Define
-.I c
+.I roff
+.RI string\~ c
 or
 .I name
-to be a string
-.IR s ;
+.RI as\~ s
+or
+.IR string ;
 .I c
-must be a one letter name.
+must be a one-character name.
+.
+Due to
+.IR getopt_long (3)
+limitations,
+.IR c\~ cannot
+be and
+.I name
+cannot contain an equals sign,
+even though that is a valid character in a
+.I roff
+identifier.
+.
 .
 .TP
 .B \-E
@@ -335,22 +355,36 @@ means print every page from
 .I \%@g@troff
 will exit after printing the last page in the list.
 .
+.
 .TP
-.BI \-r cn
+.BI \-r\~ cn
 .TQ
-.BI \-r name = n
-Set number register
-.I c
+.BI \-r\~ reg = n
+Define
+.I roff
+.RI register\~ c
 or
-.I name
-to
-.IR n ;
-.I c
-must be a one character name;
-.I n
-can be any
+.I reg
+as
+.I groff
+numeric
+.RI expression\~ n
+or
+.IR expr ;
+.IR c \~must
+be a one-character name.
+.
+Due to
+.IR getopt_long (3)
+limitations,
+.IR c\~ cannot
+be and
+.I reg
+cannot contain an equals sign,
+even though that is a valid character in a
 .I roff
-numeric expression.
+identifier.
+.
 .
 .TP
 .B \-R