gbranden pushed a commit to branch master
in repository groff.
commit 2cbda64bbea657f6a6e55cd449401edb81505471
Author: G. Branden Robinson <[email protected]>
AuthorDate: Thu Apr 24 16:39:22 2025 -0500
[doc,man]: Fix style nits.
* Clarify.
* Favor active voice over passive.
* Parallelize wording and input line breaks between our Texinfo manual
and man pages.
---
doc/groff.texi.in | 64 ++++++++++++++++------
man/groff_diff.7.man | 146 ++++++++++++++++++++++++++++++++++-----------------
2 files changed, 147 insertions(+), 63 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 712a456b0..ff0072bc0 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -8306,8 +8306,13 @@ quantity and its units.
@Defesc {\\~, , , }
@cindex unbreakable space (@code{\~})
@cindex space, unbreakable (@code{\~})
-Insert an unbreakable space that is adjustable like an ordinary space.
-It is discarded from the end of an output line if a break is forced.
+Insert an adjustable,
+unbreakable space.
+As with ordinary spaces,
+GNU
+@command{troff} @c GNU
+discards any sequence of these at the end of an output line
+if a break occurs.
@Example
Set the output speed to\~1.
@@ -12803,9 +12808,15 @@ withdrawn.}
@DefescItem {\\m, (, co, }
@DefescItem {\\m, [, col, ]}
@DefregListEndx {.m}
-Set the stroke color. The escape sequence @code{\m[]} restores the
-previous stroke color, or the default if there is none, as does a
-@code{gcolor} request without an argument.
+Set stroke color to
+@var{col}.
+The escape sequence
+@code{\m[]}
+restores the previous stroke color,
+or the default if there is none,
+as does a
+@code{gcolor}
+request without an argument.
@Example
.gcolor red
@@ -12840,10 +12851,17 @@ when writing a margin character as follows
(@pxref{Miscellaneous}).
@DefescItem {\\M, (, co, }
@DefescItem {\\M, [, col, ]}
@DefregListEndx {.M}
-Set the fill color for objects drawn with @code{\D'@dots{}'} escape
-sequences. The escape sequence @code{\M[]} restores the previous fill
-color, or the default if there is none, as does an @code{fcolor} request
-without an argument.
+Set fill color for objects drawn with
+@code{\D'@dots{}'}
+escape sequences to
+@var{col}.
+The escape sequence
+@code{\M[]}
+restores the previous fill color,
+or the default if there is none,
+as does an
+@code{fcolor}
+request without an argument.
@cindex @code{\M} escape sequence, untokenized on input
@cindex untokenized escape sequence, @code{\M}
@@ -13059,9 +13077,17 @@ Because strings are similar to macros, they too can be
defined so as to
suppress AT&T @code{troff} compatibility mode when used; see
@ref{Writing Macros} and @ref{Compatibility Mode}. The @code{ds1}
request defines a string such that compatibility mode is off when the
-string is later interpolated. To be more precise, a @dfn{compatibility
-save} token is inserted at the beginning of @var{contents}, and a
-@dfn{compatibility restore} token at the end.
+string is later interpolated.
+To be more precise,
+GNU
+@command{troff} @c GNU
+inserts a
+a
+@dfn{compatibility save}
+token at the beginning of @var{contents},
+and a
+@dfn{compatibility restore}
+token at the end.
@Example
.nr xxx 12345
@@ -13491,9 +13517,17 @@ comparisons in other programming languages.
@cindex copy mode, and @code{\?}
@cindex mode, copy, and @code{\?}
@noindent
-Since GNU @code{troff} reads comparands protected with @code{\?} in copy
-mode (@pxref{Copy Mode}), they need not even be valid @code{groff}
-syntax. The escape character is still lexically recognized, however,
+Since
+GNU
+@command{troff}
+reads comparands protected with
+@code{\?}
+in copy mode (@pxref{Copy Mode}),
+they need not even be valid
+@code{groff}
+syntax.
+The escape character is still lexically recognized,
+however,
and consumes the next character.
@Example
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 5ed6b6eb9..f4127ef01 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -80,11 +80,11 @@ by the
.I troff \" generic
formatter.
.
-Differences arising from
+We also note here differences arising from
.IR groff 's
implementation of AT&T
.I troff \" AT&T
-features are also noted.
+features.
.
See
.MR roff @MAN7EXT@
@@ -92,8 +92,8 @@ for background.
.
GNU
.I troff \" GNU
-can operate in a mode that increases support for documents written for
-AT&T
+can operate in a manner that increases support
+for documents written for AT&T
.IR troff ; \" AT&T
see section \[lq]Compatibility mode\[rq] below.
.
@@ -696,7 +696,10 @@ to a form suitable for Versatec and Benson-Varian
plotters.)
.
GNU
.I troff \" GNU
-offers drawing commands to create filled
+extends the
+.B \[rs]D
+escape sequence
+with drawing commands to create filled
circles and ellipses,
and polygons.
.\" CSTR #54 did not countenance polygons, but DWB 3.3 had outlined ones
@@ -810,10 +813,11 @@ with its leftmost point at the drawing position.
.
.TP
.BI \[rs]D\[aq]E\~ "h v" \[aq]
-Draw filled ellipse with axis lengths
-.IR h ,
+Draw filled ellipse of axis lengths
+.I h
+and
.IR v ,
-and its leftmost point at the drawing position.
+with its leftmost point at the drawing position.
.
.
.TP
@@ -945,7 +949,8 @@ or arbitrary register
.BI \[rs]m( cl
.TQ
.BI \[rs]m[ col ]
-Set the stroke color.
+Set stroke color to
+.IR col .
.
.B \[rs]m[]
restores the previous stroke color,
@@ -958,7 +963,8 @@ or the default if there is none.
.BI \[rs]M( cl
.TQ
.BI \[rs]M[ col ]
-Set the fill color.
+Set fill color to
+.IR col .
.
.B \[rs]M[]
restores the previous fill color,
@@ -1104,9 +1110,9 @@ Synonymous with
.IR name\~\[+-]n \[rq].
.
.TP
-.BI \[rs]s[ 0 ]
+.B \[rs]s[0]
.TQ
-.BI \[rs]s\[aq] 0 \[aq]
+.B \[rs]s\[aq]0\[aq]
Restore the previous type size;
no operation if there is none.
.
@@ -1340,7 +1346,9 @@ or
.IR nnn th
argument.
.
-Macros and strings can have an unlimited number of arguments.
+In GNU
+.IR troff , \" GNU
+macros and strings can have an unlimited number of arguments.
.
.
.TP
@@ -1428,7 +1436,7 @@ between them
.\}
avoids this problem.
.
-Use
+Consider using
.B \[rs]\^/
whenever a slanted glyph
is immediately followed by an upright glyph
@@ -1463,8 +1471,8 @@ between them
.\}
avoids this problem.
.
-Use
-@code{\,}
+Consider using
+.B \[rs]\^,
whenever an upright glyph
is followed immediately by a slanted glyph
without any intervening space.
@@ -1496,7 +1504,8 @@ Use it with the output comparison operator to compare its
operands
by character rather than as formatted output.
.
Since
-.MR @g@troff
+GNU
+.I troff \" GNU
reads comparands protected with
.B \[rs]?\&
in copy mode,
@@ -1566,9 +1575,14 @@ for a list of components used in composite glyph names.
.
.TP
.B \[rs]\[ti]
-Insert an unbreakable space that is adjustable like an ordinary space.
+Insert an adjustable,
+unbreakable space.
.
-It is discarded from the end of an output line if a break is forced.
+As with ordinary spaces,
+GNU
+.I troff \" GNU
+discards any sequence of these at the end of an output line
+if a break occurs.
.
.
.\" ====================================================================
@@ -1700,11 +1714,17 @@ remove its name first.
.RI [ end-name ]
As
.RB \[lq] am \[rq],
-but compatibility mode is disabled while the appendment to
-.I name
-is interpreted:
-a \[lq]compatibility save\[rq] token is inserted at its beginning,
-and a \[lq]compatibility restore\[rq] token at its end.
+but
+GNU
+.I troff \" GNU
+disables compatibility mode while interpreting the appendment to
+.I name:
+it inserts a
+.I "compatibility save"
+token at the beginning of the appendment,
+and a
+.I "compatibility restore"
+token at its end.
.
As a consequence,
the requests
@@ -1735,8 +1755,13 @@ below.
.RI [ end-name ]
As
.BR ami ,
-but compatibility mode is disabled during interpretation of the
-appendment.
+but
+GNU
+.I troff \" GNU
+disables compatibility mode
+while interpreting the appendment to the macro
+named by the contents of string
+.I name.
.
.
.TP
@@ -1745,12 +1770,18 @@ appendment.
.IR contents ]
As
.RB \[lq] as \[rq],
-but compatibility mode is disabled while the appendment to
-.I name
-is interpreted:
-a \[lq]compatibility save\[rq] token is inserted at the beginning of
-.IR contents ,
-and a \[lq]compatibility restore\[rq] token after it.
+but
+GNU
+.I troff \" GNU
+disables compatibility mode
+while interpreting the appendment to the string
+.I name:
+it inserts a
+.I "compatibility save"
+token at the beginning of the appendment,
+and a
+.I "compatibility restore"
+token at its end.
.
As a consequence,
the requests
@@ -2415,11 +2446,17 @@ A device's default stroke and fill colors are not
necessarily the same.
.RI [ end-name ]
As
.RB \[lq] de \[rq],
-but compatibility mode is disabled while the macro
-.I ident
-is interpreted:
-a \[lq]compatibility save\[rq] token is inserted at its beginning,
-and a \[lq]compatibility restore\[rq] token at its end.
+but
+GNU
+.I troff \" GNU
+disables compatibility mode while interpreting
+.I name:
+it inserts a
+.I "compatibility save"
+token at the beginning of the macro definition,
+and a
+.I "compatibility restore"
+token at its end.
.
See
.BR .am1 .
@@ -2440,10 +2477,18 @@ and the name of the end macro terminating its
definition in string
.RI [ end-name ]
As
.BR dei ,
-but compatibility mode is disabled while the definition of the macro
-named in string
-.I name
-is interpreted.
+but
+GNU
+.I troff \" GNU
+disables compatibility mode
+while interpreting the macro
+named by the contents of string
+.I name.
+.
+See
+.B am1
+and
+.BR de1 .
.
.
.TP
@@ -4264,13 +4309,18 @@ these requests behave similarly to
and
.BR as1 ,
respectively:
-a \[lq]compatibility save\[rq] token is inserted at the beginning,
-and a \[lq]compatibility restore\[rq] token at the end,
-with compatibility mode switched on during interpolation of the
-applicable macro definition,
-appendment,
-or string
-.I contents.
+GNU
+.I troff \" GNU
+inserts a
+.I "compatibility save"
+token at its beginning of
+.I contents
+and a
+.I "compatibility restore"
+token at its end,
+causing compatibility mode to switch on during interpolation
+of the applicable macro or string definition,
+or appendment thereto.
.
.
.TP
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
