{
    "mode": "man",
    "parameter": "groff",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/groff/1/json",
    "generated": "2026-10-09T09:37:35Z",
    "sections": {
        "Name": {
            "content": "groff - front end to the GNU roff document formatting system\n",
            "subsections": []
        },
        "Synopsis": {
            "content": "groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text] [-D fallback-encoding] [-f font-\nfamily] [-F font-directory] [-I inclusion-directory] [-K input-encoding] [-L spooler-\nargument] [-m macro-package] [-M macro-directory] [-n page-number] [-o page-list]\n[-P postprocessor-argument] [-r cnumeric-expression] [-r register=numeric-expression]\n[-T output-device] [-w warning-category] [-W warning-category] [file ...]\n",
            "subsections": [
                {
                    "name": "groff -h",
                    "content": ""
                },
                {
                    "name": "groff --help",
                    "content": "groff -v [option ...] [file ...]\ngroff --version [option ...] [file ...]\n"
                }
            ]
        },
        "Description": {
            "content": "groff  is  the  primary  front end to the GNU roff document formatting system.  GNU roff is a\ntypesetting system that reads plain text input files that include formatting commands to pro‐\nduce output in PostScript, PDF, HTML, DVI, or other formats, or for display  to  a  terminal.\nFormatting  commands can be low-level typesetting primitives, macros from a supplied package,\nor user-defined macros.  All three approaches can be combined.  If no file operands are spec‐\nified, or if file is “-”, groff reads the standard input stream.\n\nA reimplementation and extension of the typesetter from AT&T Unix, groff is present  on  most\nPOSIX  systems owing to its long association with Unix manuals (including man pages).  It and\nits predecessor are notable for their production of several best-selling software engineering\ntexts.  groff is capable of producing typographically sophisticated documents while consuming\nminimal system resources.\n\nThe groff command orchestrates the execution of preprocessors, the  transformation  of  input\ndocuments  into  a device-independent page description language, and the production of output\nfrom that language.\n",
            "subsections": []
        },
        "Options": {
            "content": "",
            "subsections": [
                {
                    "name": "-h  --help",
                    "content": "Because groff is intended to subsume most users' direct invocations of the  troff(1)  format‐\nter,  the  two  programs  share a set of options.  However, groff has some options that troff\ndoes not share, and others which groff interprets differently.  At the  same  time,  not  all\nvalid troff options can be given to groff.\n\ngroff-specific options\nThe  following  options  either  do  not exist in GNU troff or are interpreted differently by\ngroff.\n",
                    "flag": "-h",
                    "long": "--help"
                },
                {
                    "name": "-D _ -k",
                    "content": "",
                    "flag": "-k"
                },
                {
                    "name": "-e",
                    "content": "",
                    "flag": "-e"
                },
                {
                    "name": "-g",
                    "content": "",
                    "flag": "-g"
                },
                {
                    "name": "-G      -p",
                    "content": "",
                    "flag": "-p"
                },
                {
                    "name": "-I _ -g  -s",
                    "content": "soelim(1)  and the output driver, and grn is passed an -M option with dir as its argu‐\nment.\n",
                    "flag": "-s"
                },
                {
                    "name": "-j      -p",
                    "content": "",
                    "flag": "-p"
                },
                {
                    "name": "-k",
                    "content": "groff's -K or -D options is also specified.\n",
                    "flag": "-k"
                },
                {
                    "name": "-K _ -k",
                    "content": "",
                    "flag": "-k"
                },
                {
                    "name": "-l",
                    "content": "vice description file specifies the default command to be used; see grofffont(5).  If\nno such directive is present for the output device, output is piped  to  lpr(1).   See\noptions -L and -X.\n",
                    "flag": "-l"
                },
                {
                    "name": "-L _",
                    "content": "a separate -L option.  groff does not prefix an option dash to arg before  passing  it\nto the spooler program.\n",
                    "flag": "-L"
                },
                {
                    "name": "-M",
                    "content": "grn(1).\n",
                    "flag": "-M"
                },
                {
                    "name": "-N      -N",
                    "content": "",
                    "flag": "-N"
                },
                {
                    "name": "-p",
                    "content": "",
                    "flag": "-p"
                },
                {
                    "name": "-P _",
                    "content": "rate  -P option.  groff does not prefix an option dash to arg before passing it to the\npostprocessor.\n",
                    "flag": "-P"
                },
                {
                    "name": "-R",
                    "content": "because  most  refer  options  have equivalent language elements that can be specified\nwithin the document.\n",
                    "flag": "-R"
                },
                {
                    "name": "-s",
                    "content": "",
                    "flag": "-s"
                },
                {
                    "name": "-S      -U",
                    "content": "mode is enabled by default.\n",
                    "flag": "-U"
                },
                {
                    "name": "-t",
                    "content": "",
                    "flag": "-t"
                },
                {
                    "name": "-T _",
                    "content": "put driver to convert troff's output to a form appropriate  for  dev;  see  subsection\n“Output devices” below.\n",
                    "flag": "-T"
                },
                {
                    "name": "-U      -U",
                    "content": "",
                    "flag": "-U"
                },
                {
                    "name": "-v",
                    "content": "",
                    "flag": "-v"
                },
                {
                    "name": "--version",
                    "content": "Write  version information for groff and all programs run by it to the standard output\nstream; that is, the given command line is processed in the usual way, passing  -v  to\nthe formatter and any pre- or postprocessors invoked.\n",
                    "long": "--version"
                },
                {
                    "name": "-V",
                    "content": "ecute it.  If given more than once, groff both writes and runs the pipeline.\n",
                    "flag": "-V"
                },
                {
                    "name": "-X",
                    "content": "display.  Combining this option with -Tps uses the font metrics of the PostScript  de‐\nvice, whereas the -TX75 and -TX100 options use the metrics of X11 fonts.\n",
                    "flag": "-X"
                },
                {
                    "name": "-Z",
                    "content": "less suppressed with -z); see groffout(5) for a description of this format.\n",
                    "flag": "-Z"
                },
                {
                    "name": "Transparent options",
                    "content": "The following options are passed as-is to the formatter program  troff(1)  and  described  in\nmore detail in its man page.\n"
                },
                {
                    "name": "-a",
                    "content": "",
                    "flag": "-a"
                },
                {
                    "name": "-b",
                    "content": "",
                    "flag": "-b"
                },
                {
                    "name": "-c",
                    "content": "",
                    "flag": "-c"
                },
                {
                    "name": "-C      -c",
                    "content": "",
                    "flag": "-c"
                },
                {
                    "name": "-d _",
                    "content": "",
                    "flag": "-d"
                },
                {
                    "name": "-d _",
                    "content": "Define string.\n",
                    "flag": "-d"
                },
                {
                    "name": "-E      -Ww",
                    "content": "",
                    "flag": "-E"
                },
                {
                    "name": "-f _",
                    "content": "",
                    "flag": "-f"
                },
                {
                    "name": "-F _",
                    "content": "description files.\n",
                    "flag": "-F"
                },
                {
                    "name": "-i",
                    "content": "",
                    "flag": "-i"
                },
                {
                    "name": "-I _",
                    "content": "",
                    "flag": "-I"
                },
                {
                    "name": "-m _",
                    "content": "Process name.tmac before input files.\n",
                    "flag": "-m"
                },
                {
                    "name": "-M _",
                    "content": "",
                    "flag": "-M"
                },
                {
                    "name": "-n _",
                    "content": "",
                    "flag": "-n"
                },
                {
                    "name": "-o _",
                    "content": "Output only pages in list.\n",
                    "flag": "-o"
                },
                {
                    "name": "-r _",
                    "content": "",
                    "flag": "-r"
                },
                {
                    "name": "-r _",
                    "content": "Define register.\n",
                    "flag": "-r"
                },
                {
                    "name": "-w _",
                    "content": "",
                    "flag": "-w"
                },
                {
                    "name": "-W _",
                    "content": "Enable (-w) or inhibit (-W) emission of warnings in category name.\n",
                    "flag": "-W"
                },
                {
                    "name": "-z",
                    "content": "",
                    "flag": "-z"
                }
            ]
        },
        "Usage": {
            "content": "The architecture of the GNU roff system follows that of other device-independent roff  imple‐\nmentations, comprising preprocessors, macro packages, output drivers (or “postprocessors”), a\nsuite  of utilities, and the formatter troff at its heart.  See roff(7) for a survey of how a\nroff system works.\n\nThe front end programs available in the GNU roff system make it easier  to  use  than  tradi‐\ntional roffs that required the construction of pipelines or use of temporary files to carry a\nsource  document  from maintainable form to device-ready output.  The discussion below summa‐\nrizes the constituent parts of the GNU roff system.  It complements roff(7)  with  groff-spe‐\ncific information.\n",
            "subsections": [
                {
                    "name": "Getting started",
                    "content": "Those  who prefer to learn by experimenting or are desirous of rapid feedback from the system\nmay wish to start with a “Hello, world!” document.\n\n$ echo \"Hello, world!\" | groff -Tascii | sed '/^$/d'\nHello, world!\n\nWe used a sed command only to eliminate the 65 blank lines that  would  otherwise  flood  the\nterminal  screen.   (roff systems were developed in the days of paper-based terminals with 66\nlines to a page.)\n\nToday's users may prefer output to a UTF-8-capable terminal.\n\n$ echo \"Hello, world!\" | groff -Tutf8 | sed '/^$/d'\n\nProducing PDF, HTML, or TeX's DVI is also straightforward.  The hard part may be selecting  a\nviewer program for the output.\n\n$ echo \"Hello, world!\" | groff -Tpdf > hello.pdf\n$ evince hello.pdf\n$ echo \"Hello, world!\" | groff -Thtml > hello.html\n$ firefox hello.html\n$ echo \"Hello, world!\" | groff -Tdvi > hello.dvi\n$ xdvi hello.html\n"
                },
                {
                    "name": "Using _groff_ as a REPL",
                    "content": "Those with a programmer's bent may be pleased to know that they can use groff in a read-eval‐\nuate-print  loop  (REPL).  Doing so can be handy to verify one's understanding of the format‐\nter's behavior and/or the syntax it accepts.  Turning on all warnings with -ww can  aid  this\ngoal.\n\n$ groff -ww -Tutf8"
                },
                {
                    "name": "\\# This is a comment. Let's define a register.",
                    "content": ""
                },
                {
                    "name": ".nr a 1",
                    "content": ""
                },
                {
                    "name": "\\# Do integer arithmetic with operators evaluated left-to-right.",
                    "content": ""
                },
                {
                    "name": ".nr b \\n[a]+5/2",
                    "content": ""
                },
                {
                    "name": "\\# Let's get the result on the standard error stream.",
                    "content": ""
                },
                {
                    "name": ".tm \\n[b]",
                    "content": "3"
                },
                {
                    "name": "\\# Now we'll define a string.",
                    "content": ""
                },
                {
                    "name": ".ds name Leslie\\\" This is another form of comment.",
                    "content": ""
                },
                {
                    "name": ".nr b (\\n[a] + (7/2))",
                    "content": ""
                },
                {
                    "name": "\\# Center the next two text input lines.",
                    "content": ""
                },
                {
                    "name": ".ce 2",
                    "content": "Hi, \\*[name]."
                },
                {
                    "name": "Your secret number is \\n[b].",
                    "content": ""
                },
                {
                    "name": "\\# We will see that the division rounded toward zero.",
                    "content": ""
                },
                {
                    "name": "It is",
                    "content": ""
                },
                {
                    "name": "\\# Here's an if-else control structure.",
                    "content": ""
                },
                {
                    "name": ".ie (\\n[b] % 2) odd.",
                    "content": ""
                },
                {
                    "name": ".el even.",
                    "content": ""
                },
                {
                    "name": "\\# This trick sets the page length to the current vertical",
                    "content": ""
                },
                {
                    "name": "\\# position, so that blank lines don't spew when we're done.",
                    "content": ""
                },
                {
                    "name": ".pl \\n[nl]u",
                    "content": "<Control-D>\nHi, Leslie.\nYour secret number is 4.\nIt is even.\n"
                },
                {
                    "name": "Paper format",
                    "content": "In  GNU  roff, the page dimensions for the formatter troff and for output devices are handled\nseparately.  In the formatter, requests are used to set the page length  (.pl),  page  offset\n(or left margin, .po), and line length (.ll).  The right margin is not explicitly configured;\nthe  combination  of page offset and line length provides the information necessary to derive\nit.  The papersize macro package, automatically loaded by troff, provides  an  interface  for\nconfiguring  page  dimensions  by convenient names, like “letter” or “A4”; see grofftmac(5).\nThe formatter's default in this installation is “A4”.\n\nIt is up to each macro package to respect the page dimensions configured in this  way.   Some\noffer alternative mechanisms.\n\nFor each output device, the size of the output medium can be set in its DESC file.  Most out‐\nput drivers also recognize a command-line option -p to override the default dimensions and an\noption -l to use landscape orientation.  See grofffont(5) for a description of the papersize\ndirective,  which  takes  an  argument of the same form as -p.  The output driver's man page,\nsuch as grops(1), may also be helpful.  groff uses the command-line option -P to pass options\nto output devices; for example, use the following for PostScript output on A4 paper in  land‐\nscape orientation.\n\ngroff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps\n"
                },
                {
                    "name": "Front end",
                    "content": "The  groff  program  is a wrapper around the troff(1) program.  It allows one to specify pre‐\nprocessors via command-line options and automatically runs the appropriate postprocessor  for\nthe  selected output device.  Doing so, the manual construction of pipelines or management of\ntemporary files required of users of traditional roff(7) systems can  be  avoided.   Use  the\ngrog(1) program to infer an appropriate groff command line to format a document.\n"
                },
                {
                    "name": "Language",
                    "content": "Input  to a roff system is in plain text interleaved with control lines and escape sequences.\nThe combination constitutes a document in one of a family of languages we also call roff; see\nroff(7) for background.  An overview of GNU roff  language  syntax  and  features,  including\nlists  of all supported escape sequences, requests, and predefined registers, can be found in\ngroff(7).  GNU roff extensions to the AT&T troff language, a common subset of  roff  dialects\nextant today, are detailed in groffdiff(7).\n"
                },
                {
                    "name": "Preprocessors",
                    "content": "A  preprocessor  interprets  a  domain-specific  language that produces roff language output.\nFrequently, such input is confined to sections or regions of a  roff  input  file  (bracketed\nwith  macro calls specific to each preprocessor), which it replaces.  Preprocessors therefore\noften interpret a subset of roff syntax along with their own  language.   GNU  roff  provides\nreimplementations of most preprocessors familiar to users of AT&T troff; these routinely have\nextended features and/or require GNU troff to format their output.\n\ntbl         lays out tables;\neqn         typesets mathematics;\npic         draws diagrams;\nrefer       processes bibliographic references;\nsoelim      preprocesses “sourced” input files;\ngrn         renders gremlin(1) diagrams;\nchem        draws chemical structural formulæ using pic;\ngperl       populates groff registers and strings using perl(1);\nglilypond   embeds LilyPond sheet music; and\ngpinyin     eases Mandarin Chinese input using Hanyu Pinyin.\n\nA  preprocessor  unique  to GNU roff is preconv(1), which converts various input encodings to\nsomething GNU troff can understand.  When used, it is run before any other preprocessors.\n\nMost preprocessors enclose content between a pair of characteristic  tokens.   Such  a  token\nmust  occur  at the beginning of an input line and use the dot control character.  Spaces and\ntabs must not follow the control character or precede the end of the input  line.   Deviating\nfrom  these  rules  defeats  a token's recognition by the preprocessor.  Tokens are generally\npreserved in preprocessor output and interpreted as macro calls subsequently by  troff.   The\nideal preprocessor is not yet available in groff.\n\n┌──────────────┬─────────────────┬────────────────┐\n│ preprocessor │ starting token  │  ending token  │\n├──────────────┼─────────────────┼────────────────┤\n│     chem     │     .cstart     │     .cend      │\n│     eqn      │       .EQ       │      .EN       │\n│     grap     │       .G1       │      .G2       │\n│     grn      │       .GS       │      .GE       │\n│    ideal     │       .IS       │      .IE       │\n│              │                 │      .IF       │\n│     pic      │       .PS       │      .PE       │\n│              │                 │      .PF       │\n│              │                 │      .PY       │\n│    refer     │       .R1       │      .R2       │\n│     tbl      │       .TS       │      .TE       │\n├──────────────┼─────────────────┼────────────────┤\n│  glilypond   │ .lilypond start │ .lilypond stop │\n│    gperl     │   .Perl start   │   .Perl stop   │\n│   gpinyin    │  .pinyin start  │  .pinyin stop  │\n└──────────────┴─────────────────┴────────────────┘\n"
                },
                {
                    "name": "Macro packages",
                    "content": "Macro  files  are  roff input files designed to produce no output themselves but instead ease\nthe preparation of other roff documents.  When a macro file is installed at a standard  loca‐\ntion and suitable for use by a general audience, it is termed a macro package.\n\nMacro  packages  can be loaded prior to any roff input documents with the -m option.  The GNU\nroff system implements most well-known macro packages for AT&T troff in a compatible way  and\nextends  them.   These have one- or two-letter names arising from intense practices of naming\neconomy in early Unix culture, a laconic approach that led to  many  of  the  packages  being\nidentified in general usage with the nroff and troff option letter used to invoke them, some‐\ntimes  to  punning effect, as with “man” (short for “manual”), and even with the option dash,\nas in the case of the s package, much better known as ms or even -ms.\n\nMacro packages serve a variety of purposes.  Some are “full-service” packages,  adopting  re‐\nsponsibility for page layout among other fundamental tasks, and defining their own lexicon of\nmacros  for document composition; each such package stands alone and a given document can use\nat most one.\n\nan     is used to compose man pages in the format originating in Version 7 Unix  (1979);  see\ngroffman(7).  It can be specified on the command line as -man.\n\ndoc    is  used  to  compose  man  pages in the format originating in 4.3BSD-Reno (1990); see\ngroffmdoc(7).  It can be specified on the command line as -mdoc.\n\ne      is the Berkeley general-purpose macro suite, developed as an alternative to AT&T's  s;\nsee groffme(7).  It can be specified on the command line as -me.\n\nm      implements the format used by the second-generation AT&T macro suite for general docu‐\nments,  a successor to s; see groffmm(7).  It can be specified on the command line as\n-mm.\n\nom     (invariably called “mom”) is a modern package written by Peter Schaffter  specifically\nfor  GNU  roff.  Consult the mom HTML manual for extensive documentation.  She—for mom\ntakes the female pronoun—can be specified on the command line as -mom.\n\ns      is the original AT&T general-purpose document format;  see  groffms(7).   It  can  be\nspecified on the command line as -ms.\n\nOthers  are supplemental.  For instance, andoc is a wrapper package specific to GNU roff that\nrecognizes whether a document uses man or mdoc format and loads the corresponding macro pack‐\nage.  It can be specified on the command line as -mandoc.  A man(1) librarian program may use\nthis macro file to delegate loading of the correct macro package; it is thus unnecessary  for\nman itself to scan the contents of a document to decide the issue.\n\nMany macro files augment the function of the full-service packages, or of roff documents that\ndo  not  employ such a package—the latter are sometimes characterized as “raw”.  These auxil‐\niary packages are described, along with details  of  macro  file  naming  and  placement,  in\ngrofftmac(5).\n"
                },
                {
                    "name": "Formatters",
                    "content": "The formatter, the program that interprets roff language input, is troff(1).  It provides the\nfeatures  of  the AT&T troff and nroff programs as well as many extensions.  The command-line\noption -C switches troff into compatibility mode,  which  tries  to  emulate  AT&T  troff  as\nclosely as is practical to enable the formatting of documents written for the older system.\n\nA  shell script, nroff(1), emulates the behavior of AT&T nroff.  It attempts to correctly en‐\ncode the output based on the locale, relieving the user of the need to specify an output  de‐\nvice with the -T option and is therefore convenient for use with terminal output devices, de‐\nscribed in the next subsection.\n\nGNU troff generates output in a device-independent, but not device-agnostic, page description\nlanguage detailed in groffout(5).\n"
                },
                {
                    "name": "Output devices",
                    "content": "troff  output  is formatted for a particular output device, typically specified by the -T op‐\ntion to the formatter or a front end.  If neither this option nor the GROFFTYPESETTER  envi‐\nronment  variable  is  used, the default output device is ps.  An output device may be any of\nthe following.\n\nascii    for terminals using the ISO 646 1991:IRV character set and encoding, also  known  as\nUS-ASCII.\n\ncp1047   for terminals using the IBM code page 1047 character set and encoding.\n\ndvi      for TeX DVI format.\n"
                },
                {
                    "name": "html",
                    "content": "xhtml    for HTML and XHTML output, respectively.\n\nlatin1   for terminals using the ISO Latin-1 (ISO 8859-1) character set and encoding.\n\nlbp      for Canon CaPSL printers (LBP-4 and LBP-8 series laser printers).\n\nlj4      for HP LaserJet4-compatible (or other PCL5-compatible) printers.\n\npdf      for PDF output.\n\nps       for PostScript output.\n\nutf8     for terminals using the ISO 10646 (“Unicode”) character set in UTF-8 encoding.\n\nX75      for previewing with gxditview using 75 dpi resolution and a 10-point base type size.\n\nX75-12   for previewing with gxditview using 75 dpi resolution and a 12-point base type size.\n\nX100     for  previewing  with  gxditview  using  100 dpi resolution and a 10-point base type\nsize.\n\nX100-12  for previewing with gxditview using 100 dpi resolution  and  a  12-point  base  type\nsize.\n"
                },
                {
                    "name": "Postprocessors",
                    "content": "Any  program  that interprets the output of GNU troff is a postprocessor.  The postprocessors\nprovided by GNU roff are output drivers, which prepare a document for  viewing  or  printing.\nPostprocessors  for other purposes, such as page resequencing or statistical measurement of a\ndocument, are conceivable.\n\nAn output driver supports one or more output devices, each with its  own  device  description\nfile.   A  device  determines  its postprocessor with the postpro directive in its device de‐\nscription file; see grofffont(5).  The -X option overrides this selection, causing gxditview\nto serve as the output driver.\n\ngrodvi(1)\nprovides dvi.\n\ngrohtml(1)\nprovides html and xhtml.\n\ngrolbp(1)\nprovides lbp.\n\ngrolj4(1)\nprovides lj4.\n\ngropdf(1)\nprovides pdf.\n\ngrops(1)\nprovides ps.\n\ngrotty(1)\nprovides ascii, cp1047, latin1, and utf8.\n\ngxditview(1)\nprovides X75, X75-12, X100, and X100-12, and additionally can preview ps.\n"
                },
                {
                    "name": "Utilities",
                    "content": "GNU roff includes a suite of utilities.\n\ngdiffmk(1)\nmarks differences between a pair of roff input files.\n\ngrog(1)\ninfers the groff command a document requires.\n\nSeveral utilities prepare descriptions of fonts, enabling the formatter to use them when pro‐\nducing output for a given device.\n\naddftinfo(1)\nadds information to AT&T troff font description files to enable  their  use  with  GNU\ntroff.\n\nafmtodit(1)\ncreates font description files for PostScript Type 1 fonts.\n\npfbtops(1)\ntranslates  a  PostScript  Type  1  font  in  PFB  (Printer Font Binary) format to PFA\n(Printer Font ASCII), which can then be interpreted by afmtodit.\n\nhpftodit(1)\ncreates font description files for the HP LaserJet 4 family of printers.\n\ntfmtodit(1)\ncreates font description files for the TeX DVI device.\n\nxtotroff(1)\ncreates font description files for X Window System core fonts.\n\nA trio of tools transform material constructed using roff preprocessor languages into graphi‐\ncal image files.\n\neqn2graph(1)\nconverts an eqn equation into a cropped image.\n\ngrap2graph(1)\nconverts a grap diagram into a cropped image.\n\npic2graph(1)\nconverts a pic diagram into a cropped image.\n\nAnother set of programs works with the bibliographic data files used  by  the  refer(1)  pre‐\nprocessor.\n\nindxbib(1)\nmakes  inverted  indices  for  bibliographic  databases, speeding lookup operations on\nthem.\n\nlkbib(1)\nsearches the databases.\n\nlookbib(1)\ninteractively searches the databases.\n"
                }
            ]
        },
        "Exit status": {
            "content": "groff exits with a failure status if there was a problem parsing its arguments and a success‐\nful status if either of the options -h or --help was  specified.   Otherwise,  groff  runs  a\npipeline  to  process its input; if all commands within the pipeline exit successfully, groff\ndoes likewise.  If not, groff's exit status encodes a summary of problems  encountered,  set‐\nting  bit 0 if a command exited with a failure status, bit 1 if a command was terminated with\na signal, and bit 2 if a command could not be executed.  (Thus, if all three misfortunes  be‐\nfell  one's  pipeline,  groff  would exit with status 2^0 + 2^1 + 2^2 = 1+2+4 = 7.)  To trou‐\nbleshoot pipeline problems, you may wish to re-run the groff command with the -V  option  and\nbreak  the reported pipeline down into separate stages, inspecting the exit status of and di‐\nagnostic messages emitted by each command.\n",
            "subsections": []
        },
        "Environment": {
            "content": "Normally, the path separator in environment variables ending with PATH is the colon; this may\nvary depending on the operating system.  For example, Windows uses a semicolon instead.\n\nGROFFBINPATH\nThis search path, followed by PATH, is used to locate commands executed by groff.   If\nit  is  not  set, the installation directory of the GNU roff executables, /usr/bin, is\nsearched before PATH.\n\nGROFFCOMMANDPREFIX\nGNU roff can be configured at compile time to apply a prefix to the names of the  pro‐\ngrams  it  provides  that had a counterpart in AT&T troff, so that name collisions are\navoided at run time.  The default prefix is empty.\n\nWhen used, this prefix is conventionally the letter “g”.  For example, GNU troff would\nbe installed as gtroff.  Besides troff, the prefix applies to the formatter nroff; the\npreprocessors eqn, grn, pic, refer, tbl, and soelim; and  the  utilities  indxbib  and\nlookbib.\n\nGROFFENCODING\nThe value of this variable is passed to the preconv(1) preprocessor's -e option to se‐\nlect  the  character  encoding  of input files.  This variable's existence implies the\ngroff option -k.  If set but empty, groff calls preconv without an -e option.  groff's\n-K option overrides GROFFENCODING.\n\nGROFFFONTPATH\nSeek the selected output device's directory of device and font  description  files  in\nthis list of directories.  See troff(1) and grofffont(5).\n\nGROFFTMACPATH\nSeek macro files in this list of directories.  See troff(1) and grofftmac(5).\n\nGROFFTMPDIR\nCreate  temporary  files  in this directory.  If not set, but the environment variable\nTMPDIR is set, temporary files are created there instead.  On Windows systems, if nei‐\nther of the foregoing are set, the environment variables TMP and TEMP (in that  order)\nare  checked  also.   Otherwise,  temporary  files are created in /tmp.  The refer(1),\ngrohtml(1), and grops(1) commands use temporary files.\n\nGROFFTYPESETTER\nSet the default output device.  If empty or not set, ps is used.  The -T option  over‐\nrides GROFFTYPESETTER.\n\nSOURCEDATEEPOCH\nA time stamp (expressed as seconds since the Unix epoch) to use as the output creation\ntime stamp in place of the current time.  The time is converted to human-readable form\nusing  gmtime(3)  and  asctime(3) 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\ntzset(3).  If SOURCEDATEEPOCH is used, it is always converted to human-readable form\nusing UTC.\n",
            "subsections": []
        },
        "Examples": {
            "content": "roff  systems  are  best known for formatting man pages.  Once a man(1) librarian program has\nlocated a man page, it may execute a groff command much like the following.\ngroff -t -man -Tutf8 /usr/share/man/man1/groff.1\nThe librarian will also pipe the output through a pager, which might not  interpret  the  SGR\nterminal  escape  sequences  groff  emits  for boldface, underlining, or italics; see section\n“Limitations” below.\n\nTo process a roff input file using the preprocessors tbl and pic and the me macro package  in\nthe way to which AT&T troff users were accustomed, one would type (or script) a pipeline.\n\npic foo.me | tbl | troff -me -Tutf8 | grotty\n\nUsing groff, this pipe can be shortened to an equivalent command.\n\ngroff -p -t -me -T utf8 foo.me\n\nAn  even  easier way to do this is to use grog(1) to guess the preprocessor and macro options\nand execute the result by using the command substitution feature of the shell.\n\n$(grog -Tutf8 foo.me)\n\nEach command-line option to a postprocessor must  be  specified  with  any  required  leading\ndashes  “-” because groff passes the arguments as-is to the postprocessor; this permits arbi‐\ntrary arguments to be transmitted.  For example, to pass a title to the gxditview postproces‐\nsor, the shell commands\ngroff -X -P -title -P 'trial run' mydoc.t\nand\ngroff -X -Z mydoc.t | gxditview -title 'trial run' -\nare equivalent.\n",
            "subsections": []
        },
        "Limitations": {
            "content": "When paging output for the ascii, cp1047, latin1, and utf8 devices, programs like more(1) and\nless(1) may require command-line options to correctly handle some terminal escape  sequences;\nsee grotty(1).\n\nOn  EBCDIC  hosts  such as OS/390 Unix, the output devices ascii and latin1 aren't available.\nConversely, the output device cp1047 is not available on systems based  on  the  ISO  646  or\nISO 8859 character encoding standards.\n",
            "subsections": []
        },
        "Installation directories": {
            "content": "GNU roff installs files in varying locations depending on its compile-time configuration.  On\nthis installation, the following locations are used.\n\n/etc/X11/app-defaults\nApplication defaults directory for gxditview(1).\n\n/usr/bin\nDirectory containing groff's executable commands.\n\n/usr/share/groff/1.23.0/eign\nList of common words for indxbib(1).\n\n/usr/share/groff/1.23.0\nDirectory for data files.\n\n/usr/dict/papers/Ind\nDefault index for lkbib(1) and refer(1).\n\n/usr/share/doc/groff-base\nDocumentation directory.\n\n/usr/share/doc/groff-base/examples\nExample directory.\n\n/usr/share/groff/1.23.0/font\nFont directory.\n\n/usr/share/doc/groff-base/html\nHTML documentation directory.\n\n/usr/lib/font\nLegacy font directory.\n\n/usr/share/groff/site-font\nLocal font directory.\n\n/usr/share/groff/site-tmac\nLocal macro package (tmac file) directory.\n\n/usr/share/groff/1.23.0/tmac\nMacro package (tmac file) directory.\n\n/usr/share/groff/1.23.0/oldfont\nFont directory for compatibility with old versions of groff; see grops(1).\n\n/usr/share/doc/groff-base/pdf\nPDF documentation directory.\n\ngroff macro directory\nMost  macro  files  supplied with GNU roff are stored in /usr/share/groff/1.23.0/tmac for the\ninstallation corresponding to this document.  As a rule, multiple  directories  are  searched\nfor  macro  files;  see  troff(1).   For  a  catalog  of  macro  files GNU roff provides, see\ngrofftmac(5).\n\ngroff device and font description directory\nDevice and font description files supplied with GNU  roff  are  stored  in  /usr/share/groff/\n1.23.0/font  for the installation corresponding to this document.  As a rule, multiple direc‐\ntories are searched for device and font description files; see troff(1).  For the formats  of\nthese files, see grofffont(5).\n",
            "subsections": []
        },
        "Availability": {
            "content": "Obtain links to groff releases for download, its source repository, discussion mailing lists,\na support ticket tracker, and further information from the groff page of the GNU website.\n\nA  free  implementation  of  the grap preprocessor, written by Ted Faber, can be found at the\ngrap website.  groff supports only this grap.\n",
            "subsections": []
        },
        "Authors": {
            "content": "groff (both the front-end command and the overall system)  was  primarily  written  by  James\nClark.   Contributors  to this document include Clark, Trent A. Fisher, Werner Lemberg, Bernd\nWarken, and G. Branden Robinson.\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\nIntroduction, history, and further reading:\nroff(7)\n\nViewer for groff (and AT&T device-independent troff) documents:\ngxditview(1)\n\nPreprocessors:\nchem(1),  eqn(1),  neqn(1),  glilypond(1),  grn(1),  preconv(1),   gperl(1),   pic(1),\ngpinyin(1), refer(1), soelim(1), tbl(1)\n\nMacro packages and package-specific utilities:\ngroffhdtbl(7),    groffman(7),   groffmanstyle(7),   groffmdoc(7),   groffme(7),\ngroffmm(7),  groffmmse(7)  (only  in  Swedish  locales),  mmroff(1),   groffmom(7),\npdfmom(1), groffms(7), groffrfc1345(7), grofftrace(7), groffwww(7)\n\nBibliographic database management tools:\nindxbib(1), lkbib(1), lookbib(1)\n\nLanguage, conventions, and GNU extensions:\ngroff(7), groffchar(7), groffdiff(7), grofffont(5), grofftmac(5)\n\nIntermediate output language:\ngroffout(5)\n\nFormatter program:\ntroff(1)\n\nFormatter wrappers:\nnroff(1), pdfroff(1)\n\nPostprocessors for output devices:\ngrodvi(1), grohtml(1), grolbp(1), grolj4(1), gropdf(1), grops(1), grotty(1)\n\nFont support utilities:\naddftinfo(1), afmtodit(1), hpftodit(1), pfbtops(1), tfmtodit(1), xtotroff(1)\n\nGraphics conversion utilities:\neqn2graph(1), grap2graph(1), pic2graph(1)\n\nDifference-marking utility:\ngdiffmk(1)\n\n“groff guess” utility:\ngrog(1)\n\ngroff 1.23.0                                31 March 2024                                   groff(1)",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": [],
    "tldr": {
        "source": "official",
        "description": "GNU replacement for the `troff` and `nroff` typesetting utilities.",
        "examples": [
            {
                "description": "Format output for a PostScript printer, saving the output to a file",
                "command": "groff {{path/to/input.roff}} > {{path/to/output.ps}}"
            },
            {
                "description": "Render a man page using the ASCII output device, and display it using a pager",
                "command": "groff -man -T ascii {{path/to/manpage.1}} | less --RAW-CONTROL-CHARS"
            },
            {
                "description": "Render a man page into an HTML file",
                "command": "groff -man -T html {{path/to/manpage.1}} > {{path/to/manpage.html}}"
            },
            {
                "description": "Typeset a roff file containing [t]ables and [p]ictures, using the [me] macro set, to PDF, saving the output",
                "command": "groff {{t}} {{p}} -{{me}} -T {{pdf}} {{path/to/input.me}} > {{path/to/output.pdf}}"
            },
            {
                "description": "Run a `groff` command with preprocessor and macro options guessed by the `grog` utility",
                "command": "eval \"$(grog -T utf8 {{path/to/input.me}})\""
            }
        ]
    }
}