Groff Options (The GNU Troff Manual)

+Next: Environment, Previous: Invoking groff, Up: Invoking groff [Contents][Index]

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

+ + + +