| grotty(1) | User Commands | grotty(1) |
grotty - groff output driver for typewriter-like (terminal) devices
grotty |
[-dfhot] [-i|-r] [-F font-directory] [file ...] |
grotty -c |
[-bBdfhouU] [-F font-directory] [file ...] |
grotty |
--help |
grotty |
-v |
grotty |
--version |
The GNU roff TTY (“Teletype”) output driver translates the output of gtroff(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.
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.
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.
grotty recognizes a device extension command produced by the groff request device or roff \X escape sequence.
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.
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.
grotty shares a naming scheme for East Asian typefaces with grohtml(1), gropdf(1), and grops(1).
--help displays a usage message, while -v and --version show version information; all exit afterward.
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.
grotty is intended only for simple documents.
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.--
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) 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
“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.
“Hyperlinks in Terminal Emulators”, Egmont Koblinger.
groff(1), gtroff(1), groff_out(5), groff_font(5), groff_char(7), ul(1), more(1), less(1), man(1)
| 2026-03-14 | groff 1.24.1 |