|
Name | Synopsis | Description | Options | Environment | Files | Bugs | Example | See Also | COLOPHON |
grotty(1) General Commands Manual grotty(1)
grotty - groff driver for typewriter-like (terminal) devices
grotty [-dfho] [-i|-r] [-F dir] [file ...]
grotty -c [-bBdfhouU] [-F dir] [file ...]
grotty --help
grotty -v
grotty --version
The GNU roff TTY (“teletype”) output driver translates the
intermediate, device-independent output of groff(1) into a form
suitable for typewriter-like devices, including terminal emulators.
Normally, grotty is invoked by groff when the latter is given one of
the -Tascii, -Tlatin1 or -Tutf8 options on ASCII-based systems, or
with -Tcp1047 or -Tutf8 on EBCDIC-based hosts. If no file arguments
are given, or if file is “-”, grotty reads the standard input.
Output is written to the standard output.
By default, grotty emits SGR escape sequences (from ISO 6429,
popularly called “ANSI escapes”) to change text attributes (bold,
italic, underline, reverse-video, and colors). Devices supporting
the appropriate sequences can view roff documents using eight
different background and foreground colors or which require the bold
and italic attributes at the same time (by using the “BI” font
style).
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—but see
the -i option below.
Following ISO 6429, the following colors are defined in tty.tmac:
black, white, red, green, blue, yellow, magenta, and cyan.
Unrecognized colors are mapped to the default color, which is
dependent on the settings of the terminal.
SGR support in pagers
When paging grotty's output with less(1), the latter program must be
instructed to pass SGR sequences through to the device; its -R option
is one way to achieve this. Consequently, programs like man(1) which
page roff documents with less must call it with an appopriate option.
Legacy output format
The -c option tells grotty to use an output format compatible with
paper terminals, like the Teletype machines for which roff and nroff
were first developed but which are no longer in wide use. SGR escape
sequences are not emitted. Instead, grotty overstrikes, representing
a bold character c with the sequence “c BACKSPACE c” and an italic
character c with the sequence “_ BACKSPACE c”. Furthermore, color
output is disabled. The same effect can be achieved either by
setting the GROFF_NO_SGR environment variable or by using a groff
escape sequence within the document; see subsection “Device control
commands”, below.
The legacy output format can be rendered on a video terminal (or
emulator) by piping grotty's output through ul(1), which may render
bold italics as reverse video. Some implementations of more(1) are
also able to display these sequences; you may wish to experiment with
that command's -b option. less renders legacy bold and italics
without requiring options. In contrast to the teletype output
drivers of some other roff implementations, grotty never outputs
reverse line feeds. There is therefore no need to filter its output
through col(1).
Device control commands
grotty understands a single device control function produced using
the roff \X escape sequence in a document.
\X'tty: sgr [
n]' If n is non-zero or missing, enable SGR sequences (this is
the default); otherwise, use the legacy output format.
Device description files
If DESC file for the character encoding contains the keyword
“unicode”, 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 groff_font(5) for more
details.
A font description file may contain a command “internalname n” where
n is a decimal integer. If the 01 bit in 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.
Whitespace is permitted between a command-line option and its
argument.
-b Suppress the use of overstriking for bold characters. Ignored
if -c isn't used.
-B Use only overstriking for bold-italic characters. Ignored if
-c isn't used.
-c Use grotty's legacy output format (see subsection “Legacy
output format” above).
-d Ignore all \D roff escapes (draw commands). By default,
grotty renders \D'l...' commands that have at least one zero
argument (and so are either horizontal or vertical) using
Unicode box drawing characters (for the “utf8” device) or the
-, |, and + characters (for all other devices). In a similar
way, grotty handles \D'p...' commands which consist entirely
of horizontal and vertical lines.
-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.
-Fdir Prepend directory dir/devname to the search path for font and
device description files; name is the name of the device,
usually ascii, latin1, utf8, or cp1047.
-h Use literal horizontal tab characters in the output. Tabs are
assumed to be set every 8 columns.
-i Render italic-styled text (fonts “I” and “BI”) with the SGR
attribute for italic text rather than underlined text. Note
that many terminals don't support this attribute; however,
xterm(1), since patch #314 (2014-12-28), does. Ignored if -c
is also specified.
-o Suppress overstriking (other than for bold and/or underlined
characters when the legacy output format is in use).
-r Render italic-styled text (fonts “I” and “BI”) with the SGR
attribute for reverse-video text rather than underlined text.
Ignored if -c or -i is also specified.
-u Suppress the use of underlining for italic characters.
Ignored if -c isn't used.
-U Use only underlining for bold-italic characters. Ignored if
-c isn't used.
-v
--version
Display version information and exit.
--help Display a brief usage message and exit.
GROFF_FONT_PATH
A list of directories in which to search for the devname
directory in addition to the default ones. See troff(1) and
groff_font(5) for more details.
GROFF_NO_SGR
If set, grotty's legacy output format is used; see subsection
“Legacy output format” above.
/usr/local/share/groff/1.22.4/font/devascii/DESC
Device description file for the “ascii” device.
/usr/local/share/groff/1.22.4/font/devascii/F
Font description file for font F of the “ascii” device.
/usr/local/share/groff/1.22.4/font/devcp1047/DESC
Device description file for the “cp1047” device.
/usr/local/share/groff/1.22.4/font/devcp1047/F
Font description file for font F of the “cp1047” device.
/usr/local/share/groff/1.22.4/font/devlatin1/DESC
Device description file for the “latin1” device.
/usr/local/share/groff/1.22.4/font/devlatin1/F
Font description file for font F of the “latin1” device.
/usr/local/share/groff/1.22.4/font/devutf8/DESC
Device description file for the “utf8” device.
/usr/local/share/groff/1.22.4/font/devutf8/F
Font description file for font F of the “utf8” device.
/usr/local/share/groff/1.22.4/tmac/tty.tmac
Macros for use with grotty.
/usr/local/share/groff/1.22.4/tmac/tty-char.tmac
Additional character definitions for use with grotty.
grotty is intended only for simple documents.
There is no support for fractional horizontal or vertical motions.
There is no support for the roff \D escape sequence (draw command)
other than horizontal and vertical lines.
Characters above the first line (i.e., with a vertical position of 0)
cannot be printed.
Color handling differs from grops(1). The groff \M escape sequence
doesn't set the fill color for closed graphic objects (which grotty
doesn't support anyway) but instead changes the background color of
the character cell, affecting all subsequent operations.
The following groff document exercises several features, not all of
which may be supported by a given output device: (1) bold style;
(2) italic (underline) style; (3) bold-italic style; (4) character
composition by overstriking (“coöperate”); (5) foreground color;
(6) background color; and (7) horizontal and vertical line-drawing.
You might see \f[B]bold\f[] and \f[I]italic\f[].
Some people see \f[BI]both\f[].
If the output device does (not) co\z\[ad]operate,
you might see \m[red]red\m[].
Black on cyan can have a \M[cyan]\m[black]prominent\m[]\M[]
\D'l 1i 0'\D'l 0 2i'\D'l 1i 0' look.
.\" If in nroff mode, end page now.
.if n .pl \n[nl]u
Compare and contrast the output of the following:
$ nroff file
$ groff -T ascii file
$ groff -T utf8 -Z file | grotty -i
$ groff -T utf8 -Z file | grotty -c | ul
Note that the example file above is a “raw” groff document, not a man
page. Use of color escapes in man pages is strongly discouraged.
Some implementations of man(1) completely disable them. See subsec‐
tion “Portability” of groff_man(7) for guidance on writing man pages
that are viewable by as many readers as possible.
ECMA-48,
“Control Functions for Coded Character Sets”, 5th edition,
June 1991, Ecma International. A gratis version of ISO 6429,
this document includes a normative description of SGR escape
sequences. Available at
⟨http://www.ecma-international.org/publications/files/ECMA-ST/
Ecma-048.pdf⟩.
groff(1), troff(1), groff_out(5), groff_font(5), groff_char(7),
ul(1), more(1), less(1), man(1)
This page is part of the groff (GNU troff) project. Information
about the project can be found at
⟨http://www.gnu.org/software/groff/⟩. If you have a bug report for
this manual page, see ⟨http://www.gnu.org/software/groff/⟩. This
page was obtained from the project's upstream Git repository
⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2020-08-13. (At that
time, the date of the most recent commit that was found in the repos‐
itory was 2020-08-12.) If you discover any rendering problems in
this HTML version of the page, or you believe there is a better or
more up-to-date source for the page, or you have corrections or
improvements to the information in this COLOPHON (which is not part
of the original manual page), send a mail to man-pages@man7.org
groff 1.22.4.234-3ba6 14 June 2020 grotty(1)
Pages that refer to this page: groff(1) , nroff(1) , groff_out(5)