groff: Groff Options
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,
DONTPRINTYET Invoking gsoelim, Invoking preconv, *noteInvoking
DONTPRINTYET DONTPRINTYET Invoking gsoelim, Invoking preconv, Invoking
grotty, Invoking grops, Invoking gropdf, *noteDONTPRINTYET DONTPRINTYET 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. 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. 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. 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 (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 (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. 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. 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'). Built-in Registers.
The postprocessor to be used for a device is specified by the
'postpro' command in the device description file. (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.
Info Catalog
groff: Invoking groff
groff: Invoking groff
groff: Environment