# grotty

## Name



           grotty - _groff_ output driver for typewriter-like (terminal)
           devices
    


## Synopsis



           **grotty**[**-dfhot**] [**-i** |**-r**] [**-F** _font-directory_] [_file_ ...]
    
           **grotty -c**[**-bBdfhouU**] [**-F** _font-directory_] [_file_ ...]
    
           **grotty --help**
    
           **grotty -v**
    
           **grotty --version**
    


## Description



           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
    


## 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 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 _/dev_ name 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.
    


## Exit status



           _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.
    


## 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 _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.
    


## Files



           _/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).
    


## Limitations



           _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.--
    


## 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 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**
    


## See also



           “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)
    


* * *