Groff Options (The GNU troff Manual)

2.1 Options

groff runs the GNU troff program and, normally, a postprocessor appropriate to the selected device. The default device is ‘ps’, unless changed at groff’s build-time configuration. groff can preprocess input with any of pic, eqn, tbl, grn, grap, chem, refer, soelim, or preconv.

This section documents only options to the groff front end. Since it passes many of its arguments to GNU troff, we describe many of the latter’s options here. Arguments to preprocessors and output drivers can be found in the man pages pic(1), eqn(1), tbl(1), grn(1), refer(1), chem(1), soelim(1), preconv(1), grotty(1), grops(1), gropdf(1), grohtml(1), grodvi(1), grolj4(1), grolbp(1), and gxditview(1).

A summary of groff’s usage follows.

groff [-abcCeEgGijklNpRsStUVXzZ] [-d cs] [-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 …]

troff shares much of this interface; groff passes relevant options and operands to it.

troff [-abcCEiRSUz] [-f font-family] [-F font-directory]
      [-I inclusion-directory] [-m macro-package]
      [-M macro-directory] [-n page-number] [-o page-list]
      [-r cnumeric-expression]
      [-r register=numeric-expression] [-T output-device]
      [-w warning-category] [-W warning-category]
      [file …]

Options that don’t take arguments can be clustered after a single -. A file operand of - denotes the standard input stream.

All groff commands accept a --help option, which summarizes usage similarly to the foregoing, and --version, which discloses release information. Both exit with a successful status after reporting.

The rest of 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 formatted output.
Vertical motion, apart from that implied by a break, is not represented.
A horizontal motion of any size is represented as one space. Adjacent horizontal motions are not combined. Supplemental inter-sentence space (configured by the second argument to the ss request) is not represented.
A special character is rendered as its identifier between angle brackets; for example, a hyphen 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 troff’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 troff’s idea of line numbers can be confused by requests that append to macros.

‘-c’

Disable multi-color output and color request’s ability to enable it.

‘-C’

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

‘-d ctext’

‘-d string=text’

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

‘-D enc’

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

‘-e’

Run eqn preprocessor.

‘-E’

Inhibit troff error messages; implies -Ww. This option does not suppress messages sent to the standard error stream by documents or macro packages using tm or related requests.

‘-f fam’

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

‘-F dir’

Search in directory dir for the selected output device’s directory of device and font description files. See Font Directories.

‘-g’

Run grn preprocessor.

‘-G’

Run grap preprocessor; implies -p.

‘-h’

Display a usage message and exit.

‘-i’

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

‘-I dir’

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

soelim replaces lines matching ‘.so file-name’ with the contents of file-name.
troff 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 extension 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.

groff passes -I options and their arguments to soelim, troff, and output drivers; with the option letter changed to -M, it passes the same arguments to grn.

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

‘-K enc’

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.

‘-L arg’

Pass arg to the print spooler. 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.

‘-m mac’

Search for the macro package mac.tmac and read it prior to any input. If not found, tmac.mac is attempted. See Macro Directories. groff passes -m options and their arguments to eqn, grap, and grn.

The following “full-service” macro packages are available. groff_tmac(5) documents these and many other, “auxiliary”, packages.⁸

Two full-service macro packages are specialized for formatting Unix reference manuals; they do not support features like footnotes or multiple columnation.

man: constructs man pages in a format introduced by Seventh Edition Unix (1979). Its macro interface is small, and the package widely used; see groff_man(7).
mdoc: constructs man pages in a format introduced by 4.3BSD-Reno (1990). It provides many more features than man but is also larger, more complex, and not as widely adopted; see groff_mdoc(7).
mandoc: recognizes a document’s use of man or mdoc and loads the corresponding macro package. Multiple man pages, in either format, can be handled; mandoc reloads each macro package as necessary.

The following packages each support composition of documents of any kind, from single-page memos to lengthy monographs. They are similar in functionality; select one that suits your taste.

me: originates in 2BSD (1978); see groff_me(7).
mm: originates in Programmer’s Workbench (PWB) Unix 1.0 (1977); see groff_mm(7).
mom: was contributed to groff in 2002, and freely exercises its many extended features. see groff_mom(7).
ms: originates in Sixth Edition Unix (1975); see groff_ms(7).

‘-M dir’

Search directory dir for macro files. See Macro Directories. groff passes -M options and their arguments to eqn, grap, and grn.

‘-n num’

Begin numbering pages at num. The default is ‘1’.

‘-N’

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

‘-o list’

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. troff stops processing and exits after formatting the last page enumerated in list.

‘-p’

Run pic preprocessor.

‘-P arg’

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.

‘-r cnumeric-expression’

‘-r register=numeric-expression’

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

‘-R’

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

troff also accepts a -R option, which is not accessible via groff. This option facilitates troubleshooting by preventing the loading of the troffrc and troffrc-end files.

‘-s’

Run soelim preprocessor.

‘-S’

Operate in “safer” mode; see -U below for its opposite. Safer mode is enabled by default. Explicitly specifying -S causes troff to ignore any subsequent -U option.

‘-t’

Run tbl preprocessor.

‘-T dev’

Prepare output for device dev. groff passes the -T option and its argument to troff, then (unless the -Z option is used) runs an output driver to convert troff’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) ISO 646:1991 IRV (US-ASCII) character set.
latin1: For typewriter-like devices that support the ISO Latin-1 (8859-1) character set.
utf8: For typewriter-like devices that use the ISO 10646 (Unicode) character set with UTF-8 encoding.
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 formatter string .T contains the name of the selected 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 run GNU troff). See Built-in Registers.

The device description file’s postpro command specifies the default postprocessor to be used by a device. See Device and Font Description Files. The -X option overriddes this selection.

‘-U’

Operate in unsafe mode, enabling the cf, open, opena, pi, pso, and sy requests, which are disabled by default because they allow an untrusted input document to run arbitrary commands, put arbitrary content into troff output, or write to arbitrary file names.⁹ This option also adds the current directory to the macro package search path; see the -m and -M option above. groff passes -U to pic and GNU troff.

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

Write the command pipeline that groff would run to the standard output stream and exit. If given more than once, groff both writes the pipeline to the standard error stream and runs it.

‘-w cat’

‘-W cat’

Enable and inhibit, respectively, warnings in category cat. See Warnings.

‘-X’

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

‘-z’

Suppress formatted output from troff.

‘-Z’

Disable postprocessing. troff output appears on the standard output stream (unless suppressed with -z); see GNU troff Output for a description of this format.