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 documents only options to the groff front end. Many of the arguments to groff are passed on to gtroff; therefore, those are also included. Arguments to preprocessors and output drivers can be found in the man pages gpic(1), geqn(1), gtbl(1), ggrn(1), grefer(1), gchem(1), gsoelim(1), preconv(1), grotty(1), grops(1), gropdf(1), grohtml(1), grodvi(1), grolj4(1), grolbp(1), and gxditview(1).

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. Whitespace is permitted between an option and its argument.

The grog command can be used to guess the correct groff command to format a file. See its man page grog(1); type ‘man grog’ at the command line to view it.

groff’s command-line options are as follows.

‘-a’

Generate a plain text approximation of the typeset output. The read-only register .A is set to 1. See Built-in Registers. This option produces a sort of abstract preview of the formatted output.

• Page breaks are marked by a phrase in angle brackets; for example, ‘<beginning of page>’.
• Lines are broken where they would be in the formatted output.
• A horizontal motion of any size is represented as one space. Adjacent horizontal motions are not combined. Inter-sentence space nodes (those arising from the second argument to the ss request) are not represented.
• Vertical motions are not represented.
• Special characters are rendered in angle brackets; for example, the default soft hyphen character appears as ‘<hy>’.

The above description should not be considered a specification; the details of -a output are subject to change.

‘-b’

Write a backtrace reporting the state of gtroff’s input parser to the standard error stream with each diagnostic message. The line numbers given in the backtrace might not always be correct, because gtroff’s idea of line numbers can be confused by requests that append to macros.

‘-c’

Start with color output disabled.

‘-C’

Enable AT&T troff compatibility mode; implies -c. See Implementation Differences, for the list of incompatibilities between groff and AT&T troff.

‘-dctext’

‘-dstring=text’

Define roff string c or string as t or text. c must be one character; string can be of arbitrary length. Such string assignments happen before any macro file is loaded, including the startup file. Due to getopt_long limitations, c cannot be, and string cannot contain, an equals sign, even though that is a valid character in a roff identifier.

‘-Denc’

Set fallback input encoding used by preconv to enc; implies -k.

‘-e’

Run geqn preprocessor.

‘-E’

Inhibit gtroff error messages. This option does not suppress messages sent to the standard error stream by documents or macro packages using tm or related requests.

‘-ffam’

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

‘-Fdir’

Search in directory dir for the selected output device’s directory of device and font description files. See the description of GROFF_FONT_PATH in Environment below for the default search locations and ordering.

‘-g’

Run ggrn preprocessor.

‘-G’

Run grap preprocessor; implies -p.

‘-h’

Display a usage message and exit.

‘-i’

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

‘-Idir’

Search the directory dir for files named in several contexts; implies -g and -s.

• gsoelim replaces so requests with the contents of their file name arguments.
• gtroff searches for files named as operands in its command line and as arguments to psbb, so, and soquiet requests.
• Output drivers may search for files; for instance, grops looks for files named in ‘\X'ps: import …'’, ‘\X'ps: file …'’, and ‘\X'pdf: pdfpic …'’ device control escape sequences.

This option may be specified more than once; the directories are searched in the order specified. If you want to search the current directory before others, add ‘-I .’ at the desired place. The current working directory is otherwise searched last. -I works similarly to, and is named for, the “include” option of Unix C compilers.

-I options are passed to gsoelim, gtroff, and output drivers; with the flag letter changed to -M, they are also passed to ggrn.

‘-j’

Run gchem preprocessor. Implies -p.

‘-k’

Run preconv preprocessor. Refer to its man page for its behavior if neither of groff’s -K or -D options is also specified.

‘-Kenc’

Set input encoding used by preconv to enc; implies -k.

‘-l’

Send the output to a spooler for printing. The print directive in the device description file specifies the default command to be used; see Device and Font Description Files. See options -L and -X.

‘-Larg’

Pass arg to the print spooler program. If multiple args are required, pass each with a separate -L option. groff does not prefix an option dash to arg before passing it to the spooler program.

‘-mname’

Process the file name.tmac prior to any input files. If not found, tmac.name is attempted. name (in both arrangements) is presumed to be a macro file; see the description of GROFF_TMAC_PATH in Environment below for the default search locations and ordering. This option and its argument are also passed to geqn, grap, and ggrn.

‘-Mdir’

Search directory dir for macro files; see the description of GROFF_TMAC_PATH in Environment below for the default search locations and ordering. This option and its argument are also passed to geqn, grap, and ggrn.

‘-nnum’

Number the first page num.

‘-N’

Prohibit newlines between eqn delimiters: pass -N to geqn.

‘-olist’

Output only pages in list, which is a comma-separated list of page ranges; ‘n’ means page n, ‘m-n’ means every page between m and n, ‘-n’ means every page up to n, ‘n-’ means every page from n on. gtroff stops processing and exits after formatting the last page enumerated in list.

‘-p’

Run gpic preprocessor.

‘-Parg’

Pass arg to the postprocessor. If multiple args are required, pass each with a separate -P option. groff does not prefix an option dash to arg before passing it to the postprocessor.

‘-rcnumeric-expression’

‘-rregister=expr’

Set roff register c or register to the value numeric-expression (see Numeric Expressions). c must be one character; register can be of arbitrary length. Such register assignments happen before any macro file is loaded, including the startup file. Due to getopt_long limitations, c cannot be, and register cannot contain, an equals sign, even though that is a valid character in a roff identifier.

‘-R’

Run grefer preprocessor. No mechanism is provided for passing arguments to grefer because most grefer options have equivalent language elements that can be specified within the document.

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’

Run gsoelim preprocessor.

‘-S’

Operate in “safer” mode; see -U below for its opposite. For security reasons, safer mode is enabled by default.

‘-t’

Run gtbl preprocessor.

‘-Tdev’

Direct gtroff to format the input for the output device dev. groff then calls an output driver to convert gtroff’s output to a form appropriate for dev. The following output devices are 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 12-point base font in the document.

X100

For a 100dpi X11 previewer.

X100-12

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

ascii

For typewriter-like devices using the (7-bit) ASCII (ISO 646) 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 code page 1047.

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. This driver consists of two parts, a preprocessor (pre-grohtml) and a postprocessor (post-grohtml).

The predefined GNU troff string .T contains the name of the output device; the read-only register .T is set to 1 if this option is used (which is always true if groff is used to call GNU troff). See Built-in Registers.

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

‘-U’

Operate in unsafe mode, which enables the open, opena, pi, pso, and sy requests. These requests are disabled by default because they allow an untrusted input document to write to arbitrary file names and run arbitrary commands. This option also adds the current directory to the macro package search path; see the -m option above. -U is passed to gpic and gtroff.

‘-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 would be run by groff (as a wrapper program) to the standard output stream, but do not execute it. If given more than once, the pipeline is both written to the standard error stream and run.

‘-wcategory’

Enable warnings in category. Categories are listed in Warnings.

‘-Wcategory’

Inhibit warnings in category. Categories are listed in Warnings.

‘-X’

Use gxditview instead of the usual postprocessor to (pre)view a document on an X11 display. Combining this option with -Tps uses the font metrics of the PostScript device, whereas the -TX75 and -TX100 options use the metrics of X11 fonts.

‘-z’

Suppress formatted output from gtroff.

‘-Z’

Disable postprocessing. gtroff output will appear on the standard output stream (unless suppressed with -z; see gtroff Output for a description of this format.