grotty(1) General Commands Manual grotty(1)
Name
grotty - groff output driver for typewriter-like (terminal) devices
Synopsis
grotty [-dfho] [-i|-r] [-F dir] [file ...]
grotty -c [-bBdfhouU] [-F dir] [file ...]
grotty --help
grotty -v
grotty --version
Description
The GNU roff TTY (“Teletype”) output driver translates the output of
]8;;man:troff(1)\troff(1)]8;;\ into a form suitable for typewriter-like devices, including
terminal emulators. Normally, grotty is invoked by ]8;;man:groff(1)\groff(1)]8;;\ when the
latter is given one of the “-T ascii”, “-T latin1”, -Tlatin1, or
“-T utf8” options on systems using ISO character encoding standards, or
with “-T cp1047” or “-T utf8” on EBCDIC-based hosts. (In this installa-
tion, 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. Output is writ-
ten 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, under-
line, reverse video [“negative image”] and colors). Devices supporting
the appropriate sequences can view roff documents using eight different
background and foreground colors. 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. OSC 8 hyperlinks
are produced for these devices.
In keeping with long-standing practice and the rarity of terminals (and
emulators) that support oblique or italic fonts, italicized text is rep-
resented with underlining by default—but see the -i option below.
SGR and OSC support in pagers
When paging grotty's output with ]8;;man:less(1)\less(1)]8;;\, the latter program must be in-
structed to pass SGR and OSC sequences through to the device; its -R op-
tion is one way to achieve this (less version 566 or later is required
for OSC 8 support). Consequently, programs like ]8;;man:man(1)\man(1)]8;;\ 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 se-
quences are not emitted; bold, italic, and underlining character attrib-
utes are thus not manipulated. Instead, grotty overstrikes, represent-
ing 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 emula-
tor) by piping grotty's output through ]8;;man:ul(1)\ul(1)]8;;\, which may render bold
italics as reverse video. Some implementations of ]8;;man:more(1)\more(1)]8;;\ are also able
to display these sequences; you may wish to experiment with that com-
mand's -b option. less renders legacy bold and italics without requir-
ing options. In contrast to the terminal output drivers of some other
roff implementations, grotty never outputs reverse line feeds. There is
therefore no need to filter its output through ]8;;man:col(1)\col(1)]8;;\.
Device control commands
grotty understands one device control function produced by the roff \X
escape sequence in a document.
\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 re-
sponsibility of the pager or terminal. Spaces or tabs cannot ap-
pear 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” di-
rective, 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 ]8;;man:groff_font(5)\groff_font(5)]8;;\.
A font description file may contain a directive “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.
Typefaces
grotty supports the standard four styles: R (roman), I (italic), B
(bold), and BI (bold-italic). Because the output driver operates in
nroff mode, attempts to set or change the font family or type size are
ignored.
Options
--help displays a usage message, while -v and --version show version in-
formation; 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 \D drawing escape sequences in the input. By default,
grotty renders \D'l...' escape sequences 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...' escape sequences that consist entirely of horizontal and
vertical lines similarly.
-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 de-
vice description files; name describes the output device's char-
acter encoding, one of 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 oblique-styled fonts (I and BI) with the SGR attribute for
italic text rather than underlined text. Many terminals don't
support this attribute; however, ]8;;man:xterm(1)\xterm(1)]8;;\, 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 oblique-styled 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 in legacy
output format.
-U Use only underlining for bold-italic characters in legacy output
format.
Environment
GROFF_FONT_PATH
A list of directories in which to seek the selected output de-
vice's directory of device and font description files. See
]8;;man:troff(1)\troff(1)]8;;\ and ]8;;man:groff_font(5)\groff_font(5)]8;;\.
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
/usr/share/groff/1.23.0/font/devascii/DESC
describes the ascii output device.
/usr/share/groff/1.23.0/font/devascii/F
describes the font known as F on device ascii.
/usr/share/groff/1.23.0/font/devcp1047/DESC
describes the cp1047 output device.
/usr/share/groff/1.23.0/font/devcp1047/F
describes the font known as F on device cp1047.
/usr/share/groff/1.23.0/font/devlatin1/DESC
describes the latin1 output device.
/usr/share/groff/1.23.0/font/devlatin1/F
describes the font known as F on device latin1.
/usr/share/groff/1.23.0/font/devutf8/DESC
describes the utf8 output device.
/usr/share/groff/1.23.0/font/devutf8/F
describes the font known as F on device utf8.
/usr/share/groff/1.23.0/tmac/tty.tmac
defines macros for use with the ascii, cp1047, latin1, and utf8
output devices. It is automatically loaded by troffrc when any
of those output devices is selected.
/usr/share/groff/1.23.0/tmac/tty-char.tmac
defines fallback characters for use with grotty. See ]8;;man:nroff(1)\nroff(1)]8;;\.
Limitations
grotty is intended only for simple documents.
• There is no support for fractional horizontal or vertical motions.
• roff \D escape sequences producing anything other than horizontal and
vertical lines are not supported.
• Characters above the first line (that is, with a vertical drawing po-
sition of 0) cannot be rendered.
• Color handling differs from other output drivers. The groff requests
and escape sequences that set the stroke and fill colors instead set
the foreground and background character cell colors, respectively.
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
(“coöperate”); (5) foreground color; (6) background color; and (7) hori-
zontal 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
Given the foregoing input, compare and contrast the output of the fol-
lowing.
$ 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. A gratis version of ISO 6429, this document
includes a normative description of SGR escape sequences. Available at
]8;;http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-048.pdf\http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-048
.pdf]8;;\.
]8;;https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda\“Hyperlinks in Terminal Emulators”]8;;\, Egmont Koblinger.
]8;;man:groff(1)\groff(1)]8;;\, ]8;;man:troff(1)\troff(1)]8;;\, ]8;;man:groff_out(5)\groff_out(5)]8;;\, ]8;;man:groff_font(5)\groff_font(5)]8;;\, ]8;;man:groff_char(7)\groff_char(7)]8;;\, ]8;;man:ul(1)\ul(1)]8;;\,
]8;;man:more(1)\more(1)]8;;\, ]8;;man:less(1)\less(1)]8;;\, ]8;;man:man(1)\man(1)]8;;\
groff 1.23.0 3 June 2025 grotty(1)
Generated by dwww version 1.16 on Tue Dec 16 04:18:02 CET 2025.