[PATCH v2] terminfo(5): Improve tables.

[G. Branden Robinson]

v2
--
+ Document change to use `n` column classifier in
  "Attribute/Bit/Decimal" table.
+ Capitalize headings in "tparm parameter/attribute/escape sequence"
  table.
+ Set ACS_* object-like macro names (i.e., C literals) in bold.
+ Fix grammar error in commit message.
+ Clarify discussion in footnote.  Add exhibit of buggy DWB output.

* man/terminfo.head:
* man/terminfo.tail: Set column headings in boldface by using column
  modifiers in table format specifications instead of using font
  selection escape sequences in the entries themselves.

* man/terminfo.head:
  - Define `^` and `~` strings to indirectly define spacing/"large"
    carets and tildes portably, similar to the "``" and "''" strings
    already defined to access directional double quotes on
    groff-compatible formatters.
  - Add horizontal rule below table heading for consistency with other
    tables in the page.

* man/terminfo.tail:
  - Add paragraphing macros before tables where absent to better
    resemble a display, and for consistency with existing tables in the
    page.
  - Migrate from using multiple "_" column classifiers in table format
    specifications to single "_" entries between table rows to
    accomplish the same goal of drawing a horizontal rule.[1]
  - Stop using explicit column widths (with the 'w' column modifier);
    they achieve no esthetic advantage that I can perceive.  Perhaps
    this usage was meant as a safety measure; if so, it was a poor one,
    since if your table entry exceeds the explicit width, it will be
    overprinted with no diagnostic message.  Consider using GNU tbl in
    groff 1.23.0 if you want to see warnings when your tables overrun
    the available line length.
  - Set table columns in bold where they represent capability names or
    other literals, except where this would make the whole table bold.
  - Use `\e` escape sequence to interpolate a backslash instead of
    doubling the backslash.  `\\` will get you into trouble if you put
    it into a string and then interpolate that string in a table entry.
  - Use the `^` and `*` strings defined in "terminfo.head".
  - Apply title capitalization to column headings of tables lacking
    them, for consistency with other tables.  "terminfo" remains fully
    uncapitalized deliberately.
  - Drop `H` argument to `TS` macro calls.  It is meaningless to, and
    unsupported by, man(7) implementations.  In other macro packages,
    this is a convention that must be be used with a `TH` macro to mark
    the end of headings to be repeated across a multi-page table, but
    that macro name is already used for another purpose in man(7).
  - Stop using "expand" region option in tables.  It has little effect
    where it is used (in the descriptions of the DEC ACS glyphs) on a
    standard 80-column terminal because the table nearly spans the
    available line length anyway.  Further, the "expand" option is
    commonly misunderstood to make more room available for table
    entries--it does not.  All it does is expand the empty gaps between
    columns.  Usually, what people want is the `x` column modifier,
    which is portable if used only once in a row.  (In GNU tbl, you can
    use `x` in as many columns as you like.)
  - Float headings that occupy a single line "down", toward the rule
    that separates the headings from the content, to improve
    readability.
  - Say "ASCII Fallback" instead of "Ascii Default".
  - Say "Symbol" instead of "Char".  The column does not require
    abbreviation.
  - Use `.T&` token to start new table format instead of garrulously
    repeating row descriptions.
  - Set ACS_* object-like macro names (i.e., C literals) in bold.
  - Use `c` column classifier in a table where the meaning of `n`
    degenerates to the former (where only integers of co-equal widths
    were used).  In other words, the `n` format wasn't buying anything.
  - Use `n` column classifier in "Attribute/Bit/Decimal" table, where it
    _does_ buy numerical alignment at the (implied) decimal point.
  - Use horizontal span column classifiers `s` and explicit column
    separations to more pleasantly lay out the RGB columns of the tables
    describing ANSI X3.4 colors.
  - Drop garbage trailing spaces from table entries.

I recommend perusal of the tbl(1) man page in groff 1.23.0 to whomever
composed these tables.

[1] Full disclosure: I perceive what may be the reason the awkward "_ _"
    approach was taken.  It seems that AT&T tbl has a bug, if one judges
    by DWB 3.3 troff and Heirloom Doctools (which is descended from DWB
    3.3).  When used with nroff, its tbl draws these horizontal rules of
    (what looks like) the correct length, but leftward to the extreme
    left of the output.  And I mean extreme--it even ignores the page
    offset to do this.

    Exhibit:

    .po 30n
    .TS
    l.
    Here is my table.
    _
    Ain't it neat?
    .TE

    $ DWBHOME=. ./bin/tbl table-with-rule.roff \
        | DWBHOME=. ./bin/nroff |less -R

                              Here is my table.
________________
                              Ain't it neat?

    Piping nroff output through ul(1) before less(1) resolves the
    problem in this case and for several tables in terminfo(5), but not
    all of them: cf. the two Color/#define/Value/RGB tables.  And in
    fact Heirloom does a bit _worse_ than DWB in this respect,
    misrendering the horizontal rule on more tables.  But my hypothesis
    about "_" usage as column classifiers may be mistaken; it behaves
    just as badly.

    Typesetter output (e.g., with dpost(1)) is fine.

    This is a cosmetic problem, so I don't think it should gate this
    reform to tbl expression in man pages.  I didn't check Solaris
    10 troff, but my guess is that this defect would be found in all
    AT&T device-independent troffs.  I also didn't check Seventh Edition
    Unix tbl and nroff.

    I noticed something else; when back-scrolling with less(1), a few
    bytes of page content was sometimes corrupted with DWB 3.3 nroff.
    When using less without options, artifacts "ESC8" and "ESC9" appear
    at the left margin and redrawing is impotent to correct this.  With
    "less -R", damage occurs in the form of lost characters, but this is
    fixed with an explicit redraw.  Emulation of printing, overstriking
    terminals is certainly a brilliant thing, long ago perfected, and
    everybody should definitely keep hating ECMA-48 forever.  :-|

    groff and mandoc render the pages without apparent defect.
---
 man/terminfo.head |  13 +++--
 man/terminfo.tail | 134 +++++++++++++++++++++++-----------------------
 2 files changed, 76 insertions(+), 71 deletions(-)

diff --git a/man/terminfo.head b/man/terminfo.head
index b04e2df8..6e7fad48 100644
--- a/man/terminfo.head
+++ b/man/terminfo.head
@@ -35,6 +35,10 @@
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
+.ie \n(.g .ds ^ \(ha
+.el       .ds ^ ^
+.ie \n(.g .ds ~ \(ti
+.el       .ds ~ ~
 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2
@@ -135,10 +139,11 @@ Thus, a vt100 in 132-column mode would be vt100\-w.
 The following suffixes should be used where possible:
 .PP
 .TS
-center ;
-l c l
-l l l.
-\fBSuffix      Meaning Example\fP
+center;
+lb cb lb
+l  l  l .
+Suffix Meaning Example
+_
 \-\fInn\fP     Number of lines on the screen   aaa\-60
 \-\fIn\fPp     Number of pages of memory       c100\-4p
 \-am   With automargins (usually the default)  vt100\-am
diff --git a/man/terminfo.tail b/man/terminfo.tail
index b2715770..62b757e1 100644
--- a/man/terminfo.tail
+++ b/man/terminfo.tail
@@ -739,12 +739,13 @@ If either is omitted, the corresponding margin is set to 
the left or
 right edge of the display (rather than leaving the margin unmodified).
 .PP
 These are the margin-related capabilities:
+.PP
 .TS
 center;
-l l
-_ _
-lw8 lw18.
-\fBName        Description\fP
+lb lb
+lb l .
+Name   Description
+_
 smgl   Set left margin at current column
 smgr   Set right margin at current column
 smgb   Set bottom margin at current line
@@ -1085,19 +1086,18 @@ For example, the DEC vt220 supports most of the modes:
 .PP
 .TS
 center;
-l l l
-l l l
-lw18 lw14 lw18.
-\fBtparm parameter     attribute       escape sequence\fP
-
-none   none    \\E[0m
-p1     standout        \\E[0;1;7m
-p2     underline       \\E[0;4m
-p3     reverse \\E[0;7m
-p4     blink   \\E[0;5m
+lb lb lb
+l  l  l .
+tparm Parameter        Attribute       Escape Sequence
+_
+none   none    \eE[0m
+p1     standout        \eE[0;1;7m
+p2     underline       \eE[0;4m
+p3     reverse \eE[0;7m
+p4     blink   \eE[0;5m
 p5     dim     not available
-p6     bold    \\E[0;1m
-p7     invis   \\E[0;8m
+p6     bold    \eE[0;1m
+p7     invis   \eE[0;8m
 p8     protect not used
 p9     altcharset      ^O (off) ^N (on)
 .TE
@@ -1121,12 +1121,10 @@ Writing out the above sequences, along with their 
dependencies yields
 .ne 11
 .TS
 center;
-l l l
-l l l
-lw18 lw14 lw18.
-\fBsequence    when to output  terminfo translation\fP
-
-.ft CW
+lb lb lb
+l  l  l .
+Sequence       When to Output  terminfo Translation
+_
 \\E[0  always  \\E[0
 ;1     if p1 or p6     %?%p1%p6%|%t;1%;
 ;4     if p2   %?%p2%|%t;4%;
@@ -1134,8 +1132,7 @@ lw18 lw14 lw18.
 ;7     if p1 or p3     %?%p1%p3%|%t;7%;
 ;8     if p7   %?%p7%|%t;8%;
 m      always  m
-^N or ^O       if p9 ^N, else ^O       %?%p9%t^N%e^O%;
-.ft R
+\*^N or \*^O   if p9 \*^N, else \*^O   %?%p9%t\*^N%e\*^O%;
 .TE
 .PP
 Putting this all together into the sgr sequence gives:
@@ -1551,18 +1548,17 @@ for most of the drawing characters
 supported by the VT100, with some characters from the AT&T 4410v1 added.
 This alternate character set may be specified by the \fBacsc\fP capability.
 .PP
-.TS H
-center expand;
-l l l l l
-l l l l l
-_ _ _ _ _
-lw25 lw10 lw6 lw6 lw6.
-.\".TH
-\fBGlyph       ACS     Ascii   acsc    acsc\fP
-\fBName        Name    Default Char    Value\fP
+.TS
+center;
+lb lb lb lb lb.
+\&     \&      ASCII   acsc    acsc
+Glyph Name     ACS Name        Fallback        Symbol  Value
+_
+.T&
+l  lb l  l  l .
 arrow pointing right   ACS_RARROW      >       +       0x2b
 arrow pointing left    ACS_LARROW      <       ,       0x2c
-arrow pointing up      ACS_UARROW      ^       \-      0x2d
+arrow pointing up      ACS_UARROW      \*^     \-      0x2d
 arrow pointing down    ACS_DARROW      v       .       0x2e
 solid square block     ACS_BLOCK       #       0       0x30
 diamond                ACS_DIAMOND     +       `       0x60
@@ -1576,7 +1572,7 @@ upper right corner        ACS_URCORNER    +       k       
0x6b
 upper left corner      ACS_ULCORNER    +       l       0x6c
 lower left corner      ACS_LLCORNER    +       m       0x6d
 large plus or crossover        ACS_PLUS        +       n       0x6e
-scan line 1            ACS_S1          ~       o       0x6f
+scan line 1            ACS_S1          \*~     o       0x6f
 scan line 3            ACS_S3          \-      p       0x70
 horizontal line        ACS_HLINE       \-      q       0x71
 scan line 7            ACS_S7          \-      r       0x72
@@ -1591,7 +1587,7 @@ greater-than-or-equal-to  ACS_GEQUAL      >       z       
0x7a
 greek pi               ACS_PI  *       {       0x7b
 not-equal              ACS_NEQUAL      !       |       0x7c
 UK pound sign          ACS_STERLING    f       }       0x7d
-bullet                 ACS_BULLET      o       ~       0x7e
+bullet                 ACS_BULLET      o       \*~     0x7e
 .TE
 .PP
 A few notes apply to the table itself:
@@ -1683,36 +1679,39 @@ The terminal hardware is free to
 map these as it likes, but the RGB values indicate normal locations in color
 space.
 .PP
-.TS H
+.TS
 center;
-l c c c
-l l n l.
-\fBColor       #define         Value   RGB\fP
-black  \fBCOLOR_BLACK\fP       0       0, 0, 0
-red    \fBCOLOR_RED\ \fP       1       max,0,0
-green  \fBCOLOR_GREEN\fP       2       0,max,0
-yellow \fBCOLOR_YELLOW\fP      3       max,max,0
-blue   \fBCOLOR_BLUE\fP        4       0,0,max
-magenta        \fBCOLOR_MAGENTA\fP     5       max,0,max
-cyan   \fBCOLOR_CYAN\fP        6       0,max,max
-white  \fBCOLOR_WHITE\fP       7       max,max,max
+cb cb cb cb s  s
+l  lb c  l1 l1 l .
+Color  #define         Value   RGB
+_
+black  COLOR_BLACK     0       0,      0,      0
+red    COLOR_RED       1       max,    0,      0
+green  COLOR_GREEN     2       0,      max,    0
+yellow COLOR_YELLOW    3       max,    max,    0
+blue   COLOR_BLUE      4       0,      0,      max
+magenta        COLOR_MAGENTA   5       max,    0,      max
+cyan   COLOR_CYAN      6       0,      max,    max
+white  COLOR_WHITE     7       max,    max,    max
 .TE
 .PP
 The argument values of \fBsetf\fP/\fBsetb\fP historically correspond to
 a different mapping, i.e.,
-.TS H
+.PP
+.TS
 center;
-l c c c
-l l n l.
-\fBColor       #define         Value   RGB\fP
-black  \fBCOLOR_BLACK\fP       0       0, 0, 0
-blue   \fBCOLOR_BLUE\fP        1       0,0,max
-green  \fBCOLOR_GREEN\fP       2       0,max,0
-cyan   \fBCOLOR_CYAN\fP        3       0,max,max
-red    \fBCOLOR_RED\ \fP       4       max,0,0
-magenta        \fBCOLOR_MAGENTA\fP     5       max,0,max
-yellow \fBCOLOR_YELLOW\fP      6       max,max,0
-white  \fBCOLOR_WHITE\fP       7       max,max,max
+cb cb cb cb s  s
+l  lb c  l1 l1 l .
+Color  #define         Value   RGB
+_
+black  COLOR_BLACK     0       0,      0,      0
+blue   COLOR_BLUE      1       0,      0,      max
+green  COLOR_GREEN     2       0,      max,    0
+cyan   COLOR_CYAN      3       0,      max,    max
+red    COLOR_RED       4       max,    0,      0
+magenta        COLOR_MAGENTA   5       max,    0,      max
+yellow COLOR_YELLOW    6       max,    max,    0
+white  COLOR_WHITE     7       max,    max,    max
 .TE
 .PP
 It is important to not confuse the two sets of color capabilities;
@@ -1753,16 +1752,17 @@ attributes understood by \fBcurses\fP is as follows:
 .PP
 .TS
 center;
-l l l l
-lw20 lw2 lw10 lw10.
-\fBAttribute   Bit     Decimal Set by\fP
+cb cb cb cb
+lb n  n  lb.
+Attribute      Bit     Decimal Set by
+_
 A_STANDOUT     0       1       sgr
 A_UNDERLINE    1       2       sgr
 A_REVERSE      2       4       sgr
-A_BLINK        3       8       sgr
-A_DIM          4       16      sgr
-A_BOLD         5       32      sgr
-A_INVIS        6       64      sgr
+A_BLINK        3       8       sgr
+A_DIM  4       16      sgr
+A_BOLD 5       32      sgr
+A_INVIS        6       64      sgr
 A_PROTECT      7       128     sgr
 A_ALTCHARSET   8       256     sgr
 A_HORIZONTAL   9       512     sgr1
-- 
2.30.2

signature.asc
Description: PGP signature