grotty(1) General Commands Manual grotty(1)
Name
grotty - groff output driver for typewriter-like (terminal) devices
Synopsis
grotty [-dfhot] [-i|-r] [-F font-directory] [file ...]
grotty -c [-bBdfhouU] [-F font-directory] [file ...]
grotty --help
grotty -v
grotty --version
Description
The GNU roff TTY ("Teletype") output driver translates the output of
troff(1) into a form suitable for typewriter-like devices, including
video terminal emulators. Normally, grotty is invoked by groff(1) when
the latter is given one of the "-T ascii", "-T latin1", or "-T utf8"
options. (In this installation, ps is the default output device.) Use
groff's -P option to pass any options shown above to grotty. If no
file arguments are given, or if file is "-", grotty reads the standard
input stream. It writes to the standard output stream.
By default, grotty emits SGR escape sequences (from ISO 6429, popularly
called "ANSI escapes") to change text attributes (bold, italic,
underline, reverse video ["negative image"] and colors). Devices
supporting SGR 30-37 and 40-47 sequences can view roff documents using
eight different background and foreground colors. grotty's tty.tmac
file defines the eight color names of ISO 6429: black, white, red,
green, blue, yellow, magenta, and cyan. Unrecognized colors map to the
default color, the value of which depends on the settings of the
terminal. Also see the -t option below.
By default, grotty produces OSC 8 hyperlinks on devices employing SGR
escape sequences.
In accord with long-standing practice and terminals (emulators) that
lack support for slanted (oblique or italic) faces, grotty marks
italicized character cells with underlines instead by default--but see
the -i option below.
SGR and OSC support in pagers
When paging grotty's output with less(1), the latter program must be
instructed to pass SGR and OSC sequences through to the device; its -R
option is one way to achieve this (less version 566 or later is
required for OSC 8 support). Consequently, programs like man(1) that
page roff documents with less must call it with an appropriate 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; bold, italic, and underlining character
attributes are thus not manipulated. Instead, grotty overstrikes,
representing a bold character c with the sequence "c BACKSPACE c", an
italic character c with the sequence "_ BACKSPACE c", and bold italics
with "_ BACKSPACE c BACKSPACE c". This rendering is inherently
ambiguous when the character c is itself the underscore.
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) also
are 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 terminal output drivers of some
other roff implementations, grotty never outputs reverse line feeds.
You need not filter its output through col(1) to remove them.
Device extension commands
grotty recognizes a device extension command produced by the groff
request device or roff \X escape sequence.
\X'tty: link [uri [key=value] ...]'
Embed a hyperlink using the OSC 8 terminal escape sequence.
Specifying uri starts hyperlinked text, and omitting it ends the
hyperlink. When uri is present, any number of additional
key/value pairs can be specified; their interpretation is the
responsibility of the pager or terminal. Spaces or tabs cannot
appear literally in uri, key, or value; they must be represented
in an alternate form.
Device description files
If the DESC file for the character encoding contains the "unicode"
directive, 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).
A font description file may contain a directive "internalname n" where
n is a decimal integer. If the 01 bit in n is set, grotty treats the
font as slanted; if the 02 bit is set, grotty treats the font as bold.
Typefaces
grotty supports the standard four styles: R (roman), I (italic), B
(bold), and BI (bboolldd--iittaalliicc). Because the output driver operates in
nroff mode, attempts to set or change the font family or type size are
ignored.
grotty shares a naming scheme for East Asian typefaces with grohtml(1),
gropdf(1), and grops(1).
CSH Simplified Chinese, Hei style
CSS Simplified Chinese, Song style
CTH Traditional Chinese, Hei style
CTS Traditional Chinese, Song style
JPG Japanese, Gothic style
JPM Japanese, Mincho style
KOG Korean, Gothic style
KOM Korean, Mincho style
Options
--help displays a usage message, while -v and --version show version
information; all exit afterward.
-b Suppress the use of overstriking for bold characters in legacy
output format.
-B Use only overstriking for bold-italic characters in legacy
output format.
-c Use grotty's legacy output format (see subsection "Legacy
output format" above). SGR and OSC escape sequences are not
emitted.
-d Ignore all drawing commands in the input. 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). grotty handles "D p"
commands that consist entirely of horizontal and vertical lines
similarly. See groff_out(5).
-f Emit a form feed at the end of each page having no output on
its last line.
-F dir Prepend directory dir/devname to the search path for font and
device description files; name describes the output device's
character encoding, one of ascii, latin1, or utf8.
-h Use literal horizontal tab characters in the output. Tabs are
assumed to be set every 8 columns.
-i Render fonts marked as slanted with the SGR attribute for
italic text rather than underlined text. 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; see options
-b and -u).
-r Render fonts marked as slanted with the SGR attribute for
reverse video text rather than underlined text. Ignored if -c
or -i is also specified.
-t Assume that the output device supports SGR 38 and 48 escape
sequences, which permit specification of character cell
foreground and background colors in the RGB color space with 8
bits per channel.
-u Suppress the use of underlining for italic characters in legacy
output format.
-U Use only underlining for bold-italic characters in legacy
output format.
Exit status
grotty exits with status 0 on successful operation, status 2 if the
program cannot interpret its command-line arguments, and status 1 if it
encounters an error during operation.
Environment
GROFF_FONT_PATH
A list of directories in which to seek the selected output
device's directory of device and font description files. See
troff(1) and groff_font(5).
GROFF_NO_SGR
If set, grotty's legacy output format is used just as if the -c
option were specified; see subsection "Legacy output format"
above.
Files
/opt/local/share/groff/1.24.1/font/devascii/DESC
describes the ascii output device.
/opt/local/share/groff/1.24.1/font/devascii/F
describes the font known as F on device ascii.
/opt/local/share/groff/1.24.1/font/devlatin1/DESC
describes the latin1 output device.
/opt/local/share/groff/1.24.1/font/devlatin1/F
describes the font known as F on device latin1.
/opt/local/share/groff/1.24.1/font/devutf8/DESC
describes the utf8 output device.
/opt/local/share/groff/1.24.1/font/devutf8/F
describes the font known as F on device utf8.
/opt/local/share/groff/1.24.1/tmac/tty.tmac
defines macros for use with the ascii, latin1, and utf8 output
devices. It is automatically loaded by troffrc when any of
those output devices is selected.
/opt/local/share/groff/1.24.1/tmac/tty-char.tmac
defines fallback characters for use with grotty. See nroff(1).
Limitations
grotty is intended only for simple documents.
o There is no support for horizontal or vertical motions smaller than
a character cell.
o Drawing commands producing anything other than horizontal and
vertical lines are not supported.
o Color handling differs from other output drivers. The GNU troff
output commands produced by requests and escape sequences that set
the stroke and fill colors instead set the foreground and background
character cell colors, respectively.
The commands generated by the \l and \L escape sequences on one hand,
and the \D'l' line-drawing escape sequence on the other, make different
compromises due to the first two factors. Specifically, (1) \l draws
horizontal lines with underscore characters; \D'l' uses ACS or Unicode
line-drawing characters if possible, and hyphen-minus signs if not.
(2) \D'l' draws vertical lines an extra character cell high, and
horizontal lines an extra cell to the right. grotty does this to
detect intersecting lines so that it can replace them with glyphs of
appropriate appearance (like "+"). Observe the difference below.
The input
Hello,\L'1v'
world.\l'1n'
.sp 2v
Hello,\D'l 0 1v'
world.\D'l 1n 0'
.pl \n(nlu \" truncate page for convenience
rendered with "nroff -T ascii" produces the following output.
Hello,
| world._
Hello,|
|world.--
Examples
The following groff document exercises several features for which
output device support varies: (1) bold style; (2) italic (underline)
style; (3) bold-italic style; (4) character composition by overstriking
("cooperate"); (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 at once\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
Given the foregoing input, compare and contrast the output of the
following.
$ groff -T ascii file
$ groff -T utf8 -P -i file
$ groff -T utf8 -P -c file | ul
See also
"Control Functions for Coded Character Sets" (ECMA-48) 5th edition,
Ecma International, June 1991. <https://ecma-international.org/
wp-content/uploads/ECMA-48_5th_edition_june_1991.pdf> A gratis version
of ISO 6429, this document includes a normative description of SGR
escape sequences.
"Hyperlinks in Terminal Emulators" <https://gist.github.com/egmontkob/
eb114294efbcd5adb1944c9f3cb5feda>, Egmont Koblinger.
groff(1), troff(1), groff_out(5), groff_font(5), groff_char(7), ul(1),
more(1), less(1), man(1)
groff 1.24.1 2026-05-15 grotty(1)
groff 1.24.1 - Generated Mon May 18 13:01:23 CDT 2026