[groff] 13/28: groff_char(7): Update table annotations.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ad6ed7b988320885d56b9825a9aab8703d3da10e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Aug 31 21:29:45 2020 +1000

    groff_char(7): Update table annotations.
    
    * Add cross-references between table subsections.
    * Remove paragraph macros before tables.
    * Align markup style of groff escapes with existing practice.
    * Use special character escapes for apostrophes in code example.
    * Move annotations so that they always precede the table they document.
    * Note in comments which tables overrun 78n in nroff.
---
 man/groff_char.7.man | 140 +++++++++++++++++++++++++++++++++------------------
 1 file changed, 91 insertions(+), 49 deletions(-)

diff --git a/man/groff_char.7.man b/man/groff_char.7.man
index 2ff8544..14b5dbe 100644
--- a/man/groff_char.7.man
+++ b/man/groff_char.7.man
@@ -829,8 +829,30 @@ or
 .SS "Basic Latin"
 .\" ====================================================================
 .
-.\" TODO: describe
+Apart from basic Latin characters with special mappings,
+described in subsection \[lq]Fundamental character set\[rq] above,
+a few others in that range have special character glyph names.
 .
+.\" XXX: I surmise that...
+These were defined for ease of input on non-U.S.\& keyboards lacking
+keycaps for them,
+or for symmetry with other special character glyph names serving a
+similar purpose.
+.
+.
+.P
+Note the overloading of the vertical bar;
+the
+.B \[rs][ba]
+and
+.B \[rs][or]
+escapes may render differently.
+.
+See subsection \[lq]Mathematical symbols\[rq] below for special variants
+of the plus,
+minus,
+and equals
+signs normally drawn from this range.
 .
 .TS
 l l l l lx.
@@ -860,6 +882,9 @@ _
 .SS "Supplementary Latin letters"
 .\" ====================================================================
 .
+\[lq]Lowercase f with hook\[rq] is also used as a function symbol;
+see subsection \[lq]Mathematical symbols\[rq] below.
+.
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes
@@ -905,6 +930,10 @@ _
 .SS "Accented characters"
 .\" ====================================================================
 .
+All of these glyphs can be composed using combining glyph names as
+described in subsection \[lq]Special character escape forms\[rq] above;
+the names below can be thought of short aliases for convenience.
+.
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes
@@ -981,7 +1010,6 @@ The
 request is used to map most of the accents to non-spacing glyph names;
 the values given in parentheses are their spacing counterparts.
 .
-.P
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes
@@ -1054,14 +1082,16 @@ brackets,
 braces,
 and
 parentheses:
-.RB \[lq] \[rs](bv \[rq].
+.BR \[rs](bv .
+.
+We map it rather arbitrarily to U+23AA
+(\[lq]curly bracket extension\[rq]).
 .
-We map it rather arbitrarily to u23AA.
 .
 .P
 Note that not all devices contain extensible bracket pieces which can
 be piled up with
-.RB \[lq] \[rs]b \[rq]
+.B \[rs]b
 due to the restrictions of the escape's piling algorithm.
 .
 A general solution to build brackets out of pieces is the following
@@ -1070,10 +1100,9 @@ macro:
 .
 .RS
 .EX
-\&.\e" Make a pile centered vertically 0.5em
-\&.\e" above the baseline.
+\&.\e" Make a pile centered vertically 0.5em above the baseline.
 \&.\e" The first argument is placed at the top.
-\&.\e" The pile is returned in string 'pile'
+\&.\e" The pile is returned in string \[aq]pile\[aq].
 \&.eo
 \&.de pile-make
 \&.  nr pile-wd 0
@@ -1082,18 +1111,18 @@ macro:
 \&.
 \&.  nr pile-# \en[.$]
 \&.  while \en[pile-#] \e{\e
-\&.    nr pile-wd (\en[pile-wd] >? \ew'\e$[\en[pile-#]]')
+\&.    nr pile-wd (\en[pile-wd] >? \ew\[aq]\e$[\en[pile-#]]\[aq])
 \&.    nr pile-ht +(\en[rst] - \en[rsb])
-\&.    as pile-args \ev'\en[rsb]u'\e"
-\&.    as pile-args \eZ'\e$[\en[pile-#]]'\e"
-\&.    as pile-args \ev'-\en[rst]u'\e"
+\&.    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'(-0.5m + (\en[pile-ht]u / 2u))'\e"
+\&.  ds pile \ev\[aq](-0.5m + (\en[pile-ht]u / 2u))\[aq]\e"
 \&.  as pile \e*[pile-args]\e"
-\&.  as pile \ev'((\en[pile-ht]u / 2u) + 0.5m)'\e"
-\&.  as pile \eh'\en[pile-wd]u'\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
@@ -1106,23 +1135,24 @@ bracket pieces in AT&T
 .I troff
 can be used for other mathematical symbols as well,
 for example
-\[oq]lf\[cq]
+.B \[rs](lf
 and
-\[oq]rf\[cq]
-which provide the \[oq]floor\[cq] operator.
+.B \[rs](rf
+which provide the floor operator.
 .
-Some output devices,
+Some output postprocessors,
 such as
 .IR grodvi (@MAN1EXT@) ,
 don't unify such glyphs.
 .
 For this reason,
 the four glyphs
-\[oq]lf\[cq],
-\[oq]rf\[cq],
-\[oq]lc\[cq],
+.BR \[rs][lf] ,
+.BR \[rs][rf] ,
+.BR \[rs][lc] ,
 and
-\[oq]rc\[cq] are not unified with similar-looking bracket pieces.
+.BR \[rs][rc] ,
+are not unified with similar-looking bracket pieces.
 .
 In
 .IR groff ,
@@ -1130,7 +1160,7 @@ only glyphs with long names are guaranteed to pile up 
correctly for all
 devices\[em]provided those glyphs exist.
 .
 .
-.P
+.\" XXX: This table overruns 78n on nroff devices.
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes
@@ -1178,6 +1208,7 @@ _
 .SS Arrows
 .\" ====================================================================
 .
+.\" XXX: This table overruns 78n on nroff devices.
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes
@@ -1203,31 +1234,41 @@ _
 .\" ====================================================================
 .
 The font-invariant glyphs
-\[lq]br\[rq],
-\[lq]ul\[rq],
+.BR \[rs][br] ,
+.BR \[rs][ul] ,
 and
-\[lq]rn\[rq]
+.B \[rs][rn]
 form corners when adjacent;
 they can be used to build boxes.
 .
-Note that both the AGL and the Unicode-derived names of these
-three glyphs are rough approximations.
+Note that both the AGL and the Unicode-derived names of these three
+glyphs are rough approximations.
 .
 .
 .P
-\[lq]rn\[rq] also serves in AT&T
+.B \[rs][rn]
+also serves in AT&T
 .I troff
 as the horizontal extension of the radical
 (square root)
 sign.
 .
-.
-.P
-The baseline rule \[lq]ru\[rq] is a font-invariant glyph,
-namely a rule of length 0.5m.
+The baseline rule
+.B \[rs][ru]
+is a font-invariant glyph,
+namely a rule of one-half em.
 .
 .
 .P
+Use
+.B \[rs][radicalex]
+(see subsection \[lq]Mathematical symbols\[rq] below),
+not
+.BR \[rs][overline] ,
+for continuation of radical signs
+(e.g.,
+square roots).
+.
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes
@@ -1244,14 +1285,6 @@ _
 .TE
 .
 .
-.P
-Use \[lq]\e[radicalex]\[rq]
-(see subsection \[lq]Mathematical symbols\[rq] below),
-not \[lq]\e[overline]\[rq],
-for continuation of radical signs
-(e.g.,
-square roots).
-.
 .
 .\" ====================================================================
 .SS "Text markers"
@@ -1281,6 +1314,9 @@ _
 .SS "Legal symbols"
 .\" ====================================================================
 .
+The Bell Systems logo is not supported in
+.IR groff .
+.
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes
@@ -1291,10 +1327,6 @@ _
 \[bs]  \e[bs]  ---     ---     Bell Systems logo +
 .TE
 .
-.P
-The Bell Systems logo is not supported in
-.IR groff .
-.
 .
 .\" ====================================================================
 .SS "Currency symbols"
@@ -1361,10 +1393,20 @@ _
 .SS "Mathematical symbols"
 .\" ====================================================================
 .
-Note the two variants of the
+.B \[rs][Fn]
+also appears in see subsection \[lq]Supplementary Latin letters\[rq]
+above.
+.
+Note the two varieties of the
 plus-minus,
 multiplication,
-and division signs.
+and division signs;
+.BR \[rs][+\-] ,
+.BR \[rs][mu] ,
+and
+.BR \[rs][di]
+are normally drawn from the special font,
+but have regular (\[lq]text\[rq]) font variants.
 .
 Also be aware of three glyphs available in special font variants that
 are normally drawn from regular fonts:
@@ -1375,6 +1417,7 @@ and equals signs.
 Whether these variants differ in appearance or spacing will depend on
 the device and font selected.
 .
+.\" XXX: This table overruns 78n on nroff devices.
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes
@@ -1477,7 +1520,6 @@ the uppercase letters have upright shape,
 and the lowercase ones are slanted.
 .
 .
-.P
 .TS
 l l l l lx.
 Output Input   AGL     Unicode Notes