2. Invoking groff

This section focuses on how to invoke the groff front end. This front end takes care of the details of constructing the pipeline among the preprocessors, gtroff and the postprocessor.

It has become a tradition that GNU programs get the prefix `g' to distinguish it from its original counterparts provided by the host (see 2.2 Environment, for more details). Thus, for example, geqn is GNU eqn. On operating systems like Linux or the Hurd, which don't contain proprietary software, and on MS-DOS/MS-Windows, where troff and associated programs are not available at all, this prefix is omitted since GNU troff is the only used incarnation of troff. Exception: groff is never replaced by roff.

2.1 Options
2.2 Environment
2.3 Invocation Examples

2.1 Options

groff normally runs the gtroff program and a postprocessor appropriate for the selected device. The default device is `ps' (but it can be changed when groff is configured and built). It can optionally preprocess with any of gpic, geqn, gtbl, ggrn, grap, grefer, or gsoelim.

This section only documents options to the groff front end. Many of the arguments to groff are passed on to gtroff, therefore those are also included. Arguments to pre- or postprocessors can be found in 6.3.1 Invoking gpic, 6.1.1 Invoking geqn, 6.2.1 Invoking gtbl, 6.4.1 Invoking ggrn, 6.6.1 Invoking grefer, 6.7.1 Invoking gsoelim, 7.2.1 Invoking grotty, 7.3.1 Invoking grops, 7.7.1 Invoking grohtml, 7.4.1 Invoking grodvi, 7.5.1 Invoking grolj4, 7.6.1 Invoking grolbp, and 7.8.1 Invoking gxditview.

The command line format for groff is:

groff [ -abeghilpstvzCEGNRSUVXZ ] [ -Fdir ] [ -mname ] [ -Tdef ] [ -ffam ] [ -wname ] [ -Wname ] [ -Mdir ] [ -dcs ] [ -rcn ] [ -nnum ] [ -olist ] [ -Parg ] [ -Larg ] [ -Idir ] [ files... ]

The command line format for gtroff is as follows.

gtroff [ -abivzCERU ] [ -wname ] [ -Wname ] [ -dcs ] [ -ffam ] [ -mname ] [ -nnum ] [ -olist ] [ -rcn ] [ -Tname ] [ -Fdir ] [ -Mdir ] [ files... ]

Obviously, many of the options to groff are actually passed on to gtroff.

Options without an argument can be grouped behind a single `-'. A filename of `-' denotes the standard input. It is possible to have whitespace between an option and its parameter.

The grog command can be used to guess the correct groff command to format a file.

Here's the description of the command-line options:

`-h'

Print a help message.

`-e'

Preprocess with geqn.

`-t'

Preprocess with gtbl.

`-g'

Preprocess with ggrn.

`-G'

Preprocess with grap.

`-p'

Preprocess with gpic.

`-s'

Preprocess with gsoelim.

`-R'

Preprocess with grefer. No mechanism is provided for passing arguments to grefer because most grefer options have equivalent commands which can be included in the file. See section 6.6 grefer, for more details.

Note that gtroff also accepts a `-R' option, which is not accessible via groff. This option prevents the loading of the `troffrc' and `troffrc-end' files.

`-v'

Make programs run by groff print out their version number.

`-V'

Print the pipeline on stdout instead of executing it.

`-z'

Suppress output from gtroff. Only error messages will be printed.

`-Z'

Do not postprocess the output of gtroff. Normally groff will automatically run the appropriate postprocessor.

`-Parg'

Pass arg to the postprocessor. Each argument should be passed with a separate `-P' option. Note that groff does not prepend `-' to arg before passing it to the postprocessor.

`-l'

Send the output to a printer. The command used for this is specified by the print command in the device description file.

`-Larg'

Pass arg to the spooler. Each argument should be passed with a separate `-L' option. Note that groff does not prepend a `-' to arg before passing it to the postprocessor.

`-Tdev'

Prepare output for device dev. The default device is `ps', unless changed when groff was configured and built. The following are the output devices currently available:

ps

For PostScript printers and previewers.

dvi

For TeX DVI format.

X75

For a 75dpi X11 previewer.

X100

For a 100dpi X11 previewer.

ascii

For typewriter-like devices.

latin1

For typewriter-like devices that support the Latin-1 (ISO 8859-1) character set.

utf8

For typewriter-like devices which use the Unicode (ISO 10646) character set with UTF-8 encoding.

cp1047

For typewriter-like devices which use the EBCDIC encoding IBM cp1047.

lj4

For an HP LaserJet4-compatible (or other PCL5-compatible) printer.

lbp

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

html

To produce HTML output.

The predefined gtroff string register .T contains the current output device; the read-only number register .T is set to 1 if this option is used (which is always true if groff is used to call gtroff). See section 5.7.5 Built-in Registers.

The postprocessor to be used for a device is specified by the postpro command in the device description file. (See section 8.2 Font Files, for more info.) This can be overridden with the `-X' option.

`-X'

Preview with gxditview instead of using the usual postprocessor. This is unlikely to produce good results except with `-Tps'.

Note that this is not the same as using `-TX75' or `-TX100' to view a document with gxditview: The former will use the metrics of the specified device, whereas the latter will use X-specific fonts and metrics.

`-N'

Don't allow newlines with eqn delimiters. This is the same as the `-N' option in geqn.

`-S'

Safer mode. Pass the `-S' option to gpic and use the `-msafer' macros with gtroff (enabled by default).

`-U'

Unsafe mode. Reverts to the old unsafe behaviour.

`-a'

Generate an ASCII approximation of the typeset output. The read-only register .A is then set to 1. See section 5.7.5 Built-in Registers.

`-b'

Print a backtrace with each warning or error message. This backtrace should help track down the cause of the error. The line numbers given in the backtrace may not always be correct: gtroff can get confused by as or am requests while counting line numbers.

`-i'

Read the standard input after all the named input files have been processed.

`-wname'

Enable warning name. Available warnings are described in 5.30 Debugging. Multiple `-w' options are allowed.

`-Wname'

Inhibit warning name. Multiple `-W' options are allowed.

`-E'

Inhibit all error messages.

`-C'

Enable compatibility mode. See section 5.31 Implementation Differences, for the list of incompatibilites between groff and traditional Unix troff.

`-dcs'

`-dname=s'

Define c or name to be a string s. c must be a one-letter name; name can be of arbitrary length.

`-ffam'

Use fam as the default font family.

`-mname'

Read in the file `tmac.name'. Normally this will be searched for in the library directory of groff.

`-nnum'

Number the first page num.

`-olist'

Output only pages in list, which is a comma-separated list of page ranges; `n' means print page n, `m-n' means print every page between m and n, `-n' means print every page up to n, `n-' means print every page beginning with n. gtroff will exit after printing the last page in the list. All the ranges are inclusive on both ends.

Within gtroff, this information can be extracted with the `.P' register. See section 5.7.5 Built-in Registers.

`-rcn'

`-rname=n'

Set number register c or name to the value n. c must be a one-letter name; name can be of arbitrary length. n can be any gtroff numeric expression.

`-Fdir'

Search `dir' for subdirectories `devname' (name is the name of the device), for the `DESC' file, and for font files before looking in the standard directory.

`-Mdir'

Search directory `dir' for macro files before the standard directory.

`-Idir'

This option is as described in 6.7 gsoelim. It implies the `-s' option.

2.2 Environment

There are also several environment variables (of the operating system, not within gtroff) which can modify the behavior of groff.

GROFF_COMMAND_PREFIX

If this is set to X, then groff will run Xtroff instead of gtroff. This also applies to tbl, pic, eqn, grn, refer, and soelim. It does not apply to grops, grodvi, grotty, grohtml, grolj4, and gxditview.

GROFF_TMAC_PATH

A colon-separated list of directories in which to search for macro files.

GROFF_TYPESETTER

The default output device.

GROFF_FONT_PATH

A colon-separated list of directories in which to search for the devname directory.

PATH

The search path for commands executed by groff.

GROFF_TMPDIR

The directory in which temporary files will be created. If this is not set and TMPDIR is set, temporary files will be created in that directory. Otherwise temporary files will be created in a system-dependent default directory (on Unix and GNU/Linux systems, this is usually `/tmp'). The grops and grefer commands can create temporary files in this directory.

Note that MS-DOS and MS-Windows ports of groff use semi-colons, rather than colons, to separate the directories in the lists described above.

2.3 Invocation Examples

This section will list several common uses of groff and the command line which will accomplish it.

groff file

This command processes `file' without a macro package or a preprocessor. The output device is the default, `ps', and the output is sent to stdout.

groff -t -mandoc -Tascii file | less

This is basically what a call to the man program does. The manual page `file' is processed with the `mandoc' macros (which in turn either calls the `man' or the `mdoc' macro package), using the tbl preprocessor and the ASCII output device. Finally, the result is displayed with the less pager.

groff -X -m me file

Preview `file' with gxditview, using the `me' macro package. Since no `-T' option is specified, use the default device (`ps'). Note that you can either say `-m me' or `-me'; the latter is an anachronism from the early days of UNIX.(2)

groff -man -rD1 -z file

Check `file' with the `man' macro package, forcing double-sided printing -- don't produce any output.

2.3.1 grog

2.3.1 grog

grog reads files, guesses which of the groff preprocessors and/or macro packages are required for formatting them, and prints the groff command including those options on the standard output. The options generated are one of `-e', `-man', `-me', `-mm', `-ms', `-p', `-R', `-g', `-G', `-s', and `-t'.

A special file name `-' is taken to refer to the standard input. If no files are specified the standard input will be read. Any specified options will be included in the printed command. No space is allowed between options and their arguments. For example,

grog -Tdvi paper.ms

will guess the appropriate command to print `paper.ms' and then print it to the command line after adding the `-Tdvi' option. For direct execution, enclose the call to grog in backquotes at the UNIX shell prompt:

`grog -Tdvi paper.ms` > paper.dvi

As seen in the example, it is still necessary to redirect the output to something meaningful (i.e. either a file or a pager program like less).