[groff] 02/25: [docs]: Revise `{f,}special` request descriptions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 99122da8b753a4a30e81f5e89a3d357f40b563f3
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Nov 3 10:48:35 2023 -0500

    [docs]: Revise `{f,}special` request descriptions.
    
    * doc/groff.texi (Special fonts) <fspecial, special>:
    * man/groff_diff.7.man (New requests) <fspecial, special>: Recast
      explanations of requests.
    
    * man/groff_diff.7.man (New requests) <fspecial, special>: Properly
      mark mandatory and required arguments in synopses.
---
 doc/groff.texi       | 38 ++++++++++++++++++--------------------
 man/groff_diff.7.man | 35 +++++++++++++++++------------------
 2 files changed, 35 insertions(+), 38 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 0ae293260..0748a93d8 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -11438,34 +11438,32 @@ See the @code{cflags} request in @ref{Using Symbols}, 
for more details.
 @cindex special fonts
 @cindex fonts, special
 
-Special fonts are those that @command{gtroff} searches when it cannot
-find the requested glyph in the current font.  The Symbol font is
-usually a special font.
+Special fonts are those that GNU @command{troff} searches when it cannot
+find a requested glyph in the selected font.  Typically, special fonts
+contain unstyled glyphs and are declared as such in their description
+files; see @ref{Font Description File Format}.  The ``Symbol'' and
+``Zapf Dingbats'' fonts of the PostScript and PDF standards are
+examples.  Ordinarily, only typesetters have special fonts.
 
-@command{gtroff} provides the following two requests to add more special
-fonts.  @xref{Using Symbols}, for a detailed description of the glyph
-searching mechanism in @command{gtroff}.
-
-Usually, only non-TTY devices have special fonts.
+GNU @command{troff}'s @code{special} and @code{fspecial} requests permit
+a document to supplement the set of fonts searched for glyphs.
+@xref{Using Symbols}.
 
 @DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
 @DefreqListEndx {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
 @kindex fonts
 @pindex DESC
-Use the @code{special} request to define special fonts.  Initially, this
-list is empty.
-
-Use the @code{fspecial} request to designate special fonts only when
-font@tie{}@var{f} is active.  Initially, this list is empty.
-
-Previous calls to @code{special} or @code{fspecial} are overwritten;
-without arguments, the particular list of special fonts is set to empty.
-Special fonts are searched in the order they appear as arguments.
+@code{special} designates each font @var{s}n as special.  Initially,
+this list is empty.
 
-All fonts that appear in a call to @code{special} or @code{fspecial}
-are loaded.
+@code{fspecial} designates each font as special only when
+font@tie{}@var{f} is selected.  Initially, this list is empty.
 
-@xref{Using Symbols}, for the exact search order of glyphs.
+Invoking @code{special} or @code{fspecial} again overwrites the previous
+list; without arguments, the relevant list is made empty.  Special fonts
+are searched in the order they appear as arguments.  Each font @var{s}n
+is mounted, and not automatically unmounted if superseded by a
+subsequent @code{special} or @code{fspecial} request.
 @endDefreq
 
 @c ---------------------------------------------------------------------
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 07854212d..5191c350e 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2358,32 +2358,30 @@ is searched but before those declared with the
 request.
 .
 .TP
-.BI .fspecial\~ "f s1 s2\~"\c
-\&.\|.\|.
+.BI .fspecial\~ f\~\c
+.RI [ s\~ .\|.\|.]
 When
 .RI font\~ f
 is selected,
-fonts
-.IR s1 ,
-.IR s2 ,
-\&.\|.\|.\&
-are treated as special;
+treat each font
+.I s
+as special;
 that is,
-they are searched for glyphs not found in
+search it for any glyph not found in
 .IR f .
 .
-Any fonts specified in the
+Fonts specified by the
 .RB \%\[lq] special \[rq]
-request are searched after
-.IR s1 ,
-.IR s2 ,
-and so on.
+request are searched after those
+listed in the
+.B fspecial
+request.
 .
 Without
 .I s
 arguments,
 .B \%fspecial
-clears the list of fonts treated as special when
+empties the list of fonts treated as special when
 .I f
 is selected.
 .
@@ -3287,15 +3285,16 @@ does not exist.
 .
 .
 .TP
-.BI .special\~ f\~\c
-\&.\|.\|.
+.BR .special\~ [\c
+.IR s\~ .\|.\|.]
 Declare each font
-.I f
+.I s
 as special,
 searching it for glyphs not found in the selected font.
 .
 Without arguments,
-this list of special fonts is made empty.
+.RB \[lq] \%special \[dq]
+empties this list of special fonts.
 .
 .
 .TP