[groff] 28/39: [docs]: Update discussion of font positions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f76ab61df5425d62b0d8499294912583a2a4d191
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon May 30 20:28:05 2022 -0500

    [docs]: Update discussion of font positions.
    
    * doc/groff.texi (Font Positions): Identify groff's "styles" feature as
      a motivator for the font positions feature, not just AT&T
      compatibility.  Talk about "font selection" rather than "font
      changing" (it is not in groff's power to alter a font per se).
      Describe how the initial set of mounting positions is populated in
      more detail.  Drop footnote about position 0 "usually" being unused;
      none of our output devices populates it by default.  Describe what the
      second argument to the `fp` request really is--a font description file
      name.  Better separate formal presentation of `.f` register from an
      example of its use.  Clarify that the `.fp` register won't report the
      availablity of position 0.  Clarify what an "external name", the third
      argument to the `fp` request, really is, and how its presence changes
      how the second argument is handled.  Document that GNU troff won't
      traverse directories to locate a font description file (see Savannah
      #61424).  Elaborate upon how this feature enables use of long font
      names in compatibility mode.  Say "escape sequence" instead of
      "escape".  Stop calling the two different interpretation modes of `ft`
      different "syntax forms"; this is false.  They are only _semantically_
      different (particularly since integers are valid *roff identifiers
      anyway).
    
    * man/groff.7.man (Request short reference) <ft>: As above, talk about
      "font selection" rather than "font changing".  Clarify that the
      argument can be a style, font name, or mounting position.  Parallelize
      summaries of the two invocation forms grammatically.
---
 doc/groff.texi  | 100 +++++++++++++++++++++++++++++---------------------------
 man/groff.7.man |  16 +++++----
 2 files changed, 60 insertions(+), 56 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 475cb57d..8e36060b 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9940,66 +9940,73 @@ A solution to this problem is to use a dummy font like 
the following:
 
 @c ---------------------------------------------------------------------
 
+@codequotebacktick on
+@codequoteundirected on
+
 @node Font Positions, Using Symbols, Font Families, Fonts and Symbols
 @subsection Font Positions
 @cindex font positions
 @cindex positions, font
 
-For compatibility with @acronym{AT&T} @code{troff}, GNU @code{troff}
-has the concept of font @dfn{positions} at which various fonts are
-@dfn{mounted}.
+To support typeface indirection through styles, and for compatibility
+with @acronym{AT&T} @code{troff}, GNU @code{troff} has the concept of
+font @dfn{positions}, at which various fonts are @dfn{mounted}.
 
 @DefreqList {fp, pos font [@Var{external-name}]}
 @DefregItemx {.f}
 @DefregListEndx {.fp}
 @cindex mounting font (@code{fp})
 @cindex font, mounting (@code{fp})
-Mount font @var{font} at position @var{pos} (which must be a
-non-negative integer).  This numeric index can then be referred to with
-font-changing commands.  When GNU @code{troff} starts, it uses font
-position@tie{}1 (which must exist; position@tie{}0 is unused at
-startup.@footnote{Usually.})
+Mount the font named @var{font} at position @var{pos}, a non-negative
+integer.  This numeric index can then be referred to with font selection
+instructions.  When the formatter starts up, it reads the output
+device's description to mount an initial set of faces, and selects font
+position@tie{}1.  Position@tie{}0 is unused by default.  Unless the
+@var{external-name} argument is given, the name @var{font} should be
+that of a font description file stored in a directory corresponding to
+the selected output device.@footnote{In other words, the font
+description file must be located in the same directory as the output
+device's @file{DESC} file; see @ref{Device and Font Description Files}.}
 
 @cindex font position register (@code{.f})
-The current font in use, as a font position, is available in the
-read-only register @samp{.f}.  This can be useful to save the current
-font for later recall.  It is associated with the environment
+The position of the currently selected font (or style) is available in
+the read-only register @samp{.f}.  It is associated with the environment
 (@pxref{Environments}).
 
+The value of @code{.f} can be copied to another register to save the
+current font or style for later recall.
+
 @Example
-.nr save-font \n[.f]
+.nr saved-font \n[.f]
 .ft B
-... text text text ...
-.ft \n[save-font]
+@r{@dots{}} text text text @r{@dots{}}
+.ft \n[saved-font]
 @endExample
 
 @cindex next free font position register (@code{.fp})
-The index of the next free font position is available in the read-only
-register @samp{.fp}.  This is useful when mounting a new font, like so:
-
-@Example
-.fp \n[.fp] NEATOFONT
-@endExample
-
+The index of the next (nonzero) free font position is available in the
+read-only register @samp{.fp}.
 @cindex @file{DESC} file, and font mounting
-Fonts not listed in the @file{DESC} file are automatically mounted on
-the next available font position when they are referenced.  If a font is
-to be mounted explicitly with the @code{fp} request on an unused font
-position, it should be mounted on the first unused font position, which
-can be found in the @code{.fp} register, although GNU @code{troff} does
-not enforce this strictly.
-
-The @code{fp} request has an optional third argument.  This argument
-gives the external name of the font, which is used for finding the font
-description file.  The second argument gives the internal name of the
-font, which is used to refer to the font in @code{gtroff} after it has
-been mounted.  If there is no third argument then the internal name is
-used as the external name.  This feature makes it possible to use fonts
-with long names in compatibility mode.
+Fonts not listed in the @file{DESC} file are automatically mounted at
+position @samp{\n[.fp]} when selected.  When mounting a font at a
+position explicitly with the @code{fp} request, this same practice
+should be followed, although GNU @code{troff} does not enforce this
+strictly.
+
+The optional third argument @var{external-name} is the name of a font
+description file in the operating environment.  GNU @code{troff} refuses
+to traverse directories to locate the font description.  The second
+argument @var{font} is then the internal name of the font, which
+identifies it to GNU @code{troff} once it has been mounted.  If there is
+no third argument, the font description is sought in the file system
+under its internal name.  This feature enables font names to be aliased,
+which can be necessary in compatibility mode since AT&T @code{troff}
+syntax affords no means of loading fonts with names longer than two
+characters, like @samp{TBI} or @samp{ZCMI}.  @xref{Compatibility Mode}.
 @endDefreq
 
-Both the @code{ft} request and the @code{\f} escape have alternative
-syntax forms to access font positions.
+The @code{ft} request and @code{\f} escape sequence accept mounting
+positions in the place of font or style names.
 
 @DefreqList {ft, nnn}
 @DefescItemx {\\f, , n, }
@@ -10013,14 +10020,12 @@ syntax forms to access font positions.
 @kindex styles
 @kindex family
 @pindex DESC
-Change the current font position to @var{nnn} (one-digit
-position@tie{}@var{n}, two-digit position @var{nn}), which must be a
-non-negative integer.
-
-If @var{nnn} is associated with a style (as set with the @code{sty}
-request or with the @code{styles} command in the @file{DESC} file), use
-it within the current font family (as set with the @code{fam} request,
-the @code{\F} escape, or the @code{family} command in the
+Select font position @var{nnn} (one-digit position@tie{}@var{n},
+two-digit position @var{nn}), which must be a non-negative integer.  If
+@var{nnn} is associated with a style (as set with the @code{sty} request
+or with the @code{styles} command in the @file{DESC} file), use it
+within the current font family (as set with the @code{fam} request, the
+@code{\F} escape sequence, or the @code{family} command in the
 @file{DESC} file).
 
 @Example
@@ -10034,14 +10039,11 @@ this is font 3
 this is font 1 again
 @endExample
 
-@xref{Changing Fonts}, for the standard syntax form.
+@xref{Changing Fonts}, for font selection by name.
 @endDefreq
 
 @c ---------------------------------------------------------------------
 
-@codequotebacktick on
-@codequoteundirected on
-
 @node Using Symbols, Character Classes, Font Positions, Fonts and Symbols
 @subsection Using Symbols
 @cindex using symbols
diff --git a/man/groff.7.man b/man/groff.7.man
index 3e0ca588..92e2d55e 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2230,16 +2230,16 @@ Flush output buffer.
 .REQ .fp "n font"
 Mount
 .I font
-on position
+at position
 .IR n .
 .
 .TPx
 .REQ .fp "n internal external"
-Mount font with long
+Mount font with description file
 .I external
-name to short
+under the name
 .I internal
-name on position
+at position
 .IR n .
 .
 .TPx
@@ -2269,15 +2269,17 @@ are special.
 .
 .TPx
 .REQ .ft
-Return to previous font.
-Same as
+Select previous style or font;
+same as
 .esc f[]
 or
 .esc fP .
 .
 .TPx
 .REQ .ft "font"
-Change to font name or number
+Select style,
+font name,
+or mounting position
 .IR font ;
 same as
 .esc[] f font