|
Name | Synopsis | Description | Options | Environment | Files | Limitations | Examples | See also | COLOPHON |
|
|
|
grotty(1) General Commands Manual grotty(1)
grotty - groff output driver for typewriter-like (terminal)
devices
grotty [-dfho] [-i|-r] [-F dir] [file ...]
grotty -c [-bBdfhouU] [-F dir] [file ...]
grotty --help
grotty -v
grotty --version
The GNU roff TTY (“Teletype”) output driver translates the output
of into a form suitable for typewriter-like devices, including
terminal emulators. Normally, grotty is invoked by 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 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. Output is written 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 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 represented with underlining by default—but
see the -i option below.
SGR and OSC support in pagers
When paging grotty's output with 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 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 which may render bold
italics as reverse video. Some implementations of are also 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
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 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
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.
--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 \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 device description files; name describes the output
device's character 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,
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.
GROFF_FONT_PATH
A list of directories in which to seek the selected output
device's directory of device and font description files.
See and
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/devcp1047/DESC
describes the cp1047 output device.
/usr/local/share/groff/1.23.0/font/devcp1047/F
describes the font known as F on device cp1047.
/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, cp1047, 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
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 position 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.
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\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. Available at
⟨http://www.ecma-international.org/publications/files/ECMA-ST/
Ecma-048.pdf⟩.
“Hyperlinks in Terminal Emulators”
⟨https://gist.github.com/egmontkob/eb114294efbcd5ad
b1944c9f3cb5feda⟩, Egmont Koblinger.
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 2022-12-17. (At
that time, the date of the most recent commit that was found in
the repository was 2022-12-14.) 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
man-pages@man7.org
groff 1.23.0.rc1.3569-94746-d1i4rtDyecember 2022 grotty(1)
|
HTML rendering created 2022-12-18 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|