[groff] 12/27: [docs]: Revise discussion of `ftr` request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d1121498e9e8bdf639c8826f430c9f7f07b3eda7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Aug 27 14:38:09 2023 -0500

    [docs]: Revise discussion of `ftr` request.
    
    * Clarify that `ftr` can be applied to abstract styles.
    * (groff(7)) Document single-argument form of `ftr`.
    * Use active voice more.
    * Tighten wording.
---
 doc/groff.texi  | 28 +++++++++++++---------------
 man/groff.7.man | 19 ++++++++++++-------
 2 files changed, 25 insertions(+), 22 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 9fa6bd913..2b2604766 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10234,12 +10234,12 @@ one.
 In digital typography, a @dfn{font} is a collection of characters in a
 specific typeface that a device can render as glyphs at a desired
 size.@footnote{Terminals and some typesetters have fonts that render at
-only one or two sizes.  As examples of the latter, take the @code{groff}
-@code{lj4} device's Lineprinter, and @code{lbp}'s Courier and Elite
-faces.}  A @code{roff} formatter can change typefaces at any point in
-the text.  The basic faces are a set of @dfn{styles} combining upright
-and slanted shapes with normal and heavy stroke weights: @samp{R},
-@samp{I}, @samp{B}, and @samp{BI}---these stand for @slanted{roman},
+only one or two sizes.  As examples, take the @code{groff} @code{lj4}
+device's Lineprinter, and @code{lbp}'s Courier and Elite faces.}  A
+@code{roff} formatter can change typefaces at any point in the text.
+The basic faces are a set of @dfn{styles} combining upright and slanted
+shapes with normal and heavy stroke weights: @samp{R}, @samp{I},
+@samp{B}, and @samp{BI}---these stand for @slanted{roman},
 @slanted{italic}, @slanted{bold}, and @slanted{bold-italic}.  For
 linguistic text, GNU @code{troff} groups typefaces into @dfn{families}
 containing each of these styles.@footnote{Font designers prepare
@@ -10432,15 +10432,13 @@ assign a font to a margin character as follows 
(@pxref{Miscellaneous}).
 @cindex @code{if} request, and font translations
 @cindex @code{ie} request, and font translations
 @cindex @code{while} request, and font translations
-Translate font@tie{}@var{f} to font@tie{}@var{g}.  Whenever a font
-named@tie{}@var{f} is referred to in a @code{\f} escape sequence, in the
-@code{F} and @code{S} conditional operators, or in the @code{ft},
-@code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
-@code{fspecial}, @code{fp}, or @code{sty} requests, font@tie{}@var{g} is
-used.  If @var{g} is missing or equal to@tie{}@var{f}, the translation
-is undone.
-@c XXX: Do font translations work on mounting positions?  Abstract
-@c styles?
+Translate font name@tie{}@var{f} to@tie{}@var{g}.  Where the @code{\f}
+escape sequence, the @code{F} and @code{S} conditional operators, and
+the @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
+@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests refer
+to@tie{}@var{f}, GNU @command{troff} uses @var{g} instead.  Omit @var{g}
+or repeat @var{f} as@tie{}@var{g} to untranslate @var{f}.  @var{f} and
+@var{g} need not be mounted fonts.
 @endDefreq
 
 @DefreqList {fzoom, font [@Var{zoom}]}
diff --git a/man/groff.7.man b/man/groff.7.man
index a6cb0ed1a..8b3b2ff89 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3205,11 +3205,16 @@ cannot be
 .BR P .
 .
 .TPx
-.REQ .ftr "font1 font2"
-Translate
-.I font1
+.REQ .ftr f
+Remove transalation of font named
+.IR f .
+.
+.TPx
+.REQ .ftr "f1 f2"
+Translate font name
+.I f1
 to
-.IR font2 .
+.IR f2 .
 .
 .TPx
 .REQ .fzoom font
@@ -6607,7 +6612,7 @@ render as glyphs at a desired size.
 (Terminals and some typesetters have fonts that render at only one or
 two sizes.
 .
-As examples of the latter,
+As examples,
 take the
 .I groff
 .B lj4
@@ -6792,9 +6797,9 @@ escape sequence set the default font family.
 .
 The
 .B ftr
-request remaps a (resolved) font name;
+request translates one font name to another;
 .B fzoom
-magnifies one.
+magnifies a resolved one.
 .
 .B sty
 and