gbranden pushed a commit to branch master
in repository groff.
commit 6ebd46f676d776f1158e5ecfea20972636369ae8
Author: G. Branden Robinson <[email protected]>
AuthorDate: Fri Mar 27 21:05:49 2026 -0500
[doc,man]: Make numerous minor revisions.
* Alphabetically arrange laundry list of implementation differences in
individual requests.
* Fix unclear use of pronouns.
* Tighten wording.
* Sync wording between our Texinfo manual and man pages.
* Break Texinfo input lines in a roff-friendly way.
* Fix markup nits.
---
doc/groff.texi.in | 121 ++++++++++++++++++++++++++++++++-------------------
man/groff.7.man | 35 ++++++++-------
man/groff_char.7.man | 4 +-
man/groff_diff.7.man | 89 +++++++++++++++++--------------------
4 files changed, 138 insertions(+), 111 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 088e06c06..08b0fc011 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -12466,12 +12466,22 @@ line.
@DefescListEnd {\\F, [, family, ]}
@cindex changing font family (@code{fam}, @code{\F})
@cindex font family, changing (@code{fam}, @code{\F})
-Set the default font family, used in combination with abstract styles to
-construct a resolved font name, to @var{family} (one-character
-name@tie{}@var{f}, two-character name @var{fm}). If no argument is
-given, GNU @code{troff} selects the previous font family; if there are
-none, it falls back to the device's default@footnote{@xref{DESC File
-Format}.} or its own (@samp{T}).
+Set the default font family,
+used in combination with abstract styles
+to construct a resolved font name,
+to
+@var{family}
+(one-character name@tie{}@var{f},
+two-character name @var{fm}).
+Without an argument,
+GNU
+@command{troff}
+selects the previous font family;
+if there is none,
+it falls back to the device's default@footnote{@xref{DESC File
+Format}.}
+or its own
+(@samp{T}).
The @code{\F} escape sequence works similarly. In disanalogy to
@code{\f}, @samp{\FP} makes @samp{P} the default family. Use
@@ -14833,14 +14843,19 @@ and
@code{.ps}
registers represent the type size selected by the formatter
as it understands a device's capability.
-The last
-@emph{requested}
-type size is interpolated in scaled points
-by the read-only register
+The read-only registers
@code{.psr}
-and in points as a decimal fraction
-by the read-only string-valued register
-@code{.sr}.
+and
+(string-valued)
+@code{.sr}
+interpolate the last
+@emph{requested}
+type size
+in scaled points
+and in points as a decimal fraction,
+respectively.
+Like the selected current and previous type size,
+the requested ones are properties of an environment.
For example,
if a document requests a type size of 10.95@tie{}points,
@@ -17367,12 +17382,11 @@ their left edges, in contrast to @code{\o}'s
centering.
Save the drawing position,
format
@var{input},
-then restore it.
+then restore the saved position.
GNU
@command{troff} @c GNU
-ignores tabs and leaders in
-@var{input}
-with an error diagnostic.
+disallows tabs and leaders in
+@var{input}.
We might implement a strike-through macro thus.
@@ -18667,11 +18681,19 @@ of qualifying lines enumerated in that environment.
@Defreq {blm, [@Var{name}]}
@cindex blank line macro (@code{blm})
-Set a blank line trap, calling the macro @var{name} when GNU
-@code{troff} encounters a blank line in input, instead of the usual
-behavior (@pxref{Breaking}). A line consisting only of spaces is also
-treated as blank and subject to this trap. If no argument is supplied,
-the default blank line behavior is (re-)established.
+Set a blank line trap,
+calling the macro
+@var{name}
+when
+GNU
+@command{troff}
+encounters a blank line in input,
+instead of the usual behavior
+(@pxref{Breaking}).
+A line consisting only of spaces
+is also treated as blank and subject to this trap.
+Omitting the argument
+re�stablishes the default blank line behavior.
@endDefreq
@c ---------------------------------------------------------------------
@@ -18704,10 +18726,12 @@ irrespective of whether a leading space trap is set.
When it is, GNU @command{troff} removes the leading spaces from
the input line and produces no motion before calling @var{name}.
-If no argument is supplied, GNU @command{troff} re�stablishes the
-default handling of leading spaces on text lines (breaking the line when
-filling, and formatting a horizontal motion of @samp{\n[lsn]} word
-spaces).
+Omitting the argument re�stablishes the default handling
+of leading spaces on text lines
+(breaking the line when filling,
+and formatting a horizontal motion of
+@samp{\n[lsn]}
+word spaces).
@c XXX The following discussion does not seem to be correct; leading
@c space traps don't "see" _any_ tokens. Nothing on the line is
@@ -18740,9 +18764,13 @@ spaces).
@cindex trap, end-of-input, setting (@code{em})
@cindex end-of-input macro (@code{em})
@cindex macro, end-of-input (@code{em})
-Set a trap at the end of input, calling macro @var{name} after the last
-line of the last input file has been processed. If no argument is
-given, any existing end-of-input trap is removed.
+Set a trap at the end of input;
+the formatter
+calls macro
+@var{name}
+after processing the last line of the last input file.
+Without an argument,
+the formatter removes any existing end-of-input trap.
For example, if the document had to have a section at the bottom of the
last page for someone to approve it, the @code{em} request could be
@@ -21102,7 +21130,7 @@ environments,
occupied font mounting positions,
font translations,
automatic hyphenation codes
-and exceptions,
+and exception words,
registers,
open streams,
and page location traps.
@@ -21574,7 +21602,7 @@ warning category that is to be enabled; all other
categories are
disabled. The categories and their associated codes are listed in
@ref{Warnings}. For example, @samp{.warn 0} disables all warnings, and
@samp{.warn 1} disables all warnings except those about missing glyphs.
-If no argument is given, all warning categories are enabled.
+Omitting the argument enables all warning categories.
The read-only register @code{.warn} contains the sum of the numeric
codes of enabled warning categories.
@@ -22589,18 +22617,6 @@ GNU
honors such requests.
Recall @ref{Built-in Registers}.
-@cindex @code{lf} request, incompatibilities with @acronym{AT&T} @code{troff}
-The
-@code{lf}
-request sets the number of the
-@emph{current}
-input line in AT&T
-@command{troff} @c AT&T
-and the
-@emph{next}
-in GNU
-@command{troff}. @c GNU
-
@cindex environment availability and naming, incompatibilities with
@acronym{AT&T}
@command{troff} @c AT&T
@@ -22664,6 +22680,18 @@ does not accept a scaling unit on the argument,
a page number;
the former does (uselessly).
+@cindex @code{lf} request, incompatibilities with @acronym{AT&T} @code{troff}
+The
+@code{lf}
+request sets the number of the
+@emph{current}
+input line in AT&T
+@command{troff} @c AT&T
+and the
+@emph{next}
+in GNU
+@command{troff}. @c GNU
+
@cindex @code{pm} request, incompatibilities with @acronym{AT&T} @code{troff}
In @acronym{AT&T}
@command{troff}, @c AT&T
@@ -22702,8 +22730,8 @@ and does not move the drawing position.
@acronym{AT&T}
@command{troff} @c AT&T
sets the vertical drawing position
-to two basic units fewer than the specified argument
-(or one vee minus one basic unit if no argument is present).
+to two basic units fewer than the specified argument,
+and to one vee minus one basic unit if no argument is present.
@c Yes, really. Try:
@c printf '.tm \\n(nl\n.c2 $\n$sp\n.tm \\n(nl\n'
@c printf '.tm \\n(nl\n.c2 $\n.nr nl -1\n$sp\n.tm \\n(nl\n'
@@ -22744,6 +22772,9 @@ Glyphs represent graphemes
(supplied by the output device)
and populate diversions
(recall @ref{Diversions}).
+There is no such thing as a space character in
+GNU
+@command{troff}. @c GNU
Formatting converts characters into
(sequences of)
glyphs.
diff --git a/man/groff.7.man b/man/groff.7.man
index cdc19b0ef..7b8ebb494 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5923,9 +5923,9 @@ Interpolate glyph of special character with identifier
.
.
.TP
-.ESC[] "" "base-char comp \fR\&.\|.\|."
+.ESC[] "" "base-character comp \fR\&.\|.\|."
Interpolate composite glyph constructed from
-.I base-char
+.I base-character
and each component
.IR comp .
.
@@ -5946,10 +5946,10 @@ in uppercase hexadecimal.
.
.
.TP
-.ESC[] "" "\f[B]u\f[]base-char\f[R][\f[]\f[B]_\f[]\
+.ESC[] "" "\f[B]u\f[]base-character\f[R][\f[]\f[B]_\f[]\
combining-component\f[R]].\|.\|."
Interpolate composite glyph from Unicode character
-.I base-char
+.I base-character
and
.IR combining-components .
.
@@ -6626,13 +6626,12 @@ with zero width\[em]without advancing the drawing
position.
Save the drawing position,
format
.IR input ,
-then restore it.
+then restore the saved position.
.
GNU
.I troff \" GNU
-ignores tabs and leaders in
-.I input
-with an error diagnostic.
+disallows tabs and leaders in
+.IR input .
.LE
.
.
@@ -7515,7 +7514,7 @@ The environment's post-vertical line spacing.
.
.TP
.REG .R
-Maximum representable integer in GNU
+Maximum integer representable in GNU
.IR troff . \" GNU
.
.TP
@@ -7538,10 +7537,10 @@ Reserved.
.
Plan\~9
.I troff \" Plan 9
-uses this name for roughly the same purpose as
+uses this name for a purpose similar to
GNU
.IR troff 's \" GNU
-.REG .tabs .
+.register .tabs .
.
.TP
.REG .slant
@@ -7569,6 +7568,9 @@ in twelfths of the space width of the selected font.
Size of the environment's supplemental inter-sentence space
in twelfths of the space width of the selected font.
.
+See
+.request ss .
+.
.TP
.REG .sty
The environment's selected abstract style (string-valued);
@@ -8166,7 +8168,7 @@ can be written in an upright or slanted typeface,
producing distinct glyphs.
.
Sometimes,
-a sequence of characters map to a single glyph:@:
+a sequence of characters map to a single glyph:
this is a
.IR ligature \[em]\c
the most common is `fi'.
@@ -8190,7 +8192,7 @@ is the most commonly used,
has no special syntax,
and typically represents itself.
.
-(Depending on the breadth
+Depending on the breadth
of the output device's glyph repertoire,
the characters
.BR \[aq] ,
@@ -8231,16 +8233,17 @@ An
.I "indexed character"
bypasses most character-to-glyph resolution logic,
uses the
-.RB \[lq] \[rs]N\[aq]\c
+.RB \[lq]\| \[rs]N\[aq]\c
.IB i \[aq]\c
+\|\[rq]
syntax,
and selects a glyph from the currently selected font
by its integer-valued position
.I i
in the output device's representation of that font.
.
-(A device's fonts
-do not necessarily arrange their glyphs
+(A device's font
+might not arrange its glyphs
according to a standard character encoding.)
.
.
diff --git a/man/groff_char.7.man b/man/groff_char.7.man
index 7b8fa894c..dc6e3bf44 100644
--- a/man/groff_char.7.man
+++ b/man/groff_char.7.man
@@ -722,7 +722,7 @@ or
.
.
.TP
-.BI \[rs][ "base-char composite-1 composite-2"\~\c
+.BI \[rs][ "base-character composite-1 composite-2"\~\c
\&.\|.\|.\~\c
.IB composite-n ]
is a composite glyph.
@@ -836,7 +836,7 @@ on ISO\~Latin-1 systems.)
.
.
.TP
-.BI \[rs][u base-char\c
+.BI \[rs][u base-character\c
[\c
.BI _ combining-component\c
].\|.\|.]
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index b7a29b3eb..bb42b1638 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -497,18 +497,19 @@ and
registers represent the type size selected by the formatter
as it understands a device's capability.
.
-the read-only registers
+The read-only registers
.B .psr
and
(string-valued)
.B .sr
interpolate the last
.I requested
+type size
in scaled points
and in points as a decimal fraction,
respectively.
.
-Like the actual current and previous type size,
+Like the selected current and previous type size,
the requested ones are properties of an environment.
.
.
@@ -1429,7 +1430,7 @@ further,
.I mac
can be a macro and thus contain newlines,
unlike the argument to
-.B \[rs]X .
+.BR \[rs]X .
.
This inclusion of newlines requires an extension to the AT&T
.I troff \" AT&T
@@ -1444,13 +1445,12 @@ and their presence confuses drivers that do not know
about it
Save the drawing position,
format
.IR input ,
-then restore it.
+then restore the saved position.
.
GNU
.I troff \" GNU
-ignores tabs and leaders in
-.I input
-with an error diagnostic.
+disallows tabs and leaders in
+.IR input .
.
.
.TP
@@ -1698,10 +1698,10 @@ See
.
.
.TP
-.BI \[rs][ "base-char combining-component\~"\c
+.BI \[rs][ "base-character combining-component\~"\c
.RB .\|.\|. ]
Typeset a composite glyph consisting of
-.I base-char
+.I base-character
overlaid with one or more
.IR combining-component s.
.
@@ -1710,7 +1710,7 @@ For example,
is a capital letter \[lq]A\[rq] with a \[lq]hook accent\[rq] (ogonek).
.
See the
-.B \%composite
+.RB \%\[lq] composite \[rq]
request below;
.IR "Groff: The GNU Implementation of troff" ,
the
@@ -1803,7 +1803,7 @@ the contents of
.I file
are immediately copied to the output regardless of whether a diversion
is being written to;
-this behavior is so anomalous that it must be considered a bug.
+this behavior is so anomalous that we consider it a bug.
.
.
.IP
@@ -1883,7 +1883,7 @@ request is selected.
.RB [[ \[dq] ]\c
.IR file-identifier ]
In GNU
-.I troff \" GNU
+.IR troff , \" GNU
the first argument becomes the input line number of the
.I next
line the formatter reads.
@@ -2076,10 +2076,6 @@ GNU
produces a warning in category
.RB \[lq] reg \[rq].
.
-See section \[lq]Warnings\[rq] of
-.MR @g@troff 1
-regarding the enablement and suppression of warnings.
-.
To remove a register alias,
invoke
.B rr
@@ -2115,10 +2111,6 @@ If
already exists,
its contents are lost unless already aliased.
.
-See section \[lq]Warnings\[rq] of
-.MR @g@troff 1
-regarding the enablement and suppression of warnings.
-.
To remove an alias,
invoke
.B rm
@@ -2306,8 +2298,8 @@ instead of the usual behavior.
A line consisting only of spaces is also treated as blank and subject to
this trap.
.
-If no argument is supplied,
-the default blank line behavior is (re-)established.
+Omitting the argument
+re\[e ad]stablishes the default blank line behavior.
.
.
.br
@@ -3750,10 +3742,8 @@ and produces no motion before calling
.
.
.IP
-If no argument is supplied,
-GNU
-.I troff \" GNU
-re\[e ad]stablishes the default handling of leading spaces on text lines
+Omitting the argument re\[e ad]stablishes the default handling
+of leading spaces on text lines
(breaking the line when filling,
and formatting a horizontal motion of
.B \[rs]n[lsn]
@@ -4696,8 +4686,7 @@ and
.RB \[lq] ".warn 1" \[rq]
disables all warnings except those about missing glyphs.
.
-If no argument is given,
-all warning categories are enabled.
+Omitting the argument enables all warning categories.
.
.
.TP
@@ -5776,8 +5765,8 @@ character will subsequently be disabled.
.P
GNU
.I troff \" GNU
-permits tabs and spaces after the first dot on a control line that ends
-a macro definition.
+permits tabs and spaces after the first control character
+on a control line that ends a macro definition.
.
.
.\" ====================================================================
@@ -6312,7 +6301,7 @@ font translations
.RB ( pftr ),
automatic hyphenation codes
.RB ( pchar )
-and exceptions
+and exception words
.RB ( phw ),
registers
.RB ( pnr ),
@@ -6397,7 +6386,7 @@ at the distal end).
In compatibility mode,
GNU
.I troff \" GNU
-interprets names in the traditional way,
+interprets names in the traditional way;
they thus can be two characters long at most.
.
See the
@@ -6872,19 +6861,6 @@ GNU
honors such requests.
.
.
-.P
-The
-.B lf
-request sets the number of the
-.I current
-input line in AT&T
-.IR troff ,\" AT&T
-and the
-.I next
-in GNU
-.IR troff .\" GNU
-.
-.
.br
.ne 2v
.P
@@ -6950,6 +6926,19 @@ the former does (uselessly).
.
.
.P
+The
+.B lf
+request sets the number of the
+.I current
+input line in AT&T
+.IR troff ,\" AT&T
+and the
+.I next
+in GNU
+.IR troff .\" GNU
+.
+.
+.P
In AT&T
.I troff \" AT&T
the
@@ -6989,8 +6978,8 @@ and does not move the drawing position.
AT&T
.I troff \" AT&T
sets the vertical drawing position
-to two basic units fewer than the specified argument
-(or one vee minus one basic unit if no argument is present).
+to two basic units fewer than the specified argument,
+and to one vee minus one basic unit if no argument is present.
.\" Yes, really. Try:
.\" printf '.tm \\n(nl\n.c2 $\n$sp\n.tm \\n(nl\n'
.\" printf '.tm \\n(nl\n.c2 $\n.nr nl -1\n$sp\n.tm \\n(nl\n'
@@ -7031,6 +7020,10 @@ Glyphs represent graphemes
and populate diversions.
.\" (recall @ref{Diversions}).
.
+There is no such thing as a space character in
+GNU
+.IR troff .\" GNU
+.
Formatting converts characters into
(sequences of)
glyphs.
@@ -7107,7 +7100,7 @@ for \[lq]reverse solidus\[rq],
from its name in the ECMA-6 and ISO\~10646 standards.
.
[AT&T
-.I troff 's \" AT&T
+.IR troff 's \" AT&T
font description files
did not define the
.B rs
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
