[groff] 04/07: groff_char(7): Fix style and clarity issues.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 4e101bce45f0d7f07856aad8fd62616743738297
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 5 13:26:50 2020 +1000

    groff_char(7): Fix style and clarity issues.
    
    * Further motivate the diversity of available special character escapes.
    
    * Add notes on \[ss] and its uppercase counterpart.  Thanks to
      Colin Watson, Ingo Schwarze, and Werner Lemberg for the discussion.
    
    * Rename subsection "Ligatures" to "Ligatures and digraphs", for greater
      accuracy.
    * Rename some glyphs therein:
      + [LlOo] slash -> L with stroke, etc. (Unicode)
      + [AaOo]+[Ee] combined -> {A,O}{E,} ligature (half-Unicode)
        (The Unicode character names of {OE,oe} are described as
        "ligatures"; their {AE,ae} counterparts are not.  I assume this is
        due to arguments in the standardization process, or Unicode's sworn
        policy to never correct errata in character names; see UTN #27.)
    
    * Clarify explanation of the .composite request's function.
    
    * Restrict suggested usage of \- for a minus sign to "running prose";
      in equations, \[mi] should be used.
    
    * Drop relic explanation of why SHY isn't in the Latin-1 table.
    
    * Reorder phrasing for clarity.
    * Fix spacing errors with two-font macros.
    * Fix comma splice.
    * Escape hyphens in code example.
---
 man/groff_char.7.man | 120 ++++++++++++++++++++++++++++++---------------------
 1 file changed, 70 insertions(+), 50 deletions(-)

diff --git a/man/groff_char.7.man b/man/groff_char.7.man
index c4fa494..1826ec2 100644
--- a/man/groff_char.7.man
+++ b/man/groff_char.7.man
@@ -386,7 +386,7 @@ use the character in input without an escape
 to mean a hyphen,
 as in the phrase \[lq]long-term\[rq].
 .
-For a minus sign or a Unix command-line option dash,
+For a minus sign in running prose or a Unix command-line option dash,
 use
 .B \[rs]\-
 (or
@@ -406,8 +406,8 @@ The special character escape for the apostrophe as a 
neutral single
 quote is typically needed only in technical content;
 typing words like \[lq]can't\[rq] and \[lq]Anne's\[rq] in a natural way
 will render correctly,
-because an apostrophe is typeset either as a closing single quotation
-mark or as a neutral single quote in ordinary prose,
+because in ordinary prose an apostrophe is typeset either as a closing
+single quotation mark or as a neutral single quote,
 depending on the capabilities of the output device.
 .
 By contrast,
@@ -505,8 +505,7 @@ SHY
 encodes the soft hyphen character.
 .
 .I groff
-never uses this character for output
-(thus it is omitted in the table below);
+never uses this character for output;
 on input it is mapped to the hyphenation control escape,
 .BR \[rs]% .
 .
@@ -585,6 +584,15 @@ Glyphs that lack a character code in the basic Latin 
repertoire to
 directly represent them are entered by one of several special character
 escape forms.
 .
+Such glyphs can be simple or composite,
+and accessed either by name or numerically by code point.
+.
+Code points and combining properties are determined by character
+encoding standards,
+whereas glyph names originated in AT&T
+.I troff \" AT&T
+special character escapes.
+.
 Glyph names are not limited to alphanumeric characters;
 any of the printable characters from the Unicode basic Latin repertoire
 may be used.
@@ -596,7 +604,7 @@ is a special character escape for the glyph with the 
two-character name
 .IR gl .
 .
 This is the syntax form supported by AT&T
-.IR troff.
+.IR troff .
 .
 The acute accent,
 .BR \[rs](aa ,
@@ -656,20 +664,25 @@ can be expressed as
 See subsection \[lq]Accents\[rq] below for a table of combining glyph
 names.
 .
+.
+.P
+Unicode encodes far more characters than
+.I groff
+has glyph names for;
+special character escape forms based on numerical code points enable
+access to any of them.
+.
 Frequently-used glyphs or glyph combinations can be stored in strings,
 and new glyph names can be created with the
 .B .char
-request;
+request,
+enabling the user to devise
+.I ad hoc
+names for them;
 see
 .IR groff (@MAN7EXT@).
 .
 .
-.P
-.I groff
-also features special character escapes based on numerical code points
-rather than glyph names.
-.
-.
 .TP
 .BI \[rs][u nnnn\c
 .RI [ n\c
@@ -677,11 +690,6 @@ rather than glyph names.
 .B ]
 is a Unicode numeric special character escape.
 .
-Unicode encodes far more characters than
-.I groff
-can ever hope to devise glyph names for,
-and doing so would merely give users yet another list to remember.
-.
 With this form,
 any Unicode point can be indicated using four to six hexadecimal digits.
 .
@@ -716,8 +724,7 @@ separating each component.
 .
 Thus,
 .B \[rs][u0065_0301]
-produces
-.RB \[lq] \[u0065_0301] \[rq].
+produces \[lq]\[u0065_0301]\[rq].
 .
 .
 .TP
@@ -890,6 +897,18 @@ _
 .SS "Supplementary Latin letters"
 .\" ====================================================================
 .
+Historically,
+.B \[rs][ss]
+could be considered a ligature of \[lq]sz\[rq].
+.
+An uppercase form is available as
+.BR \[rs][u1e9e] ,
+but in the German language it is of specialized use;
+\[ss] does
+.I not
+normally uppercase-transform to it,
+but rather to \[lq]SS\[rq].
+.
 \[lq]Lowercase f with hook\[rq] is also used as a function symbol;
 see subsection \[lq]Mathematical symbols\[rq] below.
 .
@@ -909,7 +928,7 @@ _
 .
 .
 .\" ====================================================================
-.SS Ligatures
+.SS "Ligatures and digraphs"
 .\" ====================================================================
 .
 .TS
@@ -921,16 +940,16 @@ _
 \[fl]  \e[fl]  fl      u0066_006C      fl ligature +
 \[Fi]  \e[Fi]  ffi     u0066_0066_0069 ffi ligature +
 \[Fl]  \e[Fl]  ffl     u0066_0066_006C ffl ligature +
-\[/L]  \e[/L]  Lslash  u0141   L slash
-\[/l]  \e[/l]  lslash  u0142   l slash
-\[/O]  \e[/O]  Oslash  u00D8   O slash
-\[/o]  \e[/o]  oslash  u00F8   o slash
-\[AE]  \e[AE]  AE      u00C6   A+E combined
-\[ae]  \e[ae]  ae      u00E6   a+e combined
-\[OE]  \e[OE]  OE      u0152   O+E combined
-\[oe]  \e[oe]  oe      u0153   o+e combined
-\[IJ]  \e[IJ]  IJ      u0132   I+J combined
-\[ij]  \e[ij]  ij      u0133   i+j combined
+\[AE]  \e[AE]  AE      u00C6   AE ligature
+\[ae]  \e[ae]  ae      u00E6   ae ligature
+\[OE]  \e[OE]  OE      u0152   OE ligature
+\[oe]  \e[oe]  oe      u0153   oe ligature
+\[IJ]  \e[IJ]  IJ      u0132   IJ digraph
+\[ij]  \e[ij]  ij      u0133   ij digraph
+\[/L]  \e[/L]  Lslash  u0141   L with stroke
+\[/l]  \e[/l]  lslash  u0142   l with stroke
+\[/O]  \e[/O]  Oslash  u00D8   O with stroke
+\[/o]  \e[/o]  oslash  u00F8   o with stroke
 .TE
 .
 .
@@ -1022,7 +1041,8 @@ _
 .
 The
 .B .composite
-request is used to map most of the accents to non-spacing glyph names;
+request is used to map the accents to code points with non-spacing
+semantics;
 the values given in parentheses are their spacing counterparts.
 .
 .TS
@@ -1096,7 +1116,7 @@ they are rendered the same way regardless of font.
 On terminals,
 they are
 .I not
-font-invariant,
+font-invariant;
 .I groff
 maps them rather arbitrarily to U+23AA
 (\[lq]curly bracket extension\[rq]).
@@ -1127,25 +1147,25 @@ macro:
 \&.\e" The first argument is placed at the top.
 \&.\e" The pile is returned in string \[aq]pile\[aq].
 \&.eo
-\&.de pile-make
-\&.  nr pile-wd 0
-\&.  nr pile-ht 0
-\&.  ds pile-args
+\&.de pile\-make
+\&.  nr pile\-wd 0
+\&.  nr pile\-ht 0
+\&.  ds pile\-args
 \&.
-\&.  nr pile-# \en[.$]
-\&.  while \en[pile-#] \e{\e
-\&.    nr pile-wd (\en[pile-wd] >? \ew\[aq]\e$[\en[pile-#]]\[aq])
-\&.    nr pile-ht +(\en[rst] - \en[rsb])
-\&.    as pile-args \ev\[aq]\en[rsb]u\[aq]\e"
-\&.    as pile-args \eZ\[aq]\e$[\en[pile-#]]\[aq]\e"
-\&.    as pile-args \ev\[aq]-\en[rst]u\[aq]\e"
-\&.    nr pile-# -1
+\&.  nr pile\-# \en[.$]
+\&.  while \en[pile\-#] \e{\e
+\&.    nr pile\-wd (\en[pile\-wd] >? \ew\[aq]\e$[\en[pile\-#]]\[aq])
+\&.    nr pile\-ht +(\en[rst] \- \en[rsb])
+\&.    as pile\-args \ev\[aq]\en[rsb]u\[aq]\e"
+\&.    as pile\-args \eZ\[aq]\e$[\en[pile\-#]]\[aq]\e"
+\&.    as pile\-args \ev\[aq]\-\en[rst]u\[aq]\e"
+\&.    nr pile\-# \-1
 \&.  \e}
 \&.
-\&.  ds pile \ev\[aq](-0.5m + (\en[pile-ht]u / 2u))\[aq]\e"
-\&.  as pile \e*[pile-args]\e"
-\&.  as pile \ev\[aq]((\en[pile-ht]u / 2u) + 0.5m)\[aq]\e"
-\&.  as pile \eh\[aq]\en[pile-wd]u\[aq]\e"
+\&.  ds pile \ev\[aq](\-0.5m + (\en[pile\-ht]u / 2u))\[aq]\e"
+\&.  as pile \e*[pile\-args]\e"
+\&.  as pile \ev\[aq]((\en[pile\-ht]u / 2u) + 0.5m)\[aq]\e"
+\&.  as pile \eh\[aq]\en[pile\-wd]u\[aq]\e"
 \&..
 \&.ec
 .EE
@@ -1165,7 +1185,7 @@ which provide the floor operator.
 .
 Some output postprocessors,
 such as
-.IR grodvi (@MAN1EXT@) ,
+.IR grodvi (@MAN1EXT@),
 don't unify such glyphs.
 .
 For this reason,