# groff

## Name



           groff - front end to the GNU _roff_ document formatting system
    


## Synopsis



           **groff**[**-abcCeEgGijklNpRsStUVXzZ**] [**-d** _ctext_] [**-d** _string_**=**_text_]
                 [**-D** _fallback-encoding_] [**-f** _font-family_] [**-F** _font-directory_]
                 [**-I** _inclusion-directory_] [**-K** _input-encoding_] [**-L** _spooler-_
                 _argument_] [**-m** _macro-package_] [**-M** _macro-directory_] [**-n** _page-_
                 _number_] [**-o** _page-list_] [**-P** _postprocessor-argument_]
                 [**-r** _cnumeric-expression_] [**-r** _register_**=**_numeric-expression_]
                 [**-T** _output-device_] [**-w** _warning-category_] [**-W** _warning-_
                 _category_] [_file_ ...]
    
           **groff -h**
    
           **groff --help**
    
           **groff -v**[_option_ ...] [_file_ ...]
    
           **groff --version**[_option_ ...] [_file_ ...]
    


## Description



           _groff_ is the primary front end to the GNU _roff_ document formatting
           system.  GNU _roff_ is a typesetting system that reads plain text
           input that includes formatting commands to produce output in
           PostScript, PDF, HTML, or other formats, or for display to a
           terminal.  Formatting commands can be low-level typesetting
           primitives, macros from a supplied package, or user-defined
           macros.  All three approaches can be combined.  If no _file_
           operands are specified, or if _file_ is “**-** ”, _groff_ reads the
           standard input stream.
    
           A reimplementation and extension of _troff_ and other programs from
           AT&T Unix, _groff_ is widely available on POSIX and other systems
           owing to its long association with Unix manuals, including man
           pages.  It and its predecessor have produced several best-selling
           software engineering texts.  _groff_ can create typographically
           sophisticated documents while consuming minimal system resources.
    
           The _groff_ command orchestrates the execution of preprocessors, the
           transformation of input documents into a device-independent page
           description language, and the production of output from that
           language.
    


## Options



           **-h** and **--help** display a usage message and exit.
    
           Because _groff_ is intended to subsume most users' direct
           invocations of the _troff_(1) formatter, the two programs share a
           set of options.  However, _groff_ has some options that _troff_ does
           not share, and others which _groff_ interprets differently.  At the
           same time, not all valid _troff_ options can be given to _groff_.
    
       [1mgroff[24m-specific options
           The following options either do not exist in GNU _troff_ or are
           interpreted differently by _groff_.
    
           **-D** _enc_ Use _enc_ as _preconv_(1)'s fallback input encoding; implies
                  **-k**.
    
           **-e** Run _eqn_(1) preprocessor.
    
           **-g** Run _grn_(1) preprocessor.
    
           **-G** Run _grap_(1) preprocessor; implies **-p**.
    
           **-I** _dir_ Works as _troff_ 's option (see below), but also implies **-g**
                  and **-s**.  _groff_ passes **-I** options and their arguments to
                  _soelim_(1), _troff_(1), and output drivers; with the option
                  letter changed to **-M** , the same arguments are passed to
                  _grn_(1).
    
           **-j** Run _chem_(1) preprocessor; implies **-p**.
    
           **-k** Run _preconv_(1) preprocessor.  Refer to its man page for its
                  behavior if neither of _groff_ 's **-K** or **-D** options is also
                  specified.
    
           **-K** _enc_ Set input encoding used by _preconv_(1) to _enc_ ; implies **-k**.
    
           **-l** Send the output to a spooler program for printing.  The
                  “**print** ” directive in the device description file specifies
                  the default command to be used; see _groff_font_(5).  If no
                  such directive is present for the output device, output is
                  piped to _lpr_(1).  See options **-L** and **-X**.
    
           **-L** _arg_ Pass _arg_ to the print spooler.  If multiple _arg_ s are
                  required, pass each with a separate **-L** option.  _groff_ does
                  not prefix an option dash to _arg_ before passing it to the
                  spooler.
    
           **-M** Works as _troff_ 's option (see below), but is also passed to
                  _eqn_(1), _grap_(1), and _grn_(1).
    
           **-N** Prohibit newlines between _eqn_ delimiters: pass **-N** to
                  _eqn_(1).
    
           **-p** Run _pic_(1) preprocessor.
    
           **-P** _arg_ Pass _arg_ to the postprocessor.  If multiple _arg_ s are
                  required, pass each with a separate **-P** option.  _groff_ does
                  not prefix an option dash to _arg_ before passing it to the
                  postprocessor.
    
           **-R** Run _refer_(1) preprocessor.  No mechanism is provided for
                  passing arguments to it; most _refer_ options have equivalent
                  language elements that can be specified within the
                  document.
    
           **-s** Run _soelim_(1) preprocessor.
    
           **-S** Operate in “safer” mode; see **-U** below for its opposite.
                  Safer mode is enabled by default.
    
           **-t** Run _tbl_(1) preprocessor.
    
           **-T** _dev_ Prepare output for device _dev._  _groff_ passes the **-T** option
                  and its argument to _troff_ , then (unless the **-Z** option is
                  used) runs an output driver to convert _troff_ 's output to a
                  form appropriate for _dev_ ; see subsection “Output devices”
                  below.
    
           **-U** Operate in unsafe mode.  _groff_ passes the **-U** option to
                  _pic_(1) and _troff_(1).
    
           **--version**
           **-v** Write version information for _groff_ and all programs run by
                  it to the standard output stream; that is, the given
                  command line is processed in the usual way, passing **-v** to
                  the formatter and any pre- or postprocessors invoked.
    
           **-V** Output the pipeline that _groff_ would run to the standard
                  output stream and exit.  If given more than once, _groff_
                  both writes the pipeline to the standard error stream and
                  runs it.
    
           **-X** Use _gxditview_(1) instead of the usual postprocessor to
                  (pre)view a document on an X11 display.  Combining this
                  option with “**-T ps** ” uses the font metrics of the PostScript
                  device, whereas the “**-T X75** ”, “**-T X75-12** ” “**-T X100** ”, and
                  “**-T X100-12** ” options use the metrics of X11 fonts.
    
           **-Z** Disable postprocessing.  _troff_ output will appear on the
                  standard output stream (unless suppressed with **-z**); see
                  _groff_out_(5) for a description of this format.
    
       **Transparent options**
           The following options are passed as-is to the formatter program
           _troff_(1) and described in more detail in its man page.
    
           **-a** Generate a plain text approximation of the typeset output.
    
           **-b** Write a backtrace to the standard error stream on each
                  error or warning.
    
           **-c** Start with color output disabled.
    
           **-C** Enable AT&T _troff_ compatibility mode; implies **-c**.
    
           **-d** _ctext_
           **-d** _string_**=**_text_
                  Define string.
    
           **-E** Inhibit _troff_ error messages; implies **-Ww**.
    
           **-f** _fam_ Set default font family.
    
           **-F** _dir_ Search in directory _dir_ for the selected output device's
                  directory of device and font description files.
    
           **-i** Process standard input after the specified input files.
    
           **-I** _dir_ Search _dir_ for input files.
    
           **-m** _mac_ Read macro package _mac_ before input.  _groff_ passes **-m**
                  options and their arguments to _eqn_(1), _grap_(1), and _grn_(1).
    
           **-M** _dir_ Search directory _dir_ for macro files.  _groff_ passes **-M**
                  options and their arguments to _eqn_(1), _grap_(1), and _grn_(1).
    
           **-n** _num_ Begin numbering pages at _num._
    
           **-o** _list_
                  Output only pages in _list_.
    
           **-r** _cnumeric-expression_
           **-r** _register_**=**_numeric-expression_
                  Define register.
    
           **-w** _cat_
           **-W** _cat_ Enable and inhibit, respectively, warnings in category _cat._
    
           **-z** Suppress formatted device-independent output of _troff_.
    


## Usage



           The architecture of the GNU _roff_ system follows that of other
           device-independent _roff_ implementations, comprising preprocessors,
           macro packages, output drivers (or “postprocessors”), and a suite
           of utilities, with the formatter program _troff_(1) at its heart.
           See _roff_(7) for a survey of how a _roff_ system works.
    
           The front end programs available in the GNU _roff_ system make it
           easier to use than traditional _roff_ s that required the
           construction of pipelines or use of temporary files to carry a
           source document from maintainable form to device-ready output.
           The discussion below summarizes the constituent parts of the GNU
           _roff_ system.  It complements _roff_(7) with _groff_ -specific
           information.
    
       **Getting started**
           Those who prefer to learn by experimenting or are desirous of
           rapid feedback from the system may wish to start with a “Hello,
           world!” document.
    
           $ **echo "Hello, world!" | groff -Tascii | sed '/^$/d'**
           Hello, world!
    
           We used a _sed_(1) command only to eliminate the 65 blank lines that
           would otherwise flood the terminal screen.  (_roff_ systems were
           developed in the days of paper-based terminals with 66 lines to a
           page.)
    
           Today's users may prefer output to a UTF-8-capable terminal.
    
           $ **echo "Hello, world!" | groff -Tutf8 | sed '/^$/d'**
    
           Producing PDF, HTML, or TeX's DVI is also straightforward.  The
           hard part may be selecting a viewer program for the output.
    
           $ **echo "Hello, world!" | groff -Tpdf > hello.pdf**
           $ **evince hello.pdf**
           $ **echo "Hello, world!" | groff -Thtml > hello.html**
           $ **firefox hello.html**
           $ **echo "Hello, world!" | groff -Tdvi > hello.dvi**
           $ **xdvi hello.dvi**
    
       **Using _groff_ as a REPL**
           Those with a programmer's bent may be pleased to know that they
           can use _groff_ in a read-evaluate-print loop (REPL).  Doing so can
           be handy to verify one's understanding of the formatter's behavior
           and/or the syntax it accepts.  Turning on all warnings with **-ww**
           can aid this goal.
    
           $ **groff -ww -Tutf8**
           **\# This is a comment. Let's define a register.**
           **.nr a 1**
           **\# Do integer arithmetic with operators evaluated left-to-right.**
           **.nr b \n[a]+5/2**
           **\# Let's get the result on the standard error stream.**
           **.tm \n[b]**
           3
           **\# Now we'll define a string.**
           **.ds name Leslie\" This is another form of comment.**
           **.nr b (\n[a] + (7/2))**
           **\# Center the next two text input lines.**
           **.ce 2**
           **Hi, \*[name].**
           **Your secret number is \n[b].**
           **\# We will see that the division rounded toward zero.**
           **It is**
           **\# Here's an if-else control structure.**
           **.ie (\n[b] % 2) odd.**
           **.el even.**
           **\# This trick sets the page length to the current vertical**
           **\# position, so that blank lines don't spew when we're done.**
           **.pl \n[nl]u**
           _< Control-D>_
                                      Hi, Leslie.
                               Your secret number is 4.
           It is even.
    
       **Paper format**
           _troff_ reads the device description file _DESC_ for the selected
           output device when it starts; page dimensions declared there are
           used if present.  _groff_ 's build process configures a default page
           format and writes it to typesetters' _DESC_ files.  This
           installation defaults to “**letter** ”.  If the _DESC_ file lacks this
           information, the formatter and output driver use a page length of
           11i (inches) for compatibility with AT&T _troff_.  See
           _groff_font_(5).
    
           In the formatter, the **pl** request changes the page length, but
           macro packages often do not support alteration of the paper format
           within a document.  One might, for instance, want to switch
           between portrait and landscape orientations.  Macro packages lack
           a consistent approach to configuration of parameters dependent on
           the paper format; some, like _ms_ , benefit from a preamble in the
           document prior to the first macro call, while others, like _mm_ ,
           instead require the specification of registers on the command
           line, or otherwise before its macro file is interpreted, to
           configure page dimensions.
    
           Output drivers for typesetters also recognize command-line options
           **-p** to override the default page dimensions and **-l** to use landscape
           orientation.  The output driver's man page, such as _grops_(1), may
           be helpful.
    
           _groff_ 's “**-d paper** ” command-line option is a convenient means of
           setting the paper format; see _groff_tmac_(5).  Combine it with
           appropriate **-P** options for the output driver, overriding its
           defaults.  The following command formats for PostScript on A4
           paper in landscape orientation.
    
                  $ **groff -T ps -d paper=a4l -P -pa4 -P -l -ms my.ms >my.ps**
    
       **Front end**
           The _groff_ program wraps _troff_(1), allowing one to specify
           preprocessors via command-line options and running the appropriate
           output driver for the selected output device.  This convenience
           avoids the manual construction of pipelines or management of
           temporary files required of users of traditional _roff_(7) systems.
           Use _grog_(1) to infer an appropriate _groff_ command line to format a
           document.
    
       **Language**
           Input to a _roff_ system is in plain text interleaved with control
           lines and escape sequences.  The combination constitutes a
           document in one of a family of languages we also call _roff_ ; see
           _roff_(7) for background.  An overview of GNU _roff_ language syntax
           and features, including lists of all supported escape sequences,
           requests, and predefined registers, can be found in _groff_(7).  GNU
           _roff_ extensions to the AT&T _troff_ language, a common subset of
           _roff_ dialects extant today, are detailed in _groff_diff_(7).
    
       **Preprocessors**
           A preprocessor interprets a domain-specific language that produces
           _roff_ language output.  Frequently, such input is confined to
           sections or regions of _roff_ input (bracketed with macro calls
           specific to each preprocessor), which it replaces.  Preprocessors
           therefore often interpret a subset of _roff_ syntax along with their
           own language.  GNU _roff_ provides reimplementations of most
           preprocessors familiar to users of AT&T _troff_ ; these routinely
           have extended features and/or require GNU _troff_ to format their
           output.
    
                  _tbl_         lays out tables;
                  _eqn_         typesets mathematics;
                  _pic_         draws diagrams;
                  _refer_       processes bibliographic references;
                  _soelim_      preprocesses “sourced” input files;
                  _grn_         renders _gremlin_(1) diagrams;
                  _chem_        draws chemical structural formulæ using _pic_ ;
                  _gperl_       populates _groff_ registers and strings using
                              _perl_(1);
                  _glilypond_   embeds _LilyPond_ sheet music; and
                  _gpinyin_     eases Mandarin Chinese input using Hanyu
                              Pinyin.
    
           A preprocessor unique to GNU _roff_ is _preconv_(1), which converts
           various input encodings to something GNU _troff_ can understand.
           When used, it is run before any other preprocessors.
    
           Most preprocessors enclose content between a pair of
           characteristic tokens.  Such a token must occur at the beginning
           of an input line and use the dot control character.  Spaces and
           tabs must not follow the control character or precede the end of
           the input line.  Deviating from these rules defeats a token's
           recognition by the preprocessor.  Tokens are generally preserved
           in preprocessor output and interpreted as macro calls subsequently
           by _troff_.  The _ideal_ preprocessor is not yet available in _groff_.
    
                  ┌──────────────┬─────────────────┬────────────────┐
                  │ preprocessor │ starting token  │  ending token  │
                  ├──────────────┼─────────────────┼────────────────┤
                  │     _chem_     │     .cstart     │     .cend      │
                  │     _eqn_      │       .EQ       │      .EN       │
                  │     _grap_     │       .G1       │      .G2       │
                  │     _grn_      │       .GS       │      .GE       │
                  │    _ideal_     │       .IS       │      .IE       │
                  │              │                 │      .IF       │
                  │     _pic_      │       .PS       │      .PE       │
                  │              │                 │      .PF       │
                  │              │                 │      .PY       │
                  │    _refer_     │       .R1       │      .R2       │
                  │     _tbl_      │       .TS       │      .TE       │
                  ├──────────────┼─────────────────┼────────────────┤
                  │  _glilypond_   │ .lilypond start │ .lilypond stop │
                  │    _gperl_     │   .Perl start   │   .Perl stop   │
                  │   _gpinyin_    │  .pinyin start  │  .pinyin stop  │
                  └──────────────┴─────────────────┴────────────────┘
    
       **Macro packages**
           Macro files are _roff_ input files designed to produce no output
           themselves but instead ease the preparation of other _roff_
           documents.  When a macro file is installed at a standard location
           and suitable for use by a general audience, it is termed a _macro_
           _package_.
    
           Macro packages can be loaded prior to any _roff_ input documents
           with the **-m** option.  The GNU _roff_ system implements most well-
           known macro packages for AT&T _troff_ in a compatible way and
           extends them.  These have one- or two-letter names arising from
           intense practices of naming economy in early Unix culture, a
           laconic approach that led to many of the packages being identified
           in general usage with the _nroff_ and _troff_ option letter used to
           invoke them, sometimes to punning effect, as with “man” (short for
           “manual”), and even with the option dash, as in the case of the _s_
           package, much better known as _ms_ or even _-ms_.
    
           Macro packages serve a variety of purposes.  Some are “full-
           service” packages, adopting responsibility for page layout among
           other fundamental tasks, and defining their own lexicon of macros
           for document composition; each such package stands alone and a
           given document can use at most one.
    
           _an_     is used to compose man pages in the format originating in
                  Version 7 Unix (1979); see _groff_man_(7).  It can be
                  specified on the command line as **-man**.
    
           _doc_    is used to compose man pages in the format originating in
                  4.3BSD-Reno (1990); see _groff_mdoc_(7).  It can be specified
                  on the command line as **-mdoc**.
    
           _e_      is the Berkeley general-purpose macro suite, developed as
                  an alternative to AT&T's _s_ ; see _groff_me_(7).  It can be
                  specified on the command line as **-me**.
    
           _m_      implements the format used by the second-generation AT&T
                  macro suite for general documents, a successor to _s_ ; see
                  _groff_mm_(7).  It can be specified on the command line as
                  **-mm**.
    
           _om_     (invariably called “mom”) is a modern package written by
                  Peter Schaffter specifically for GNU _roff_.  Consult the _mom_
                  HTML manual ⟨file:///usr/local/share/doc/groff-1.23.0/html/
                  mom/toc.html⟩ for extensive documentation.  She—for _mom_
                  takes the female pronoun—can be specified on the command
                  line as **-mom**.
    
           _s_      is the original AT&T general-purpose document format; see
                  _groff_ms_(7).  It can be specified on the command line as
                  **-ms**.
    
           Others are supplemental.  For instance, _andoc_ is a wrapper package
           specific to GNU _roff_ that recognizes whether a document uses _man_
           or _mdoc_ format and loads the corresponding macro package.  It can
           be specified on the command line as **-mandoc**.  A _man_(1) librarian
           may use this macro file to delegate loading of the correct macro
           package; it is thus unnecessary for _man_ itself to scan the
           contents of a document to decide the issue.
    
           Many macro files augment the function of the full-service
           packages, or of _roff_ documents that do not employ such a package—
           the latter are sometimes characterized as “raw”.  These auxiliary
           packages are described, along with details of macro file naming
           and placement, in _groff_tmac_(5).
    
       **Formatters**
           The formatter, the program that interprets _roff_ language input, is
           _troff_(1).  It provides the features of the AT&T _troff_ and _nroff_
           programs as well as many extensions.  The command-line option **-C**
           switches _troff_ into _compatibility mode_ , which tries to emulate
           AT&T _troff_ as closely as is practical to enable the formatting of
           documents written for the older system.
    
           A shell script, _nroff_(1), emulates the behavior of AT&T _nroff_.  It
           attempts to correctly encode the output based on the locale,
           relieving the user of the need to specify an output device with
           the **-T** option and is therefore convenient for use with terminal
           output devices, described in the next subsection.
    
           GNU _troff_ generates output in a device-independent, but not
           device-agnostic, page description language detailed in
           _groff_out_(5).
    
       **Output devices**
           _troff_ output is formatted for a particular _output device_ ,
           typically specified by the **-T** option to the formatter or a front
           end.  If neither this option nor the _GROFF_TYPESETTER_ environment
           variable is used, the default output device is **ps**.  An output
           device may be any of the following.
    
           **ascii** for terminals using the ISO 646 1991:IRV character set and
                  encoding, also known as US-ASCII.
    
           **dvi** for TeX DVI format.
    
           **html**
           **xhtml** for HTML and XHTML output, respectively.
    
           **latin1** for terminals using the ISO Latin-1 (8859-1) character set
                  and encoding.
    
           **lbp** for Canon CaPSL printers (LBP-4 and LBP-8 series laser
                  printers).
    
           **lj4** for HP LaserJet4-compatible (or other PCL5-compatible)
                  printers.
    
           **pdf** for PDF output.
    
           **ps** for PostScript output.
    
           **utf8** for terminals using the ISO 10646 (“Unicode”) character set
                  in UTF-8 encoding.
    
           **X75** for previewing with _gxditview_ using 75 dpi resolution and a
                  10-point base type size.
    
           **X75-12** for previewing with _gxditview_ using 75 dpi resolution and a
                  12-point base type size.
    
           **X100** for previewing with _gxditview_ using 100 dpi resolution and
                  a 10-point base type size.
    
           **X100-12**
                  for previewing with _gxditview_ using 100 dpi resolution and
                  a 12-point base type size.
    
       **Postprocessors**
           Any program that interprets the output of GNU _troff_ is a
           postprocessor.  The postprocessors provided by GNU _roff_ are _output_
           _drivers_ , which prepare a document for viewing or printing.
           Postprocessors for other purposes, such as page resequencing or
           statistical measurement of a document, are conceivable.
    
           An output driver supports one or more output devices, each with
           its own device description file.  A device determines its
           postprocessor with the **postpro** directive in its device description
           file; see _groff_font_(5).  The **-X** option overrides this selection,
           causing _gxditview_ to serve as the output driver.
    
           _grodvi_(1)
                  provides **dvi**.
    
           _grohtml_(1)
                  provides **html** and **xhtml**.
    
           _grolbp_(1)
                  provides **lbp**.
    
           _grolj4_(1)
                  provides **lj4**.
    
           _gropdf_(1)
                  provides **pdf**.
    
           _grops_(1)
                  provides **ps**.
    
           _grotty_(1)
                  provides **ascii** , **latin1** , and **utf8**.
    
           _gxditview_(1)
                  provides **X75** , **X75-12** , **X100** , and **X100-12** , and additionally
                  can preview **ps**.
    
       **Utilities**
           GNU _roff_ includes a suite of utilities.
    
           _gdiffmk_(1)
                  marks differences between a pair of _roff_ input files.
    
           _grog_(1)
                  infers the _groff_ command a document requires.
    
           Several utilities prepare descriptions of fonts, enabling the
           formatter to use them when producing output for a given device.
    
           _addftinfo_(1)
                  adds information to AT&T _troff_ font description files to
                  enable their use with GNU _troff_.
    
           _afmtodit_(1)
                  creates font description files for PostScript Type 1 fonts.
    
           _pfbtops_(1)
                  translates a PostScript Type 1 font in PFB (Printer Font
                  Binary) format to PFA (Printer Font ASCII), which can then
                  be interpreted by _afmtodit_.
    
           _hpftodit_(1)
                  creates font description files for the HP LaserJet 4 family
                  of printers.
    
           _tfmtodit_(1)
                  creates font description files for the TeX DVI device.
    
           _xtotroff_(1)
                  creates font description files for X Window System core
                  fonts.
    
           A trio of tools transform material constructed using _roff_
           preprocessor languages into graphical image files.
    
           _eqn2graph_(1)
                  converts an _eqn_ equation into a cropped image.
    
           _grap2graph_(1)
                  converts a _grap_ diagram into a cropped image.
    
           _pic2graph_(1)
                  converts a _pic_ diagram into a cropped image.
    
           Another set of programs works with the bibliographic data files
           used by the _refer_(1) preprocessor.
    
           _indxbib_(1)
                  makes inverted indices for bibliographic databases,
                  speeding lookup operations on them.
    
           _lkbib_(1)
                  searches the databases.
    
           _lookbib_(1)
                  interactively searches the databases.
    


## Exit status



           _groff_ exits successfully (with status **0**) if either of the options
           **-h** or **--help** is specified, status **2** if the program cannot
           interpret its command-line arguments, and status **1** if it
           encounters an error during operation.  Otherwise, _groff_ runs a
           pipeline to process its input; if all commands within the pipeline
           exit successfully, _groff_ does likewise.  If not, _groff_ 's exit
           status encodes a summary of problems encountered, setting bit 2 if
           a command exited with a failure status, bit 3 if a command was
           terminated with a signal, and bit 4 if a command could not be
           executed.  (Thus, if all three misfortunes befall one's pipeline,
           _groff_ exits with status 2^2 + 2^3 + 2^4 = 4+8+16 = 28.)  To
           troubleshoot pipeline problems, re-run the _groff_ command with the
           **-V** option and break the reported pipeline down into separate
           stages, inspecting the exit status of, and diagnostic messages
           emitted by, each command.
    


## Environment



           Environment variables in the host system affect the behavior of
           programs supplied by _groff_ as follows.  Normally, the path
           separator in environment variables ending with _PATH_ is the colon;
           this may vary depending on the operating system.  For example,
           Windows uses a semicolon instead.
    
           _GROFF_BIN_PATH_
                  Locate _groff_ commands in these directories, followed by
                  those in _PATH_.  If not set, the installation directory of
                  GNU _roff_ executables, _/usr/local/bin_ , is searched before
                  _PATH_.
    
           _GROFF_COMMAND_PREFIX_
                  Apply a prefix to certain GNU _roff_ commands.  _groff_ can be
                  configured at compile time to apply a prefix to the names
                  of programs it provides that had counterparts in AT&T
                  _troff_ , so that name collisions are avoided at run time.
                  The default prefix is empty.
    
                  When used, this prefix is conventionally the letter “g”.
                  For example, GNU _troff_ would be installed as _gtroff_.
                  Besides _troff_ , the prefix applies to the formatter wrapper
                  _nroff_ ; the preprocessors _eqn_ , _grn_ , _pic_ , _refer_ , _tbl_ , and
                  _soelim_ ; and the utilities _indxbib_ and _lookbib_.
    
           _GROFF_ENCODING_
                  Specify the assumed character encoding of the input.  _groff_
                  passes its value as an argument to preconv(1)
                  preprocessor's **-e** option.  This variable's existence
                  implies the _groff_ option **-k**.  If set but empty, _groff_ runs
                  _preconv_ without an **-e** option.  _groff_ 's **-K** option overrides
                  _GROFF_ENCODING_.
    
           _GROFF_FONT_PATH_
                  Seek the selected output device's directory of device and
                  font description files in this list of directories.  See
                  _troff_(1) and _groff_font_(5).
    
           _GROFF_TMAC_PATH_
                  Seek macro packages in this list of directories.  See
                  _troff_(1) and _groff_tmac_(5).
    
           _GROFF_TMPDIR_
                  Create temporary files in this directory.  If not set, but
                  _TMPDIR_ is, the latter is used instead.  On Windows systems,
                  if neither of the foregoing are set, the environment
                  variables _TMP_ and _TEMP_ (in that order) are checked also.
                  Otherwise, temporary files are created in _/tmp_.  The
                  _refer_(1), _grohtml_(1), and _grops_(1) commands use temporary
                  files.
    
           _GROFF_TYPESETTER_
                  Set the default output device.  If empty or not set, **ps** is
                  used.  The **-T** option overrides _GROFF_TYPESETTER_.
    
           _SOURCE_DATE_EPOCH_
                  Declare a time stamp (expressed as seconds since the Unix
                  epoch) to use as the output creation time stamp in place of
                  the current time.  The time is converted to human-readable
                  form using _gmtime_(3) and _asctime_(3) when the formatter
                  starts up and stored in registers usable by documents and
                  macro packages.
    
           _TZ_     Declare the time zone to use when converting the current
                  time to human-readable form; see _tzset_(3).  If
                  _SOURCE_DATE_EPOCH_ is used, it is always converted to human-
                  readable form using UTC.
    


## Examples



           _roff_ systems are best known for formatting man pages.  A _man_(1)
           librarian program, having located a page, might render it with a
           _groff_ command.
                  groff -t -man -Tutf8 /usr/share/man/man1/groff.1
           The librarian will also pipe the output through a pager, which
           might not interpret terminal escape sequences _groff_ emits for
           boldface, underlining, italics, or hyperlinking; see section
           “Limitations” below.
    
           To process a _roff_ input file using the preprocessors _tbl_ and _pic_
           and the _me_ macro package in the way to which AT&T _troff_ users were
           accustomed, one would type (or script) a pipeline.
    
                  pic foo.me | tbl | troff -me -Tutf8 | grotty
    
           Shorten this pipeline to an equivalent command using _groff_.
    
                  groff -p -t -me -T utf8 foo.me
    
           An even easier way to do this is to use _grog_(1) to guess the
           preprocessor and macro options and execute the result by using the
           command substitution feature of the shell.
    
                  $(grog -Tutf8 foo.me)
    
           Each command-line option to a postprocessor must be specified with
           any required leading dashes “**-** ” because _groff_ passes the arguments
           as-is to the postprocessor; this permits arbitrary arguments to be
           transmitted.  For example, to pass a title to the _gxditview_
           postprocessor, the shell commands
                  groff -X -P -title -P 'trial run' mydoc.t
           and
                  groff -X -Z mydoc.t | gxditview -title 'trial run' -
           are equivalent.
    


## Limitations



           When paging output for the **ascii** , **latin1** , and **utf8** devices,
           programs like _more_(1) and _less_(1) may require command-line options
           to correctly handle some terminal escape sequences; see _grotty_(1).
    


## Installation directories



           GNU _roff_ installs files in varying locations depending on its
           compile-time configuration.  On this installation, the following
           locations are used.
    
           _/usr/local/bin_
                  Directory containing _groff_ 's executable commands.
    
           _/usr/local/share/groff/1.23.0/eign_
                  List of common words for _indxbib_(1).
    
           _/usr/local/share/groff/1.23.0_
                  Directory for data files.
    
           _/usr/dict/papers/Ind_
                  Default index for _lkbib_(1) and _refer_(1).
    
           _/usr/local/share/doc/groff-1.23.0_
                  Documentation directory.
    
           _/usr/local/share/doc/groff-1.23.0/examples_
                  Example directory.
    
           _/usr/local/share/groff/1.23.0/font_
                  Font directory.
    
           _/usr/local/share/doc/groff-1.23.0/html_
                  HTML documentation directory.
    
           _/usr/lib/font_
                  Legacy font directory.
    
           _/usr/local/share/groff/site-font_
                  Local font directory.
    
           _/usr/local/share/groff/site-tmac_
                  Local macro package (_tmac_ file) directory.
    
           _/usr/local/share/groff/1.23.0/tmac_
                  Macro package (_tmac_ file) directory.
    
           _/usr/local/share/groff/1.23.0/oldfont_
                  Font directory for compatibility with old versions of
                  _groff_ ; see _grops_(1).
    
           _/usr/local/share/doc/groff-1.23.0/pdf_
                  PDF documentation directory.
    
       [1mgroff[24m macro directory
           Most macro files supplied with GNU _roff_ are stored in _/usr/local/_
           _share/groff/1.23.0/tmac_ for the installation corresponding to this
           document.  As a rule, multiple directories are searched for macro
           files; see _troff_(1).  For a catalog of macro files GNU _roff_
           provides, see _groff_tmac_(5).
    
       [1mgroff[24m device and font description directory
           Device and font description files supplied with GNU _roff_ are
           stored in _/usr/local/share/groff/1.23.0/font_ for the installation
           corresponding to this document.  As a rule, multiple directories
           are searched for device and font description files; see _troff_(1).
           For the formats of these files, see _groff_font_(5).
    


## Availability



           Obtain links to _groff_ releases for download, its source
           repository, discussion mailing lists, a support ticket tracker,
           and further information from the _groff_ page of the GNU website 
           ⟨http://www.gnu.org/software/groff⟩.
    
           A free implementation of the _grap_ preprocessor, written by Ted
           Faber ⟨faber@lunabase.org⟩, can be found at the _grap_ website 
           ⟨http://www.lunabase.org/~faber/Vault/software/grap/⟩.  _groff_
           supports only this _grap_.
    


## Authors



           _groff_ (both the front-end command and the overall system) was
           primarily written by James Clark ⟨jjc@jclark.com⟩.  Contributors
           to this document include Clark, Trent A. Fisher, Werner Lemberg
           ⟨wl@gnu.org⟩, Bernd Warken ⟨groff-bernd.warken-72@web.de⟩, and G.
           Branden Robinson ⟨g.branden.robinson@gmail.com⟩.
    


## See also



           _Groff: The GNU Implementation of troff_ , by Trent A. Fisher and
           Werner Lemberg, is the primary _groff_ manual.  You can browse it
           interactively with “info groff”.
    
           A list of all _groff_ man pages follows.  A few (_grohtml_ , _gropdf_ ,
           _gxditview_ , and _xtotroff_) will be unavailable if their
           corresponding programs were disabled during compilation.
    
           Introduction, history, and further reading:
                  _roff_(7)
    
           Viewer for _groff_ (and AT&T device-independent _troff_) documents:
                  _gxditview_(1)
    
           Preprocessors:
                  _chem_(1), _eqn_(1), _neqn_(1), _glilypond_(1), _grn_(1), _preconv_(1),
                  _gperl_(1), _pic_(1), _gpinyin_(1), _refer_(1), _soelim_(1), _tbl_(1)
    
           Macro packages and package-specific utilities:
                  _groff_hdtbl_(7), _groff_man_(7), _groff_man_style_(7),
                  _groff_mdoc_(7), _groff_me_(7), _groff_mm_(7), _groff_mmse_(7),
                  _mmroff_(1), _groff_mom_(7), _groff_ms_(7), _groff_rfc1345_(7),
                  _groff_trace_(7), _groff_www_(7)
    
           Bibliographic database management tools:
                  _indxbib_(1), _lkbib_(1), _lookbib_(1)
    
           Language, conventions, and GNU extensions:
                  _groff_(7), _groff_char_(7), _groff_diff_(7), _groff_font_(5),
                  _groff_tmac_(5)
    
           Device-independent page description language:
                  _groff_out_(5)
    
           Formatter program:
                  _troff_(1)
    
           Formatter wrappers:
                  _nroff_(1), _pdfmom_(1)
    
           Postprocessors for output devices:
                  _grodvi_(1), _grohtml_(1), _grolbp_(1), _grolj4_(1), _gropdf_(1),
                  _grops_(1), _grotty_(1)
    
           Font support utilities:
                  _addftinfo_(1), _afmtodit_(1), _hpftodit_(1), _pfbtops_(1),
                  _tfmtodit_(1), _xtotroff_(1)
    
           Graphics conversion utilities:
                  _eqn2graph_(1), _grap2graph_(1), _pic2graph_(1)
    
           Difference-marking utility:
                  _gdiffmk_(1)
    
           “groff guess” utility:
                  _grog_(1)
    


* * *