gbranden pushed a commit to branch master
in repository groff.
commit 0750ebf833a7f14f200d9c366784795e40167a01
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Dec 6 03:50:30 2025 -0600
[doc,man]: Recast discussion of {f,}special reqs.
* Attempt to clarify.
* Use more idiomatic synopsis syntax for request invocations.
* Better parallelize wording between our Texinfo manual and man pages.
* Sync input line breaks between our Texinfo manual and man pages.
* Protect literals from hyphenation.
---
doc/groff.texi.in | 55 ++++++++++++++++++++++++++++--------
man/groff.7.man | 46 +++++++++++++++++++-----------
man/groff_diff.7.man | 80 ++++++++++++++++++++++++++++++++--------------------
3 files changed, 123 insertions(+), 58 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 73d446a12..84b459585 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -12795,25 +12795,58 @@ when using the
@code{ps}
device.
-@DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
-@DefreqListEndx {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
+@DefreqList {special, [@Var{s} @dots{}]}
+@DefreqListEndx {fspecial, f [@Var{s} @dots{}]}
@kindex fonts
@pindex DESC
-@code{special} designates each font @var{s}n as special.
+@code{special}
+declares each font
+@var{s}
+as special,
+irrespective of its description file,
+populating a list that
+GNU
+@command{troff} @c GNU
+searches,
+in order,
+to find the glyph demanded.
+GNU
+@command{troff} @c GNU
+mounts each font
+@var{s}.
+Invoking
+@code{special}
+without arguments empties the list.
+A font is not automatically unmounted
+if a subsequent
+@code{special}
+request removes it from the list.
Initially,
-this list is empty.
+the list is empty.
-@code{fspecial} designates each font as special only when
+@code{fspecial}
+is similar;
+it designates each font
+@var{s}
+as special only when
font@tie{}@var{f} is selected.
Initially,
-this list is empty for all fonts.
+a font
+@var{f}'s
+list of associated special fonts is empty for all
+@var{f}.
@c TODO: Add requests `pspecial`, `pfspecial`?
-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.
+Invoking
+@code{special}
+or
+@code{fspecial}
+again overwrites the previous list;
+if you invoke them
+without arguments,
+GNU
+@command{troff} @c GNU
+deletes the corresponding list.
@endDefreq
@c ---------------------------------------------------------------------
diff --git a/man/groff.7.man b/man/groff.7.man
index 665a70a44..bcf3fe2cb 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3626,30 +3626,27 @@ are searched and before those named as arguments to the
request.
.
.TPx
-.REQ .fspecial font
+.REQ .fspecial f
Empty the list of fonts treated as special when
-.I font
+.I f
is selected.
.
.TPx
-.REQ .fspecial "fnt sfnt \fR\&.\|.\|.\&\fP"
-When
-.RI font\~ fnt
-is selected,
-treat each font
-.I sfnt
-as
-.I special;
-that is,
-search it for any glyph not found in
-.IR f .
+.REQ .fspecial "f s \fR\&.\|.\|.\&\fP"
+Declare each font
+.I s
+as special only when
+.RB font\~ f
+is selected.
.
+.\" TODO: Move this sentence to a new (sub)section describing the glyph
+.\" resolution procedure.
GNU
.I troff \" GNU
searches fonts specified as arguments to the
.RB \%\[lq] special \[rq]
request after those given as arguments to the
-.B fspecial
+.B \%fspecial
request.
.
.TPx
@@ -4915,9 +4912,24 @@ when given arguments.
.REQ .special "s \fR\&.\|.\|.\&\fP"
Declare each font
.I s
-as
-.I special,
-searching it for glyphs not found in the selected font.
+as special,
+irrespective of its description file,
+populating a list that
+GNU
+.I troff \" GNU
+searches,
+in order,
+to find the glyph demanded.
+.
+.\" TODO: Move this sentence to a new (sub)section describing the glyph
+.\" resolution procedure.
+GNU
+.I troff \" GNU
+searches fonts specified as arguments to the
+.RB \%\[lq] special \[rq]
+request after those given as arguments to the
+.B \%fspecial
+request.
.
.TPx
.REQ .spreadwarn
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index dc8e75994..a9c32c034 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3050,37 +3050,32 @@ are searched and before those named as arguments to the
request.
.
.TP
-.BI .fspecial\~ fnt\~\c
-.RI [ sfnt\~ .\|.\|.]
-When
-.RI font\~ fnt
-is selected,
-treat each font
-.I sfnt
-as
-.I special;
-that is,
-search it for any glyph not found in
-.IR f .
+.BI .fspecial\~ f\~\c
+.RI [ s\~ .\|.\|.]
+Declare each font
+.I s
+as special only when
+.RB font\~ f
+is selected.
+.
+Initially,
+a font
+.IR f 's
+list of associated special fonts is empty for all
+.I f.
.
+.\" TODO: Move this sentence to a new (sub)section describing the glyph
+.\" resolution procedure.
GNU
.I troff \" GNU
searches fonts specified as arguments to the
.RB \%\[lq] special \[rq]
request after those given as arguments to the
-.B fspecial
-request.
-.
-Without
-.I sfnt
-arguments,
.B \%fspecial
-empties the list of fonts treated as special when
-.RI font\~ fnt
-is selected.
+request.
.
-Initially,
-this list is empty for all fonts.
+See
+.RB \%\[lq] special \[rq].
.
.
.TP
@@ -4229,16 +4224,41 @@ does not exist.
.IR s\~ .\|.\|.]
Declare each font
.I s
-as
-.I special,
-searching it for glyphs not found in the selected font.
+as special,
+irrespective of its description file,
+populating a list that
+GNU
+.I troff \" GNU
+searches,
+in order,
+to find the glyph demanded.
+.
+GNU
+.I troff \" GNU
+mounts each font
+.I s.
.
-Without arguments,
-.RB \[lq] \%special \[rq]
-empties this list of special fonts.
+Invoking
+.B \%special
+without arguments empties the list.
+.
+A font is not automatically unmounted
+if a subsequent
+.B \%special
+request removes it from the list.
.
Initially,
-this list is empty.
+the list is empty.
+.
+.\" TODO: Move this sentence to a new section description the glyph
+.\" resolution procedure.
+GNU
+.I troff \" GNU
+searches fonts specified as arguments to the
+.RB \%\[lq] special \[rq]
+request after those given as arguments to the
+.B \%fspecial
+request.
.
.
.TP
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
