gbranden pushed a commit to branch master
in repository groff.
commit a7cb1e5948c0576ef7a918669b398a5d9909bf8e
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Apr 25 18:38:11 2026 -0500
[doc,man]: Wordsmith, resync abstract style stuff.
* Favor active voice over passive.
* Break Texinfo input lines in a roff-friendly way.
---
doc/groff.texi.in | 122 ++++++++++++++++++++++++++++++++++++---------------
man/groff.7.man | 26 ++++++-----
man/groff_diff.7.man | 34 +++++++++++---
3 files changed, 128 insertions(+), 54 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index d04bfbf7c..297ff0631 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -12401,39 +12401,70 @@ a place in an ordered list of available typefaces.
@cindex abstract font style
@cindex font style, abstract
@cindex style, font, abstract
-So that a document need not be strongly coupled to a specific font
-family, in GNU @code{troff} an output device can associate a style in
-the abstract sense with a mounting position. Thus the default family
-can be combined with a style dynamically, producing a @dfn{resolved font
-name}. A user-specified font name that combines family and style, or
-refers to a font that is not a member of a family, is already
-``resolved''.
-
-Fonts often have trademarked names, and even Free Software fonts can
-require renaming upon modification. @code{groff} maintains a
-convention that a device's serif font family is given the name @samp{T}
-(``Times''), its sans-serif family @samp{H} (``Helvetica''), and its
-monospaced family @samp{C} (``Courier''). Historical inertia has driven
-@code{groff}'s font identifiers to short uppercase abbreviations of font
-names, as with @samp{TR}, @samp{TI}, @samp{TB}, @samp{TBI}, and a
-special font @samp{S}.
-
-The default family used with abstract styles is initially @samp{T}.
-Typically, abstract styles are arranged in the first four mounting
-positions in the order shown above. The default mounting position, and
-therefore style, is always @samp{1} (@samp{R}). By issuing appropriate
-formatter instructions, you can override these defaults before your
-document writes its first glyph.
+So that a document need not be strongly coupled
+to a specific font family,
+in
+GNU @command{troff} @c GNU
+an output device can associate a style in the abstract sense
+with a mounting position.
+Thus the default family can be combined with a style dynamically,
+producing a
+@dfn{resolved font name}.
+A user-specified font name that combines family and style,
+or refers to a font that is not a member of a family,
+is already ``resolved''.
+
+Fonts often have trademarked names,
+and even Free Software fonts can require renaming upon modification.
+@code{groff}
+maintains a convention that a device's serif font family
+bears the name
+@samp{T}
+(``Times''),
+its sans-serif family
+@samp{H}
+(``Helvetica''),
+and its monospaced family
+@samp{C}
+(``Courier'').
+Historical inertia has driven
+@code{groff}'s
+font identifiers to short uppercase abbreviations of font names,
+as with
+@samp{TR},
+@samp{TI},
+@samp{TB},
+@samp{TBI},
+and a special font
+@samp{S}.
+
+The default family used with abstract styles can be changed at any time;
+initially,
+it
+is@tie{}@samp{T}.
+Typically,
+device description files arrange abstract styles
+in the first four mounting positions in the order shown above.
+@footnote{@xref{DESC File Format}.}
+The default mounting position,
+and therefore style,
+is always
+@samp{1}
+(@samp{R}).
+By issuing appropriate formatter instructions,
+you can override these defaults
+before your document writes its first glyph.
@cindex graphic renditions
@cindex renditions, graphic
@cindex character cell attributes
@cindex attributes, character cell
@cindex cell, character, attributes
-Terminals cannot change font families and lack special fonts. They
-support style changes by overstriking, or by altering
-@w{ISO 6429}/ECMA-48 @dfn{graphic renditions} (character cell
-attributes).
+Terminals cannot change font families and lack special fonts.
+They support style changes by overstriking,
+or by altering @w{ISO 6429}/ECMA-48
+@dfn{graphic renditions}
+(character cell attributes).
@c END Keep (roughly) parallel with section "Using fonts" of groff(7).
@menu
@@ -12772,20 +12803,37 @@ or
@code{fspecial}
to an abstract style affects the member of the default family
corresponding to that style.
-@c END Keep parallel with subsection "Font families, abstract styles,
-@c and translation" of groff_diff(7).
@pindex DESC
@kindex styles
-The default family can be set with the @option{-f} option (@pxref{Groff
-Options}). The @code{styles} command in the @file{DESC} file controls
-which font positions (if any) are initially associated with abstract
-styles rather than fonts.
+GNU
+@command{troff}'s @c GNU
+@option{-f}
+command-line option
+(recall @ref{Groff Options})
+and
+@code{fam}
+request set the default family.
+The
+@code{styles}
+directive in the output device's
+@file{DESC}
+file controls which mounting positions
+(if any)
+initially associate with abstract styles rather than fonts,
+and the
+@code{sty}
+request updates this association.
-@strong{Caution:@:} The @var{style} argument is not validated.
+@strong{Caution:@:}
+GNU
+@command{troff} @c GNU
+does not validate the
+@var{style} argument.
@c XXX: This would be a really good thing to fix.
-Errors may occur later, when the formatter attempts to construct a
-resolved font name, or format a character for output.
+Errors may occur later,
+when the formatter attempts to construct a resolved font name,
+or format a character for output.
@Example
.nr BarPos \n[.fp]
@@ -12804,6 +12852,8 @@ register @samp{.sty} interpolates its name; this datum
is associated
with the environment (@pxref{Environments}). Otherwise, @samp{.sty}
interpolates nothing.
@endDefreq
+@c END Keep parallel with subsection "Font families, abstract styles,
+@c and translation" of groff_diff(7).
@c ---------------------------------------------------------------------
diff --git a/man/groff.7.man b/man/groff.7.man
index abcc86b33..e472dc11e 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -8190,12 +8190,13 @@ the formatter associates it with a
.I "mounting position,"
a place in an ordered list of available typefaces.
.
-So that a document need not be strongly coupled to a specific font
-family,
-in GNU
+So that a document need not be strongly coupled
+to a specific font family,
+in
+GNU
.I troff \" GNU
-an output device can associate a style in the abstract sense with a
-mounting position.
+an output device can associate a style in the abstract sense
+with a mounting position.
.
Thus the default family can be combined with a style dynamically,
producing a
@@ -8211,8 +8212,8 @@ Fonts often have trademarked names,
and even Free Software fonts can require renaming upon modification.
.
.I groff
-maintains a convention that a device's serif font family is given the
-name
+maintains a convention that a device's serif font family
+bears the name
.B T
(\[lq]Times\[rq]),
its sans-serif family
@@ -8242,8 +8243,11 @@ it
.RB is\~ T .
.
Typically,
-abstract styles are arranged in the first four mounting positions in the
-order shown above.
+device description files arrange abstract styles
+in the first four mounting positions in the order shown above.
+.
+(See
+.MR groff_font @MAN5EXT@ .)
.
The default mounting position,
and therefore style,
@@ -8252,8 +8256,8 @@ is always
.RB ( R ).
.
By issuing appropriate formatter instructions,
-you can override these defaults before your document writes its first
-glyph.
+you can override these defaults
+before your document writes its first glyph.
.
.
.P
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 93698d189..c84ce9a56 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -200,13 +200,18 @@ or
.B \%fspecial
to an abstract style affects the member of the default family
corresponding to that style.
-.\" END Keep parallel with node "Font Families" in our Texinfo manual.
.
-The default family can be set with the
-.B fam
-request or
+.
+.P
+GNU
+.IR troff 's \" GNU
.B \-f
-command-line option.
+command-line option
+(see
+.MR @g@troff @MAN1EXT@ )
+and
+.B fam
+request set the default family.
.
The
.B styles
@@ -214,10 +219,11 @@ directive in the output device's
.I DESC
file controls which mounting positions
(if any)
-are initially associated with abstract styles rather than fonts,
+initially associate with abstract styles rather than fonts,
and the
.B sty
-request can update this association.
+request updates this association.
+.\" END Keep parallel with node "Font Families" in our Texinfo manual.
.
.
.\" ====================================================================
@@ -4519,6 +4525,20 @@ with non-negative font mounting
.RI position\~ pos .
.
.
+.IP
+.I Caution:
+GNU
+.I troff \" GNU
+does not validate the
+.I style
+argument.
+.\" XXX: This would be a really good thing to fix.
+.
+Errors may occur later,
+when the formatter attempts to construct a resolved font name,
+or format a character for output.
+.
+.
.TP
.BI .substring\~ "str start\~"\c
.RI [ end ]
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
