[groff] 14/17: [docs]: Revise discussion of `char` request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7371548d8161674760e58d47413683c6f4e5adc1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Jan 18 10:34:48 2024 -0600

    [docs]: Revise discussion of `char` request.
    
    ...and related requests.
    
    Drop mention of "glyphs" except as things provided by a device's fonts;
    that is, stop using it as a synonym for "special character".
    
    Further recast for clarity.
    
    In man pages, use metasyntactical variable "contents" rather than
    "anything", a rather animated handwave of traditional troff
    documentation.
    
    In groff_diff(7), mark "contents" arguments as optional to `char`,
    `fchar`, `fschar`, and `schar` requests.
---
 doc/groff.texi       | 30 +++++++++++--------
 man/groff.7.man      | 58 ++++++++++++++++++++++++++----------
 man/groff_diff.7.man | 84 +++++++++++++++++++++++++++++++++++-----------------
 3 files changed, 117 insertions(+), 55 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b42958da7..2c9ad5b95 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -11293,18 +11293,24 @@ on the right doesn't get examined.
 @cindex @code{\&}, and glyph definitions
 @cindex @code{\e}, and glyph definitions
 @cindex @code{hcode} request, and glyph definitions
-Define a new character or glyph@tie{}@var{c} to be @var{contents}, which
-can be empty.  More precisely, @code{char} defines a @code{groff} object
-(or redefines an existing one) that is accessed with the
-name@tie{}@var{c} on input, and produces @var{contents} on output.
-Every time glyph@tie{}@var{c} needs to be printed, @var{contents} is
-processed in a temporary environment and the result is wrapped up into a
-single object.  Compatibility mode is turned off and the escape
-character is set to@tie{}@code{\} while @var{contents} is processed.
-Any emboldening, constant spacing, or track kerning is applied to this
-object rather than to individual glyphs in @var{contents}.
-
-An object defined by these requests can be used just like a glyph
+Define an ordinary or special character@tie{}@var{c} as @var{contents}.
+If @var{contents} is absent, an existing character definition made with
+the same request is deleted.
+
+Defining (or redefining) a character@var{c} creates an object in the
+formatter that is recognized like any other ordinary special character
+on input, and produces @var{contents} on output.  Every time @var{c} is
+to be output, @var{contents} is processed in a temporary environment and
+the result encapsulated in a node.@footnote{@xref{Gtroff Internals}.}
+A leading neutral double quote in the final argument is stripped from
+it, allowing embedded leading spaces in @var{contents}, which is read in
+copy mode and continues to the end of the input line.  Further,
+compatibility mode is disabled and the escape character set to @code{\}
+while @var{contents} is interpreted.  Any emboldening, constant spacing,
+or track kerning is applied to this object rather than to individual
+glyphs in @var{contents}.
+
+A character defined by these requests can be used just like a glyph
 provided by the output device.  In particular, other characters can be
 translated to it with the @code{tr} or @code{trin} requests; it can be
 made the tab or leader fill character with the @code{tc} and @code{lc}
diff --git a/man/groff.7.man b/man/groff.7.man
index 502588a8c..4bb0c7bdc 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2768,7 +2768,7 @@ Remove definition of ordinary or special
 .RI character\~ c.
 .
 .TPx
-.REQ .char "c anything"
+.REQ .char "c contents"
 Define ordinary or special character
 .I c
 as
@@ -3157,12 +3157,20 @@ Remove definition of fallback
 .RI character\~ c.
 .
 .TPx
-.REQ .fchar "c anything"
-Define fallback character
-(or glyph)
-.I c
+.REQ .fchar "c contents"
+Define fallback
+.RI character\~ c
 as
-.IR anything .
+.IR contents .
+.
+As
+.request .char ,
+but while that request hides a glyph with the same name in the selected
+font,
+.B fchar
+definitions are used only if the font
+lacks a glyph for
+.IR c .
 .
 .TPx
 .REQ .fcolor
@@ -3210,13 +3218,23 @@ specific to
 .RI font\~ f.
 .
 .TPx
-.REQ .fschar "f c anything"
-Define fallback character (or glyph)
-.I c
-for font
-.I f
-as string
-.IR anything .
+.REQ .fschar "f c contents"
+Define fallback
+.RI character\~ c
+specific to
+.RI font\~ f
+as
+.IR contents .
+.
+As
+.request char ,
+but a character defined by
+.B fschar
+is located after the list of fonts declared with
+.B \%fspecial
+is searched and before those declared with the
+.RB \%\[lq] special \[rq]
+request.
 .
 .TPx
 .REQ .fspecial font
@@ -4129,11 +4147,19 @@ Remove definition of global fallback
 .RI character\~ c.
 .
 .TPx
-.REQ .schar "c anything"
-Define global fallback character (or glyph)\~\c
+.REQ .schar "c contents"
+Define global fallback character
 .I c
 as
-.IR anything .
+.IR contents .
+.
+As
+.request char ,
+but a character defined with
+.B schar
+is located after the list of fonts declared with the
+.request \%.special
+request and before any mounted special fonts.
 .
 .TPx
 .REQ .shc
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 9f5429e75..283f84d13 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1864,27 +1864,51 @@ character on the right doesn't get examined.
 .
 .
 .TP
-.BI .char\~ "c contents"
-Define the ordinary or special
+.BI .char\~ c\~\c
+.RI [ contents ]
+Define an ordinary or special
 .RI character\~ c
 as
-.IR contents ,
-which can be empty.
+.I contents.
 .
-More precisely,
-.B char
-defines a
-.I groff
-object
-(or redefines an existing one)
-that is accessed with the
-.RI name\~ c
-on input,
+If
+.I contents
+is absent,
+an existing character definition made with the same request is deleted.
+.
+.
+.IP
+Defining
+(or redefining)
+a
+.RI character\~ c
+creates an object in the formatter that is recognized like any other
+ordinary special character on input,
 and produces
 .I contents
 on output.
 .
-Compatibility mode is disabled and the escape character set
+Every time
+.I c
+is to be output,
+.I contents
+is processed in a temporary environment and the result encapsulated in a
+node.
+.
+(See section \[lq]Gtroff Internals\[rq] in
+.IR "Groff: The GNU Implementation of troff" ,
+the
+.I groff
+Texinfo manual.)
+.
+An initial neutral double quote in the final argument is stripped from
+it,
+allowing embedded leading spaces in
+.I contents,
+which is read in copy mode and continues to the end of the input line.
+.
+Further,
+compatibility mode is disabled and the escape character set
 .RB to\~ \[rs]
 while
 .I contents
@@ -1898,7 +1922,7 @@ not to each character in
 .
 .
 .IP
-An object defined by this request can be used just like a glyph
+A character defined by this request can be used just like a glyph
 provided by the output device.
 .
 In particular,
@@ -2384,15 +2408,17 @@ See
 .
 .
 .TP
-.BI .fchar\~ c\~contents
+.BI .fchar\~ c\~\c
+.RI [ contents ]
 Define fallback
 .RI character\~ c
 as
 .IR contents .
 .
-While
-.B char
-hides a glyph with the same name in the selected font,
+As
+.BR char ,
+but while that request hides a glyph with the same name in the selected
+font,
 .B fchar
 definitions are used only if the font
 lacks a glyph for
@@ -2413,7 +2439,8 @@ or the default if there is none.
 .
 .
 .TP
-.BI .fschar\~ f\~c\~contents
+.BI .fschar\~ f\~c\~\c
+.RI [ contents ]
 Define fallback special
 .RI character\~ c
 for font\~\c
@@ -2421,11 +2448,13 @@ for font\~\c
 as
 .IR contents .
 .
-A character defined by
+As
+.BR char ,
+but a character defined by
 .B fschar
 is located after the list of fonts declared with
 .B \%fspecial
-is searched but before those declared with the
+is searched and before those declared with the
 .RB \%\[lq] special \[rq]
 request.
 .
@@ -3328,19 +3357,20 @@ the request is ignored.
 .
 .
 .TP
-.BI .schar\~ c\~contents
+.BI .schar\~ c\~\c
+.RI [ contents ]
 Define global fallback character
 .I c
 as
 .IR contents .
 .
-See
-.BR char ;
-the distinction is that a character defined with
+As
+.BR char ,
+but a character defined with
 .B schar
 is located after the list of fonts declared with the
 .B \%special
-request but before any mounted special fonts.
+request and before any mounted special fonts.
 .
 .
 .TP