[groff] 14/15: man pages: Increase consistency with other pages.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d1b084aa092af76ed7b9890b4b9b402e4077f806
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 19 23:15:19 2020 +1100

    man pages: Increase consistency with other pages.
    
    Replace usage of "filespec" as a command operand with "file", in
    parallel with other groff man pages.
    
    Describe --help and --version options (and their short option synonyms)
    much more tersely.
    
    Explain the GNU double-dash option convention more briefly.
    
    Also delete lengthy exposition about "breaking" options, which seems to
    be a Bernd-ism for options that cause an early exit.  I think it's
    easier and briefer to simply say that such options...cause an exit.
---
 contrib/chem/chem.1.man           | 18 ++++----
 contrib/glilypond/glilypond.1.man | 86 +++++++++------------------------------
 contrib/gperl/gperl.1.man         | 67 +++++++++++-------------------
 src/roff/grog/grog.1.man          | 60 +++++++++++----------------
 4 files changed, 75 insertions(+), 156 deletions(-)

diff --git a/contrib/chem/chem.1.man b/contrib/chem/chem.1.man
index c3bfee4..db5dde7 100644
--- a/contrib/chem/chem.1.man
+++ b/contrib/chem/chem.1.man
@@ -31,7 +31,7 @@
 .
 .SY @g@chem
 .OP \-\-
-.RI [ filespec
+.RI [ file
 \&.\|.\|.]
 .YS
 .
@@ -81,15 +81,13 @@ language.
 .
 .
 .P
-A
-.I filespec
-argument is either a file name of an existing file or a minus
-character
-.BR \- ,
-meaning standard input.
-.
-If no argument is specified then standard input is taken
-automatically.
+If no operands are given,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+.I @g@chem
+reads the standard input stream.
 .
 .B \-h
 and
diff --git a/contrib/glilypond/glilypond.1.man 
b/contrib/glilypond/glilypond.1.man
index 8548d93..c094f71 100644
--- a/contrib/glilypond/glilypond.1.man
+++ b/contrib/glilypond/glilypond.1.man
@@ -45,7 +45,7 @@ glilypond \- embed LilyPond musical notation in groff 
documents
 .RB [{ \-v | \-V }]
 .OP \-
 .OP \-\-
-.RI [ filespec
+.RI [ file
 \&.\|.\|.]
 .
 .
@@ -63,7 +63,7 @@ glilypond \- embed LilyPond musical notation in groff 
documents
 .OP \-\-verbose
 .OP \-
 .OP \-\-
-.RI [ filespec
+.RI [ file
 \&.\|.\|.]
 .YS
 .
@@ -111,11 +111,20 @@ is available, but does on yet work with lilypond.
 .
 .
 .P
-Files in
-.I groff
-language and
-.I "standard input"
-can be provided as arguments.
+If no operands are given,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+.I glilypond
+reads the standard input stream.
+.
+A double-dash argument
+.RB (\[lq] \-\- \[rq])
+causes all subsequent arguments to be interpreted as
+.I file
+operands,
+even if their names start with a dash.
 .
 .
 .\" ====================================================================
@@ -164,25 +173,18 @@ does not work.
 .SH "Option Overview"
 .\" ====================================================================
 .
-.\" ====================================================================
-.SS "Breaking options"
-.\" ====================================================================
 .
-.nh
-.nf
 .TP
 .BR \-? | \-h | \-\-help | \-\-usage
-Print help or usage information, then leave the program.
+Display usage information and exit.
 .
 .TP
 .B \-\-version
-Print version information.
+Display version information and exit.
 .
 .TP
 .BR \-l | \-\-license
-Print license information.
-.fi
-.hy
+Display copyright license information and exit.
 .
 .
 .\" ====================================================================
@@ -444,56 +446,6 @@ or even as an abbreviation like
 .
 .
 .\" ====================================================================
-.SH "Filespec Arguments"
-.\" ====================================================================
-.
-An argument that is not an option or an option argument is called a
-.I filespec
-argument.
-.
-.
-.P
-Without any
-.I filespec
-argument,
-.I "standard input"
-is read.
-.
-.
-.P
-Each
-.I filespec
-argument must either be the name of a readable file or a dash
-.B \-
-for
-.IR "standard input" .
-.
-Each input must be written in the
-.I roff
-or
-.I groff
-language and can include
-.I lilypond
-parts.
-.
-.
-.P
-Normally arguments starting with a dash
-.B \-
-are interpreted as an option.
-.
-But if you use an argument that consists only of a doubled dash
-.B \-\- R ,
-all following arguments are taken as
-.I filespec
-argument, even if such an argument starts with a dash.
-.
-This is handled according to the
-.I GNU
-standard.
-.
-.
-.\" ====================================================================
 .SH "The LilyPond Parts in roff Input"
 .\" ====================================================================
 .
diff --git a/contrib/gperl/gperl.1.man b/contrib/gperl/gperl.1.man
index d9a67ca..27fc48b 100644
--- a/contrib/gperl/gperl.1.man
+++ b/contrib/gperl/gperl.1.man
@@ -30,7 +30,7 @@ gperl \- execute Perl commands in groff documents
 .\" ====================================================================
 .
 .SY gperl
-.RI [ filespec
+.RI [ file
 \&.\|.\|.]
 .YS
 .
@@ -73,51 +73,32 @@ based on the arguments at a final line of a
 .IR "Perl part" .
 .
 .
-.\" ====================================================================
-.SH Options
-.\" ====================================================================
-.
-So far, there are only
-.I filespec
-or
-.I breaking
-options.
-.
-.
 .P
-.I filespec
-are file names or the minus character
-.B \-
-character for standard input.
-.
-As usual, the argument
-.B \-\-
-can be used in order to let all following arguments mean file names,
-even if the names begin with a minus character
-.BR \- .
-.
-.
-.P
-An option is
-.IR breaking ,
-when the program just writes the information that was asked for and
-then stops.
-.
-All other arguments will be ignored by that.
-.
-These
-.I breaking
-options are here
-.
-.TP
-.B \-h\~\fR|\fB\~\-\-help
-Print help information with a short explanation of options to
-standard output.
+If no operands are given,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+.I gperl
+reads the standard input stream.
 .
+A double-dash argument
+.RB (\[lq] \-\- \[rq])
+causes all subsequent arguments to be interpreted as
+.I file
+operands,
+even if their names start with a dash.
 .
-.TP
-.B \-v\~\fR|\fB\~\-\-version
-Print version information to standard output.
+.B \-h
+and
+.B \-\-help
+display a usage message,
+whereas
+.B \-v
+and
+.B \-\-version
+display version information;
+all exit afterward.
 .
 .
 .\" ====================================================================
diff --git a/src/roff/grog/grog.1.man b/src/roff/grog/grog.1.man
index a8101b7..d64e2a2 100644
--- a/src/roff/grog/grog.1.man
+++ b/src/roff/grog/grog.1.man
@@ -42,7 +42,7 @@ grog \- \(lqgroff guess\(rq\(eminfer a document's groff 
command
 .RI [ groff-option
 \&.\|.\|.\&]
 .OP \-\-
-.RI [ filespec
+.RI [ file
 \&.\|.\|.]
 .YS
 .
@@ -75,6 +75,18 @@ options are needed to perform the input with the
 .B groff
 program.
 .
+.
+.P
+If no operands are given,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+.I @g@chem
+reads the standard input stream.
+.
+.
+.P
 A suitable device is now always written as
 .BI \-T device
 including the groff default as
@@ -93,34 +105,22 @@ the generated line is output into standard error and the 
generated
 command is run on the
 .IR "standard output" .
 .
+.
 .\" ====================================================================
 .SH Options
 .\" ====================================================================
 .
-The option
-.B \-v
-or
-.B \-\-version
-prints information on the version number.
-.
-Also
 .B \-h
-or
+and
 .B \-\-help
-prints usage information.
-.
-Both of these options automatically end the
-.B grog
-program.
-.
-Other options are then ignored, and no
-.B groff
-command line is generated.
-.
+display a usage message,
+whereas
+.B \-v
+and
+.B \-\-version
+display version information;
+all exit afterward.
 .
-The following 3 options are the only
-.B grog
-options,
 .
 .TP
 .B \-C
@@ -165,25 +165,13 @@ unchanged in the command for the output without effecting 
the work of
 .BR grog .
 .
 .
-.P
-A
-.I filespec
-argument can either be the name of an existing file or a single minus
-.B \-
-to mean standard input.
-.
-If no
-.I filespec
-is specified standard input is read automatically.
-.
-.
 .\" ====================================================================
 .SH Details
 .\" ====================================================================
 .
 .B grog
 reads all
-.I filespec
+.I file
 parameters as a whole.
 .
 It tries to guess which of the following
@@ -216,7 +204,7 @@ and
 The guessed
 .B groff
 command including those options and the found
-.I filespec
+.I file
 parameters is put on the standard output.
 .
 .