[groff] 02/04: grotty.1.man: Make editorial fixes.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c105b1725cc928e225d23237f3cf1a7a5239d5ba
Author: G. Branden Robinson <address@hidden>
Date:   Thu Jun 27 22:14:50 2019 +1000

    grotty.1.man: Make editorial fixes.
    
    * Add "terminal" keyword to summary line.
    * Reorganize synopsis.
      + Distinguish modes of operation.
        - Only SGR mode (the default) accepts -i or -r.
        - Only legacy mode accepts -[bBuU].
        - Note --help and --version modes.
    * Recast introductory paragraph; because groff does its own pipeline
      management, people tend to think of "the output of *roff" not as the
      device-independent form but of device-specific output (PDF, TTY, ...).
    * Add man page cross-references, particularly to groff(1) itself.
    * Hyphenate attributive phrases (e.g., "EBCDIC-based hosts").
    * Note the historically-driven practice of rendering (and speaking of)
      underlined text as "italics" in nroff/TTY contexts.
      + Also call out the relatively new grotty -i option which gives you
        something closer to true italics on xterm(1).
    * Set pathnames/filenames in italics, not bold.
    * Remove false claim about the default color scheme for terminals being
      black text on a white background "in most cases".
      + I don't know who wrote that, but I suspect a Macintosh or Sun
        workstation partisan.  Whoever they were, they ignored a huge number
        of monochrome hardware terminals by that were manufactured after
        1980 (when green and amber phosphors grew popular) and by about 1987
        the DEC VT340 was supporting color escapes (the VT420 and VT520
        reverted to monochrome, and the VT525 (~1993) brought color back
        again).  The rise of the IBM 5150 ("PC") -compatible microcomputer
        and the default white-on-black color scheme of MS-DOS/PC-DOS
        contributed to user expectations of similar terminal color schemes
        by 1990.  By the mid-1990s when people started to hear of the Linux
        kernel, official maintenance of the X Window System by the Open
        Group was moribund, and the xterm client in the sample
        implementation was _still_ monochrome as late as X11R6.5.1 (August
        2000), but the Linux console (white-on-black, on PC VGA hardware)
        wasn't, and a thousand clueless flowers bloomed across the land as
        system integrators rushed to bring refugees from Microsoft Windows
        the joy of colorized GNU ls(1) output in a GUI terminal window.  For
        the sake of "brand differentiation", these vendors chose "attractive
        color schemes" for "the desktop", and imposed this scheme on the
        terminal emulator without regard for the color palette, often
        resulting in unreadable foreground colors against the "pleasant"
        default background.  But venture capitalists and IPO-hungry day
        traders cared little for usability issues, being concerned more with
        who was going to do the biggest cannonball into the swimming pool.
        Had they bothered to look, they'd have noticed the similarity
        between these initiatives and the ill-fated COSE/CDE at the tail end
        of the Unix Wars only a few years previous.  Upon these
        lavishly-funded but dubiously-engineered foundations the dot-com
        bubble burst, and billions of dollars of notional wealth disappeared
        overnight.  After that we had terrorist attacks and wars in the
        Middle East, and it's all thanks to people who don't support their
        claims about what "most" terminals use as a default color scheme.
    * Structure a somewhat miscellaneous compendium of information into
      subsections:
      + SGR support in pagers
      + Legacy output format
      + Device control commands
      + Device description files
    * Comment out paragraph that I think might better belong elsewhere.
      Feedback welcome.
    * Add internal cross-references.
    * Carefully distinguish *roff escape sequences from SGR escape sequences
      in narrative.  There's no escaping the terminology, so be clear about
      context in each case.
    * Note that horizontal and vertical lines are drawn with Unicode
      box-drawing characters on the utf8 device.
    * Don't set a metasyntactical ellipsis in bold.  It's not a literal.
    * Document supported long options.
    * Don't talk about an option being "active"; talk about whether it's
      specified--that's what the user has control over.
    * Quote output device names instead of shouting them in bold (except
      when part of option syntax).
    * Comment out claim that cp1047 device files are only shipped on EBCDIC
      platforms.  The build no longer seems to practice this restriction?
    * Style: ensure two empty requests between paragraphs.
---
 src/devices/grotty/grotty.1.man | 505 +++++++++++++++++++++++-----------------
 1 file changed, 295 insertions(+), 210 deletions(-)

diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man
index d60ac7c..b90e681 100644
--- a/src/devices/grotty/grotty.1.man
+++ b/src/devices/grotty/grotty.1.man
@@ -1,6 +1,6 @@
 .TH GROTTY @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH NAME
-grotty \- groff driver for typewriter-like devices
+grotty \- groff driver for typewriter-like (terminal) devices
 .
 .
 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
@@ -35,207 +35,253 @@ grotty \- groff driver for typewriter-like devices
 .\" ====================================================================
 .
 .SY grotty
-.OP \-bBcdfhioruUv
+.OP \-dfho
+.RB [ \-i | \-r ]
 .OP \-F dir
 .RI [ file
 \&.\|.\|.\&]
 .YS
 .
 .
+.SY "grotty -c"
+.OP \-bBdfhouU
+.OP \-F dir
+.RI [ file
+\&.\|.\|.\&]
+.YS
+.
+.
+.SY grotty
+.B \-\-help
+.YS
+.
+.
+.SY grotty
+.B \-v
+.SY grotty
+.B \-\-version
+.YS
+.
+.
 .\" ====================================================================
 .SH DESCRIPTION
 .\" ====================================================================
 .
-.B grotty
-translates the output of GNU
-.B troff
-into a form suitable for typewriter-like devices.
-.
-Normally
-.B grotty
-should be invoked by using the
-.B groff
-command with a
+The GNU
+.I roff
+TTY
+(\[lq]teletype\[rq])
+output driver translates the intermediate,
+device-independent output of
+.IR groff (@MAN1EXT@)
+into a form suitable for typewriter-like devices,
+including terminal emulators.
+.
+Normally,
+.I grotty
+is invoked by
+.I groff
+when the latter is given one of the
 .BR \-Tascii ,
 .B \-Tlatin1
 or
 .B \-Tutf8
-option on ASCII based systems, and with
+options on ASCII-based systems,
+or with
 .B \-Tcp1047
-and
+or
 .B \-Tutf8
-on EBCDIC based hosts.
-.
-If no files are given,
-.B grotty
+on EBCDIC-based hosts.
+.
+If no
+.I file
+arguments are given,
+or if
+.I file
+is \[lq]\-\[rq],
+.I grotty
 reads the standard input.
 .
-A filename of
-.B \-
-also causes
-.B grotty
-to read the standard input.
-.
 Output is written to the standard output.
 .
 .
 .LP
 By default,
-.B grotty
-emits SGR escape sequences (from ISO 6429, also called ANSI color
-escapes) to change text attributes (bold, italic, colors).
+.I grotty
+emits SGR escape sequences
+(from ISO 6429,
+popularly called \[lq]ANSI escapes\[rq])
+to change text attributes
+(bold, italic, underline, reverse-video, and colors).
+.
+Devices supporting the appropriate sequences can view
+.I roff
+documents using eight different background and foreground colors or
+which require the bold and italic attributes \f[BI]at the same time\f[]
+(by using the \[lq]BI\[rq] font style).
 .
-This makes it possible to have eight different background and
-foreground colors; additionally, bold and italic attributes can be
-used \f[BI]at the same time\f[] (by using the BI font).
+.
+.LP
+In keeping with long-standing practice and the rarity of terminals,
+hardware or emulated,
+that support oblique or italic fonts,
+italicized text is represented with underlining by default\[em]but see
+the
+.B \-i
+option below.
 .
 .
 .LP
 The following colors are defined in
-.BR tty.tmac :
+.IR tty.tmac :
 black, white, red, green, blue, yellow, magenta, cyan.
 .
-Unknown colors are mapped to the default color (which is dependent on
-the settings of the terminal; in most cases, this is black for the
-foreground and white for the background).
+Unrecognized colors are mapped to the default color,
+which is dependent on the settings of the terminal.
 .
 .
-.LP
-For SGR support, it is necessary to use the
-.B \-R
-option of
-.BR less (1)
-to disable the interpretation of
-.BR grotty 's
-old output format.
-.
-Consequently, all programs which use
-.B less
-as the pager program have to pass this option to it.
-.
-For
-.BR man (1)
-in particular, either add
-.B \-R
-to the
-.I PAGER
-environment variable, e.g.\&
+.\" ====================================================================
+.SS "SGR support in pagers"
+.\" ====================================================================
 .
-.RS
-.LP
-.B PAGER="/usr/bin/less \-R"
-.br
-.B export PAGER
-.RE
-.LP
+When paging
+.IR grotty 's
+output with
+.IR less (1),
+it is necessary to use either the
+.B \-r
+or the
+.B \-R
+option of the latter for SGR sequences to be rendered correctly.
 .
-or use the
-.B \-P
-option of
-.B man
-to set the pager executable and its options, or modify the
-configuration file of
-.B man
-in a similar fashion.
+Consequently,
+programs like
+.IR man (1)
+which page
+.I roff
+documents with
+.I less
+must pass one of these options to it.
 .
-Note that with some
-.BR man (1)
-versions, you have to use the
-.I \%MANPAGER
-environment variable instead.
 .
+.\" ====================================================================
+.SS "Legacy output format"
+.\" ====================================================================
 .
-.LP
-Use the
+The
 .B \-c
-switch to revert to the old behaviour, printing a bold character
+option tells
+.I grotty
+to use an output format compatible with paper teletypes.
+.
+SGR escape sequences are not used.
+.
+Instead,
+.I grotty
+overstrikes,
+representing a bold character
 .I c
 with the sequence
-.RI \[lq] c
-BACKSPACE
+.RI \[lq] c\~\c
+BACKSPACE\~\c
 .IR c \[rq]
 and an italic character
 .I c
-by the sequence
-.RB \[lq] _
-BACKSPACE
+with the sequence
+.RB \[lq] _\~\c
+BACKSPACE\~\c
 .IR c \[rq].
 .
-At the same time, color output is disabled.
+Furthermore, color output is disabled.
 .
-The same effect can be achieved by setting either the
+The same effect can be achieved either by setting the
 .I GROFF_NO_SGR
-environment variable or using the \[oq]sgr\[cq] X command (see below).
+environment variable or by using a
+.I groff
+escape sequence within the document;
+see subsection \[lq]Device control commands\[rq],
+below.
 .
 .
 .LP
-.BR grotty 's
-old output format can be displayed on a terminal
-by piping through
-.BR ul (1).
-Pagers such as
-.BR more (1)
-or
-.BR less (1)
-are also able to display these sequences.
-Use either
-.B \-B
-or
-.B \-U
-when piping into
-.BR less (1);
-use
+The legacy output format can be rendered on a terminal
+(or emulator)
+by piping
+.IR grotty 's
+output through
+.IR ul (1),
+.\" from bsdmainutils 11.1.2+b1 (on Debian Buster)
+which may render bold italics as reverse video.
+.
+.\" 'more' from util-linux 2.33.1 (on Debian Buster) neither renders
+.\" double-struck characters as bold nor supports -b, but does render
+.\" SGR sequences (including color) with no flags required.
+Some implementations of
+.IR more (1)
+are also able to display these sequences;
+you may wish to experiment with that command's
 .B \-b
-when piping into
-.BR more (1).
+option.
+.
+.\" Version 487 of...
+.I less
+renders legacy bold and italics without requiring options.
+.
 There is no need to filter the output through
-.BR col (1)
+.IR col (1)
 since
-.B grotty
+.I grotty
 never outputs reverse line feeds.
 .
 .
 .\" ====================================================================
-.SH USAGE
+.SS "Device control commands"
 .\" ====================================================================
 .
-.B grotty
-understands a single X command produced using the
+.I grotty
+understands a single device control function produced using the
+.I roff
 .B \[rs]X
-escape sequence.
+escape sequence in a document.
+.
 .
 .TP
-.BI \[rs]X'tty:\ sgr\  n '
+.BR "\[rs]X'tty: sgr " [\c
+.IR n ]\c
+.B '
 .
 If
 .I n
-is non-zero or missing, enable SGR output (this is the default),
-otherwise use the old drawing scheme for bold and underline.
+is non-zero or missing, enable SGR sequences
+(this is the default);
+otherwise,
+use the legacy output format.
 .
 .
+.\" ====================================================================
+.SS "Device description files"
+.\" ====================================================================
+.
 .LP
-If the
+If
 .I DESC
-file contains the keyword
-.BR unicode ,
-.B grotty
+file for the character encoding contains the keyword
+.RB \[lq] unicode \[rq],
+.I grotty
 emits Unicode characters in UTF-8 encoding.
 .
 Otherwise, it emits characters in a single-byte encoding depending on
 the data in the font description files.
 .
-See the
-.BR groff_font (@MAN5EXT@)
-man page for more details.
-.
+See
+.IR groff_font (@MAN5EXT@)
+for more details.
 .
-.LP
-The font description file may contain a command
 .
-.IP
-.BI internalname\  n
 .LP
-.
+A font description file may contain a command
+.RB \[lq] internalname\~\c
+.IR n \[rq]
 where
 .I n
 is a decimal integer.
@@ -247,13 +293,15 @@ then the font is treated as an italic font;
 if the 02 bit is set,
 then it is treated as a bold font.
 .
-The code field in the font description field gives the code which is
-used to output the character.
-.
-This code can also be used in the
-.B \[rs]N
-escape sequence in
-.BR troff .
+.\" The following seems to say nothing that is not true of font
+.\" description files in general; if so, it belongs in groff_font(5).
+.\"The code field in the font description field gives the code which is
+.\"used to output the character.
+.\".
+.\"This code can also be used in the
+.\".I groff
+.\".B \[rs]N
+.\"escape sequence in a document.
 .
 .
 .\" ====================================================================
@@ -271,6 +319,7 @@ Ignored if
 .B \-c
 isn't used.
 .
+.
 .TP
 .B \-B
 Use only overstriking for bold-italic characters.
@@ -278,36 +327,43 @@ Ignored if
 .B \-c
 isn't used.
 .
+.
 .TP
 .B \-c
 Use
-.BR grotty 's
-old output format (see above).
-This also disables color output.
+.IR grotty 's
+legacy output format
+(see subsection \[lq]Legacy output format\[rq] above).
+.
 .
 .TP
 .B \-d
 Ignore all
 .B \[rs]D
-commands.
+.I roff
+escapes
+(draw commands).
 .
-Without this
-.B grotty
+By default,
+.I grotty
 renders
-.B \[rs]D'l\|.\|.\|.\&'
+.BR \[rs]D'l \|.\|.\|.\& '
 commands that have at least one zero argument
 (and so are either horizontal or vertical)
-using
+using Unicode box drawing characters
+(for the \[lq]utf8\[rq] device)
+or the
 .BR \- ,
 .BR | ,
 and
 .B +
-characters.
+characters
+(for all other devices).
 .
 In a similar way,
-.B grotty
+.I grotty
 handles
-.B \[rs]D'p\|.\|.\|.\&'
+.BR \[rs]D'p \|.\|.\|.\& '
 commands which consist entirely of horizontal and vertical lines.
 .
 .
@@ -318,6 +374,7 @@ Use form feeds in the output.
 A form feed is output at the end of each page that has no output on
 its last line.
 .
+.
 .TP
 .BI \-F dir
 Prepend directory
@@ -331,37 +388,53 @@ is the name of the device, usually
 or
 .BR cp1047 .
 .
+.
 .TP
 .B \-h
-Use horizontal tabs in the output.
+Use literal horizontal tab characters in the output.
 .
 Tabs are assumed to be set every 8 columns.
 .
+.
 .TP
 .B \-i
-Use escape sequences to set the italic text attribute instead of the
-underline attribute for italic fonts (\[oq]I\[cq] and \[oq]BI\[cq]).
+Render italic-styled text
+(fonts \[lq]I\[rq] and \[lq]BI\[rq])
+with the SGR attribute for italic text
+rather than underlined text.
 .
-Note that most terminals (including xterm) don't support this.
+Note that many terminals don't support this attribute;
+however,
+.IR xterm (1),
+since patch\~#314 (2014-12-28),
+does.
 .
 Ignored if
 .B \-c
-is active.
+is also specified.
+.
 .
 .TP
 .B \-o
-Suppress overstriking (other than for bold or underlined characters in
-case the old output format has been activated with
-.BR \-c ).
+Suppress overstriking
+(other than for bold and/or underlined characters when the legacy output
+format is in use).
+.
 .
 .TP
 .B \-r
-Use escape sequences to set the reverse text attribute instead of the
-underline attribute for italic fonts (\[oq]I\[cq] and \[oq]BI\[cq]).
+Render italic-styled text
+(fonts \[lq]I\[rq] and \[lq]BI\[rq])
+with the SGR attribute for reverse-video text
+.\" ECMA-48, 2nd edition (1979) calls it "negative image".
+rather than underlined text.
 .
 Ignored if
 .B \-c
-is active.
+or
+.B \-i
+is also specified.
+.
 .
 .TP
 .B \-u
@@ -371,6 +444,7 @@ Ignored if
 .B \-c
 isn't used.
 .
+.
 .TP
 .B \-U
 Use only underlining for bold-italic characters.
@@ -379,9 +453,17 @@ Ignored if
 .B \-c
 isn't used.
 .
+.
 .TP
 .B \-v
-Print the version number.
+.TQ
+.B \-\-version
+Display version information and exit.
+.
+.
+.TP
+.B \-\-help
+Display a brief usage message and exit.
 .
 .
 .\" ====================================================================
@@ -395,18 +477,18 @@ A list of directories in which to search for the
 directory in addition to the default ones.
 .
 See
-.BR @g@troff (@MAN1EXT@)
+.IR @g@troff (@MAN1EXT@)
 and
-.BR \%groff_font (@MAN5EXT@)
+.IR \%groff_font (@MAN5EXT@)
 for more details.
 .
 .
 .TP
 .I GROFF_NO_SGR
-If set, the old drawing scheme for bold and underline (using the
-backspace character) is active.
-.
-Colors are disabled.
+If set,
+.IR grotty 's
+legacy output format is used;
+see subsection \[lq]Legacy output format\[rq] above.
 .
 .
 .\" ====================================================================
@@ -415,81 +497,76 @@ Colors are disabled.
 .
 .TP
 .I @FONTDIR@/devascii/DESC
-Device description file for the
-.B ascii
-device.
+Device description file for the \[lq]ascii\[rq] device.
+.
 .
 .TP
 .IR @FONTDIR@/devascii/ F
 Font description file for font
 .I F
-of the
-.B ascii
-device.
+of the \[lq]ascii\[rq] device.
+.
 .
 .TP
 .I @FONTDIR@/devcp1047/DESC
-Device description file for the
-.B cp1047
-device.
+Device description file for the \[lq]cp1047\[rq] device.
+.
 .
 .TP
 .IR @FONTDIR@/devcp1047/ F
 Font description file for font
 .I F
-of the
-.B cp1047
-device.
+of the \[lq]cp1047\[rq] device.
+.
 .
 .TP
 .I @FONTDIR@/devlatin1/DESC
-Device description file for the
-.B latin1
-device.
+Device description file for the \[lq]latin1\[rq] device.
+.
 .
 .TP
 .IR @FONTDIR@/devlatin1/ F
 Font description file for font
 .I F
-of the
-.B latin1
-device.
+of the \[lq]latin1\[rq] device.
+.
 .
 .TP
 .I @FONTDIR@/devutf8/DESC
-Device description file for the
-.B utf8
-device.
+Device description file for the \[lq]utf8\[rq] device.
+.
 .
 .TP
 .IR @FONTDIR@/devutf8/ F
 Font description file for font
 .I F
-of the
-.B utf8
-device.
+of the \[lq]utf8\[rq] device.
+.
 .
 .TP
 .I @MACRODIR@/tty.tmac
 Macros for use with
-.BR grotty .
+.IR grotty .
+.
 .
 .TP
 .I @MACRODIR@/tty\-char.tmac
 Additional character definitions for use with
-.BR grotty .
+.IR grotty .
 .
-.LP
-Note that on EBCDIC hosts, only files for the
-.B cp1047
-device is installed.
+.
+.\" The following no longer seems to be true; an inspection of the
+.\" font/*/dev*.am files suggests no evidence of it, at any rate.
+.\".LP
+.\"Note that on EBCDIC hosts,
+.\"only files for the \[lq]cp1047\[rq] device are installed.
 .
 .
 .\" ====================================================================
 .SH BUGS
 .\" ====================================================================
 .
-.B grotty
+.I grotty
 is intended only for simple documents.
 .
 .
@@ -498,38 +575,46 @@ There is no support for fractional horizontal or vertical 
motions.
 .
 .
 .LP
-There is no support for
+There is no support for the
+.I roff
 .B \[rs]D
-commands other than horizontal and vertical lines.
+escape sequence (draw command) other than horizontal and vertical lines.
 .
 .
 .LP
-Characters above the first line (i.e.\& with a vertical position
-of\~0) cannot be printed.
+Characters above the first line
+(i.e., with a vertical position of\~0)
+cannot be printed.
 .
 .
 .LP
 Color handling differs from
-.BR grops (@MAN1EXT@).
+.IR grops (@MAN1EXT@).
+.
+The
+.I groff
 .B \[rs]M
-doesn't set the fill color for closed graphic objects (which
-.B grotty
-doesn't support anyway) but changes the background color of the
-character cell, affecting all subsequent operations.
+escape sequence doesn't set the fill color for closed graphic objects
+(which
+.I grotty
+doesn't support anyway)
+but instead changes the background color of the character cell,
+affecting all subsequent operations.
 .
 .
 .\" ====================================================================
 .SH "SEE ALSO"
 .\" ====================================================================
-.BR groff (@MAN1EXT@),
-.BR @g@troff (@MAN1EXT@),
-.BR groff_out (@MAN5EXT@),
-.BR groff_font (@MAN5EXT@),
-.BR groff_char (@MAN7EXT@),
-.BR ul (1),
-.BR more (1),
-.BR man (1),
-.BR less (1)
+.
+.IR groff (@MAN1EXT@),
+.IR @g@troff (@MAN1EXT@),
+.IR groff_out (@MAN5EXT@),
+.IR groff_font (@MAN5EXT@),
+.IR groff_char (@MAN7EXT@),
+.IR ul (1),
+.IR more (1),
+.IR less (1),
+.IR man (1)
 .
 .
 .\" Restore compatibility mode (for, e.g., Solaris 10/11).