diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/grotty.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/grotty.1 | 570 |
1 files changed, 570 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/grotty.1 b/upstream/debian-bookworm/man1/grotty.1 new file mode 100644 index 00000000..6544fa87 --- /dev/null +++ b/upstream/debian-bookworm/man1/grotty.1 @@ -0,0 +1,570 @@ +.TH GROTTY 1 "7 March 2023" "groff 1.22.4" +.SH NAME +grotty \- groff driver for typewriter-like devices +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2018 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr grotty_C \n[.C] +.cp 0 +. +. +.\" ==================================================================== +.SH SYNOPSIS +.\" ==================================================================== +. +.SY grotty +.OP \-bBcdfhioruUv +.OP \-F dir +.RI [ file +\&.\|.\|.\&] +.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 +.BR \-Tascii , +.B \-Tlatin1 +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 +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). +. +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 +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 +with the sequence +.RI \[lq] c +BACKSPACE +.IR c \[rq] +and an italic character +.I c +by the sequence +.RB \[lq] _ +BACKSPACE +.IR c \[rq]. +. +At the same time, color output is disabled. +. +The same effect can be achieved by setting either the +.I GROFF_NO_SGR +environment variable or using the \[oq]sgr\[cq] X command (see below). +. +. +.LP +(Debian-specific: The old behaviour is the default when using the +.B man +and +.B mdoc +macro packages, because most pagers either fail to cope with SGR escape +sequences or need special options to do so. +SGR output can be re-enabled permanently by editing +.I /etc/groff/man.local +and +.IR /etc/groff/mdoc.local , +or temporarily by setting the +.I GROFF_SGR +environment variable to something non-empty.) +. +. +.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.\& +. +.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. +. +Note that with some +.BR man (1) +versions, you have to use the +.I \%MANPAGER +environment variable instead. +. +. +.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 +.B \-b +when piping into +.BR more (1). +There is no need to filter the output through +.BR col (1) +since +.B grotty +never outputs reverse line feeds. +. +. +.LP +The font description file may contain a command +. +.IP +.BI internalname\ n +.LP +. +where +.I n +is a decimal integer. +. +If the 01 bit in +.I n +is set, +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 . +. +. +.LP +If the +.I DESC +file contains the keyword +.BR unicode , +.B 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 (5) +man page for more details. +. +. +.\" ==================================================================== +.SH OPTIONS +.\" ==================================================================== +. +Whitespace is permitted between a command-line option and its argument. +. +. +.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. +(Debian-specific: This option is enabled by default when using the +.B man +and +.B mdoc +macro packages. +It can be disabled by default permanently by editing +.I /etc/groff/man.local +and +.IR /etc/groff/mdoc.local , +or temporarily by setting the +.I GROFF_SGR +environment variable to something non-empty.) +. +.TP +.B \-d +Ignore all +.B \[rs]D +commands. +. +Without this +.B grotty +renders +.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. +. +In a similar way, +.B grotty +handles +.B \[rs]D'p\|.\|.\|.\&' +commands which consist entirely of horizontal and vertical lines. +. +. +.TP +.B \-f +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 +.RI dir /dev name +to the search path for font and device description files; +.I name +is the name of the device, usually +.BR ascii , +.BR latin1 , +.BR utf8 , +or +.BR cp1047 . +. +.TP +.B \-h +Use horizontal tabs 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]). +. +Note that most terminals (including xterm) don't support this. +. +Ignored if +.B \-c +is active. +. +.TP +.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 \-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]). +. +Ignored if +.B \-c +is active. +. +.TP +.B \-u +Suppress the use of underlining for italic characters. +. +Ignored if +.B \-c +isn't used. +. +.TP +.B \-U +Use only underlining for bold-italic 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 +.I GROFF_NO_SGR +If set, the old drawing scheme for bold and underline (using the +backspace character) is active. +. +Colors are disabled. +. +. +.TP +.I GROFF_FONT_PATH +A list of directories in which to search for the +.IR dev name +directory in addition to the default ones. +. +See +.BR troff (1) +and +.BR \%groff_font (5) +for more details. +. +. +.\" ==================================================================== +.SH FILES +.\" ==================================================================== +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:font/devascii/DESC +Device description file for the +.B ascii +device. +. +.TP +.IR /usr/\:share/\:groff/\:1.22.4/\:font/devascii/ F +Font description file for font +.I F +of the +.B ascii +device. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:font/devlatin1/DESC +Device description file for the +.B latin1 +device. +. +.TP +.IR /usr/\:share/\:groff/\:1.22.4/\:font/devlatin1/ F +Font description file for font +.I F +of the +.B latin1 +device. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:font/devutf8/DESC +Device description file for the +.B utf8 +device. +. +.TP +.IR /usr/\:share/\:groff/\:1.22.4/\:font/devutf8/ F +Font description file for font +.I F +of the +.B utf8 +device. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:font/devcp1047/DESC +Device description file for the +.B cp1047 +device. +. +.TP +.IR /usr/\:share/\:groff/\:1.22.4/\:font/devcp1047/ F +Font description file for font +.I F +of the +.B cp1047 +device. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:tmac/tty.tmac +Macros for use with +.BR grotty . +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:tmac/tty\-char.tmac +Additional character definitions for use with +.BR grotty . +. +.LP +Note that on EBCDIC hosts, only files for the +.B cp1047 +device is installed. +. +. +.\" ==================================================================== +.SH BUGS +.\" ==================================================================== +. +.B grotty +is intended only for simple documents. +. +. +.LP +There is no support for fractional horizontal or vertical motions. +. +. +.LP +There is no support for +.B \[rs]D +commands other than horizontal and vertical lines. +. +. +.LP +Characters above the first line (i.e.\& with a vertical position +of\~0) cannot be printed. +. +. +.LP +Color handling differs from +.BR grops (1). +.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 (1), +.BR troff (1), +.BR groff_out (5), +.BR groff_font (5), +.BR groff_char (7), +.BR ul (1), +.BR more (1), +.BR man (1), +.BR less (1) +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[grotty_C] +. +. +.\" Local Variables: +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff: |