{
    "mode": "man",
    "parameter": "troff",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/troff/1/json",
    "generated": "2026-09-11T09:27:39Z",
    "sections": {
        "Name": {
            "content": "troff - GNU roff typesetter and document formatter\n",
            "subsections": []
        },
        "Synopsis": {
            "content": "troff [-abcCEiRUz] [-d ctext] [-d string=text] [-f font-family] [-F font-directory]\n[-I inclusion-directory] [-m macro-package] [-M macro-directory] [-n page-number]\n[-o page-list] [-r cnumeric-expression] [-r register=numeric-expression] [-T output-\ndevice] [-w warning-category] [-W warning-category] [file ...]\n",
            "subsections": [
                {
                    "name": "troff --help",
                    "content": ""
                },
                {
                    "name": "troff -v",
                    "content": ""
                },
                {
                    "name": "troff --version",
                    "content": ""
                }
            ]
        },
        "Description": {
            "content": "GNU  troff  transforms  \u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\ language input into the device-independent output format de‐\nscribed in \u001b]8;;man:groffout(5)\u001b\\groffout(5)\u001b]8;;\u001b\\; troff is thus the heart of the GNU roff document formatting  system.\nIf  no  file  operands  are  given on the command line, or if file is “-”, the standard input\nstream is read.\n\nGNU troff is functionally compatible with the AT&T troff typesetter and features numerous ex‐\ntensions.  Many people prefer to use the \u001b]8;;man:groff(1)\u001b\\groff(1)\u001b]8;;\u001b\\ command, a front end which also  runs  pre‐\nprocessors and output drivers in the appropriate order and with appropriate options.\n",
            "subsections": []
        },
        "Options": {
            "content": "",
            "subsections": [
                {
                    "name": "-h   --help  -v  --version",
                    "content": "exit afterward.\n",
                    "flag": "-v",
                    "long": "--version"
                },
                {
                    "name": "-a",
                    "content": "is set to 1.  This option produces a sort of abstract preview of the formatted output.\n\n• Page  breaks  are  marked by a phrase in angle brackets; for example, “<beginning of\npage>”.\n\n• Lines are broken where they would be in the formatted output.\n\n• A horizontal motion of any size is represented as one  space.   Adjacent  horizontal\nmotions are not combined.  Inter-sentence space nodes (those arising from the second\nargument to the .ss request) are not represented.\n\n• Vertical motions are not represented.\n\n• Special characters are rendered in angle brackets; for example, the default soft hy‐\nphen character appears as “<hy>”.\n\nThe above description should not be considered a specification; the details of -a out‐\nput are subject to change.\n",
                    "flag": "-a"
                },
                {
                    "name": "-b",
                    "content": "stream with each diagnostic message.  The line numbers given in  the  backtrace  might\nnot  always  be  correct,  because troff's idea of line numbers can be confused by re‐\nquests that append to macros.\n",
                    "flag": "-b"
                },
                {
                    "name": "-c",
                    "content": "",
                    "flag": "-c"
                },
                {
                    "name": "-C      -c",
                    "content": "",
                    "flag": "-c"
                },
                {
                    "name": "-d _",
                    "content": "",
                    "flag": "-d"
                },
                {
                    "name": "-d _",
                    "content": "Define roff string c or string as text.  c must be one character; string can be of ar‐\nbitrary length.  Such string assignments happen before any macro file is  loaded,  in‐\ncluding  the startup file.  Due to \u001b]8;;man:getoptlong(3)\u001b\\getoptlong(3)\u001b]8;;\u001b\\ limitations, c cannot be, and string\ncannot contain, an equals sign, even though that is a valid character in a roff  iden‐\ntifier.\n",
                    "flag": "-d"
                },
                {
                    "name": "-E      -Ww",
                    "content": "sent to the standard error stream by documents or macro packages using tm  or  related\nrequests.\n",
                    "flag": "-E"
                },
                {
                    "name": "-f _",
                    "content": "",
                    "flag": "-f"
                },
                {
                    "name": "-F _",
                    "content": "description files.  See the description of GROFFFONTPATH  in  section  “Environment”\nbelow for the default search locations and ordering.\n",
                    "flag": "-F"
                },
                {
                    "name": "-i",
                    "content": "",
                    "flag": "-i"
                },
                {
                    "name": "-I _",
                    "content": "soquiet requests; and in “\\X'ps: import'”, “\\X'ps: file'”, and “\\X'pdf:  pdfpic'”  de‐\nvice  control  escape  sequences).   -I  may  be specified more than once; each dir is\nsearched in the given order.  To search the current working directory  before  others,\nadd  “-I  .”  at the desired place; it is otherwise searched last.  -I works similarly\nto, and is named for, the “include” option of Unix C compilers.\n",
                    "flag": "-I"
                },
                {
                    "name": "-m _",
                    "content": "Process the file name.tmac prior to any input files.  If not found, tmac.name  is  at‐\ntempted.  name (in both arrangements) is presumed to be a macro file; see the descrip‐\ntion  of  GROFFTMACPATH  in section “Environment” below for the default search loca‐\ntions and ordering.\n",
                    "flag": "-m"
                },
                {
                    "name": "-M _",
                    "content": "tion “Environment” below for the default search locations and ordering.\n",
                    "flag": "-M"
                },
                {
                    "name": "-n _",
                    "content": "",
                    "flag": "-n"
                },
                {
                    "name": "-o _",
                    "content": "Output only pages in list, which is a comma-separated list of inclusive page ranges; n\nmeans  page  n, m-n means every page between m and n, -n means every page up to n, and\nn- means every page from n on.  troff stops processing and exits after formatting  the\nlast page enumerated in list.\n",
                    "flag": "-o"
                },
                {
                    "name": "-r _",
                    "content": "",
                    "flag": "-r"
                },
                {
                    "name": "-r _",
                    "content": "Define  roff  register c or register as numeric-expression.  c must be a one-character\nname; register can be of arbitrary length.  Such register  assignments  happen  before\nany  macro  file is loaded, including the startup file.  Due to \u001b]8;;man:getoptlong(3)\u001b\\getoptlong(3)\u001b]8;;\u001b\\ limita‐\ntions, c cannot be, and register cannot contain, an equals sign, even though that is a\nvalid character in a roff identifier.\n",
                    "flag": "-r"
                },
                {
                    "name": "-R",
                    "content": "",
                    "flag": "-R"
                },
                {
                    "name": "-T _",
                    "content": "",
                    "flag": "-T"
                },
                {
                    "name": "-U",
                    "content": "disabled  by  default because they allow an untrusted input document to write to arbi‐\ntrary file names and run arbitrary commands.  This option also adds the current direc‐\ntory to the macro package search path; see the -m and -M options above.\n",
                    "flag": "-U"
                },
                {
                    "name": "-w _",
                    "content": "",
                    "flag": "-w"
                },
                {
                    "name": "-W _",
                    "content": "Enable (-w) or inhibit (-W) warnings in category name.  See section “Warnings” below.\n",
                    "flag": "-W"
                },
                {
                    "name": "-z",
                    "content": "",
                    "flag": "-z"
                }
            ]
        },
        "Warnings": {
            "content": "Warning diagnostics emitted by troff are divided into named, numbered categories.   The  name\nassociated  with  each  warning  category is used by the -w and -W options.  Each category is\nalso assigned a power of two; the sum of enabled category codes is used by the  warn  request\nand  the  .warn register.  Warnings of each category are produced under the following circum‐\nstances.\n\n┌───────────────────────┬─────────────────────────────┐\n│ Bit   Code   Category │ Bit    Code      Category   │\n├───────────────────────┼─────────────────────────────┤\n│   0      1   char     │  10      1024   reg         │\n│   1      2   number   │  11      2048   tab         │\n│   2      4   break    │  12      4096   right-brace │\n│   3      8   delim    │  13      8192   missing     │\n│   4     16   el       │  14     16384   input       │\n│   5     32   scale    │  15     32768   escape      │\n│   6     64   range    │  16     65536   space       │\n│   7    128   syntax   │  17    131072   font        │\n│   8    256   di       │  18    262144   ig          │\n│   9    512   mac      │  19    524288   color       │\n│                       │  20   1048576   file        │\n└───────────────────────┴─────────────────────────────┘\n\nbreak           4   A filled output line could not be broken such that its  length  was  less\nthan the output line length \\n[.l].  This category is enabled by default.\n\nchar            1   No  mounted font defines a glyph for the requested character.  This cate‐\ngory is enabled by default.\n\ncolor      524288   An undefined color name was selected, an attempt was  made  to  define  a\ncolor  using an unrecognized color space, an invalid component in a color\ndefinition was encountered, or an attempt was made to redefine a  default\ncolor.\n\ndelim           8   The closing delimiter in an escape sequence was missing or mismatched.\n\ndi            256   A di, da, box, or boxa request was invoked without an argument when there\nwas no current diversion.\n\nel             16   The el request was encountered with no prior corresponding ie request.\n\nescape      32768   An unsupported escape sequence was encountered.\n\nfile      1048576   An attempt was made to load a file that does not exist.  This category is\nenabled by default.\n\nfont       131072   A  non-existent font was selected, or the selection was ignored because a\nfont selection escape sequence was used after the output  line  continua‐\ntion  escape  sequence on an input line.  This category is enabled by de‐\nfault.\n\nig         262144   An invalid escape sequence occurred in input ignored  using  the  ig  re‐\nquest.  This warning category diagnoses a condition that is an error when\nit occurs in non-ignored input.\n\ninput       16384   An invalid character occurred on the input stream.\n\nmac           512   An  undefined  string, macro, or diversion was used.  When such an object\nis dereferenced, an empty one of that name is automatically created.  So,\nunless it is later deleted, at most one warning is given for each.\n\nThis warning is also emitted upon an attempt to move  an  unplanted  trap\nmacro.   In such cases, the unplanted macro is not dereferenced, so it is\nnot created if it does not exist.\n\nmissing      8192   A request was invoked with a mandatory argument absent.\n\nnumber          2   An invalid numeric expression was encountered.  This category is  enabled\nby default.\n\nrange          64   A numeric expression was out of range for its context.\n\nreg          1024   An  undefined  register was used.  When an undefined register is derefer‐\nenced, it is automatically defined with a value of 0.  So, unless  it  is\nlater deleted, at most one warning is given for each.\n\nright-brace  4096   A  right  brace escape sequence \\} was encountered where a number was ex‐\npected.\n\nscale          32   A scaling unit inappropriate to its context was used in a numeric expres‐\nsion.\n\nspace       65536   A space was missing between a request or macro and  its  argument.   This\nwarning  is produced when an undefined name longer than two characters is\nencountered and the first two characters of the name constitute a defined\nname.  No request is invoked, no macro called, and an empty macro is  not\ndefined.   This  category is enabled by default.  It never occurs in com‐\npatibility mode.\n\nsyntax        128   A self-contradictory hyphenation mode was requested; an empty  or  incom‐\nplete  numeric expression was encountered; an operand to a numeric opera‐\ntor was missing; an attempt was made to define  a  recursive,  empty,  or\nnonsensical  character class; or a groff extension conditional expression\noperator was used while in compatibility mode.\n\ntab          2048   A tab character was encountered where a number was expected, or  appeared\nin an unquoted macro argument.\n\nTwo warning names group other warning categories for convenience.\n\nall    All warning categories except di, mac, and reg.  This shorthand is intended to produce\nall  warnings that are useful with macro packages and documents written for AT&T troff\nand its descendants, which have less fastidious diagnostics than GNU troff.\n\nw      All warning categories.  Authors of documents and macro packages targeting  groff  are\nencouraged to use this setting.\n",
            "subsections": []
        },
        "Environment": {
            "content": "GROFFFONTPATH and GROFFTMACPATH each accept a search path of directories; that is, a list\nof  directory  names  separated  by the system's path component separator character.  On Unix\nsystems, this character is a colon (:); on Windows systems, it is a semicolon (;).\n\nGROFFFONTPATH\nA list of directories in which to seek the selected output device's directory  of  de‐\nvice  and  font  description files.  troff will scan directories given as arguments to\nany specified -F options before these, then in a site-specific directory  (/usr/share/\ngroff/site-font),  a  standard location (/usr/share/groff/1.23.0/font), and a compati‐\nbility directory (/usr/lib/font) after them.\n\nGROFFTMACPATH\nA list of directories in which to search for macro files.  troff will scan directories\ngiven as arguments to any specified -M options before these, then the  current  direc‐\ntory  (only  if  in unsafe mode), the user's home directory, a site-specific directory\n(/usr/share/groff/site-tmac), and a standard  location  (/usr/share/groff/1.23.0/tmac)\nafter them.\n\nGROFFTYPESETTER\nSet  the default output device.  If empty or not set, ps is used.  The -T option over‐\nrides GROFFTYPESETTER.\n\nSOURCEDATEEPOCH\nA timestamp (expressed as seconds since the Unix epoch) to use as the output  creation\ntimestamp  in place of the current time.  The time is converted to human-readable form\nusing \u001b]8;;man:gmtime(3)\u001b\\gmtime(3)\u001b]8;;\u001b\\ and \u001b]8;;man:asctime(3)\u001b\\asctime(3)\u001b]8;;\u001b\\ when the formatter starts up and  stored  in  registers\nusable by documents and macro packages.\n\nTZ     The  time  zone  to  use  when converting the current time to human-readable form; see\n\u001b]8;;man:tzset(3)\u001b\\tzset(3)\u001b]8;;\u001b\\.  If SOURCEDATEEPOCH is used, it is always converted to human-readable form\nusing UTC.\n",
            "subsections": []
        },
        "Files": {
            "content": "/usr/share/groff/1.23.0/tmac/troffrc\nis an initialization macro file loaded before any macro packages specified with -m op‐\ntions.\n\n/usr/share/groff/1.23.0/tmac/troffrc-end\nis an initialization macro file loaded after all macro packages specified with -m  op‐\ntions.\n\n/usr/share/groff/1.23.0/tmac/name.tmac\nare macro files distributed with groff.\n\n/usr/share/groff/1.23.0/font/devname/DESC\ndescribes the output device name.\n\n/usr/share/groff/1.23.0/font/devname/F\ndescribes the font F of device name.\n\ntroffrc  and  troffrc-end are sought neither in the current nor the home directory by default\nfor security reasons, even if the -U option is specified.  Use the -M command-line option  or\nthe  GROFFTMACPATH environment variable to add these directories to the search path if nec‐\nessary.\n",
            "subsections": []
        },
        "Authors": {
            "content": "The GNU version of troff was originally written by James Clark; he also  wrote  the  original\nversion  of  this document, which was updated by \u001b]8;;mailto:wl@gnu.org\u001b\\Werner Lemberg\u001b]8;;\u001b\\, \u001b]8;;mailto:groff-bernd.warken-72@web.de\u001b\\Bernd Warken\u001b]8;;\u001b\\, and \u001b]8;;mailto:g.branden.robinson@gmail.com\u001b\\G. Branden\nRobinson\u001b]8;;\u001b\\.\n\nSee also\nGroff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary\ngroff manual.  You can browse it interactively with “info groff”.\n\n\u001b]8;;man:groff(1)\u001b\\groff(1)\u001b]8;;\u001b\\\noffers an overview of the GNU roff system and describes its front end executable.\n\n\u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\\ndetails the groff language, including a short but complete reference of all predefined\nrequests, registers, and escape sequences.\n\n\u001b]8;;man:groffchar(7)\u001b\\groffchar(7)\u001b]8;;\u001b\\\nexplains the syntax of groff special character escape sequences, and lists all special\ncharacters predefined by the language.\n\n\u001b]8;;man:groffdiff(7)\u001b\\groffdiff(7)\u001b]8;;\u001b\\\nenumerates the differences between AT&T device-independent troff and groff.\n\n\u001b]8;;man:grofffont(5)\u001b\\grofffont(5)\u001b]8;;\u001b\\\ncovers the format of groff device and font description files.\n\n\u001b]8;;man:groffout(5)\u001b\\groffout(5)\u001b]8;;\u001b\\\ndescribes the format of troff's output.\n\n\u001b]8;;man:grofftmac(5)\u001b\\grofftmac(5)\u001b]8;;\u001b\\\nincludes information about macro files that ship with groff.\n\n\u001b]8;;man:roff(7)\u001b\\roff(7)\u001b]8;;\u001b\\\nsupplies background on roff systems in general, including pointers to further  related\ndocumentation.\n\ngroff 1.23.0                                31 March 2024                                   troff(1)",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": [],
    "tldr": {
        "source": "official",
        "description": "Typesetting processor for the groff (GNU Troff) document formatting system.",
        "examples": [
            {
                "description": "Format output for a PostScript printer, saving the output to a file",
                "command": "troff {{path/to/input.roff}} | grops > {{path/to/output.ps}}"
            },
            {
                "description": "Format output for a PostScript printer using the me macro package, saving the output to a file",
                "command": "troff -{{me}} {{path/to/input.roff}} | grops > {{path/to/output.ps}}"
            },
            {
                "description": "Format output as ASCII text using the man macro package",
                "command": "troff -T {{ascii}} -{{man}} {{path/to/input.roff}} | grotty"
            },
            {
                "description": "Format output as a pdf file, saving the output to a file",
                "command": "troff -T {{pdf}} {{path/to/input.roff}} | gropdf > {{path/to/output.pdf}}"
            }
        ]
    }
}