|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
Name | Synopsis | Description | Options | Exit status | Environment | Files | Limitations | Examples | See also | COLOPHON |
|
|
|
grotty(1) General Commands Manual 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 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.
OSC 8 hyperlinks are produced for these devices.
In keeping with long-standing practice and the rarity of terminals
(and emulators) that support 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. There is therefore no need to
filter its output through col(1).
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 (bold-italic). Because the output driver operates
in nroff mode, attempts to set or change the font family or type
size are ignored.
grotty furthermore supports a naming scheme for East Asian
typefaces shared 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
--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).
-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.
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.
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.
/usr/local/share/groff/1.23.0/font/devascii/DESC
describes the ascii output device.
/usr/local/share/groff/1.23.0/font/devascii/F
describes the font known as F on device ascii.
/usr/local/share/groff/1.23.0/font/devlatin1/DESC
describes the latin1 output device.
/usr/local/share/groff/1.23.0/font/devlatin1/F
describes the font known as F on device latin1.
/usr/local/share/groff/1.23.0/font/devutf8/DESC
describes the utf8 output device.
/usr/local/share/groff/1.23.0/font/devutf8/F
describes the font known as F on device utf8.
/usr/local/share/groff/1.23.0/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/local/share/groff/1.23.0/tmac/tty-char.tmac
defines fallback characters for use with grotty. See
nroff(1).
grotty is intended only for simple documents.
• There is no support for fractional horizontal or vertical
motions.
• Drawing commands producing anything other than horizontal and
vertical lines are not supported.
• 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.
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.
⟨http://www.ecma-international.org/publications/files/ECMA-ST/
Ecma-048.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/eb114294efbcd5adb1944c9f
3cb5feda⟩, Egmont Koblinger.
groff(1), troff(1), groff_out(5), groff_font(5), groff_char(7),
ul(1), more(1), less(1), man(1)
This page is part of the groff (GNU troff) project. Information
about the project can be found at
⟨http://www.gnu.org/software/groff/⟩. If you have a bug report for
this manual page, see ⟨http://www.gnu.org/software/groff/⟩. This
page was obtained from the project's upstream Git repository
⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2025-08-11. (At
that time, the date of the most recent commit that was found in
the repository was 2025-08-09.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
groff 1.23.0.3821-a8b3f 2025-08-09 grotty(1)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|