[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 09/14: groff(1) (Options): Revise.
From: |
G. Branden Robinson |
Subject: |
[groff] 09/14: groff(1) (Options): Revise. |
Date: |
Fri, 4 Jun 2021 16:02:03 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 13f2244313892631ad5187a78247372d12a3fa04
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jun 5 02:15:56 2021 +1000
groff(1) (Options): Revise.
* Recast introduction to section.
* Use more idiomatic and grammatical word ordering.
* Use \~ escape instead of "\ ".
* Set topics of man page cross references in italics, not bold.
* Add section numbers to numerous man page cross references.
* Stop setting input-only example in bold.
* Ease off on the portentous italicization of "intermediate output".
* Improve descriptions of character sets and encodings.
* Clarify to which streams -v and -V output is written.
---
src/roff/groff/groff.1.man | 305 +++++++++++++++++++++++++--------------------
1 file changed, 170 insertions(+), 135 deletions(-)
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 11c2498..a4a771d 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -107,23 +107,28 @@ displays a usage message and exits.
.
.
.P
-As
-.B groff
-is a wrapper program for
-.I \%@g@troff
-both programs share a set of options.
+Because
+.I groff
+is intended to subsume most users' direct invocations of the
+.IR \%@g@troff (@MAN1EXT@)
+formatter,
+the two programs share a set of options.
.
-But the
-.B groff
-program has some additional, native options and gives a new meaning to
-some
+However,
+.I groff
+has some options specific to it,
+some of which
.I \%@g@troff
-options.
+does not share,
+and others which
+.I groff
+interprets differently.
.
-On the other hand, not all
+At the same time,
+not all valid
.I \%@g@troff
-options can be fed into
-.BR groff .
+options can be given into
+.IR groff .
.
.
.\" ====================================================================
@@ -132,14 +137,14 @@ options can be fed into
.
The following options either do not exist for
.I \%@g@troff
-or are differently interpreted by
-.BR groff .
+or are interpreted differently by
+.IR groff .
.
.
.TP
-.BI \-D\ arg
+.BI \-D\~ arg
Set default input encoding used by
-.B preconv
+.IR preconv (@MAN1EXT@)
to
.IR arg .
.
@@ -149,22 +154,24 @@ Implies
.
.TP
.B \-e
-Preprocess with
-.IR \%@g@eqn .
+Run
+.IR \%@g@eqn (@MAN1EXT@)
+preprocessor.
.
.
.TP
.B \-g
-Preprocess with
-.IR \%@g@grn .
+Run
+.IR \%@g@grn (@MAN1EXT@)
+preprocessor.
.
.
.TP
.B \-G
-Preprocess with
-.BR grap .
-.
-Implies
+Run
+.IR grap (1)
+preprocessor;
+implies
.BR \-p .
.
.
@@ -179,38 +186,38 @@ but also implies
and passes the
.B \-I
options to
-.IR soelim .
+.IR \%@g@soelim (@MAN1EXT@).
.
.
.TP
.B \-j
-Preprocess with
-.IR \%@g@chem .
-.
-Implies
+Run
+.IR \%@g@chem (@MAN1EXT@)
+preprocessor;
+implies
.BR \-p .
.
.
.TP
.B \-k
-Preprocess with
-.BR preconv .
-.
-This is run before any other preprocessor.
+Run
+.IR preconv (@MAN1EXT@),
+which is run before any other preprocessor.
.
Please refer to
-.BR preconv 's
-manual page for its behaviour if no
+.IR preconv 's
+manual page for its behavior if neither of
+.IR groff 's
.B \-K
-(or
-.BR \-D )
-option is specified.
+or
+.B \-D
+options is also specified.
.
.
.TP
-.BI \-K\ arg
+.BI \-K\~ arg
Set input encoding used by
-.B preconv
+.IR preconv (@MAN1EXT@)
to
.IR arg .
.
@@ -224,11 +231,13 @@ Send the output to a spooler program for printing.
.
The command that should be used for this is specified by the
.B print
-command in the device description file, see
-.BR \%groff_font (@MAN5EXT@).
+command in the device description file,
+see
+.IR \%groff_font (@MAN5EXT@).
.
-If this command is not present, the output is piped into the
-.BR lpr (1)
+If this command is not present,
+the output is piped into the
+.IR lpr (1)
program by default.
.
See options
@@ -238,7 +247,7 @@ and
.
.
.TP
-.BI \-L\ arg
+.BI \-L\~ arg
Pass
.I arg
to the spooler program.
@@ -248,7 +257,7 @@ Several arguments should be passed with a separate
option each.
.
Note that
-.B groff
+.I groff
does not prepend
\[oq]\-\[cq]
(a minus sign) to
@@ -259,19 +268,20 @@ before passing it to the spooler program.
.TP
.B \-N
Don't allow newlines within
-.I eqn
+.I eqn \" language
delimiters.
.
This is the same as the
.B \-N
option in
-.IR \%@g@eqn .
+.IR \%@g@eqn (@MAN1EXT@).
.
.
.TP
.B \-p
-Preprocess with
-.IR \%@g@pic .
+Run
+.IR \%@g@pic (@MAN1EXT@)
+preprocessor.
.
.
.TP
@@ -306,7 +316,7 @@ the shell command
.RS
.RS
.EX
-.B groff \-X \-P \-title \-P \[aq]trial run\[aq] mydoc.t
+groff \-X \-P \-title \-P \[aq]trial run\[aq] mydoc.t
.EE
.RE
.
@@ -314,7 +324,7 @@ is equivalent to
.
.RS
.EX
-.B groff \-X \-Z mydoc.t | gxditview \-title \[aq]trial run\[aq] \-
+groff \-X \-Z mydoc.t | gxditview \-title \[aq]trial run\[aq] \-
.EE
.RE
.RE
@@ -322,8 +332,9 @@ is equivalent to
.
.TP
.B \-R
-Preprocess with
-.IR \%@g@refer .
+Run
+.IR \%@g@refer (@MAN1EXT@)
+preprocessor.
.
No mechanism is provided for passing arguments to
.I \%@g@refer
@@ -333,14 +344,15 @@ options have equivalent language elements that can be
specified within
the document.
.
See
-.BR \%@g@refer (@MAN1EXT@)
+.IR \%@g@refer (@MAN1EXT@)
for more details.
.
.
.TP
.B \-s
-Preprocess with
-.IR \%@g@soelim .
+Run
+.IR \%@g@soelim (@MAN1EXT@)
+preprocessor.
.
.
.TP
@@ -361,62 +373,62 @@ requests:
and
.BR .pi .
.
-For security reasons, safer mode is enabled by default.
+For security reasons,
+safer mode is enabled by default.
.
.
.TP
.B \-t
-Preprocess with
-.IR \%@g@tbl .
+Run
+.IR \%@g@tbl (@MAN1EXT@)
+preprocessor.
.
.
.TP
-.BI \-T\ dev
-Set output device to
-.IR dev .
-.
-For this device,
+.BI \-T\~ dev
+Prepare output for the device type
+.IR dev ;
.I \%@g@troff
-generates the
-.I intermediate
-.IR output ;
-see
-.BR \%groff_out (@MAN5EXT@).
+generates \[lq]intermediate output\[rq]
+.RI ( \%groff_out (@MAN5EXT@))
+appropriate to the device.
.
-Then
-.B groff
-calls a postprocessor to convert
+.I groff
+then calls a postprocessor to convert
.IR \%@g@troff 's
-.I intermediate output
-to its final format.
+output to a form appropriate for
+.IR dev .
.
Real devices in
-.B groff
+.I groff
are
.
.RS
.RS
.TP
dvi
-TeX DVI format (postprocessor is
-.BR grodvi ).
+TeX DVI format
+(postprocessor is
+.IR grodvi (@MAN1EXT@)).
.
.TP
html
.TQ
xhtml
-HTML and XHTML output (preprocessors are
+HTML and XHTML output
+(preprocessors are
.I \%@g@soelim
and
-.BR \%pre-grohtml ,
+.IR \%pre-grohtml ,
postprocessor is
-.BR \%post-grohtml ).
+.IR \%post-grohtml ).
.
.TP
lbp
-Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser printers;
+Canon CAPSL printers
+(\%LBP-4 and \%LBP-8 series laser printers;
postprocessor is
-.BR grolbp ).
+.IR grolbp (@MAN1EXT@)).
.
.TP
lj4
@@ -425,70 +437,83 @@ HP LaserJet4-compatible
printers
(postprocessor
is
-.BR grolj4 ).
+.IR grolj4 (@MAN1EXT@)).
.
.TP
ps
PostScript output (postprocessor is
-.BR grops ).
+.IR grops (@MAN1EXT@)).
.
.TP
pdf
Portable Document Format (PDF) output (postprocessor is
-.BR gropdf ).
+.IR gropdf (@MAN1EXT@)).
.RE
.RE
.
.
.IP
-For the following TTY output devices (postprocessor is always
-.BR grotty ),
+For the following TTY output devices
+(where postprocessor is
+.IR grotty (@MAN1EXT@)),
.B \-T
selects the output encoding:
.
+.
.RS
.RS
.TP
ascii
-7bit \f[CR]ASCII\f[].
+ISO 646 1991:IRV,
+also known as US-ASCII.
+.
.
.TP
cp1047
-\%Latin-1 character set for EBCDIC hosts.
+IBM code page 1047,
+an EBCDIC arrangement of ISO Latin-1.
+.
.
.TP
latin1
-ISO \%8859-1.
+ISO Latin-1
+(ISO 8859-1).
+.
.
.TP
utf8
-Unicode character set in \%UTF-8 encoding.
+ISO 10646 (\[lq]Unicode\[rq]) character set in UTF-8 encoding.
.
-This mode has the most useful fonts for TTY mode, so it is the best
-mode for TTY output.
+This encoding has the largest character repertoire,
+so it is the best choice for terminal output.
.RE
.RE
.
.
.IP
The following arguments select
-.B \%gxditview
-as the \[oq]postprocessor\[cq] (it is rather a viewing program):
+.I \%gxditview
+as the postprocessor.
+.
.
.RS
.RS
.TP
X75
-75\|dpi resolution, 10\|pt document base font.
+75\|dpi resolution,
+10\|pt document base font.
.TP
X75\-12
-75\|dpi resolution, 12\|pt document base font.
+75\|dpi resolution,
+12\|pt document base font.
.TP
X100
-100\|dpi resolution, 10\|pt document base font.
+100\|dpi resolution,
+10\|pt document base font.
.TP
X100\-12
-100\|dpi resolution, 12\|pt document base font.
+100\|dpi resolution,
+12\|pt document base font.
.RE
.RE
.
@@ -501,7 +526,8 @@ The default device is
.B \-U
Unsafe mode.
.
-Reverts to the (old) unsafe behaviour; see option
+Reverts to the (old) unsafe behaviour;
+see option
.BR \-S .
.
.
@@ -509,10 +535,12 @@ Reverts to the (old) unsafe behaviour; see option
.B \-v
.TQ
.B \-\-version
-Output version information of
-.B groff
-and of all programs that are run by it; that is, the given command line
-is parsed in the usual way, passing
+Write version information of
+.I groff
+and of all programs run by it to the standard output stream;
+that is,
+the given command line is processed in the usual way,
+passing
.B \-v
to all subprograms.
.
@@ -520,17 +548,19 @@ to all subprograms.
.TP
.B \-V
Output the pipeline that would be run by
-.B groff
-(as a wrapper program) on the standard output, but do not execute it.
+.I groff
+(as a wrapper program)
+to the standard output stream,
+but do not execute it.
.
If given more than once,
-the commands are both printed on the standard error and run.
+the commands are both written to the standard error stream and run.
.
.
.TP
.B \-X
Use
-.B \%gxditview
+.IR \%gxditview (@MAN1EXT@)
instead of using the usual postprocessor to (pre)view a document.
.
The printing spooler behavior as outlined with options
@@ -538,11 +568,10 @@ The printing spooler behavior as outlined with options
and
.B \-L
is carried over to
-.BR \%gxditview (@MAN1EXT@)
-by determining an argument for the
+.I \%gxditview
+by determining an argument for its
.B \-printCommand
-option of
-.BR \%gxditview (@MAN1EXT@).
+option.
.
This sets the default
.B Print
@@ -559,10 +588,11 @@ and
.
The default resolution for previewing
.B \-Tps
-output is 75\|dpi; this can be changed by passing the
+output is 75\|dpi;
+this can be changed by passing the
.B \-resolution
option to
-.BR \%gxditview ,
+.IR \%gxditview ,
for example
.
.RS
@@ -591,8 +621,9 @@ This will cause the
.I \%@g@troff
.I output
to appear on standard output,
-replacing the usual postprocessor output; see
-.BR \%groff_out (@MAN5EXT@).
+replacing the usual postprocessor output;
+see
+.IR \%groff_out (@MAN5EXT@).
.
.
.\" ====================================================================
@@ -603,7 +634,7 @@ The following options are transparently handed over to the
formatter
program
.I \%@g@troff
that is called by
-.B groff
+.I groff
subsequently.
.
These options are described in more detail in
@@ -624,7 +655,7 @@ Backtrace on error or warning.
Disable color output.
.
Please consult the
-.BR \%grotty (@MAN1EXT@)
+.IR \%grotty (@MAN1EXT@)
man page for more details.
.
.TP
@@ -632,9 +663,9 @@ man page for more details.
Enable compatibility mode.
.
.TP
-.BI \-d\ cs
+.BI \-d\~ cs
.TQ
-.BI \-d\ name = s
+.BI \-d\~ name = s
Define string.
.
.TP
@@ -647,11 +678,11 @@ implies
.
.
.TP
-.BI \-f\ fam
+.BI \-f\~ fam
Set default font family.
.
.TP
-.BI \-F\ dir
+.BI \-F\~ dir
Set path for device
.I DESC
files.
@@ -678,45 +709,49 @@ escape).
Process standard input after the specified input files.
.
.TP
-.BI \-m\ name
+.BI \-m\~ name
Include macro file
.RI name .tmac
(or
.IR tmac. name);
see also
-.BR \%groff_tmac (@MAN5EXT@).
+.IR \%groff_tmac (@MAN5EXT@).
.
.TP
-.BI \-M\ dir
+.BI \-M\~ dir
Path for macro files.
.
.TP
-.BI \-n\ num
+.BI \-n\~ num
Number the first page
.IR num .
.
.TP
-.BI \-o\ list
+.BI \-o\~ list
Output only pages in
.IR list .
.
.TP
-.BI \-r\ cn
+.BI \-r\~ cn
.TQ
-.BI \-r\ name = n
+.BI \-r\~ name = n
Set number register.
.
+.
.TP
-.BI \-w\ name
-Enable warning
+.BI \-w\~ name
+Enable warning category
.IR name .
.
See
.IR \%@g@troff (@MAN1EXT@)
-for names.
+or the
+.I groff
+Texinfo manual for a list of names.
+.
.
.TP
-.BI \-W\ name
+.BI \-W\~ name
disable warning category
.IR name .
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 09/14: groff(1) (Options): Revise.,
G. Branden Robinson <=