[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 02/04: grotty.1.man: Make editorial fixes.
From: |
G. Branden Robinson |
Subject: |
[groff] 02/04: grotty.1.man: Make editorial fixes. |
Date: |
Sun, 30 Jun 2019 05:19:43 -0400 (EDT) |
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).
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 02/04: grotty.1.man: Make editorial fixes.,
G. Branden Robinson <=