www.LinuxHowtos.org howtos, tips&tricks and tutorials for linux

from small one page howto to huge articles all in one place

Other .linuxhowtos.org sites:gentoo.linuxhowtos.org

Last additions:

using iotop to find disk usage hogs

words:

887

views:

215140

userrating:

May 25th. 2007:

Words

486

Views

261761

why adblockers are bad

Workaround and fixes for the current Core Dump Handling vulnerability affected kernels

words:

161

views:

153990

userrating:

April, 26th. 2006:

Words

Views

110034

New subdomain: toolsntoys.linuxhowtos.org

You are here: manpages

grotty

Section: User Commands (1)
Updated: 202-0-28
Index Return to Main Contents

Name

grotty - groff output driver for typewrite-like (terminal) devices
.nr d-fallback 1
.nr d-fallback 1

Synopsis

[-dfhot] [-i|-r] [-F~fon-directory] [file~...] [-bBdfhouU] [-F~fon-directory] [file~...] --help -v --version

Description

The GNU roff TTY ([lq]Teletype[rq]) output driver translates the output of into a form suitable for typewrite-like devices, including video terminal emulators. Normally, grotty is invoked by when the latter is given one of the [lq]-T~ascii[rq], [lq]-T~latin1[rq], or [lq]-T~utf8[rq] 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 [lq]-[rq], 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 [lq]ANSI escapes[rq]) to change text attributes (bold, italic, underline, reverse video [[lq]negative image[rq]] and colors). Devices supporting SGR 30[en]37 and 40[en]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 lon-standing practice and terminals (emulators) that lack support for slanted (oblique or italic) faces, grotty marks italicized character cells with underlines instead by default[em]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 [lq]c~BACKSPACE~c[rq], an italic character c with the sequence [lq]_~BACKSPACE~c[rq], and bold italics with [lq]_~BACKSPACE~c BACKSPACE~c[rq]. 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 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 to remove them.

Device extension commands

grotty recognizes a device extension command produced by the groff request device or roff [rs]X escape sequence.

[rs]X[aq]tty: link [: uri~[key=value] ...][aq] 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 [lq]unicode[rq] directive, grotty emits Unicode characters in UT-8 encoding. Otherwise, it emits characters in a singl-byte encoding depending on the data in the font description files. See A font description file may contain a directive [lq]internalname~n[rq] 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 (BI]bol-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 and

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

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 bol-italic characters in legacy output format.
-c: Use grotty's legacy output format (see subsection [lq]Legacy output format[rq] above). SGR and OSC escape sequences are not emitted.
-d: Ignore all drawing commands in the input. By default, grotty renders [lq]D l[rq] 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 [lq]D p[rq] commands that consist entirely of horizontal and vertical lines similarly. See
-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, since patch~#314 (201-1-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 bol-italic characters in legacy output format.

Exit status

grotty exits with status~0 on successful operation, status~2 if the program cannot interpret its comman-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 and
GROFF_NO_SGR: If set, grotty's legacy output format is used just as if the -c option were specified; see subsection [lq]Legacy output format[rq] 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

Limitations

grotty is intended only for simple documents.

[bu]

There is no support for horizontal or vertical motions smaller than a character cell.

[bu]

Drawing commands producing anything other than horizontal and vertical lines are not supported.

[bu]

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 [rs]l and [rs]L escape sequences on one hand, and the [rs]D[aq]l[aq] lin-drawing escape sequence on the other, make different compromises due to the first two factors. Specifically, (1) [rs]l draws horizontal lines with underscore characters; [rs]D[aq]l[aq] uses ACS or Unicode lin-drawing characters if possible, and hyphe-minus signs if not. (2) [rs]D[aq]l[aq] 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 [lq]+[rq]). Observe the difference below. The input

: Hello,[rs]L[aq]1v[aq] world.[rs]l[aq]1n[aq] .sp 2v Hello,[rs]D[aq]l 0 1v[aq] world.[rs]D[aq]l 1n 0[aq] .pl [rs]n(nlu [rs]" truncate page for convenience

rendered with [lq]nroff -T ascii[rq] 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)~bol-italic style; (4)~character composition by overstriking ([lq]co[:o]perate[rq]); (5)~foreground color; (6)~background color; and (7)~horizontal and vertical line drawing.

: You might see f[B]boldf[] and f[I]italicf[]. Some people see f[BI]both at oncef[]. If the output device does (not) coz[ad]operate, you might see m[red]redm[]. Black on cyan can have a M[cyan]m[black]prominentm[]M[] D[aq]l 1i 0[aq]D[aq]l 0 2i[aq]D[aq]l 1i 0[aq] 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.