[bug #59031] the \[Im] and \[Re] escapes are inadequately described

[G. Branden Robinson]

Follow-up Comment #8, bug#59031 (group groff):


commit 84639dd9012ae3efce2c38d9154e0df35df4d260
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Aug 27 21:38:17 2020 +1000

    groff_char(7): Revise glyph descriptions.
    
    Glyph descriptions have a few goals and anti-goals.  Goals:
    * Describe the glyph tersely but in an accessible way.
    * Expose the meanings of mnemonic groff (or AT&T) glyph names.
    * Use terms familiar from widespread character encoding standards.
    * Fit into the space available in a rendered man page.
    
    Anti-goals:
    * Simply copy descriptions from Unicode charts.  People can go to
      Unicode if they need that information.  (Or use the "unicode" command
      available in GNU/Linux distributions.)
    * Simply copy descriptions from names in the Adobe Glyph List (AGL).
    
    That is, descriptions from Unicode and the AGL are both useful, but our
    purpose is not to take one or the other as a sole source of truth.
    
    Changes:
    
    * Add subsection "Basic Latin" to cover glyph names for the ASCII range.
      Move \[ha] and \[ti] from "Accents" table hither, because that table
      is strictly for combining (non-spacing) accent marks.  The rest appear
      both here and in the themed tables; ASCII always was a potpourri.
    
    * Add glyph descriptions to "Notes" column where there were none.  It
      seems that the Adobe Glyph List names were being used as descriptions,
      but I've proposed dropping that column ("PostScript") from this page
      and not met much resistance to the suggestion.  Yet.
    
    * Remove localized references in glyph descriptions.  Except ancient
      Greek, of course.  ;-)  Drop terms like "Polish", "Dutch", "umlaut"
      ("dieresis" is the English term for that diacritical mark, and is
      already present), "Hungarian", "Japanese", "British", "Scandinavian",
      and "Spanish".
    
    * Replace characterizations of glyph color from their descriptions;
      change "white square" to simply "square", and replace "black" in card
      suit descriptions with "solid", since they are filled.
    
    * Drop term "overbar" in favor of "macron".
    
    * Drop "small circle" from description of ring above accent \[ao].
    
    * Drop some lengthy lists of glyph applications of \[ha] and \[ti].
      There was an error anyway--a caret is not the "power sign in
      mathematics"; that's a convention of some programming languages.
    
    * "single {left,right}-pointing angle quotation mark" is garrulous.  The
      glyphs thus described also happen to be half-guillemets, if you will.
      They are also known as chevrons.  Thus, innovate and reduce the column
      count by re-describing these as left and right "single chevron"s, and
      "double chevron" in the left and right guillemet descriptions.  This
      is _still_ cheaper in columns than the Unicode names.  This is
      admittedly my innovation, thus perhaps controversial.  If we lose
      the AGL column there should be room to bring back "guillemet".
    
    * Drop references to ASCII in glyph descriptions.  The spectre of ASCII
      is dealt with in prose earlier in the page.
    
    * Describe \[dq] and \[aq] as "neutral".
    * Update \[aq] description to mention both apostrophe and neutral single
      quote.
    
    * Drop "curly" from "curly brace".  In contrast to "brackets" (square
      and angle), there is no other kind of brace in these tables from which
      disambiguation is required.
    
    * Recast "in both directions" as "bidirectional" in arrow descriptions.
    
    * Add "low line" to \[ul].
    
    * Add "solidus" to \[sl], mainly because there is a "reverse solidus".
    
    * Drop "symbol" from em-dash, en-dash, and hyphen.
    
    * Drop "sign" from "double dagger".  It's not idiomatic and "dagger"
      lacked it.
    
    * Collate the double dagger after the (single) dagger.
    
    * Drop "pound key" from \[lz] (lozenge).  This is either an outright
      error or an esoteric reference to the first generation of commercial
      touch-tone telephone keypads introduced by Western Electric to the
      U.S. market in 1963.  Originally, the two non-digit keycaps bore
      outlines of a five-pointed star and a diamond or lozenge.  Eventually,
      and as part of the standardization of ASCII, in which Bell Telephone
      Laboratories participated, these keycaps were replaced with the
      asterisk and...the other thing, which has several correct names[1].
      "Pound" is already overloaded in typography (cf. \[Po], \[sh]), but
      never used to mean a lozenge, and documenting it as doing so makes a
      terrible situation worse.
    
    * Add "sign" to "at", "dollar", "cent", "yen", "pound", "degree" ...
    
    * Rename "end of paragraph marker" to "pilcrow sign".
    
    * Drop "tick" from \[OK].
    
    * Add descriptions of \[co], \[rg], and \[tm]; straight from Unicode
      this time.
    
    * Rename "official Euro symbol" to "Euro sign" (Unicode), and
      "font-specific Euro glyph variant" to "variant Euro sign", as is done
      for glyphs which sometimes have separate versions in ordinary and
      special fonts.
    
    * Add "indicator" to "{feminine,masculine} ordinal".  Glyph names should
      be grammatical nouns (or noun phrases), except for mathematical
      (including logical) operators.  Also, these are the Unicode names.
    
    * Rename "period centered" to "centered period", for internal
      consistency with Latin-1 supplement table.  I think the connection
      between this word order and \[pc] is still discernible.
    
    * Rename many mathematical glyph names.
      + Spell out numbers.
      + Say "special variant of" instead of "in special font", so that the
        parallelism with "text variant of" is clear.
      + Rename "multiply sign" to "multiplication sign" (Unicode).
      + Rename "multiply sign in circle" to "circled times" (Unicode).
      + Rename "plus sign in circle" to "circled plus" (Unicode).
      + Rename "bar for fractions" to "fraction slash" (Unicode).  A novice
        could infer that the horizontal bar in a fraction qualifies, and
        "bar" in *roff glyph names suggests vertical orientation (\[ba],
        \[bb]).
      + Un-hyphenate "less-than" and "greater-than".
      + Append "than" to "much greater" and "much less".
      + Rename "not equal" to "not equals".
      + Un-abbreviate "approximately" and "asymptotically".
      + Add "tilde operator" to \[ap] (Unicode).
      + Add "to" to many mathematical operators: "congruent", "approximately
        equal", "similar", "proportional".
      + Add "radical sign" to \[sr] and \[sqrt] (AGL).
      + Rename "square root extension" to "radical extension"; the reader
        knows what a "radical" is from the previous table entry if not their
        education.
      + Add "symbol" to "aleph"; it's not the Hebrew letter just as the
        Greek symbols are not Greek letters for writing the language.
      + Refer to \[Im] and \[Re] as "blackletter" instead of "Gothic", as
        "Gothic" is used in some contexts to refer to sans-serif typefaces,
        a perverse contrast to Fraktur.  Also add "part" after "imaginary"
        and "real" to clarify their domain of application.  Thanks to Ingo
        Schwarze for the discussion.
      + Replace non-breaking space in "Weierstrass p" with breaking one.
      + Drop definition of h bar (from quantum mechanics) from
        \[-h] and \[hbar] escapes.  It's long and out of scope.
    
    * Characterize \[+e] (variant epsilon) as "lunate" (Unicode).
    
    * Style special character escape cross-references in descriptions
      consistently; use escape notation and set in bold.
    
    * Remove text blocks from tables.  The bracket-building escapes make the
      page source ridiculously wide already, and it's a lot easier to see
      what's going on without the text blocks.  Even with the tab stops at
      20 characters you can get by with 132 columns.  (This figure should
      come down after the Latin-1 supplement table is redesigned.  I plan
      to do that soon; in its present form, it is terrible advice for UTF-8
      users.)
    
    [1] http://dougkerr.net/Pumpkin/articles/Octatherp-octotherp.pdf




    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?59031>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/