groff - front-end for the groff document formatting system . .


. .SY groff .OP -abcegiklpstzCEGNRSUVXZ .OP -d cs .OP -D arg .OP -f fam .OP -F dir .OP -I dir .OP -K arg .OP -L arg .OP -m name .OP -M dir .OP -n num .OP -o list .OP -P arg .OP -r cn .OP -T dev .OP -w name .OP -W name [ file\~ . . .] . .SY groff

-h |

--help . .SY groff

-v |

--version [ option\~ . . .] .YS . .


. This document describes the

groff program, the main front-end for the groff document formatting system. . The groff program and macro suite is the implementation of a

R roff (7) system within the free software collection http://www.gnu.org GNU . The groff system has all features of the classical roff , but adds many extensions. .


groff program allows to control the whole groff system by command line options. . This is a great simplification in comparison to the classical case (which uses pipes only). . .


The command line is parsed according to the usual \f[CR]GNU\f[] convention. . The whitespace between a command line option and its argument is optional. . Options can be grouped behind a single `-' (minus character). . A filename of

- (minus character) denotes the standard input. .

. As

groff is a wrapper program for

troff both programs share a set of options. . But the

groff program has some additional, native options and gives a new meaning to some

troff options. . On the other hand, not all

troff options can be fed into

R groff . . .

4.1. Native groff Options

. The following options either do not exist for

troff or are differently interpreted by

R groff . . .

  • -D  arg
        Set default input encoding used by

preconv to arg . . Implies

R -k . . .


    Preprocess with

R eqn . . .


    Preprocess with

R grn . . .


    Preprocess with

R grap . . .



--help Print a help message. . .

  • -I  dir
        This option may be used to specify a directory to search for files (both those on the command line and those named in

.psbb and

.so requests, and

\X'ps: import' and

\X'ps: file' escapes). The current directory is always searched first. This option may be specified more than once; the directories are searched in the order specified. No directory search is performed for files specified using an absolute path. This option implies the

-s option. . .


    Preprocess with

R preconv . This is run before any other preprocessor. . Please refer to

R preconv 's manual page for its behaviour if no

-K (or

R -D ) option is specified. . .

  • -K  arg
        Set input encoding used by

preconv to arg . . Implies

R -k . . .


    Send the output to a spooler program for printing. . The command that should be used for this is specified by the

print command in the device description file, see

R groff_font (5). If this command is not present, the output is piped into the

R lpr (1) program by default. . See options

-L and

R -X . . .

  • -L  arg
        Pass arg to the spooler program. Several arguments should be passed with a separate -L option each. . Note that

groff does not prepend `-' (a minus sign) to arg before passing it to the spooler program. . .


    Don't allow newlines within eqn delimiters. . This is the same as the

-N option in

R eqn . . .


    Preprocess with

R pic . . .

  • -P  -option
    -P  -option  -P  arg Pass -option or "-option\~arg" to the postprocessor. . The option must be specified with the necessary preceding minus sign(s) .Quoted - or .Quoted -- because

groff does not prepend any dashes before passing it to the postprocessor. . For example, to pass a title to the

gxditview postprocessor, the shell command .

groff -X -P -title -P 'groff it' \f[I]foo\f[]


is equivalent to .

groff -X -Z \f[I]foo\f[] | \
gxditview -title 'groff it' -

. .


    Preprocess with

R refer . . No mechanism is provided for passing arguments to

refer because most

refer options have equivalent language elements that can be specified within the document. . See

R refer (1) for more details. . .


    Preprocess with

R soelim . . .


    Safer mode. . Pass the

-S option to

pic and disable the following

troff requests:

R .open ,

R .opena ,

R .pso ,

R .sy , and

R .pi . For security reasons, safer mode is enabled by default. . .


    Preprocess with

R tbl . . .

  • -T  dev
        Set output device to dev . For this device,

troff generates the intermediate output ; see

R groff_out (5). . Then

groff calls a postprocessor to convert

R troff 's intermediate output to its final format. . Real devices in

groff are .

  • dvi
        TeX DVI format (postprocessor is

R grodvi ). .

  • html
    xhtml HTML and XHTML output (preprocessors are

soelim and

R pre-grohtml , postprocessor is

R post-grohtml ). .

  • lbp
        Canon CAPSL printers (LBP-4 and LBP-8 series laser printers; postprocessor is

R grolbp ). .

  • lj4
        HP LaserJet4 compatible (or other PCL5 compatible) printers (postprocessor is

R grolj4 ). .

  • ps
        PostScript output (postprocessor is

R grops ). . .

For the following TTY output devices (postprocessor is always

R grotty ),

-T selects the output encoding: .

  • ascii
        7bit \f[CR]ASCII\f[]. .
  • cp1047
        Latin-1 character set for EBCDIC hosts. .
  • latin1
        ISO 8859-1. .
  • utf8
        Unicode character set in UTF-8 encoding. . .

The following arguments select

gxditview as the `postprocessor' (it is rather a viewing program): .

  • X75
        75 dpi resolution, 10 pt document base font.
  • X75-12
        75 dpi resolution, 12 pt document base font.
  • X100
        100 dpi resolution, 10 pt document base font.
  • X100-12
        100 dpi resolution, 12 pt document base font. .

The default device is

R ps . . .


    Unsafe mode. . Reverts to the (old) unsafe behaviour; see option

R -S . . .



--version Output version information of

groff and of all programs that are run by it; that is, the given command line is parsed in the usual way, passing

-v to all subprograms. . .


    Output the pipeline that would be run by

R groff (as a wrapper program) on the standard output, but do not execute it. If given more than once, the commands are both printed on the standard error and run. . .



gxditview instead of using the usual postprocessor to (pre)view a document. . The printing spooler behavior as outlined with options

-l and

-L is carried over to

R gxditview (1) by determining an argument for the

-printCommand option of

R gxditview (1). . This sets the default

Print action and the corresponding menu entry to that value. .

-X only produces good results with

R -Tps ,

R -TX75 ,

R -TX75-12 ,

R -TX100 , and

R -TX100-12 . . The default resolution for previewing

-Tps output is 75 dpi; this can be changed by passing the

-resolution option to

R gxditview , for example .

groff -X -P-resolution -P100 -man foo.1

. .


    Suppress output generated by

R troff . Only error messages are printed. . .


    Do not automatically postprocess groff intermediate output in the usual manner. This will cause the

troff output to appear on standard output, replacing the usual postprocessor output; see

R groff_out (5). . .

4.2. Transparent Options

. The following options are transparently handed over to the formatter program

troff that is called by

groff subsequently. . These options are described in more detail in

R troff (1). .


    \f[CR]ASCII\f[] approximation of output. .


    Backtrace on error or warning. .


    Disable color output. . Please consult the

R grotty (1) man page for more details. .


    Enable compatibility mode. .

  • -d  cs
    -d  name = s Define string. .



troff error messages. .

  • -f  fam
        Set default font family. .
  • -F  dir
        Set path for font DESC files. .


    Process standard input after the specified input files. .

  • -m  name
        Include macro file .IB name .tmac (or tmac. name\c ); see also

R groff_tmac (5). .

  • -M  dir
        Path for macro files. .
  • -n  num
        Number the first page num . .
  • -o  list
        Output only pages in list . .
  • -r  cn
    -r  name = n Set number register. .
  • -w  name
        Enable warning name . .
  • -W  name
        disable warning name . . .


. The groff system implements the infrastructure of classical roff; see

R roff (7) for a survey on how a roff system works in general. . Due to the front-end programs available within the groff system, using groff is much easier than "classical roff" . . This section gives an overview of the parts that constitute the groff system. . It complements

R roff (7) with groff -specific features. . This section can be regarded as a guide to the documentation around the groff system. . .

5.1. Paper Size

. The virtual paper size used by

troff to format the input is controlled globally with the requests

R .po ,

R .pl , and

R .ll . See

R groff_tmac (5) for the `papersize' macro package which provides a convenient interface. .

The physical paper size, giving the actual dimensions of the paper sheets, is controlled by output devices like

R grops with the command line options

-p and

R -l . See

R groff_font (5) and the man pages of the output devices for more details.

groff uses the command line option

-P to pass options to output devices; for example, the following selects A4 paper in landscape orientation for the PS device: .

groff -Tps -P-pa4 -P-l ...

. .

5.2. Front-ends

. The

groff program is a wrapper around the

R troff (1) program. . It allows to specify the preprocessors by command line options and automatically runs the postprocessor that is appropriate for the selected device. . Doing so, the sometimes tedious piping mechanism of classical

R roff (7) can be avoided. .


R grog (1) program can be used for guessing the correct groff command line to format a file. .


R groffer (1) program is an allround-viewer for groff files and man pages. . .

5.3. Preprocessors

. The groff preprocessors are reimplementations of the classical preprocessors with moderate extensions. . The standard preprocessors distributed with the groff package are .

R eqn (1)

    for mathematical formul(ae, .

R grn (1)

    for including

R gremlin (1) pictures, .

R pic (1)

    for drawing diagrams, .

R chem (1)

    for chemical structure diagrams, .

R refer (1)

    for bibliographic references, .

R soelim (1)

    for including macro files from standard locations, .

and .

R tbl (1)

    for tables. .

A new preprocessor not available in classical troff is

R preconv (1) which converts various input encodings to something

groff can understand. . It is always run first before any other preprocessor. .

Besides these, there are some internal preprocessors that are automatically run with some devices. . These aren't visible to the user. . .

5.4. Macro Packages

. Macro packages can be included by option

R -m . . The groff system implements and extends all classical macro packages in a compatible way and adds some packages of its own. . Actually, the following macro packages come with groff : .


    The traditional man page format; see

R groff_man (7). It can be specified on the command line as

-man or

R -m\~man . .


    The general package for man pages; it automatically recognizes whether the documents uses the man or the mdoc format and branches to the corresponding macro package. . It can be specified on the command line as

-mandoc or

R -m\~mandoc . .


    The \f[CR]BSD\f[]-style man page format; see

R groff_mdoc (7). It can be specified on the command line as

-mdoc or

R -m\~mdoc . .


    The classical me document format; see

R groff_me (7). It can be specified on the command line as

-me or

R -m\~me . .


    The classical mm document format; see

R groff_mm (7). It can be specified on the command line as

-mm or

R -m\~mm . .


    The classical ms document format; see

R groff_ms (7). It can be specified on the command line as

-ms or

R -m\~ms . .


    HTML-like macros for inclusion in arbitrary groff documents; see

R groff_www (7). .

Details on the naming of macro files and their placement can be found in

R groff_tmac (5); this man page also documents some other, minor auxiliary macro packages not mentioned here. . .

5.5. Programming Language

. General concepts common to all roff programming languages are described in

R roff (7). .

The groff extensions to the classical troff language are documented in

R groff_diff (7). .

The groff language as a whole is described in the (still incomplete) "groff info file" ; a short (but complete) reference can be found in

R groff (7). . .

5.6. Formatters

. The central roff formatter within the groff system is

R troff (1). It provides the features of both the classical troff and nroff , as well as the groff extensions. . The command line option

-C switches

troff into "compatibility mode" which tries to emulate classical roff as much as possible. .

There is a shell script

R nroff (1) that emulates the behavior of classical

R nroff . . It tries to automatically select the proper output encoding, according to the current locale. .

The formatter program generates "intermediate output" ; see

R groff_out (7). . .

5.7. Devices

. In roff , the output targets are called devices . A device can be a piece of hardware, e.g., a printer, or a software file format. . A device is specified by the option

R -T . The groff devices are as follows. .


    Text output using the

R ascii (7) character set. .


    Text output using the EBCDIC code page IBM cp1047 (e.g., OS/390 Unix). .


    TeX DVI format. .


    HTML output. .


    Text output using the ISO Latin-1 (ISO 8859-1) character set; see

R iso_8859_1 (7). .


    Output for Canon CAPSL printers (LBP-4 and LBP-8 series laser printers). .


    HP LaserJet4-compatible (or other PCL5-compatible) printers. .


    PostScript output; suitable for printers and previewers like

R gv (1). .


    Text output using the Unicode (ISO 10646) character set with UTF-8 encoding; see

R unicode (7). .


    XHTML output. .


    75dpi X Window System output suitable for the previewers

R xditview (1x) and

R gxditview (1). . A variant for a 12 pt document base font is

R X75-12 . .


    100dpi X Window System output suitable for the previewers

R xditview (1x) and

R gxditview (1). . A variant for a 12 pt document base font is

R X100-12 . .

The postprocessor to be used for a device is specified by the

postpro command in the device description file; see

R groff_font (5). . This can be overridden with the

-X option. .

The default device is

R ps . . .

5.8. Postprocessors

. groff provides 3\~hardware postprocessors: .

R grolbp (1)

    for some Canon printers, .

R grolj4 (1)

    for printers compatible to the HP LaserJet\~4 and PCL5, .

R grotty (1)

    for text output using various encodings, e.g., on text-oriented terminals or line-printers. .

Today, most printing or drawing hardware is handled by the operating system, by device drivers, or by software interfaces, usually accepting PostScript. . Consequently, there isn't an urgent need for more hardware device postprocessors. .

The groff software devices for conversion into other document file formats are .

R grodvi (1)

    for the DVI format, .

R grohtml (1)

    for HTML and XHTML formats, .

R grops (1)

    for PostScript. .

Combined with the many existing free conversion tools this should be sufficient to convert a troff document into virtually any existing data format. . .

5.9. Utilities

. The following utility programs around groff are available. .

R addftinfo (1)

    Add information to troff font description files for use with groff . .

R afmtodit (1)

    Create font description files for PostScript device. .

R eqn2graph (1)

    Convert an

eqn image into a cropped image. .

R gdiffmk (1)

    Mark differences between groff , nroff , or troff files. .

R grap2graph (1)

    Convert a

grap diagram into a cropped bitmap image. .

R groffer (1)

    General viewer program for groff files and man pages. .

R gxditview (1)

    The groff X viewer, the \f[CR]GNU\f[] version of

R xditview . .

R hpftodit (1)

    Create font description files for lj4 device. .

R indxbib (1)

    Make inverted index for bibliographic databases. .

R lkbib (1)

    Search bibliographic databases. .

R lookbib (1)

    Interactively search bibliographic databases. .

R pdfroff (1)

    Create PDF documents using

R groff . .

R pfbtops (1)

    Translate a PostScript font in .pfb format to \f[CR]ASCII\f[]. .

R pic2graph (1)

    Convert a

pic diagram into a cropped image. .

R tfmtodit (1)

    Create font description files for TeX DVI device. .

R xditview (1x)

    .I roff viewer distributed with X window. .

R xtotroff (1)

    Convert X font metrics into \f[CR]GNU\f[] troff font metrics. . .


. Normally, the path separator in the following environment variables is the colon; this may vary depending on the operating system. . For example, DOS and Windows use a semicolon instead. . .

        This search path, followed by .EnvVar $PATH , is used for commands that are executed by

R groff . . If it is not set then the directory where the groff binaries were installed is prepended to .EnvVar PATH . . .

        When there is a need to run different roff implementations at the same time groff provides the facility to prepend a prefix to most of its programs that could provoke name clashings at run time (default is to have none). . Historically, this prefix was the character

R g , but it can be anything. . For example,

R gtroff stood for groff 's

R troff ,

R gtbl for the groff version of

R tbl . . By setting .EnvVar GROFF_COMMAND_PREFIX to different values, the different roff installations can be addressed. . More exactly, if it is set to prefix xxx then

groff as a wrapper program internally calls .IB xxx troff instead of

R troff . This also applies to the preprocessors

R eqn ,

R grn ,

R pic ,

R refer ,

R tbl ,

R soelim , and to the utilities

indxbib and

R lookbib . . This feature does not apply to any programs different from the ones above (most notably

groff itself) since they are unique to the groff package. . .

        The value of this environment value is passed to the

preconv preprocessor to select the encoding of input files. . Setting this option implies

R groff 's command line option

-k (this is,

groff actually always calls

R preconv ). . If set without a value,

groff calls

preconv without arguments. . An explicit

-K command line option overrides the value of .EnvVar GROFF_ENCODING . . See

R preconv (1) for details. . .

        A list of directories in which to search for the dev name directory in addition to the default ones. . See

R troff (1) and

R groff_font (5) for more details. . .

        A list of directories in which to search for macro files in addition to the default directories. . See

R troff (1) and

R groff_tmac (5) for more details. . .

        The directory in which temporary files are created. . If this is not set but the environment variable .EnvVar TMPDIR instead, temporary files are created in the directory .EnvVar $TMPDIR . On MS-DOS and Windows\~32 platforms, the environment variables .EnvVar TMP and .EnvVar TEMP (in that order) are searched also, after .EnvVar GROFF_TMPDIR and .EnvVar TMPDIR . . Otherwise, temporary files are created in

R /tmp . The

R refer (1),

R groffer (1),

R grohtml (1), and

R grops (1) commands use temporary files. . .

        Preset the default device. . If this is not set the

ps device is used as default. . This device name is overwritten by the option

R -T . . .


. There are some directories in which groff installs all of its data files. . Due to different installation habits on different operating systems, their locations are not absolutely fixed, but their function is clearly defined and coincides on all systems. . .

7.1. groff Macro Directory

. This contains all information related to macro packages. . Note that more than a single directory is searched for those files as documented in

R groff_tmac (5). . For the groff installation corresponding to this document, it is located at /usr/share/groff/1.20.1/tmac . . The following files contained in the groff macro directory have a special meaning: . .


    Initialization file for troff . . This is interpreted by

troff before reading the macro sets and any input. . .


    Final startup file for troff . . It is parsed after all macro sets have been read. . .

  • .IB name .tmac
    tmac. name Macro file for macro package name . . .

7.2. groff Font Directory

. This contains all information related to output devices. . Note that more than a single directory is searched for those files; see

R troff (1). . For the groff installation corresponding to this document, it is located at /usr/share/groff/1.20.1/font . . The following files contained in the "groff font directory" have a special meaning: . .

  • dev name /DESC
        Device description file for device name , see

R groff_font (5). . .

  • dev name / F
        Font file for font F of device name . . .


. The following example illustrates the power of the

groff program as a wrapper around

R troff . .

To process a roff file using the preprocessors

tbl and

pic and the

me macro set, classical troff had to be called by .

pic foo.me | tbl | troff -me -Tlatin1 | grotty



R groff , this pipe can be shortened to the equivalent command .

groff -p -t -me -T latin1 foo.me


An even easier way to call this is to use

R grog (1) to guess the preprocessor and macro options and execute the generated command (by using backquotes to specify shell command substitution) .

\`grog -Tlatin1 foo.me\`


The simplest way is to view the contents in an automated way by calling .

groffer foo.me

. .



On \f[CR]EBCDIC\f[] hosts (e.g., \f[CR]OS/390 Unix\f[]), output devices

ascii and

latin1 aren't available. . Similarly, output for \f[CR]EBCDIC\f[] code page

cp1047 is not available on \f[CR]ASCII\f[] based operating systems. .

Report bugs to .MT the groff maling list .ME . . Include a complete, self-contained example that allows the bug to be reproduced, and say which version of groff you are using. . .


. Information on how to get groff and related information is available at the http://www.gnu.org/software/groff groff GNU website . The most recent released version of groff is available at the http://groff.ffii.org/groff/devel/groff-current.tar.gz groff development site .

Three groff mailing lists are available:

.MT for reporting bugs .ME . .

.MT for general discussion of groff , .ME .

.MT the groff commit list .ME , a read-only list showing logs of commitments to the CVS repository. .

Details on CVS access and much more can be found in the file

README at the top directory of the groff source package. .

There is a free implementation of the

grap preprocessor, written by .MT Ted Faber .ME . . The actual version can be found at the . http://www.lunabase.org/~faber/Vault/software/grap/ grap website This is the only grap version supported by groff . . .


. Copyright © 1989, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. .

This document is distributed under the terms of the \f[CR]FDL\f[] (\f[CR]GNU Free Documentation License\f[]) version 1.3 or later. . You should have received a copy of the \f[CR]FDL\f[] on your system, it is also available on-line at the http://www.gnu.org/copyleft/fdl.html GNU copyleft site .

This document is based on the original groff man page written by .MT James Clark . It was rewritten, enhanced, and put under the FDL license by Bernd Warken. . It is maintained by .MT Werner Lemberg .ME . .

groff is a \f[CR]GNU\f[] free software project. . All parts of the groff package are protected by \f[CR]GNU copyleft licenses\f[]. . The software files are distributed under the terms of the \f[CR]GNU General Public License\f[] (\f[CR]GPL\f[]), while the documentation files mostly use the \f[CR]GNU Free Documentation License\f[] (\f[CR]FDL\f[]). . .


. The groff info file contains all information on the groff system within a single document, providing many examples and background information. . See

R info (1) on how to read it. .

Due to its complex structure, the groff system has many man pages. . They can be read with

R man (1) or

R groffer (1). .

  • Introduction, history and further readings:
        .BR roff (7). .
  • Viewer for groff files:
        .BR groffer (1),

R gxditview (1),

R xditview (1x). .

  • Wrapper programs for formatters:
        .BR groff (1),

R grog (1). .

  • Roff preprocessors:
        .BR eqn (1),

R grn (1),

R pic (1),

R chem (1),

R preconv (1),

R refer (1),

R soelim (1),

R tbl (1),

R grap (1). .

  • Roff language with the groff extensions:
        .BR groff (7),

R groff_char (7),

R groff_diff (7),

R groff_font (5). .

  • Roff formatter programs:
        .BR nroff (1),

R troff (1),

R ditroff (7). .

  • The intermediate output language:
        .BR groff_out (7). .
  • Postprocessors for the output devices:
        .BR grodvi (1),

R grohtml (1),

R grolbp (1),

R grolj4 (1),

R lj4_font (5),

R grops (1),

R grotty (1). .

  • Groff macro packages and macro-specific utilities:
        .BR groff_tmac (5),

R groff_man (7),

R groff_mdoc (7),

R groff_me (7),

R groff_mm (7),

R groff_mmse (7),

R groff_mom (7),

R groff_ms (7),

R groff_www (7),

R groff_trace (7),

R mmroff (7). .

  • The following utilities are available:
        .BR addftinfo (1),

R afmtodit (1),

R eqn2graph (1),

R gdiffmk (1),

R grap2graph (1),

R groffer (1),

R gxditview (1),

R hpftodit (1),

R indxbib (1),

R lkbib (1),

R lookbib (1),

R pdfroff (1),

R pfbtops (1),

R pic2graph (1),

R tfmtodit (1),

R xtotroff (1). . .