General Commands Manual

Name¶

grotty -groffoutput driver for typewriter-like (terminal) devices

Synopsis¶

grotty [-dfho][-i|-r][-F dir][file ...]

grotty -c [-bBdfhouU][-F dir][file ...]

grotty --help

grotty -v

grotty --version

Description¶

The GNUroffTTY(“Teletype”)output driver translates the output oftroff(1)into a form suitable for typewriter-like devices,including terminal emulators.Normally,grottyis invoked bygroff(1)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,psis the default output device.)Usegroff's-Poption to pass any options shown above togrotty.If nofilearguments are given,or iffileis “-”,grottyreads the standard input stream.Output is written to the standard output stream.

By default,grottyemits 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 viewroffdocuments using eight different background and foreground colors.Following ISO 6429,the following colors are defined intty.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 seethe-ioption below.

SGR and OSC support in pagers¶

When paginggrotty'soutput withless(1),the latter program must be instructed to pass SGR and OSC sequencesthrough to the device;its-Roption is one way to achieve this(lessversion 566 or later is required for OSC 8 support).Consequently,programs likeman(1)that pageroffdocuments withlessmust call it with an appropriate option.

Legacy output format¶

The-coption tellsgrottyto use an output format compatible with paper terminals,like the Teletype machines for whichroffandnroffwere 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,grottyoverstrikes,representing a bold charactercwith the sequence“c BACKSPACE c”,an italic charactercwith the sequence“_ BACKSPACE c”,and bold italics with“_ BACKSPACE cBACKSPACE c”.This rendering is inherently ambiguous when the charactercis itself the underscore.

The legacy output format can be rendered on a video terminal(or emulator)by pipinggrotty'soutput throughul(1),which may render bold italics as reverse video.Some implementations ofmore(1)are also able to display these sequences;you may wish to experiment with that command's-boption.lessrenders legacy bold and italics without requiring options.In contrast to the terminal output drivers of some otherroffimplementations,grottynever outputs reverse line feeds.There is therefore no need to filter its output throughcol(1).

Device control commands¶

grottyunderstands one device control function produced by theroff\Xescape sequence in a document.

\X'tty: link [uri [key=value] ...]': Embed a hyperlink using the OSC 8 terminal escape sequence.Specifyinguristarts hyperlinked text,and omitting it ends the hyperlink.Whenuriis 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 inuri,key,orvalue;they must be represented in an alternate form.

Device description files¶

If theDESCfile for the character encoding contains the“unicode”directive,grottyemits Unicode characters in UTF-8 encoding.Otherwise,it emits characters in a single-byte encoding depending on the data inthe font description files.Seegroff_font(5).

A font description file may contain a directive“internalname n”wherenis a decimal integer.If the 01 bit innis 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¶

grottysupports the standard four styles:R(roman),I(italic),B(bold),andBI(bold-italic). Because the output driver operates in nroffmode,attempts to set or change the font family or type size are ignored.

Options¶

--helpdisplays a usage message,while-vand--versionshow version information;all exit afterward.

-b: Suppress the use of overstriking for bold characters in legacy outputformat.
-B: Use only overstriking for bold-italic characters in legacy outputformat.
-c: Usegrotty'slegacy output format(see subsection “Legacy output format” above).SGR and OSC escape sequences are not emitted.
-d: Ignore all\Ddrawing escape sequences in the input.By default,grottyrenders\D'l...'escape sequences that have at least one zero argument(and so are either horizontal or vertical)using Unicode box drawing characters(for theutf8device)or the-,|,and+characters(for all other devices).grottyhandles\D'p...'escape sequences that consist entirely of horizontal and verticallines similarly.
-f: Emit a form feed at the end of each page having no output on its lastline.
-F dir: Prepend directorydir/devnameto the search path for font and device description files;namedescribes the output device's character encoding,one ofascii,latin1,utf8,orcp1047.
-h: Use literal horizontal tab characters in the output.Tabs are assumed to be set every 8 columns.
-i: Render oblique-styled fonts(IandBI)with the SGR attribute for italic textrather than underlined text.Many terminals don't support this attribute;however,xterm(1),since patch #314 (2014-12-28),does.Ignored if-cis also specified.
-o: Suppress overstriking(other than for bold and/or underlined characters when the legacy outputformat is in use).
-r: Render oblique-styled fonts(IandBI)with the SGR attribute for reverse video textrather than underlined text.Ignored if-cor-iis also specified.
-u: Suppress the use of underlining for italic characters in legacy outputformat.
-U: Use only underlining for bold-italic characters in legacy output format.

Environment¶

GROFF_FONT_PATH: A list of directories in which to seek the selected output device'sdirectory of device and font description files.Seetroff(1)andgroff_font(5).
GROFF_NO_SGR: If set,grotty'slegacy output format is used just as if the-coption were specified;see subsection “Legacy output format” above.

Files¶

/usr/share/groff/1.23.0/font/devascii/DESC: describes theasciioutput device.
/usr/share/groff/1.23.0/font/devascii/F: describes the font knownas Fon deviceascii.
/usr/share/groff/1.23.0/font/devcp1047/DESC: describes thecp1047output device.
/usr/share/groff/1.23.0/font/devcp1047/F: describes the font knownas Fon devicecp1047.
/usr/share/groff/1.23.0/font/devlatin1/DESC: describes thelatin1output device.
/usr/share/groff/1.23.0/font/devlatin1/F: describes the font knownas Fon devicelatin1.
/usr/share/groff/1.23.0/font/devutf8/DESC: describes theutf8output device.
/usr/share/groff/1.23.0/font/devutf8/F: describes the font knownas Fon deviceutf8.
/usr/share/groff/1.23.0/tmac/tty.tmac: defines macros for use with theascii,cp1047,latin1,andutf8output devices.It is automatically loaded bytroffrcwhen any of those output devices is selected.
/usr/share/groff/1.23.0/tmac/tty-char.tmac: defines fallback characters for use withgrotty.Seenroff(1).

Limitations¶

grottyis intended only for simple documents.

•: There is no support for fractional horizontal or vertical motions.
•: roff\Descape sequences producing anything other than horizontal and verticallines 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.Thegroffrequests and escape sequences that set the stroke and fill colorsinstead set the foreground and background character cell colors,respectively.

Examples¶

The followinggroffdocument exercises several features for which output device supportvaries:(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

Source file:	grotty.1.en.gz (from groff-base 1.23.0-7)
Source last updated:	2024-12-26T00:06:00Z
Converted to HTML:	2024-12-26T02:57:49Z