grotty(1) General Commands Manual grotty(1)

# [Name](#Name)

grotty - *groff* output driver for typewriter-like (terminal) devices

# [Synopsis](#Synopsis)

`grotty` \[**-dfhot**] \[**-i**|**-r**] \[**-F font-directory**] \[*file* ...]

`grotty -c` \[**-bBdfhouU**] \[**-F font-directory**] \[*file* ...]

`grotty` **--help**

`grotty` **-v**

`grotty` **--version**

# [Description](#Description)

The GNU *roff* TTY (“Teletype”) output driver translates the output of [*troff*(1)](/man/os/groff/troff.1) into a form suitable for typewriter-like devices, including video terminal emulators. Normally, *grotty* is invoked by [*groff*(1)](/man/os/groff/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](#SGR_and_OSC_support_in_pagers)

When paging *grotty*'s output with [*less*(1)](/man/os/groff/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)](/man/os/groff/man.1) that page *roff* documents with *less* must call it with an appropriate option.

## [Legacy output format](#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)](/man/os/groff/ul.1), which may render bold italics as reverse video. Some implementations of [*more*(1)](/man/os/groff/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)](/man/os/groff/col.1) to remove them.

## [Device extension commands](#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](#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)](/man/os/groff/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](#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)](/man/os/groff/grohtml.1), [*gropdf*(1)](/man/os/groff/gropdf.1), and [*grops*(1)](/man/os/groff/grops.1).

[**CSH**](#CSH)

Simplified Chinese, Hei style

[**CSS**](#CSS)

Simplified Chinese, Song style

[**CTH**](#CTH)

Traditional Chinese, Hei style

[**CTS**](#CTS)

Traditional Chinese, Song style

[**JPG**](#JPG)

Japanese, Gothic style

[**JPM**](#JPM)

Japanese, Mincho style

[**KOG**](#KOG)

Korean, Gothic style

[**KOM**](#KOM)

Korean, Mincho style

# [Options](#Options)

**--help** displays a usage message, while **-v** and **--version** show version information; all exit afterward.

[**-b**](#b)

Suppress the use of overstriking for bold characters in legacy output format.

[**-B**](#B)

Use only overstriking for bold-italic characters in legacy output format.

[**-c**](#c)

Use *grotty*'s legacy output format (see subsection “Legacy output format” above). SGR and OSC escape sequences are not emitted.

[**-d**](#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)](/man/os/groff/groff_out.5).

[**-f**](#f)

Emit a form feed at the end of each page having no output on its last line.

[**-F dir**](#F)

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**](#h)

Use literal horizontal tab characters in the output. Tabs are assumed to be set every 8 columns.

[**-i**](#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)](/man/os/groff/xterm.1), since patch #314 (2014-12-28), does. Ignored if **-c** is also specified.

[**-o**](#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**](#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**](#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**](#u)

Suppress the use of underlining for italic characters in legacy output format.

[**-U**](#U)

Use only underlining for bold-italic characters in legacy output format.

# [Exit status](#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](#Environment)

[*GROFF\_FONT\_PATH*](#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)](/man/os/groff/troff.1) and [*groff\_font*(5)](/man/os/groff/groff_font.5).

[*GROFF\_NO\_SGR*](#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](#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)](/man/os/groff/nroff.1).

# [Limitations](#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)](/man/os/groff/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](#Examples)

The following *groff* document exercises several features for which output device support [varies: (1)](/man/os/groff/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](#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)](/man/os/groff/groff.1), [*troff*(1)](/man/os/groff/troff.1), [*groff\_out*(5)](/man/os/groff/groff_out.5), [*groff\_font*(5)](/man/os/groff/groff_font.5), [*groff\_char*(7)](/man/os/groff/groff_char.7), [*ul*(1)](/man/os/groff/ul.1), [*more*(1)](/man/os/groff/more.1), [*less*(1)](/man/os/groff/less.1), [*man*(1)](/man/os/groff/man.1)

2026-10-24 groff 1.24.2

---

Document: grotty(1) from groff 1.24.2-r1 (Chainguard OS)
Source: https://git.savannah.gnu.org/git/groff.git