{
    "mode": "man",
    "parameter": "GROTTY",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/GROTTY/1/json",
    "generated": "2026-10-22T13:18:39Z",
    "sections": {
        "Name": {
            "content": "grotty - groff output driver for typewriter-like (terminal) devices\n",
            "subsections": []
        },
        "Synopsis": {
            "content": "grotty [-dfho] [-i|-r] [-F dir] [file ...]\n\ngrotty -c [-bBdfhouU] [-F dir] [file ...]\n",
            "subsections": [
                {
                    "name": "grotty --help",
                    "content": ""
                },
                {
                    "name": "grotty -v",
                    "content": ""
                },
                {
                    "name": "grotty --version",
                    "content": ""
                }
            ]
        },
        "Description": {
            "content": "The  GNU  roff  TTY  (“Teletype”) output driver translates the output of troff(1) into a form\nsuitable for typewriter-like devices, including terminal emulators.  Normally, grotty is  in‐\nvoked  by  groff(1) when the latter is given one of the “-T ascii”, “-T latin1”, -Tlatin1, or\n“-T utf8” options on systems using ISO character encoding standards, or with “-T  cp1047”  or\n“-T  utf8”  on  EBCDIC-based hosts.  (In this installation, ps is the default output device.)\nUse groff's -P option to pass any options shown above to grotty.  If no  file  arguments  are\ngiven,  or  if file is “-”, grotty reads the standard input stream.  Output is written to the\nstandard output stream.\n\nBy default, grotty emits SGR escape sequences (from ISO  6429,  popularly  called  “ANSI  es‐\ncapes”)  to change text attributes (bold, italic, underline, reverse video [“negative image”]\nand colors).  Devices supporting the appropriate sequences  can  view  roff  documents  using\neight  different  background and foreground colors.  Following ISO 6429, the following colors\nare defined in tty.tmac: black, white, red, green, blue, yellow, magenta, and cyan.  Unrecog‐\nnized colors are mapped to the default color, which is dependent on the settings of the  ter‐\nminal.  OSC 8 hyperlinks are produced for these devices.\n\nIn  keeping with long-standing practice and the rarity of terminals (and emulators) that sup‐\nport oblique or italic fonts, italicized text is represented with underlining by  default—but\nsee the -i option below.\n",
            "subsections": [
                {
                    "name": "SGR and OSC support in pagers",
                    "content": "When  paging  grotty's output with less(1), the latter program must be instructed to pass SGR\nand OSC sequences through to the device; its -R option is one way to achieve this (less  ver‐\nsion  566  or  later is required for OSC 8 support).  Consequently, programs like man(1) that\npage roff documents with less must call it with an appropriate option.\n"
                },
                {
                    "name": "Legacy output format",
                    "content": "The -c option tells grotty to use an output format compatible with paper terminals, like  the\nTeletype  machines  for  which roff and nroff were first developed but which are no longer in\nwide use.  SGR escape sequences are not emitted; bold, italic, and underlining character  at‐\ntributes  are thus not manipulated.  Instead, grotty overstrikes, representing a bold charac‐\nter c with the sequence “c BACKSPACE c”, an italic character c with  the  sequence  “  BACK‐\nSPACE  c”,  and  bold italics with “ BACKSPACE c BACKSPACE c”.  This rendering is inherently\nambiguous when the character c is itself the underscore.\n\nThe legacy output format can be rendered on a video terminal (or emulator) by piping grotty's\noutput through ul(1), which may render bold italics as reverse video.   Some  implementations\nof  more(1)  are  also  able to display these sequences; you may wish to experiment with that\ncommand's -b option.  less renders legacy bold and italics  without  requiring  options.   In\ncontrast to the terminal output drivers of some other roff implementations, grotty never out‐\nputs reverse line feeds.  There is therefore no need to filter its output through col(1).\n"
                },
                {
                    "name": "Device control commands",
                    "content": "grotty  understands  one device control function produced by the roff \\X escape sequence in a\ndocument.\n\n\\X'tty: link [uri [key=value] ...]'\nEmbed a hyperlink using the OSC 8 terminal escape sequence.  Specifying uri starts hy‐\nperlinked text, and omitting it ends the hyperlink.  When uri is present,  any  number\nof  additional key/value pairs can be specified; their interpretation is the responsi‐\nbility of the pager or terminal.  Spaces or tabs cannot appear literally in uri,  key,\nor value; they must be represented in an alternate form.\n"
                },
                {
                    "name": "Device description files",
                    "content": "If  the  DESC  file for the character encoding contains the “unicode” directive, grotty emits\nUnicode characters in UTF-8 encoding.  Otherwise, it emits characters in a single-byte encod‐\ning depending on the data in the font description files.  See grofffont(5).\n\nA font description file may contain a directive “internalname n” where n is a  decimal  inte‐\nger.  If the 01 bit in n is set, then the font is treated as an italic font; if the 02 bit is\nset, then it is treated as a bold font.\n"
                },
                {
                    "name": "Typefaces",
                    "content": "grotty  supports  the  standard  four  styles: R (roman), I (italic), B (bold), and BI (bold-\nitalic).  Because the output driver operates in nroff mode, attempts to  set  or  change  the\nfont family or type size are ignored.\n"
                }
            ]
        },
        "Options": {
            "content": "--help  displays  a  usage message, while -v and --version show version information; all exit\nafterward.\n",
            "subsections": [
                {
                    "name": "-b",
                    "content": "",
                    "flag": "-b"
                },
                {
                    "name": "-B",
                    "content": "",
                    "flag": "-B"
                },
                {
                    "name": "-c",
                    "content": "and OSC escape sequences are not emitted.\n",
                    "flag": "-c"
                },
                {
                    "name": "-d",
                    "content": "\\D'l...' escape sequences that have at least one zero argument (and so are either hor‐\nizontal or vertical) using Unicode box drawing characters (for the utf8 device) or the\n-, |, and + characters (for all other devices).  grotty handles  \\D'p...'  escape  se‐\nquences that consist entirely of horizontal and vertical lines similarly.\n",
                    "flag": "-d"
                },
                {
                    "name": "-f",
                    "content": "",
                    "flag": "-f"
                },
                {
                    "name": "-F _",
                    "content": "files; name describes the output device's character encoding, one  of  ascii,  latin1,\nutf8, or cp1047.\n",
                    "flag": "-F"
                },
                {
                    "name": "-h",
                    "content": "8 columns.\n",
                    "flag": "-h"
                },
                {
                    "name": "-i",
                    "content": "than underlined text.  Many terminals don't support this attribute; however, xterm(1),\nsince patch #314 (2014-12-28), does.  Ignored if -c is also specified.\n",
                    "flag": "-i"
                },
                {
                    "name": "-o",
                    "content": "legacy output format is in use).\n",
                    "flag": "-o"
                },
                {
                    "name": "-r",
                    "content": "rather than underlined text.  Ignored if -c or -i is also specified.\n",
                    "flag": "-r"
                },
                {
                    "name": "-u",
                    "content": "",
                    "flag": "-u"
                },
                {
                    "name": "-U",
                    "content": "",
                    "flag": "-U"
                }
            ]
        },
        "Environment": {
            "content": "GROFFFONTPATH\nA list of directories in which to seek the selected output device's directory  of  de‐\nvice and font description files.  See troff(1) and grofffont(5).\n\nGROFFNOSGR\nIf set, grotty's legacy output format is used just as if the -c option were specified;\nsee subsection “Legacy output format” above.\n",
            "subsections": []
        },
        "Files": {
            "content": "/usr/share/groff/1.23.0/font/devascii/DESC\ndescribes the ascii output device.\n\n/usr/share/groff/1.23.0/font/devascii/F\ndescribes the font known as F on device ascii.\n\n/usr/share/groff/1.23.0/font/devcp1047/DESC\ndescribes the cp1047 output device.\n\n/usr/share/groff/1.23.0/font/devcp1047/F\ndescribes the font known as F on device cp1047.\n\n/usr/share/groff/1.23.0/font/devlatin1/DESC\ndescribes the latin1 output device.\n\n/usr/share/groff/1.23.0/font/devlatin1/F\ndescribes the font known as F on device latin1.\n\n/usr/share/groff/1.23.0/font/devutf8/DESC\ndescribes the utf8 output device.\n\n/usr/share/groff/1.23.0/font/devutf8/F\ndescribes the font known as F on device utf8.\n\n/usr/share/groff/1.23.0/tmac/tty.tmac\ndefines macros for use with the ascii, cp1047, latin1, and utf8 output devices.  It is\nautomatically loaded by troffrc when any of those output devices is selected.\n\n/usr/share/groff/1.23.0/tmac/tty-char.tmac\ndefines fallback characters for use with grotty.  See nroff(1).\n",
            "subsections": []
        },
        "Limitations": {
            "content": "grotty is intended only for simple documents.\n\n• There is no support for fractional horizontal or vertical motions.\n\n• roff  \\D  escape  sequences producing anything other than horizontal and vertical lines are\nnot supported.\n\n• Characters above the first line (that is, with a vertical drawing position of 0) cannot  be\nrendered.\n\n• Color  handling differs from other output drivers.  The groff requests and escape sequences\nthat set the stroke and fill colors instead set the  foreground  and  background  character\ncell colors, respectively.\n",
            "subsections": []
        },
        "Examples": {
            "content": "The  following  groff  document  exercises  several  features for which output device support\nvaries: (1) bold style; (2) italic (underline) style; (3) bold-italic  style;  (4)  character\ncomposition  by  overstriking  (“coöperate”); (5) foreground color; (6) background color; and\n(7) horizontal and vertical line-drawing.\n\nYou might see \\f[B]bold\\f[] and \\f[I]italic\\f[].\nSome people see \\f[BI]both\\f[].\nIf the output device does (not) co\\z\\[ad]operate,\nyou might see \\m[red]red\\m[].\nBlack on cyan can have a \\M[cyan]\\m[black]prominent\\m[]\\M[]\n\\D'l 1i 0'\\D'l 0 2i'\\D'l 1i 0' look.\n.\\\" If in nroff mode, end page now.\n.if n .pl \\n[nl]u\n\nGiven the foregoing input, compare and contrast the output of the following.\n\n$ groff -T ascii file\n$ groff -T utf8 -P -i file\n$ groff -T utf8 -P -c file | ul\n\nSee also\n“Control Functions for Coded Character  Sets”  (ECMA-48)  5th  edition,  Ecma  International,\nJune  1991.   A gratis version of ISO 6429, this document includes a normative description of\nSGR escape  sequences.   Available  at  http://www.ecma-international.org/publications/files/\nECMA-ST/Ecma-048.pdf.\n\n“Hyperlinks in Terminal Emulators”, Egmont Koblinger.\n\ngroff(1),  troff(1),  groffout(5),  grofffont(5),  groffchar(7),  ul(1), more(1), less(1),\nman(1)\n\ngroff 1.23.0                                31 March 2024                                  grotty(1)",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": []
}