# groff - man(1) - [phpMan] > **TLDR:** GNU replacement for the `troff` and `nroff` typesetting utilities. > - Format output for a PostScript printer, saving the output to a file: `groff {{path/to/input.roff}} > {{path/to/output.ps}}` - Render a man page using the ASCII output device, and display it using a pager: `groff -man -T ascii {{path/to/manpage.1}} | less --RAW-CONTROL-CHARS` - Render a man page into an HTML file: `groff -man -T html {{path/to/manpage.1}} > {{path/to/manpage.html}}` - Typeset a roff file containing [t]ables and [p]ictures, using the [me] macro set, to PDF, saving the output: `groff {{t}} {{p}} -{{me}} -T {{pdf}} {{path/to/input.me}} > {{path/to/output.pdf}}` - Run a `groff` command with preprocessor and macro options guessed by the `grog` utility: `eval "$(grog -T utf8 {{path/to/input.me}})"` *Source: tldr-pages* --- [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) General Commands Manual [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) ## 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 files that include formatting commands to pro‐ duce output in PostScript, PDF, HTML, DVI, 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 spec‐ ified, or if _file_ is “**-**”, _groff_ reads the standard input stream. A reimplementation and extension of the typesetter from AT&T Unix, _groff_ is present on most POSIX systems owing to its long association with Unix manuals (including man pages). It and its predecessor are notable for their production of several best-selling software engineering texts. _groff_ is capable of producing 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 --help Because _groff_ is intended to subsume most users' direct invocations of the [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) format‐ ter, 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_. _**groff_-specific options** The following options either do not exist in GNU _troff_ or are interpreted differently by _groff_. ### -D _ -k ### -e ### -g ### -G -p ### -I _ -g -s [_soelim_(1)](https://www.chedong.com/phpMan.php/man/soelim/1/markdown) and the output driver, and _grn_ is passed an **-M **option with _dir_ as its argu‐ ment. ### -j -p ### -k _groff_'s **-K **or **-D **options is also specified. ### -K _ -k ### -l vice description file specifies the default command to be used; see [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). If no such directive is present for the output device, output is piped to [_lpr_(1)](https://www.chedong.com/phpMan.php/man/lpr/1/markdown). See options **-L **and **-X**. ### -L _ a separate **-L **option. _groff_ does not prefix an option dash to _arg_ before passing it to the spooler program. ### -M [_grn_(1)](https://www.chedong.com/phpMan.php/man/grn/1/markdown). ### -N -N ### -p ### -P _ rate **-P **option. _groff_ does not prefix an option dash to _arg_ before passing it to the postprocessor. ### -R because most _refer_ options have equivalent language elements that can be specified within the document. ### -s ### -S -U mode is enabled by default. ### -t ### -T _ put driver to convert _troff_'s output to a form appropriate for _dev_; see subsection “Output devices” below. ### -U -U ### -v ### --version 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 ecute it. If given more than once, _groff_ both writes and runs the pipeline. ### -X display. Combining this option with **-Tps **uses the font metrics of the PostScript de‐ vice, whereas the **-TX75 **and **-TX100 **options use the metrics of X11 fonts. ### -Z less suppressed with **-z**); see [_groff_out_(5)](https://www.chedong.com/phpMan.php/man/groffout/5/markdown) for a description of this format. ### Transparent options The following options are passed as-is to the formatter program [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) and described in more detail in its man page. ### -a ### -b ### -c ### -C -c ### -d _ ### -d _ Define string. ### -E -Ww ### -f _ ### -F _ description files. ### -i ### -I _ ### -m _ Process name_.tmac_ before input files. ### -M _ ### -n _ ### -o _ Output only pages in _list_. ### -r _ ### -r _ Define register. ### -w _ ### -W _ Enable (**-w**) or inhibit (**-W**) emission of warnings in category _name_. ### -z ## Usage The architecture of the GNU _roff_ system follows that of other device-independent _roff_ imple‐ mentations, comprising preprocessors, macro packages, output drivers (or “postprocessors”), a suite of utilities, and the formatter _troff_ at its heart. See [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) 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 tradi‐ tional _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 summa‐ rizes the constituent parts of the GNU _roff_ system. It complements [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) with _groff_-spe‐ cific 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_ 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.html** ### Using _groff_ as a REPL Those with a programmer's bent may be pleased to know that they can use _groff_ in a read-eval‐ uate-print loop (REPL). Doing so can be handy to verify one's understanding of the format‐ ter'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 __ Hi, Leslie. Your secret number is 4. It is even. ### Paper format In GNU _roff_, the page dimensions for the formatter _troff_ and for output devices are handled separately. In the formatter, requests are used to set the page length (**.pl**), page offset (or left margin, **.po**), and line length (**.ll**). The right margin is not explicitly configured; the combination of page offset and line length provides the information necessary to derive it. The _papersize_ macro package, automatically loaded by _troff_, provides an interface for configuring page dimensions by convenient names, like “letter” or “A4”; see [_groff_tmac_(5)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown). The formatter's default in this installation is “**A4**”. It is up to each macro package to respect the page dimensions configured in this way. Some offer alternative mechanisms. For each output device, the size of the output medium can be set in its _DESC_ file. Most out‐ put drivers also recognize a command-line option **-p **to override the default dimensions and an option **-l **to use landscape orientation. See [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown) for a description of the **papersize** directive, which takes an argument of the same form as **-p**. The output driver's man page, such as [_grops_(1)](https://www.chedong.com/phpMan.php/man/grops/1/markdown), may also be helpful. _groff_ uses the command-line option **-P **to pass options to output devices; for example, use the following for PostScript output on A4 paper in land‐ scape orientation. groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps ### Front end The _groff_ program is a wrapper around the [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) program. It allows one to specify pre‐ processors via command-line options and automatically runs the appropriate postprocessor for the selected output device. Doing so, the manual construction of pipelines or management of temporary files required of users of traditional [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) systems can be avoided. Use the [_grog_(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) program 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)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) 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)](https://www.chedong.com/phpMan.php/man/groff/7/markdown). GNU _roff_ extensions to the AT&T _troff_ language, a common subset of _roff_ dialects extant today, are detailed in [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown). ### Preprocessors A preprocessor interprets a domain-specific language that produces _roff_ language output. Frequently, such input is confined to sections or regions of a _roff_ input file (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)](https://www.chedong.com/phpMan.php/man/gremlin/1/markdown) diagrams; _chem_ draws chemical structural formulæ using _pic_; _gperl_ populates _groff_ registers and strings using [_perl_(1)](https://www.chedong.com/phpMan.php/man/perl/1/markdown); _glilypond_ embeds _LilyPond_ sheet music; and _gpinyin_ eases Mandarin Chinese input using Hanyu Pinyin. A preprocessor unique to GNU _roff_ is [_preconv_(1)](https://www.chedong.com/phpMan.php/man/preconv/1/markdown), 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 loca‐ tion 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, some‐ times 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 re‐ sponsibility 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)](https://www.chedong.com/phpMan.php/man/groffman/7/markdown). 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)](https://www.chedong.com/phpMan.php/man/groffmdoc/7/markdown). 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)](https://www.chedong.com/phpMan.php/man/groffme/7/markdown). 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 docu‐ ments, a successor to _s_; see [_groff_mm_(7)](https://www.chedong.com/phpMan.php/man/groffmm/7/markdown). 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 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)](https://www.chedong.com/phpMan.php/man/groffms/7/markdown). 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 pack‐ age. It can be specified on the command line as **-mandoc**. A [_man_(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) librarian program 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 auxil‐ iary packages are described, along with details of macro file naming and placement, in [_groff_tmac_(5)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown). ### Formatters The formatter, the program that interprets _roff_ language input, is [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). 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)](https://www.chedong.com/phpMan.php/man/nroff/1/markdown), emulates the behavior of AT&T _nroff_. It attempts to correctly en‐ code the output based on the locale, relieving the user of the need to specify an output de‐ vice with the **-T **option and is therefore convenient for use with terminal output devices, de‐ scribed in the next subsection. GNU _troff_ generates output in a device-independent, but not device-agnostic, page description language detailed in [_groff_out_(5)](https://www.chedong.com/phpMan.php/man/groffout/5/markdown). ### Output devices _troff_ output is formatted for a particular _output_ _device_, typically specified by the **-T **op‐ tion to the formatter or a front end. If neither this option nor the _GROFF_TYPESETTER_ envi‐ ronment 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. **cp1047 **for terminals using the IBM code page 1047 character set and encoding. **dvi **for TeX DVI format. ### html **xhtml **for HTML and XHTML output, respectively. **latin1 **for terminals using the ISO Latin-1 (ISO 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 de‐ scription file; see [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). The **-X **option overrides this selection, causing _gxditview_ to serve as the output driver. [_grodvi_(1)](https://www.chedong.com/phpMan.php/man/grodvi/1/markdown) provides **dvi**. [_grohtml_(1)](https://www.chedong.com/phpMan.php/man/grohtml/1/markdown) provides **html **and **xhtml**. [_grolbp_(1)](https://www.chedong.com/phpMan.php/man/grolbp/1/markdown) provides **lbp**. [_grolj4_(1)](https://www.chedong.com/phpMan.php/man/grolj4/1/markdown) provides **lj4**. [_gropdf_(1)](https://www.chedong.com/phpMan.php/man/gropdf/1/markdown) provides **pdf**. [_grops_(1)](https://www.chedong.com/phpMan.php/man/grops/1/markdown) provides **ps**. [_grotty_(1)](https://www.chedong.com/phpMan.php/man/grotty/1/markdown) provides **ascii**, **cp1047**, **latin1**, and **utf8**. [_gxditview_(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown) provides **X75**, **X75-12**, **X100**, and **X100-12**, and additionally can preview **ps**. ### Utilities GNU _roff_ includes a suite of utilities. [_gdiffmk_(1)](https://www.chedong.com/phpMan.php/man/gdiffmk/1/markdown) marks differences between a pair of _roff_ input files. [_grog_(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) infers the _groff_ command a document requires. Several utilities prepare descriptions of fonts, enabling the formatter to use them when pro‐ ducing output for a given device. [_addftinfo_(1)](https://www.chedong.com/phpMan.php/man/addftinfo/1/markdown) adds information to AT&T _troff_ font description files to enable their use with GNU _troff_. [_afmtodit_(1)](https://www.chedong.com/phpMan.php/man/afmtodit/1/markdown) creates font description files for PostScript Type 1 fonts. [_pfbtops_(1)](https://www.chedong.com/phpMan.php/man/pfbtops/1/markdown) 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)](https://www.chedong.com/phpMan.php/man/hpftodit/1/markdown) creates font description files for the HP LaserJet 4 family of printers. [_tfmtodit_(1)](https://www.chedong.com/phpMan.php/man/tfmtodit/1/markdown) creates font description files for the TeX DVI device. [_xtotroff_(1)](https://www.chedong.com/phpMan.php/man/xtotroff/1/markdown) creates font description files for X Window System core fonts. A trio of tools transform material constructed using _roff_ preprocessor languages into graphi‐ cal image files. [_eqn2graph_(1)](https://www.chedong.com/phpMan.php/man/eqn2graph/1/markdown) converts an _eqn_ equation into a cropped image. [_grap2graph_(1)](https://www.chedong.com/phpMan.php/man/grap2graph/1/markdown) converts a _grap_ diagram into a cropped image. [_pic2graph_(1)](https://www.chedong.com/phpMan.php/man/pic2graph/1/markdown) converts a _pic_ diagram into a cropped image. Another set of programs works with the bibliographic data files used by the [_refer_(1)](https://www.chedong.com/phpMan.php/man/refer/1/markdown) pre‐ processor. [_indxbib_(1)](https://www.chedong.com/phpMan.php/man/indxbib/1/markdown) makes inverted indices for bibliographic databases, speeding lookup operations on them. [_lkbib_(1)](https://www.chedong.com/phpMan.php/man/lkbib/1/markdown) searches the databases. [_lookbib_(1)](https://www.chedong.com/phpMan.php/man/lookbib/1/markdown) interactively searches the databases. ## Exit status _groff_ exits with a failure status if there was a problem parsing its arguments and a success‐ ful status if either of the options **-h **or **--help **was specified. 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, set‐ ting bit 0 if a command exited with a failure status, bit 1 if a command was terminated with a signal, and bit 2 if a command could not be executed. (Thus, if all three misfortunes be‐ fell one's pipeline, _groff_ would exit with status 2^0 + 2^1 + 2^2 = 1+2+4 = 7.) To trou‐ bleshoot pipeline problems, you may wish to re-run the _groff_ command with the **-V **option and break the reported pipeline down into separate stages, inspecting the exit status of and di‐ agnostic messages emitted by each command. ## Environment 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_ This search path, followed by _PATH_, is used to locate commands executed by _groff_. If it is not set, the installation directory of the GNU _roff_ executables, _/usr/bin_, is searched before _PATH_. _GROFF_COMMAND_PREFIX_ GNU _roff_ can be configured at compile time to apply a prefix to the names of the pro‐ grams it provides that had a counterpart 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 _nroff_; the preprocessors _eqn_, _grn_, _pic_, _refer_, _tbl_, and _soelim_; and the utilities _indxbib_ and _lookbib_. _GROFF_ENCODING_ The value of this variable is passed to the [_preconv_(1)](https://www.chedong.com/phpMan.php/man/preconv/1/markdown) preprocessor's **-e **option to se‐ lect the character encoding of input files. This variable's existence implies the _groff_ option **-k**. If set but empty, _groff_ calls _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)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) and [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). _GROFF_TMAC_PATH_ Seek macro files in this list of directories. See [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) and [_groff_tmac_(5)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown). _GROFF_TMPDIR_ Create temporary files in this directory. If not set, but the environment variable _TMPDIR_ is set, temporary files are created there instead. On Windows systems, if nei‐ ther 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)](https://www.chedong.com/phpMan.php/man/refer/1/markdown), [_grohtml_(1)](https://www.chedong.com/phpMan.php/man/grohtml/1/markdown), and [_grops_(1)](https://www.chedong.com/phpMan.php/man/grops/1/markdown) commands use temporary files. _GROFF_TYPESETTER_ Set the default output device. If empty or not set, **ps **is used. The **-T **option over‐ rides _GROFF_TYPESETTER_. _SOURCE_DATE_EPOCH_ 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)](https://www.chedong.com/phpMan.php/man/gmtime/3/markdown) and [_asctime_(3)](https://www.chedong.com/phpMan.php/man/asctime/3/markdown) when the formatter starts up and stored in registers usable by documents and macro packages. _TZ_ The time zone to use when converting the current time to human-readable form; see [_tzset_(3)](https://www.chedong.com/phpMan.php/man/tzset/3/markdown). 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. Once a [_man_(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) librarian program has located a man page, it may execute a _groff_ command much like the following. groff -t -man -Tutf8 /usr/share/man/man1/groff.1 The librarian will also pipe the output through a pager, which might not interpret the SGR terminal escape sequences _groff_ emits for boldface, underlining, or italics; 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 Using _groff_, this pipe can be shortened to an equivalent command. groff -p -t -me -T utf8 foo.me An even easier way to do this is to use [_grog_(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) 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 arbi‐ trary arguments to be transmitted. For example, to pass a title to the _gxditview_ postproces‐ sor, 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**, **cp1047**, **latin1**, and **utf8 **devices, programs like [_more_(1)](https://www.chedong.com/phpMan.php/man/more/1/markdown) and [_less_(1)](https://www.chedong.com/phpMan.php/man/less/1/markdown) may require command-line options to correctly handle some terminal escape sequences; see [_grotty_(1)](https://www.chedong.com/phpMan.php/man/grotty/1/markdown). On EBCDIC hosts such as OS/390 Unix, the output devices **ascii **and **latin1 **aren't available. Conversely, the output device **cp1047 **is not available on systems based on the ISO 646 or ISO 8859 character encoding standards. ## Installation directories GNU _roff_ installs files in varying locations depending on its compile-time configuration. On this installation, the following locations are used. _/etc/X11/app-defaults_ Application defaults directory for [_gxditview_(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown). _/usr/bin_ Directory containing _groff_'s executable commands. _/usr/share/groff/1.23.0/eign_ List of common words for [_indxbib_(1)](https://www.chedong.com/phpMan.php/man/indxbib/1/markdown). _/usr/share/groff/1.23.0_ Directory for data files. _/usr/dict/papers/Ind_ Default index for [_lkbib_(1)](https://www.chedong.com/phpMan.php/man/lkbib/1/markdown) and [_refer_(1)](https://www.chedong.com/phpMan.php/man/refer/1/markdown). _/usr/share/doc/groff-base_ Documentation directory. _/usr/share/doc/groff-base/examples_ Example directory. _/usr/share/groff/1.23.0/font_ Font directory. _/usr/share/doc/groff-base/html_ HTML documentation directory. _/usr/lib/font_ Legacy font directory. _/usr/share/groff/site-font_ Local font directory. _/usr/share/groff/site-tmac_ Local macro package (_tmac_ file) directory. _/usr/share/groff/1.23.0/tmac_ Macro package (_tmac_ file) directory. _/usr/share/groff/1.23.0/oldfont_ Font directory for compatibility with old versions of _groff_; see [_grops_(1)](https://www.chedong.com/phpMan.php/man/grops/1/markdown). _/usr/share/doc/groff-base/pdf_ PDF documentation directory. _**groff_ macro directory** Most macro files supplied with GNU _roff_ are stored in _/usr/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)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). For a catalog of macro files GNU _roff_ provides, see [_groff_tmac_(5)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown). _**groff_ device and font description directory** Device and font description files supplied with GNU _roff_ are stored in _/usr/share/groff/_ _1.23.0/font_ for the installation corresponding to this document. As a rule, multiple direc‐ tories are searched for device and font description files; see [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). For the formats of these files, see [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). ## 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](). A free implementation of the _grap_ preprocessor, written by [Ted Faber](mailto:), can be found at the [_grap_ website](). _groff_ supports only this _grap_. ## Authors _groff_ (both the front-end command and the overall system) was primarily written by James Clark. Contributors to this document include Clark, Trent A. Fisher, [Werner Lemberg](mailto:), Bernd Warken, and [G. Branden Robinson](mailto:). **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”. Introduction, history, and further reading: [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) Viewer for _groff_ (and AT&T device-independent _troff_) documents: [_gxditview_(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown) Preprocessors: [_chem_(1)](https://www.chedong.com/phpMan.php/man/chem/1/markdown), [_eqn_(1)](https://www.chedong.com/phpMan.php/man/eqn/1/markdown), [_neqn_(1)](https://www.chedong.com/phpMan.php/man/neqn/1/markdown), [_glilypond_(1)](https://www.chedong.com/phpMan.php/man/glilypond/1/markdown), [_grn_(1)](https://www.chedong.com/phpMan.php/man/grn/1/markdown), [_preconv_(1)](https://www.chedong.com/phpMan.php/man/preconv/1/markdown), [_gperl_(1)](https://www.chedong.com/phpMan.php/man/gperl/1/markdown), [_pic_(1)](https://www.chedong.com/phpMan.php/man/pic/1/markdown), [_gpinyin_(1)](https://www.chedong.com/phpMan.php/man/gpinyin/1/markdown), [_refer_(1)](https://www.chedong.com/phpMan.php/man/refer/1/markdown), [_soelim_(1)](https://www.chedong.com/phpMan.php/man/soelim/1/markdown), [_tbl_(1)](https://www.chedong.com/phpMan.php/man/tbl/1/markdown) Macro packages and package-specific utilities: [_groff_hdtbl_(7)](https://www.chedong.com/phpMan.php/man/groffhdtbl/7/markdown), [_groff_man_(7)](https://www.chedong.com/phpMan.php/man/groffman/7/markdown), [_groff_man_style_(7)](https://www.chedong.com/phpMan.php/man/groffmanstyle/7/markdown), [_groff_mdoc_(7)](https://www.chedong.com/phpMan.php/man/groffmdoc/7/markdown), [_groff_me_(7)](https://www.chedong.com/phpMan.php/man/groffme/7/markdown), [_groff_mm_(7)](https://www.chedong.com/phpMan.php/man/groffmm/7/markdown), [_groff_mmse_(7)](https://www.chedong.com/phpMan.php/man/groffmmse/7/markdown) (only in Swedish locales), [_mmroff_(1)](https://www.chedong.com/phpMan.php/man/mmroff/1/markdown), [_groff_mom_(7)](https://www.chedong.com/phpMan.php/man/groffmom/7/markdown), [_pdfmom_(1)](https://www.chedong.com/phpMan.php/man/pdfmom/1/markdown), [_groff_ms_(7)](https://www.chedong.com/phpMan.php/man/groffms/7/markdown), [_groff_rfc1345_(7)](https://www.chedong.com/phpMan.php/man/groffrfc1345/7/markdown), [_groff_trace_(7)](https://www.chedong.com/phpMan.php/man/grofftrace/7/markdown), [_groff_www_(7)](https://www.chedong.com/phpMan.php/man/groffwww/7/markdown) Bibliographic database management tools: [_indxbib_(1)](https://www.chedong.com/phpMan.php/man/indxbib/1/markdown), [_lkbib_(1)](https://www.chedong.com/phpMan.php/man/lkbib/1/markdown), [_lookbib_(1)](https://www.chedong.com/phpMan.php/man/lookbib/1/markdown) Language, conventions, and GNU extensions: [_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown), [_groff_char_(7)](https://www.chedong.com/phpMan.php/man/groffchar/7/markdown), [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown), [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown), [_groff_tmac_(5)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown) Intermediate output language: [_groff_out_(5)](https://www.chedong.com/phpMan.php/man/groffout/5/markdown) Formatter program: [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) Formatter wrappers: [_nroff_(1)](https://www.chedong.com/phpMan.php/man/nroff/1/markdown), [_pdfroff_(1)](https://www.chedong.com/phpMan.php/man/pdfroff/1/markdown) Postprocessors for output devices: [_grodvi_(1)](https://www.chedong.com/phpMan.php/man/grodvi/1/markdown), [_grohtml_(1)](https://www.chedong.com/phpMan.php/man/grohtml/1/markdown), [_grolbp_(1)](https://www.chedong.com/phpMan.php/man/grolbp/1/markdown), [_grolj4_(1)](https://www.chedong.com/phpMan.php/man/grolj4/1/markdown), [_gropdf_(1)](https://www.chedong.com/phpMan.php/man/gropdf/1/markdown), [_grops_(1)](https://www.chedong.com/phpMan.php/man/grops/1/markdown), [_grotty_(1)](https://www.chedong.com/phpMan.php/man/grotty/1/markdown) Font support utilities: [_addftinfo_(1)](https://www.chedong.com/phpMan.php/man/addftinfo/1/markdown), [_afmtodit_(1)](https://www.chedong.com/phpMan.php/man/afmtodit/1/markdown), [_hpftodit_(1)](https://www.chedong.com/phpMan.php/man/hpftodit/1/markdown), [_pfbtops_(1)](https://www.chedong.com/phpMan.php/man/pfbtops/1/markdown), [_tfmtodit_(1)](https://www.chedong.com/phpMan.php/man/tfmtodit/1/markdown), [_xtotroff_(1)](https://www.chedong.com/phpMan.php/man/xtotroff/1/markdown) Graphics conversion utilities: [_eqn2graph_(1)](https://www.chedong.com/phpMan.php/man/eqn2graph/1/markdown), [_grap2graph_(1)](https://www.chedong.com/phpMan.php/man/grap2graph/1/markdown), [_pic2graph_(1)](https://www.chedong.com/phpMan.php/man/pic2graph/1/markdown) Difference-marking utility: [_gdiffmk_(1)](https://www.chedong.com/phpMan.php/man/gdiffmk/1/markdown) “groff guess” utility: [_grog_(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) groff 1.23.0 31 March 2024 [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown)