[groff] 26/50: [docs]: Update discussion of \[] escape sequence.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7d1195b33451b381265fe1736884fd6df68eb394
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed May 18 02:49:38 2022 -0500

    [docs]: Update discussion of \[] escape sequence.
    
    * Identify the first argument, the base glyph, as distinct.
    * Fix error: there are four escape sequences with bespoke syntax forms
      that are effectively one-character special character names, not one.
    * Synchronize groff_diff(7) with our Texinfo manual in this area.
---
 doc/groff.texi       | 28 +++++++++++++++-------------
 man/groff_diff.7.man | 14 +++++++++-----
 2 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index d1330d23..9894c01f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10309,21 +10309,23 @@ example, @code{^E_u0301} is invalid.
 
 @DefescList {\\, (, nm, }
 @DefescItem {\\, [, name, ]}
-@DefescListEnd {\\, [, component1 component2 @dots{}, ]}
+@DefescListEnd {\\, [, base-glyph combining-component @dots{}, ]}
 @esindex \(
 @esindex \[
-Insert a symbol @var{name} (two-character name @var{nm}) or a composite
-glyph with component glyphs @var{component1}, @var{component2},
-@enddots{}  There is no special syntax for one-character names---the
-natural form @samp{\@var{n}} would collide with other escape
-sequences.@footnote{A one-character symbol is not the same as an input
-character, i.e., the character @code{a} is not the same as @code{\[a]}.
-By default, @code{groff} defines only a single one-character symbol,
-@code{\[-]}; it is usually accessed as @code{\-}.  On the other hand,
-GNU @code{troff} has the special feature that @code{\[char@var{XXX}]} is
-the same as the input character with character code @var{XXX}.  For
-example, @code{\[char97]} is identical to the letter @code{a} if
-@acronym{ASCII} encoding is active.}
+Typeset a special character @var{name} (two-character name @var{nm}) or
+a composite glyph consisting of @var{base-glyph} overlaid with one or
+more @var{combining-component}s.  For example, @samp{\[A ho]} is a
+capital letter ``A'' with a ``hook accent'' (ogonek).
+
+There is no special syntax for one-character names---the analogous form
+@samp{\@var{n}} would collide with other escape sequences.  However, the
+four escape sequences @code{\'}, @code{\-}, @code{\_}, and @code{\`},
+are translated on input to the special character escape sequences
+@code{\[aa]}, @code{\[-]}, @code{\[ul]}, and @code{\[ga]}, respectively.
+
+A special character name of length one is not the same thing as an
+ordinary input character: that is, the character @code{a} is not the
+same as @code{\[a]}.
 
 If @var{name} is undefined, a warning in category @samp{char} is
 produced and the escape is ignored.  @xref{Debugging}, for information
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 8092daaa..cebed86d 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -990,16 +990,20 @@ prints\~\c
 .
 .TP
 .BI \[rs][ xxx ]
-Print the special character (glyph) called
+Typeset the special character (glyph)
 .IR xxx .
 .
 .TP
-.BI \[rs][ "comp1 comp2\~"\c
+.BI \[rs][ "base-glyph combining-component\~"\c
 \&.\|.\|.]
-Print composite glyph consisting of multiple components.
+Typeset a composite glyph consisting of
+.I base-glyph
+overlaid with one or more
+.IR combining-component s.
 .
-Example: \[oq]\[rs][A\~ho]\[cq] is capital letter A with ogonek which
-finally maps to glyph name \[oq]u0041_0328\[cq].
+For example,
+.RB \[lq] \[rs][A\~ho] \[rq]
+is a capital letter \[lq]A\[rq] with a \[lq]hook accent\[rq] (ogonek).
 .
 See
 .IR "Groff: The GNU Implementation of troff" ,