Merge Groff 1.18.1 changes.

1 files changed, 187 insertions, 40 deletions

diff --git a/contrib/groff/src/devices/grotty/grotty.man b/contrib/groff/src/devices/grotty/grotty.man
index 7f38846..0b76887 100644
--- a/contrib/groff/src/devices/grotty/grotty.man
+++ b/contrib/groff/src/devices/grotty/grotty.man
@@ -1,6 +1,6 @@
 .ig
 $FreeBSD$
-Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc.
+Copyright (C) 1989-2000, 2001, 2002 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -17,22 +17,28 @@ versions, except that this permission notice may be included in
 translations approved by the Free Software Foundation instead of in
 the original English.
 ..
+.
+.
 .TH GROTTY @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
 .SH NAME
 grotty \- groff driver for typewriter-like devices
+.
+.
 .SH SYNOPSIS
 .B grotty
 [
-.B \-hfbuodBUv
+.B \-bBcdfhiouUv
 ] [
 .BI \-F dir
 ] [
-.IR files \|.\|.\|.
+.IR files \|.\|.\|.\&
 ]
 .PP
 It is possible to have whitespace between the
 .B \-F
 option and its parameter.
+.
+.
 .SH DESCRIPTION
 .B grotty
 translates the output of GNU
@@ -51,6 +57,8 @@ or
 .B \-Tutf8
 option on ASCII based systems, and with
 .B \-Tcp1047
+and
+.B \-Tutf8
 on EBCDIC based hosts.
 If no files are given,
 .B grotty
@@ -62,21 +70,75 @@ will also cause
 to read the standard input.
 Output is written to the standard output.
 .LP
-Normally
+By default,
 .B grotty
-prints a bold character
+emits SGR escape sequences (from ISO 6429, also called ANSI color escapes)
+to change text attributes (bold, italic, colors).
+This makes it possible to have eight different \M[green]background\M[]
+and \m[red]foreground\m[] colors; additionally, bold and italic
+attributes can be used \f[BI]at the same time\f[] (by using the BI font).
+.LP
+The following colors are defined in
+.BR 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).
+.LP
+Use the
+.B \-c
+switch to revert to the old behaviour, printing a bold character
 .I c
-using the sequence
+with the sequence
 .RI ` c
 .SM BACKSPACE
 .IR c '
-and a italic character
+and an italic character
 .I c
 by the sequence
 .RB ` _
 .SM BACKSPACE
 .IR c '.
-These sequences can be displayed on a terminal
+At the same time, color output is disabled.
+The same effect can be achieved by setting either the
+.B GROFF_NO_SGR
+environment variable or using the `sgr' X command (see below).
+.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
+.B $PAGER
+environment variable, e.g.\&
+.RS
+.LP
+.B PAGER="/usr/bin/less -R"
+.br
+.B export PAGER
+.RE
+.LP
+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.
+.LP
+.BR grotty 's
+old output format can be displayed on a terminal
 by piping through
 .BR ul (1).
 Pagers such as
@@ -116,11 +178,58 @@ then it will be treated as a bold font.
 The code field in the font description field gives the
 code which will be used to output the character.
 This code can also be used in the
-.B \eN
+.B \[rs]N
 escape sequence in
 .BR troff .
+.
+.
 .SH OPTIONS
 .TP
+.B \-b
+Suppress the use of overstriking for bold characters.
+Ignored if
+.B \-c
+isn't used.
+.
+.TP
+.B \-B
+Use only overstriking for bold-italic characters.
+Ignored if
+.B \-c
+isn't used.
+.
+.TP
+.B \-c
+Use
+.BR grotty 's
+old output format (see above).
+This also disables color output.
+.
+.TP
+.B \-d
+Ignore all
+.B \[rs]D
+commands.
+Without this
+.B grotty
+will render
+.B \[rs]D'l\|.\|.\|.\&'
+commands that have at least one zero argument
+(and so are either horizontal or vertical)
+using
+.BR \- ,
+.BR | ,
+and
+.B +
+characters.
+.
+.TP
+.B \-f
+Use form feeds in the output.
+A form feed will be output at the end of each page that has no output
+on its last line.
+.
+.TP
 .BI \-F dir
 Prepend directory
 .IB dir /dev name
@@ -137,52 +246,69 @@ or
 .B \-h
 Use horizontal tabs in the output.
 Tabs are assumed to be set every 8 columns.
+.
 .TP
-.B \-f
-Use form feeds in the output.
-A form feed will be output at the end of each page that has no output
-on its last line.
+.B \-i
+Use escape sequences to set the italic text attribute instead of the
+underline attribute for italic fonts (`I' and `BI').
+Note that most terminals (including xterm) don't support this.
+Ignored if
+.B \-c
+is active.
+.
 .TP
-.B \-b
-Suppress the use of overstriking for bold characters.
+.B \-o
+Suppress overstriking (other than for bold or underlined characters in
+case the old output format has been activated with
+.BR \-c ).
+.
 .TP
 .B \-u
 Suppress the use of underlining for italic characters.
-.TP
-.B \-B
-Use only overstriking for bold-italic characters.
+Ignored if
+.B \-c
+isn't used.
+.
 .TP
 .B \-U
 Use only underlining for bold-italic characters.
-.TP
-.B \-o
-Suppress overstriking (other than for bold or underlined characters).
-.TP
-.B \-d
-Ignore all
-.B \eD
-commands.
-Without this
-.B grotty
-will render
-.B \eD'l\|.\|.\|.'
-commands that have at least at least one zero argument
-(and so are either horizontal or vertical)
-using
-.BR \- ,
-.B |
-and
-.B +
-characters.
+Ignored if
+.B \-c
+isn't used.
+.
 .TP
 .B \-v
 Print the version number.
+.
+.
+.SH USAGE
+.B grotty
+understands a single X command produced using the
+.B \[rs]X
+escape sequence.
+.TP
+.BI \[rs]X'tty:\ sgr\  n '
+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.
+.
+.
+.SH ENVIRONMENT
+.TP
+.B GROFF_NO_SGR
+If set, the old drawing scheme for bold and underline (using the
+backspace character) is active.
+Colors are disabled.
+.
+.
 .SH FILES
 .TP
 .B @FONTDIR@/devascii/DESC
 Device description file for
 .B ascii
 device.
+.
 .TP
 .BI @FONTDIR@/devascii/ F
 Font description file for font
@@ -202,11 +328,13 @@ Font description file for font
 of
 .B koi8-r
 device.
+.
 .TP
 .B @FONTDIR@/devlatin1/DESC
 Device description file for
 .B latin1
 device.
+.
 .TP
 .BI @FONTDIR@/devlatin1/ F
 Font description file for font
@@ -214,11 +342,13 @@ Font description file for font
 of
 .B latin1
 device.
+.
 .TP
 .B @FONTDIR@/devutf8/DESC
 Device description file for
 .B utf8
 device.
+.
 .TP
 .BI @FONTDIR@/devutf8/ F
 Font description file for font
@@ -226,11 +356,13 @@ Font description file for font
 of
 .B utf8
 device.
+.
 .TP
 .B @FONTDIR@/devcp1047/DESC
 Device description file for
 .B cp1047
 device.
+.
 .TP
 .BI @FONTDIR@/devcp1047/ F
 Font description file for font
@@ -238,10 +370,12 @@ Font description file for font
 of
 .B cp1047
 device.
+.
 .TP
 .B @MACRODIR@/tty.tmac
 Macros for use with
 .BR grotty .
+.
 .TP
 .B @MACRODIR@/tty-char.tmac
 Additional klugdey character definitions for use with
@@ -250,6 +384,8 @@ Additional klugdey character definitions for use with
 Note that on EBCDIC hosts, only files for the
 .B cp1047
 device will be installed.
+.
+.
 .SH BUGS
 .LP
 .B grotty
@@ -258,12 +394,22 @@ is intended only for simple documents.
 There is no support for fractional horizontal or vertical motions.
 .LP
 There is no support for
-.B \eD
+.B \[rs]D
 commands
 other than horizontal and vertical lines.
 .LP
-Characters above the first line (ie with a vertical position of 0)
+Characters above the first line (ie with a vertical position of\~0)
 cannot be printed.
+.LP
+Color handling is different compared to
+.BR grops (@MAN1EXT@).
+.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.
+.
+.
 .SH "SEE ALSO"
 .BR groff (@MAN1EXT@),
 .BR @g@troff (@MAN1EXT@),
@@ -272,6 +418,7 @@ cannot be printed.
 .BR groff_char (@MAN7EXT@),
 .BR ul (1),
 .BR more (1),
+.BR man (1),
 .BR less (1)
 .
 .\" Local Variables: