[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 14/15: man pages: Increase consistency with other pages.
From: |
G. Branden Robinson |
Subject: |
[groff] 14/15: man pages: Increase consistency with other pages. |
Date: |
Tue, 20 Oct 2020 14:00:34 -0400 (EDT) |
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.
.
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 14/15: man pages: Increase consistency with other pages.,
G. Branden Robinson <=