[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 05/07: man pages: Fix clarity and style issues.
|
From: |
G. Branden Robinson |
|
Subject: |
[groff] 05/07: man pages: Fix clarity and style issues. |
|
Date: |
Sat, 5 Sep 2020 16:06:02 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 533fa381ba78f2da8fd1411d0b682e94a43b91b0
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Sep 3 23:49:58 2020 +1000
man pages: Fix clarity and style issues.
* man/groff.7.man (Escape Sequences/Escape short reference) <\k>: Fix
garbage characters left over from earlier edit.
* src/roff/troff/troff.1.man (Options) <-c>: Note that -c also disables
SGR escape output to terminal devices.
* src/roff/troff/troff.1.man (Options) <-C>: Note that -C implies -c.
* src/roff/troff/troff.1.man (Options) <-r>: Say "roff" instead of
"troff" when we mean the general language.
* src/preproc/tbl/tbl.1.man (Description/Global options) <nokeep>:
(Description/Table format specification) <n, N>:
Prefix "tbl" with "@g@" when GNU tbl is meant.
* src/preproc/tbl/tbl.1.man (Description/Table format specification)
<n, N>: Prefix "eqn" with "@g@" when GNU eqn is meant.
* src/preproc/tbl/tbl.1.man (Description/Column specifiers) <d, D>:
Write literal circumflex as "\[ha]", not "^".
* src/preproc/tbl/tbl.1.man (Description/Column specifiers) <m, M>:
Recast description to say what it does first, instead of meandering
around to it four senetences later. Reduce status of "GNU tbl
extension" to parenthetical, in parallel with other usage in the page.
* contrib/chem/chem.1.man:
* contrib/gperl/gperl.1.man:
* src/devices/grodvi/grodvi.1.man:
* src/preproc/tbl/tbl.1.man:
* src/roff/groff/groff.1.man:
Write literal apostrophe as "\[aq]", not "'".
* src/roff/troff/troff.1.man:
src/preproc/tbl/tbl.1.man:
Quote word-like literals that begin with an alphanumeric character (as
opposed to those prefixed with a punctuation sigil like escapes and
requests) so that they are easier to distinguish in contexts even when
font changes are unavailable; consider, e.g., screen readers.
* src/preproc/tbl/tbl.1.man:
Conversely, unquote word-like literals that begin with a
non-alphanumeric character, such as \$1, if they qualify for setting
in bold.
* src/preproc/tbl/tbl.1.man:
Say "terminal" instead of "TTY".
* src/roff/troff/troff.1.man:
Disfavor sesquipedialian constructions such as "This so-and-so will
frobnicate the following glorms: A, B, and C." in favor of the more
economical "So-and-so frobnicates glorms A, B, and C." Further, the
"so-and-so" is often omitted from the former; bad technical writers
tend to place immense faith in the reader's ability to disambiguate
vague pronouns. As Kerrisk recently noted on the linux-man mailing
list:
'In the preceding sentence, "it" is used three times, with two
*different* referents. That's quite hard on the reader.'
I don't recall anything that bad in the groff man page corpus, but we
certainly have our howlers.
* src/roff/troff/troff.1.man:
Prefix roff request names with a period.
* contrib/pdfmark/pdfroff.1.man (Synopsis):
* man/groff.7.man (Escape Sequences/Special characters):
* src/roff/troff/troff.1.man (Options):
Escape hyphens used as command-line dashes and in glyph names.
* src/preproc/tbl/tbl.1.man:
Add comma after "e.g".
The Latin abbreviations "e.g.", "etc.", and "i.e." ALWAYS take commas
afterwards. ...unless you're on the "mention" side of the use/mention
dichotomy as I just was. :) If it seems grammatical to omit the
comma, for instance at the end of a sentence, you're using the
abbreviation wrongly. One should never end an independent clause; it
is nauseous to begin such a clause with one, as well. As a check,
replace each abbreviation with "for example", "and so on", and "that
is", respectively; if you'd need a comma in English, you need it when
popping Latin off the stack, too. Some style authorities advocate
these very replacements in formal writing; I am not quite as
passionate. I think we can retain Latin abbreviations if we use them
properly and not to excess.
* src/preproc/tbl/tbl.1.man:
When independent clauses are separated by a colon, uncapitalize the
second. Only sentences receive first-letter capitalization.
* src/preproc/tbl/tbl.1.man:
Use em-dash correctly. An en-dash is not a substitute for an em-dash,
and takes NO spaces around itself.
* src/preproc/tbl/tbl.1.man:
Hyphenate attributive phrases like "largest-width".
* contrib/chem/chem.1.man:
* src/preproc/tbl/tbl.1.man:
* src/roff/troff/troff.1.man:
Set program names and man page titles in italics.
* src/preproc/tbl/tbl.1.man:
Set tbl keywords in bold, as "major topics of the subject under
discussion".
* src/devices/grodvi/grodvi.1.man:
Replace \space escapes in macro arguments with quoted arguments or the
\~ escape.
* src/devices/grodvi/grodvi.1.man:
Protect TeX language/macro keywords from hyphenation.
* contrib/chem/chem.1.man:
Add non-printing break points in URLs.
* src/preproc/tbl/tbl.1.man:
Break input lines after commas, colons, and semicolons.
* src/preproc/tbl/tbl.1.man:
Set multi-word parentheticals on their own input line(s).
* src/preproc/tbl/tbl.1.man:
Comment-annotate cases where a reference to a normally @g@-prefixed
command name shouldn't get the @g@. (This happens when speaking
generally [typically of *roffs], of AT&T tools, or "GNU" already
qualifies the context [often to note extensions].)
---
contrib/chem/chem.1.man | 12 +--
contrib/gperl/gperl.1.man | 2 +-
contrib/pdfmark/pdfroff.1.man | 2 +-
man/groff.7.man | 7 +-
man/groff_diff.7.man | 43 +++++-----
src/devices/grodvi/grodvi.1.man | 21 ++---
src/preproc/tbl/tbl.1.man | 185 ++++++++++++++++++++++++++--------------
src/roff/groff/groff.1.man | 4 +-
src/roff/troff/troff.1.man | 56 +++++++-----
9 files changed, 203 insertions(+), 129 deletions(-)
diff --git a/contrib/chem/chem.1.man b/contrib/chem/chem.1.man
index c97e035..caeaf13 100644
--- a/contrib/chem/chem.1.man
+++ b/contrib/chem/chem.1.man
@@ -675,7 +675,7 @@ the commands.
A period character
.B .\&
or a single quote
-.B '
+.B \[aq]
in the first column of a line signals a
.I troff
command, which is copied through as-is.
@@ -877,9 +877,9 @@ article
.\" ====================================================================
.
The GNU version of
-.B chem
+.I chem
was written by
-.MT groff\-bernd.warken\-72@\:web.de
+.MT groff\-bernd\:.warken\-72@\:web\:.de
Bernd Warken
.ME .
.
@@ -888,7 +888,7 @@ It is based on the documentation of Brian Kernighan's
original
version of
.I chem
at
-.UR http://\:cm.bell\-labs.com/\:cm/\:cs/\:who/\:bwk/\:index.html
+.UR http://\:cm\:.bell\-labs\:.com/\:cm/\:cs/\:who/\:bwk/\:index\:.html
.UE .
.
.
@@ -902,7 +902,7 @@ at
.
.P
You can still get the original
-.UR http://\:cm.bell\-labs.com/\:netlib/\:typesetting/\:chem.gz
+.UR http://\:cm\:.bell\-labs\:.com/\:netlib/\:typesetting/\:chem\:.gz
chem awk source
.UE .
.
@@ -915,7 +915,7 @@ file was used for this manual page.
The other classical document on
.I chem
is
-.UR http://\:cm.bell\-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
+.UR http://\:cm\:.bell\-labs\:.com/\:cm/\:cs/\:cstr/\:122\:.ps\:.gz
.I "CHEM \[en] A Program for Typesetting Chemical Structure Diagrams"
[CSTR\~#122]
.UE .
diff --git a/contrib/gperl/gperl.1.man b/contrib/gperl/gperl.1.man
index 5ba7cb8..fa4c0e6 100644
--- a/contrib/gperl/gperl.1.man
+++ b/contrib/gperl/gperl.1.man
@@ -401,7 +401,7 @@ could look like that:
.EX
before
\&.Perl start
-my $result = 'some data';
+my $result = \[aq]some data\[aq];
print $result;
\&.Perl stop .ds string_var
after
diff --git a/contrib/pdfmark/pdfroff.1.man b/contrib/pdfmark/pdfroff.1.man
index 1d4723a..bdd5e1b 100644
--- a/contrib/pdfmark/pdfroff.1.man
+++ b/contrib/pdfmark/pdfroff.1.man
@@ -59,7 +59,7 @@ pdfroff \- create PDF documents using groff
.OP \-W name
.OP \-\-emit\-ps
.OP \-\-no\-toc\-relocation
-.OP \-\-no-kill\-null\-pages
+.OP \-\-no\-kill\-null\-pages
.RB [ \-\-stylesheet=\c
.IR name ]
.OP \-\-no\-pdf\-output
diff --git a/man/groff.7.man b/man/groff.7.man
index bd3a954..3e90a0b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3309,7 +3309,6 @@ Set height of current font to
.ESC k r
Mark horizontal position in one-character
.RI register\~ r .
-.IR r .
.
.TP
.ESC k( rg
@@ -3790,17 +3789,17 @@ Not equal
.B \(!=
.
.TP
-.ESC (->
+.ESC (\->
Right arrow
.B \(->
.
.TP
-.ESC (<-
+.ESC (<\-
Left arrow
.B \(<-
.
.TP
-.ESC (+-
+.ESC (+\-
Plus-minus sign
.B \(+-
.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 10f994e..0ad794b 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -304,8 +304,8 @@ special character
or
.BI \[rs][ xxx\c
.BR ] ;
-.BI \[rs]N' xxx\c
-.BR ' ;
+.BI \[rs]N\[aq] xxx\c
+.BR \[aq] ;
or has been defined by the
.B .char
request.
@@ -404,7 +404,7 @@ and then by symbol roughly in Unicode code point order.
.
.
.TP
-.BI \[rs]A' anything '
+.BI \[rs]A\[aq] anything \[aq]
This expands to
.B 1
or\~\c
@@ -424,7 +424,7 @@ This is useful if you want to look up user input in some
sort of
associative table.
.
.TP
-.BI \[rs]B' anything '
+.BI \[rs]B\[aq] anything \[aq]
This expands to
.B 1
or\~\c
@@ -454,14 +454,13 @@ for GNU extensions.
This is equivalent to an escape character, but it is not interpreted in
copy mode.
.
-For example, strings to start and end superscripting could be defined
-like this
+Strings to start and end superscripting could be defined as follows.
.
.RS
.IP
.EX
-\&.ds { \[rs]v'\-.3m'\[rs]s'\[rs]En[.s]*6u/10u'
-\&.ds } \[rs]s0\[rs]v'.3m'
+\&.ds { \[rs]v\[aq]\-.3m\[aq]\[rs]s\[aq]\[rs]En[.s]*6u/10u\[aq]
+\&.ds } \[rs]s0\[rs]v\[aq].3m\[aq]
.EE
.RE
.
@@ -640,7 +639,7 @@ is associated with the production of the next inline image.
.RE
.
.TP
-.BI \[rs]R' name\~\[+-]n '
+.BI \[rs]R\[aq] name\~\[+-]n \[aq]
This has the same effect as
.
.RS
@@ -653,9 +652,9 @@ This has the same effect as
.TQ
.BI \[rs]s \[+-] [ n ]
.TQ
-.BI \[rs]s' \[+-]n '
+.BI \[rs]s\[aq] \[+-]n \[aq]
.TQ
-.BI \[rs]s \[+-] ' n '
+.BI \[rs]s \[+-] \[aq] n \[aq]
Set the point size to
.I n
scaled points;
@@ -683,7 +682,7 @@ is interpreted in copy mode.
.TQ
.BI \[rs]Y[ xxx ]
This is approximately equivalent to
-.BI \[rs]X'\[rs]*[ xxx ]'\f[R].
+.BI \[rs]X\[aq]\[rs]*[ xxx ]\[aq]\f[R].
However the contents of the string or macro
.I xxx
are not interpreted; also it is permitted for
@@ -699,7 +698,7 @@ output format,
and confuses drivers that do not know about this extension.
.
.TP
-.BI \[rs]Z' anything '
+.BI \[rs]Z\[aq] anything \[aq]
Print anything and then restore the horizontal and vertical position;
.I anything
may not contain tabs or leaders.
@@ -1281,7 +1280,7 @@ characters
.\" The following is ordered with the apostrophe and (single) closing
.\" quote on the ends so they are more easily visually distinguished
.\" from the double quotation marks in roman.
-.RB \[lq] '")]*\[rs][dg]\[rs][dd]\[rs][rq]\[rs][cq] \[rq]
+.RB \[lq] \[aq]")]*\[rs][dg]\[rs][dd]\[rs][rq]\[rs][cq] \[rq]
have this property.
.
.IP 64
@@ -1479,8 +1478,8 @@ is a character
.RS
.RS
.EX
-\&.class [quotes] ' \[rs][aq] \[rs][dq] \[rs][oq] \[rs][cq] \[rs][lq] \
-\[rs][rq]
+\&.class [quotes] \[aq] \[rs][aq] \[rs][dq] \[rs][oq] \[rs][cq] \
+\[rs][lq] \[rs][rq]
.EE
.RE
.RE
@@ -1533,7 +1532,8 @@ classes can be nested.
.RS
.EX
\&.class [prepunct] , : ; > }
-\&.class [prepunctx] \[rs]C'[prepunct]' \[rs][u2013]\-\[rs][u2016]
+\&.class [prepunctx] \[rs]C\[aq][prepunct]\[aq] \
+\[rs][u2013]\-\[rs][u2016]
.EE
.RE
The class
@@ -1574,7 +1574,7 @@ you can write the following.
.RS
.RS
.EX
-\&.cflags 2 \[rs]C'[prepunctx]'
+\&.cflags 2 \[rs]C\[aq][prepunctx]\[aq]
.EE
.RE
.RE
@@ -2879,7 +2879,7 @@ due to the regular naming convention of the special
character escapes.
.RS
.RS
.EX
-\&.ds resume R\e['e]sum\e['e]\e"
+\&.ds resume R\e[\[aq]e]sum\e[\[aq]e]\e"
\e*[resume] \e# R\['e]sum\['e]
\&.stringdown resume
\e*[resume] \e# r\['e]sum\['e]
@@ -3411,8 +3411,9 @@ large spaces between each.
The result has obvious inter-sentence spacing.
.RS
.RS \" Extra indent to get us inboard of the indented paragraph.
+.\" This is an output example, so use a real en-dash.
.EX
-1. J. Fict. Ch. Soc. 6 (2020), 3-14. 2. Better
+1. J. Fict. Ch. Soc. 6 (2020), 3\[en]14. 2. Better
known for other work.
.EE
.RE
@@ -3474,7 +3475,7 @@ This allows the reliable modification of requests.
\&.de bp
\&.tm before bp
\&.ie \[rs]\[rs]n[.br] .bp*orig
-\&.el 'bp*orig
+\&.el \[aq]bp*orig
\&.tm after bp
\&..
.EE
diff --git a/src/devices/grodvi/grodvi.1.man b/src/devices/grodvi/grodvi.1.man
index d6eaaf3..073dd34 100644
--- a/src/devices/grodvi/grodvi.1.man
+++ b/src/devices/grodvi/grodvi.1.man
@@ -79,10 +79,10 @@ is a driver for
that produces \*(tx DVI format.
.
Normally it should be run by
-.BR groff\ \-Tdvi .
+.BR "groff \-Tdvi" .
.
This will run
-.BR @g@troff\ \-Tdvi ;
+.BR "@g@troff \-Tdvi" ;
it will also input the macros in
.IR \%@MACRODIR@/\:dvi.tmac .
.
@@ -102,7 +102,7 @@ commands will not produce any output.
There is an additional drawing command available:
.
.TP
-.BI \[rs]D'R\ dh\ dv '
+.BI \[rs]D\[aq]R\~ "dh dv" \[aq]
Draw a rule (solid black rectangle), with one corner
at the current position, and the diagonally opposite corner
at the current position
@@ -117,10 +117,10 @@ commands.
.
.LP
The groff command
-.BI \[rs]X' anything '
+.BI \[rs]X\[aq] anything \[aq]
is translated into the same command in the DVI file as would be
produced by
-.BI \[rs]special{ anything }
+.BI \%\[rs]special{ anything }
in \*(tx;
.I anything
may not contain a newline.
@@ -148,19 +148,19 @@ The font description file should contain the following
additional commands:
.
.TP
-.BI internalname\ name
+.BI internalname\~ name
The name of the tfm file (without the
.I .tfm
extension) is
.IR name .
.
.TP
-.BI checksum\ n
+.BI checksum\~ n
The checksum in the tfm file is
.IR n .
.
.TP
-.BI designsize\ n
+.BI designsize\~ n
The designsize in the tfm file is
.IR n .
.
@@ -195,7 +195,7 @@ output medium.
Instead,
.B grodvi
emits the equivalent to \*[tx]'s
-.BI \[rs]special{papersize= width , length }
+.BI \%\[rs]special{\:\%papersize= width , length }
on the first page;
.B dvips
(and possibly other DVI drivers) then sets the page size accordingly.
@@ -276,7 +276,8 @@ There are styles called
.BR B ,
and
.B BI
-mounted at font positions 1 to\ 4.
+mounted at font positions 1 to\~4.
+.
The fonts are grouped into families
.B T
and
diff --git a/src/preproc/tbl/tbl.1.man b/src/preproc/tbl/tbl.1.man
index 6a541e6..dcd7ba6 100644
--- a/src/preproc/tbl/tbl.1.man
+++ b/src/preproc/tbl/tbl.1.man
@@ -136,8 +136,8 @@ This specification can have several lines, but must be
finished by a
at the end of the last line.
.
After each cell definition,
-.I column specifiers
-can be appended, but that's optional.
+column specifiers can be appended,
+but that's optional.
.
.
.P
@@ -173,16 +173,23 @@ Enclose the table in a box.
.
.TP
.B center
-Center the table (default is left-justified).
+Center the table
+(default is left-justified).
.
The alternative keyword name
.B centre
-is also recognized (this is a GNU tbl extension).
+is also recognized
+(this is a GNU
+.I tbl \" exception
+extension).
.
.TP
.BI decimalpoint( c )
Set the character to be recognized as the decimal point in numeric
-columns (GNU tbl only).
+columns
+(GNU
+.I tbl \" exception
+only).
.
.TP
.BI delim( xy )
@@ -198,7 +205,11 @@ Enclose the table in a double box.
.
.TP
.B doubleframe
-Same as doublebox (GNU tbl only).
+Same as
+.B doublebox
+(GNU
+.I tbl \" exception
+only).
.
.TP
.B expand
@@ -217,11 +228,17 @@ and there is no column separation at all.
.
.TP
.B frame
-Same as box (GNU tbl only).
+Same as
+.B box
+(GNU
+.I tbl \" exception
+only).
.
.TP
.BI linesize( n )
-Set lines or rules (e.g.\& from
+Set lines or rules
+(e.g.,
+from
.BR box )
in
.IR n -point
@@ -229,10 +246,13 @@ type.
.
.TP
.B nokeep
-Don't use diversions to prevent page breaks (GNU tbl only).
+Don't use diversions to prevent page breaks
+(GNU
+.I tbl
+only).
.
Normally
-.B tbl
+.I @g@tbl
attempts to prevent undesirable breaks in boxed tables by using
diversions.
.
@@ -241,12 +261,17 @@ diversions\[em]when footnotes, for example, are used.
.
.TP
.B nospaces
-Ignore leading and trailing spaces in data items (GNU tbl only).
+Ignore leading and trailing spaces in data items
+(GNU
+.I tbl \" exception
+only).
.
.TP
.B nowarn
Turn off warnings related to tables exceeding the current line width
-(GNU tbl only).
+(GNU
+.I tbl \" exception
+only).
.
.TP
.BI tab( x )
@@ -408,15 +433,15 @@ a\&bcde
If numerical entries are combined with
.B L
or
-.BR R \~entries
-\[en] this can happen if the table format is changed with
-.B .T&
-\%\[en]
-center the widest
+.BR R \~entries\[em]this
+this can happen if the table format is changed with
+.BR .T& \[em]center
+the widest
.I number
(of the data entered under the
.BR N \~specifier
-regime) relative to the widest
+regime)
+relative to the widest
.B L
or
.BR R \~entry,
@@ -424,23 +449,28 @@ preserving the alignment of all numerical entries.
.
Contrary to
.BR A \~type
-entries, there is no extra indentation.
+entries,
+there is no extra indentation.
.
.IP
-Using equations (to be processed with
-.BR eqn )
+Using equations
+(to be processed with
+.IR @g@eqn )
within columns which use the
.BR N \~specifier
is problematic in most cases due to
-.BR tbl 's
-algorithm for finding the vertical alignment, as described above.
+.IR @g@tbl 's
+algorithm for finding the vertical alignment,
+as described above.
.
Using the global
.B delim
-option, however, it is possible to make
-.B tbl
+option,
+however,
+it is possible to make
+.I @g@tbl
ignore the data within
-.B eqn
+.I eqn
delimiters for that purpose.
.
.
@@ -507,15 +537,21 @@ letters (in any order):
.TP
.BR b , B
Short form of
-.B fB
+.RB \[lq] fB \[rq]
(make affected entries bold).
.
.TP
.BR d , D
Start an item that vertically spans rows,
-using the \[oq]^\[cq] column specifier or \[oq]\[rs]^\[cq] data item,
-at the bottom of its range rather
-than vertically centering it (GNU tbl only).
+using the
+.RB \[lq] \[ha] \[rq]
+column specifier or
+.RB \[lq] \[rs]\[ha] \[rq]
+data item,
+at the bottom of its range rather than vertically centering it
+(GNU
+.I tbl \" exception
+only).
.
Example:
.RS
@@ -575,16 +611,20 @@ T};bar
.BR e , E
Make equally-spaced columns.
.
-All columns marked with this specifier get the same width; this happens
-after the affected column widths have been computed (this means that the
-largest width value rules).
+All columns marked with this specifier get the same width;
+this happens after the affected column widths have been computed
+(this means that the largest-width value controls).
.
.TP
.BR f , F
-Either of these specifiers may be followed by a font name (either one or
-two characters long),
-font number (a single digit),
-or long name in parentheses (the last form is a GNU tbl extension).
+Either of these specifiers may be followed by a font name
+(either one or two characters long),
+font number
+(a single digit),
+or long name in parentheses
+(this last form is a GNU
+.I tbl \" exception
+extension).
.
A one-letter font name must be separated by one or more blanks from
whatever follows.
@@ -592,12 +632,15 @@ whatever follows.
.TP
.BR i , I
Short form of
-.B fI
+.RB \[lq] fI \[rq]
(make affected entries italic).
.
.TP
.BR m , M
-This is a GNU tbl extension.
+Call named macro before outputting table cell text
+(GNU
+.I tbl \" exception
+only).
.
Either of these specifiers may be followed by a macro name
(either one or two characters long),
@@ -609,23 +652,29 @@ whatever follows.
The macro which name can be specified here must be defined before
creating the table.
.
-It is called just before the table's cell text is output.
-.
-As implemented currently, this macro is only called if block input is
-used, that is, text between \[oq]T{\[cq] and \[oq]T}\[cq].
+As implemented currently,
+this macro is only called if block input is used,
+that is,
+text between
+.RB \[lq] T{ \[rq]
+and
+.RB \[lq] T} \[rq].
.
The macro should contain only simple
-.B troff
-requests to change the text block formatting, like text adjustment,
-hyphenation, size, or font.
+.I roff
+requests to change the text block formatting,
+like text adjustment,
+hyphenation,
+size,
+or font.
.
The macro is called
.I after
other cell modifications like
-.BR b ,
-.B f
+.RB \[lq] b \[rq],
+.RB \[lq] f \[rq],
or
-.B v
+.RB \[lq] v \[rq]
are output.
.
Thus the macro can overwrite other modification specifiers.
@@ -635,8 +684,11 @@ Thus the macro can overwrite other modification specifiers.
Followed by a number,
this does a point size change for the affected fields.
.
-If signed, the current point size is incremented or decremented (using
-a signed number instead of a signed digit is a GNU tbl extension).
+If signed,
+the current point size is incremented or decremented
+(using a signed multi-digit number is a GNU
+.I tbl \" exception
+extension).
.
A point size specifier followed by a column separation number must be
separated by one or more blanks.
@@ -668,7 +720,7 @@ No effect if the corresponding table entry isn't a text
block.
.BR w , W
Minimum column width value.
Must be followed either by a
-.BR @g@troff (@MAN1EXT@)
+.IR @g@troff (@MAN1EXT@)
width expression in parentheses or a unitless integer.
.
If no unit is given, en units are used.
@@ -752,7 +804,7 @@ concatenation).
.
.LP
Note that
-.B @g@tbl
+.I @g@tbl
computes the column widths line by line, applying \[rs]w on each entry
which isn't a text block.
.
@@ -984,18 +1036,23 @@ Here an example.
.
.LP
Note, however, that not all features of
-.B @g@tbl
+.I @g@tbl
can be wrapped into a macro because
-.B @g@tbl
+.I @g@tbl
sees the input earlier than
-.BR @g@troff .
+.IR @g@troff .
.
-For example, number formatting with vertically aligned decimal points
-fails if those numbers are passed on as macro parameters because
-decimal point alignment is handled by
-.B @g@tbl
-itself: It only sees \[oq]\[rs]$1\[cq], \[oq]\[rs]$2\[cq], etc., and
-therefore can't recognize the decimal point.
+For example,
+number formatting with vertically aligned decimal points fails if those
+numbers are passed on as macro parameters because decimal point
+alignment is handled by
+.I @g@tbl
+itself:
+it only sees
+.BR \[rs]$1 ,
+.BR \[rs]$2 ,
+etc.,
+and therefore can't recognize the decimal point.
.
.
.\" ====================================================================
@@ -1059,7 +1116,7 @@ as follows
.IP
.EX
\&.de BP
-\&.\& ie '\[rs]\[rs]n(.z'' \&.bp \[rs]\[rs]$1
+\&.\& ie \[aq]\[rs]\[rs]n(.z\[aq]\[aq] \&.bp \[rs]\[rs]$1
\&.\& el \[rs]!.BP \[rs]\[rs]$1
\&..
.EE
@@ -1136,7 +1193,7 @@ as in
.
.LP
The resulting \[lq]dummy\[rq] columns are invisible and have zero width;
-note that such columns usually don't work with TTY devices.
+note that such columns usually don't work with terminal devices.
.
.
.\" ====================================================================
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 5c2182d..fdc46d2 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -320,7 +320,7 @@ the shell command
.RS
.RS
.EX
-.B groff \-X \-P \-title \-P 'trial run' mydoc.t
+.B groff \-X \-P \-title \-P \[aq]trial run\[aq] mydoc.t
.EE
.RE
.
@@ -328,7 +328,7 @@ is equivalent to
.
.RS
.EX
-.B groff \-X \-Z mydoc.t | gxditview \-title 'trial run' \-
+.B groff \-X \-Z mydoc.t | gxditview \-title \[aq]trial run\[aq] \-
.EE
.RE
.RE
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index b7d6e54..a2120a1 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -106,7 +106,7 @@ one might use the shell command
.RS
.RS
.EX
-zcat $(man \-w troff) | groff \-a -t \-man \-Tdvi | less
+zcat $(man \-w troff) | groff \-a \-t \-man \-Tdvi | less
.EE
.RE
to observe how lines are broken for the DVI device.
@@ -120,20 +120,27 @@ Print a backtrace with each warning or error message.
This backtrace should help track down the cause of the error.
.
The line numbers given in the backtrace may not always be correct, for
-.BR @g@troff 's
+.IR @g@troff 's
idea of line numbers gets confused by
-.B as
+.B .as
or
-.B am
+.B .am
requests.
.
+.
.TP
.B \-c
-Disable color output (always disabled in compatibility mode).
+Disable color output;
+also disable SGR escape output to
+.IR grotty (@MAN1EXT@)
+devices.
+.
.
.TP
.B \-C
-Enable compatibility mode.
+Enable compatibility mode;
+implies \-c.
+.
.
.TP
.BI \-d cs
@@ -295,7 +302,9 @@ to
.I c
must be a one character name;
.I n
-can be any troff numeric expression.
+can be any
+.I roff
+numeric expression.
.
.TP
.B \-R
@@ -304,31 +313,38 @@ Don't load
and
.IR troffrc\-end .
.
+.
.TP
.BI \-T name
Prepare output for device
.IR name ,
rather than the default
-.BR @DEVICE@ ;
+.RB \[lq] @DEVICE@ \[rq];
see
-.BR groff (@MAN1EXT@)
+.IR groff (@MAN1EXT@)
for a more detailed description.
.
+.
.TP
.B \-U
-Unsafe mode.
-.
-This will enable the following requests:
-.BR open ,
-.BR opena ,
-.BR pso ,
-.BR sy ,
+Unsafe mode;
+enables the
+.BR .open ,
+.BR .opena ,
+.BR .pso ,
+.BR .sy ,
and
-.BR pi .
-For security reasons, these potentially dangerous requests are
-disabled otherwise.
+.B .pi
+requests.
+.
+For security reasons,
+these potentially dangerous requests are disabled otherwise.
+.
+It will also add the current directory to the macro search path;
+see
+.B \-m
+above.
.
-It will also add the current directory to the macro search path.
.
.TP
.BI \-w name
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 05/07: man pages: Fix clarity and style issues.,
G. Branden Robinson <=