grotty(1) — Linux manual page

Name | Synopsis | Description | Options | Environment | Files | Limitations | Examples | See also | COLOPHON

grotty(1)                General Commands Manual               grotty(1)

Name         top

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

Synopsis         top

       grotty [-dfho] [-i|-r] [-F font-directory] [file ...]

       grotty -c [-bBdfhouU] [-F font-directory] [file ...]

       grotty --help

       grotty -v

       grotty --version

Description         top

       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 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.  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 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 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) 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 col(1).

   Device control commands
       grotty supports a device control command accessed with the
       “device” request or \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, 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         top

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

Environment         top

       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         top

       /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
              nroff(1).

Limitations         top

       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.

       •  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 \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         top

       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         top

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

COLOPHON         top

       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 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-06-10.)  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
       [email protected]

groff 1.23.0.1273-9d53-dirty   6 June 2024                     grotty(1)