--- name: "grotty" section: "1" platform: "linux" package: "groff" version: "1.24.2-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/grotty" --- # grotty(1) groff output driver for typewriter-like (terminal) devices ## 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)](/troff/1.md) into a form suitable for typewriter-like devices, including video terminal emulators. Normally, *grotty* is invoked by [*groff*(1)](/groff/1.md) 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)](/less/1.md), 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)](/man/1.md) 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)](/ul/1.md), which may render bold italics as reverse video. Some implementations of [*more*(1)](/more/1.md) 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)](/col/1.md) 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)](/groff_font/5.md). 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** (***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)](/grohtml/1.md), [*gropdf*(1)](/gropdf/1.md), and [*grops*(1)](/grops/1.md). - **CSH** **CSS** **CTH** **CTS** **JPG** **JPM** **KOG** **KOM** Simplified Chinese, Hei style Simplified Chinese, Song style Traditional Chinese, Hei style Traditional Chinese, Song style Japanese, Gothic style Japanese, Mincho style Korean, Gothic style 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)](/groff_out/5.md). - **-f** Emit a form feed at the end of each page having no output on its last line. - **-F** *dir* Prepend directory dir*/dev*name 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)](/xterm/1.md), 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)](/troff/1.md) and [*groff\_font*(5)](/groff_font/5.md). - *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.24.2/font/devascii/DESC* describes the **ascii** output device. - */usr/share/groff/1.24.2/font/devascii/*F describes the font known as *F* on device **ascii**. - */usr/share/groff/1.24.2/font/devlatin1/DESC* describes the **latin1** output device. - */usr/share/groff/1.24.2/font/devlatin1/*F describes the font known as *F* on device **latin1**. - */usr/share/groff/1.24.2/font/devutf8/DESC* describes the **utf8** output device. - */usr/share/groff/1.24.2/font/devutf8/*F describes the font known as *F* on device **utf8**. - */usr/share/groff/1.24.2/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. - */usr/share/groff/1.24.2/tmac/tty-char.tmac* defines fallback characters for use with *grotty.* See [*nroff*(1)](/nroff/1.md). ## Limitations *grotty* is intended only for simple documents. - • There is no support for horizontal or vertical motions smaller than a character cell. - • Drawing commands producing anything other than horizontal and vertical lines are not supported. - • 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 (“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 ``` ## 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/\\:eb114294\\:efbcd5ad\\:b1944c9f\\:3cb5feda⟩, Egmont Koblinger. [*groff*(1)](/groff/1.md), [*troff*(1)](/troff/1.md), [*groff\_out*(5)](/groff_out/5.md), [*groff\_font*(5)](/groff_font/5.md), [*groff\_char*(7)](/groff_char/7.md), [*ul*(1)](/ul/1.md), [*more*(1)](/more/1.md), [*less*(1)](/less/1.md), [*man*(1)](/man/1.md)