# GROTTY - groff output driver for typewriter-like (terminal) dev... - man(1) - [phpMan] [_grotty_(1)](https://www.chedong.com/phpMan.php/man/grotty/1/markdown) General Commands Manual [_grotty_(1)](https://www.chedong.com/phpMan.php/man/grotty/1/markdown) ## Name grotty - _groff_ output 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 GNU _roff_ TTY (“Teletype”) output driver translates the output of [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) into a form suitable for typewriter-like devices, including terminal emulators. Normally, _grotty_ is in‐ voked by [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) 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 es‐ capes”) 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. Unrecog‐ nized colors are mapped to the default color, which is dependent on the settings of the ter‐ minal. OSC 8 hyperlinks are produced for these devices. In keeping with long-standing practice and the rarity of terminals (and emulators) that sup‐ port 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 [_less_(1)](https://www.chedong.com/phpMan.php/man/less/1/markdown), 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_ ver‐ sion 566 or later is required for OSC 8 support). Consequently, programs like [_man_(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) 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 at‐ tributes are thus not manipulated. Instead, _grotty_ overstrikes, representing a bold charac‐ ter _c_ with the sequence “_c_ BACKSPACE _c_”, an italic character _c_ with the sequence “**_ **BACK‐ SPACE _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)](https://www.chedong.com/phpMan.php/man/ul/1/markdown), which may render bold italics as reverse video. Some implementations of [_more_(1)](https://www.chedong.com/phpMan.php/man/more/1/markdown) 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 out‐ puts reverse line feeds. There is therefore no need to filter its output through [_col_(1)](https://www.chedong.com/phpMan.php/man/col/1/markdown). ### 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 hy‐ perlinked 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 responsi‐ bility 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 encod‐ ing depending on the data in the font description files. See [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). A font description file may contain a directive “**internalname _**n_” where _n_ is a decimal inte‐ ger. 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. ## Options **--help **displays a usage message, while **-v **and **--version **show version information; all exit afterward. ### -b ### -B ### -c and OSC escape sequences are not emitted. ### -d **\D'l**...**' **escape sequences that have at least one zero argument (and so are either hor‐ izontal or vertical) using Unicode box drawing characters (for the **utf8 **device) or the **-**, **|**, and **+ **characters (for all other devices). _grotty_ handles **\D'p**...**' **escape se‐ quences that consist entirely of horizontal and vertical lines similarly. ### -f ### -F _ files; _name_ describes the output device's character encoding, one of **ascii**, **latin1**, **utf8**, or **cp1047**. ### -h 8 columns. ### -i than underlined text. Many terminals don't support this attribute; however, [_xterm_(1)](https://www.chedong.com/phpMan.php/man/xterm/1/markdown), since patch #314 (2014-12-28), does. Ignored if **-c **is also specified. ### -o legacy output format is in use). ### -r rather than underlined text. Ignored if **-c **or **-i **is also specified. ### -u ### -U ## Environment _GROFF_FONT_PATH_ A list of directories in which to seek the selected output device's directory of de‐ vice and font description files. See [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) and [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). _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 _/usr/share/groff/1.23.0/font/devascii/DESC_ describes the **ascii **output device. _/usr/share/groff/1.23.0/font/devascii/_F describes the font known as _F_ on device **ascii**. _/usr/share/groff/1.23.0/font/devcp1047/DESC_ describes the **cp1047 **output device. _/usr/share/groff/1.23.0/font/devcp1047/_F describes the font known as _F_ on device **cp1047**. _/usr/share/groff/1.23.0/font/devlatin1/DESC_ describes the **latin1 **output device. _/usr/share/groff/1.23.0/font/devlatin1/_F describes the font known as _F_ on device **latin1**. _/usr/share/groff/1.23.0/font/devutf8/DESC_ describes the **utf8 **output device. _/usr/share/groff/1.23.0/font/devutf8/_F describes the font known as _F_ on device **utf8**. _/usr/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/share/groff/1.23.0/tmac/tty-char.tmac_ defines fallback characters for use with _grotty._ See [_nroff_(1)](https://www.chedong.com/phpMan.php/man/nroff/1/markdown). ## Limitations _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. ## Examples 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** **See also** “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 ECMA-ST/Ecma-048.pdf. [“Hyperlinks in Terminal Emulators”](), Egmont Koblinger. [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown), [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown), [_groff_out_(5)](https://www.chedong.com/phpMan.php/man/groffout/5/markdown), [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown), [_groff_char_(7)](https://www.chedong.com/phpMan.php/man/groffchar/7/markdown), [_ul_(1)](https://www.chedong.com/phpMan.php/man/ul/1/markdown), [_more_(1)](https://www.chedong.com/phpMan.php/man/more/1/markdown), [_less_(1)](https://www.chedong.com/phpMan.php/man/less/1/markdown), [_man_(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) groff 1.23.0 31 March 2024 [_grotty_(1)](https://www.chedong.com/phpMan.php/man/grotty/1/markdown)