gbranden pushed a commit to branch master
in repository groff.
commit 9cf50c25d6f3bc86173608ac3abc908ad41aa652
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Aug 18 07:34:42 2024 -0500
[docs]: Fix content, style, and markup nits.
* Add cross references.
* Favor present tense over future.
* Favor active voice over passive.
* Favor "minimum" over "minimal" when speaking of a quantity.
* Tighten wording.
* Fix missing words.
* Protect literals from hyphenation.
* Employ the _New Yorker_ dieresis.
* Reorganize discussion of traps.
* Fix missing escape sequence function selector in register dereference.
* Drop leading dot from request name where not otherwise used in
context.
---
doc/groff.texi.in | 20 ++++++++++----------
man/groff.7.man | 51 +++++++++++++++++++++++++++------------------------
man/groff_diff.7.man | 12 ++++++------
3 files changed, 43 insertions(+), 40 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 019bdc28a..c2cc7a958 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -8474,8 +8474,8 @@ Format}. This request is incorrectly documented in the
@acronym{AT&T}
@code{troff} manual as using units of 1/36 em.} (A @dfn{word space} is
typically one-fourth to one-third em for Western scripts.) The default
for both parameters is@tie{}12. Negative values are erroneous.
-@cindex inter-word spacing, minimal
-@cindex minimal inter-word spacing
+@cindex inter-word spacing, minimum
+@cindex minimum inter-word spacing
@cindex space, between words
The first argument is a minimum; if an output line undergoes adjustment,
such spaces may increase in width.
@@ -8499,7 +8499,7 @@ inter-sentence space is not adjusted, but the inter-word
space that
always precedes it may be. Further input spaces after the second, if
present, are adjusted as normal.
-The read-only registers @code{.ss} and @code{.sss} hold the minimal
+The read-only registers @code{.ss} and @code{.sss} hold the minimum
inter-word space and additional inter-sentence space amounts,
respectively. These parameters are part of the environment
(@pxref{Environments}).
@@ -9681,7 +9681,7 @@ not possible to map the space character to any other
glyph; requests
like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
If adjustment is enabled, it occurs in spite of the `empty' space
-character; but no minimum distance---no minimal inter-word
+character; but no minimum distance---no minimum inter-word
space---separates words).
@item
@@ -14584,7 +14584,7 @@ polygon would occlude the text.
@cindex line thickness (@samp{\D't @dots{}'})
@cindex thickness of lines (@samp{\D't @dots{}'})
Set the stroke thickness of geometric objects to @var{n} basic units. A
-zero @var{n} selects the minimal supported thickness. A negative
+zero @var{n} selects the minimum supported thickness. A negative
@var{n} selects a thickness proportional to the type size; this is the
default.
@end table
@@ -15456,8 +15456,8 @@ For orthogonality it is said that GNU @command{troff}
is in the
output is being ``diverted'' immediately to the output device). The
top-level diversion has no name.
-Dereferencing an undefined diversion will create an empty one of that
-name and cause a warning in category @samp{mac} to be emitted.
+Dereferencing an undefined diversion creates an empty one of that
+name and emits a warning in category @samp{mac}.
@xref{Warnings}, regarding the enablement and suppression of warnings.
A diversion does not exist for the purpose of testing with the @code{d}
conditional operator until its initial definition ends (@pxref{Operators
@@ -17868,7 +17868,7 @@ bytes and ignores an argument to report only the sum of
the sizes.
@cindex @code{ss} request, incompatibilities with @acronym{AT&T} @code{troff}
Unlike @acronym{AT&T} @code{troff}, GNU @code{troff} does not ignore the
@code{ss} request if the output is a terminal device; instead, the
-values of minimal inter-word and additional inter-sentence space are
+values of minimum inter-word and additional inter-sentence space are
each rounded down to the nearest multiple of@tie{}12.
@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
@@ -18581,8 +18581,8 @@ but GNU @code{troff} output drivers do nothing with
this command.
@item xr @var{n} @var{h} @var{v}@angles{line break}
The @samp{r} stands for @var{resolution}.
-Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal
-motion, and @var{v} the minimal vertical motion possible with this
+Resolution is@tie{}@var{n}, while @var{h} is the minimum horizontal
+motion, and @var{v} the minimum vertical motion possible with this
device; all arguments are positive integers in basic units @samp{u} per
inch. This is the second command of the prologue.
diff --git a/man/groff.7.man b/man/groff.7.man
index 7284990b2..d2fcd4375 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5774,7 +5774,7 @@ basic units.
.
A zero
.I n
-selects the minimal supported thickness.
+selects the minimum supported thickness.
.
A negative
.I n
@@ -5908,7 +5908,8 @@ interpreted as such when the string is interpolated.
To achieve that effect,
use
.B \[rs]*
-to interpolate a macro instead.\" see @ref{Punning Names}.
+to interpolate a macro instead;
+see section \[lq]Punning names\[rq] below.
.
.
.P
@@ -6064,7 +6065,7 @@ macros,
strings,
and diversions.
.
-Bear in mind that the symbols
+The symbols
.B \[rs]n[]
are
.I not
@@ -6285,7 +6286,7 @@ The count of lines remaining in the pending input trap.
.
.TP
.REG .itc
-The pending input trap honors output line continuation
+The pending input trap honors output line continuation with
.esc c
(Boolean-valued).
.
@@ -6349,7 +6350,7 @@ and
.esc m .
.
The default stroke color is named
-.RB \[lq] default \[rq].
+.RB \%\[lq] default \[rq].
.
.TP
.REG .M
@@ -6360,7 +6361,7 @@ and
.esc M .
.
The default fill color is named
-.RB \[lq] default \[rq].
+.RB \&\[lq] default \[rq].
.
.TP
.REG .n
@@ -6470,7 +6471,7 @@ and
.
.TP
.REG .ss
-Size of minimal inter-word space in twelfths of the space width of the
+Size of minimum inter-word space in twelfths of the space width of the
selected font.
.
.TP
@@ -7530,9 +7531,17 @@ at a given location in the current diversion
.RB ( .dt )\[em]together,
these are known as
vertical position traps,
-which can be disabled and re-enabled
+which can be disabled and re\[e ad]nabled
.RB ( .vpt ).
.
+Setting a trap is also called
+.I planting
+one.
+.
+It is said that a trap is
+.I sprung
+if its condition is fulfilled.
+.
.
.P
A diversion is not formatted in the context of a page,
@@ -7555,14 +7564,6 @@ or at the end of input
.RB ( .em ).
.
Macros called by traps are passed no arguments.
-.
-Setting a trap is also called
-.I planting
-one.
-.
-It is said that a trap is
-.I sprung
-if its condition is fulfilled.
.\" END Keep (roughly) parallel with groff.texi node "Traps".
.
.
@@ -7746,12 +7747,13 @@ The top-level diversion has no name.
.
.
.P
-Dereferencing an undefined diversion will create an empty one of that
-name and cause a warning in category
-.B mac
-to be emitted.
-(see section \[lq]Warnings\[rq] in
-.MR @g@troff @MAN1EXT@ ).
+Dereferencing an undefined diversion creates an empty one of that name
+and emits a warning in category
+.BR mac .
+.
+See section \[lq]Warnings\[rq] in
+.MR @g@troff @MAN1EXT@
+regarding the enablement and suppression of warnings.
.
A diversion does not exist for the purpose of testing with the
.B d
@@ -7789,8 +7791,9 @@ Call any of these macros again without an argument to end
the diversion.
Diversion requests can be nested.
.
The registers
-.BR .d ,
-.BR .z ,
+.B .d
+and
+.B .z
report information about the current diversion,
and
.B dn
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 7fb2c64bb..6c98798b6 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -813,13 +813,13 @@ but the polygon is filled.
.
.TP
.BI \[rs]D\[aq]t\~ "n" \[aq]
-Set line thickness of geometric objects to
+Set line thickness of geometric objects
.RI to\~ n
basic units.
.
A zero
.I n
-selects the minimal supported thickness.
+selects the minimum supported thickness.
.
A negative
.I n
@@ -1163,7 +1163,7 @@ cannot.
This inclusion of newlines requires an extension to the AT&T
.I troff \" AT&T
output format,
-and will confuse postprocessors that do not know about it.
+and confuses postprocessors that do not know about it.
.
.
.TP
@@ -4467,7 +4467,7 @@ This is a string-valued register.
.B \[rs]n[.ss]
.TQ
.B \[rs]n[.sss]
-Interpolate values of minimal inter-word space and additional
+Interpolate values of minimum inter-word space and additional
inter-sentence space,
respectively,
in twelfths of the space width of the selected font.
@@ -4744,7 +4744,7 @@ Interpolate Gregorian year.
.
AT&T
.IR troff 's \" AT&T
-.B \[rs][yr]
+.B \[rs]n[yr]
interpolates the Gregorian year minus 1900.
.
.
@@ -5449,7 +5449,7 @@ composite characters
environments
.RB ( pev ),
hyphenation codes
-.RB ( .phcode ),
+.RB ( phcode ),
hyphenation exceptions
.RB ( phw ),
registers
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
