Next: Environment, Previous: Invoking groff, Up: Invoking groff [Contents][Index]
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 gpic
,
geqn
, gtbl
, ggrn
, grap
, gchem
,
grefer
, gsoelim
, 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 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).
A summary of groff
’s usage is as 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 …]
gtroff
shares much of this interface; groff
passes
relevant options and operands to it.
gtroff [-abcCEiRUz] [-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 after reporting.
The rest of groff
’s command-line options are as follows.
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.
ss
request) is not
represented.
The above description should not be considered a specification; the details of -a output are subject to change.
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.
Start with color output disabled.
Enable AT&T troff
compatibility mode; implies -c.
See Implementation Differences, for the list of incompatibilities
between groff
and AT&T troff
.
Define roff
string c or string as t or
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.
Set fallback input encoding used by preconv
to enc;
implies -k.
Run geqn
preprocessor.
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.
Use fam as the default font family. See Font Families.
Search in directory dir for the selected output device’s directory of device and font description files. See Font Directories.
Run ggrn
preprocessor.
Run grap
preprocessor; implies -p.
Display a usage message and exit.
Read the standard input stream after all the named input files have been processed.
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.
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
gsoelim
, gtroff
, and output drivers; with the option
changed to -M, the same arguments are passed to ggrn
.
Run gchem
preprocessor. Implies -p.
Run preconv
preprocessor. Refer to its man page for its
behavior if neither of groff
’s -K or -D
options is also specified.
Set input encoding used by preconv
to enc; implies
-k.
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.
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.
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 to geqn
, grap
, and
ggrn
.
Search directory dir for macro files. See Macro Directories. groff
passes -M options and their
arguments to to geqn
, grap
, and ggrn
.
Begin numbering pages at num. The default is ‘1’.
Prohibit newlines between eqn
delimiters: pass -N to
geqn
.
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.
Run gpic
preprocessor.
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.
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.
Run grefer
preprocessor. No mechanism is provided for passing
arguments to it; 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.
Run gsoelim
preprocessor.
Operate in “safer” mode; see -U below for its opposite. For security reasons, safer mode is enabled by default.
Run gtbl
preprocessor.
Prepare output for device dev. groff
passes the
-T option and its argument to gtroff
, then (unless
the -Z option is used) runs 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) 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 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
run 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 selection can be overridden with the
-X option.
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 names8 and run arbitrary commands.
This option also adds the current directory to the macro package search
path; see the -m option above. groff
passes
-U to gpic
and gtroff
.
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.
Output the 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.
Enable and inhibit, respectively, warnings in category cat. See Warnings.
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.
Suppress formatted output from gtroff
.
Disable postprocessing. gtroff
output will appear on the
standard output stream (unless suppressed with -z); see
gtroff Output for a description of this format.
Next: Environment, Previous: Invoking groff, Up: Invoking groff [Contents][Index]