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, gchem, grefer, gsoelim, or preconv.

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 Invoking gpic, Invoking geqn, Invoking gtbl, Invoking ggrn, Invoking grefer, Invoking gchem, Invoking gsoelim, Invoking preconv, Invoking grotty, Invoking grops, Invoking gropdf, Invoking grohtml, Invoking grodvi, Invoking grolj4, Invoking grolbp, and Invoking gxditview.

The command line format for groff is:

groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dcs ] [ -Darg ]
      [ -ffam ] [ -Fdir ] [ -Idir ] [ -Karg ]
      [ -Larg ] [ -mname ] [ -Mdir ] [ -nnum ]
      [ -olist ] [ -Parg ] [ -rcn ] [ -Tdev ]
      [ -wname ] [ -Wname ] [ files… ]

The command line format for gtroff is as follows.

gtroff [ -abcivzCERU ] [ -dcs ] [ -ffam ] [ -Fdir ]
       [ -mname ] [ -Mdir ] [ -nnum ] [ -olist ]
       [ -rcn ] [ -Tname ] [ -wname ] [ -Wname ]
       [ 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:

‘-a’

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

groff -a -man -Tdvi troff.man | less

which shows how lines are broken for the DVI device. Note that this option is rather useless today since graphic output devices are available virtually everywhere.

‘-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.

‘-c’

Suppress color output.

‘-C’

Enable compatibility mode. See Implementation Differences, for the list of incompatibilities between groff and AT&T 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. All string assignments happen before loading any macro file (including the start-up file).

‘-Darg’

Set default input encoding used by preconv to arg. Implies -k.

‘-e’

Preprocess with geqn.

‘-E’

Inhibit all error messages.

‘-ffam’

Use fam as the default font family. See Font Families.

‘-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 directories (see Font Directories). This option is passed to all pre- and postprocessors using the GROFF_FONT_PATH environment variable.

‘-g’

Preprocess with ggrn.

‘-G’

Preprocess with grap. Implies -p.

‘-h’

Print a help message.

‘-i’

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

‘-Idir’

This option may be used to specify a directory to search for files. It is passed to the following programs:

• gsoelim (see gsoelim for more details); it also implies groff’s -s option.
• gtroff; it is used to search files named in the psbb and so requests.
• grops; it is used to search files named in the \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.

‘-j’

Preprocess with gchem. Implies -p.

‘-k’

Preprocess with preconv. This is run before any other preprocessor. Please refer to preconv’s manual page for its behaviour if no -K (or -D) option is specified.

‘-Karg’

Set input encoding used by preconv to arg. Implies -k.

‘-l’

Send the output to a spooler for printing. The command used for this is specified by the print command in the device description file (see Font Files, for more info). If not present, -l is ignored.

‘-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. If the print keyword in the device description file is missing, -L is ignored.

‘-mname’

Read in the file name.tmac. Normally groff searches for this in its macro directories. If it isn’t found, it tries tmac.name (searching in the same directories).

‘-Mdir’

Search directory dir for macro files before the standard directories (see Macro Directories).

‘-nnum’

Number the first page num.

‘-N’

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

‘-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 exits 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 Built-in Registers.

If your document restarts page numbering at the beginning of each chapter, then gtroff prints the specified page range for each chapter.

‘-p’

Preprocess with gpic.

‘-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.

‘-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. All register assignments happen before loading any macro file (including the start-up file).

‘-R’

Preprocess with grefer. No mechanism is provided for passing arguments to grefer because most grefer options have equivalent commands that can be included in the file. See 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.

‘-s’

Preprocess with gsoelim.

‘-S’

Safer mode. Pass the -S option to gpic and disable the open, opena, pso, sy, and pi requests. For security reasons, this is enabled by default.

‘-t’

Preprocess with gtbl.

‘-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.

pdf

For PDF viewers or printers.

dvi

For TeX DVI format.

X75

For a 75dpi X11 previewer.

X75-12

For a 75dpi X11 previewer with a 12pt base font in the document.

X100

For a 100dpi X11 previewer.

X100-12

For a 100dpi X11 previewer with a 12pt base font in the document.

ascii

For typewriter-like devices using the (7-bit) ASCII character set.

latin1

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

utf8

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

cp1047

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

lj4

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

lbp

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

html

xhtml

To produce HTML and XHTML output, respectively. Note that this driver consists of two parts, a preprocessor (pre-grohtml) and a postprocessor (post-grohtml).

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 Built-in Registers.

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

‘-U’

Unsafe mode. This enables the open, opena, pso, sy, and pi requests.

‘-wname’

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

‘-Wname’

Inhibit warning name. Multiple -W options are allowed.

‘-v’

Make programs run by groff print out their version number.

‘-V’

Print the pipeline on stdout instead of executing it. If specified more than once, print the pipeline on stderr and execute it.

‘-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 uses the metrics of the specified device, whereas the latter uses X-specific fonts and metrics.

‘-z’

Suppress output from gtroff. Only error messages are printed.

‘-Z’

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