GROFF(1) GROFF(1)
NAME
groff - front-end for the groff document formatting system
SYNOPSIS
ggrrooffff [-aabbcceeggiillppssttzzCCEEGGNNRRSSUUVVXXZZ] [-dd cs] [-ff fam] [-FF dir] [-II dir]
[-LL arg] [-mm name] [-MM dir] [-nn num] [-oo list] [-PP arg] [-rr cn]
[-TT dev] [-ww name] [-WW name] [file ...]
ggrrooffff -hh | --hheellpp
ggrrooffff -vv | --vveerrssiioonn [option ...]
The command line is parsed according to the usual GNU convention. The
whitespace between a command line option and its argument is optional.
Options can be grouped behind a single - (minus character). A filename
of - (minus character) denotes the standard input.
DESCRIPTION
This document describes the ggrrooffff program, the main front-end for the
groff document formatting system. The groff program and macro suite is
the implementation of a rrooffff(7) system within the free software collec-
tion GGNNUU . The groff system has all features of
the classical roff, but adds many extensions.
The ggrrooffff program allows to control the whole groff system by command
line options. This is a great simplification in comparison to the
classical case (which uses pipes only).
OOPPTTIIOONNSS
As ggrrooffff is a wrapper program for ttrrooffff both programs share a set of
options. But the ggrrooffff program has some additional, native options and
gives a new meaning to some ttrrooffff options. On the other hand, not all
ttrrooffff options can be fed into ggrrooffff.
Native groff Options
The following options either do not exist for ttrrooffff or are differently
interpreted by ggrrooffff.
-ee Preprocess with eeqqnn.
-gg Preprocess with ggrrnn.
-GG Preprocess with ggrraapp.
-hh --hheellpp
Print a help message.
-II dir This option may be used to specify a directory to search for
files (both those on the command line and those named in ..ppssbbbb
and ..ssoo requests, and \\XX''ppss:: iimmppoorrtt'' and \\XX''ppss:: ffiillee'' escapes).
The current directory is always searched first. This option may
be specified more than once; the directories will be searched in
the order specified. No directory search is performed for files
specified using an absolute path. This option implies the -ss
option.
-ll Send the output to a spooler program for printing. The command
that should be used for this is specified by the pprriinntt command
in the device description file, see ggrrooffffffoonntt(5). If this com-
mand is not present, the output is piped into the llpprr(1) program
by default. See options -LL and -XX.
-LL arg Pass arg to the spooler program. Several arguments should be
passed with a separate -LL option each. Note that ggrrooffff does not
prepend - (a minus sign) to arg before passing it to the spooler
program.
-NN Don't allow newlines within eqn delimiters. This is the same as
the -NN option in eeqqnn.
-pp Preprocess with ppiicc.
-PP -option
-PP -option -PP arg
Pass -option or -option arg to the postprocessor. The option
must be specified with the necessary preceding minus sign(s) `-'
or `-' because groff does not prepend any dashes before passing
it to the postprocessor. For example, to pass a title to the
gxditview postprocessor, the shell command
sh# groff -X -P -title -P 'groff it' foo
is equivalent to
sh# groff -X -Z foo | gxditview -title 'groff it' -
-RR Preprocess with rreeffeerr. No mechanism is provided for passing ar-
guments to rreeffeerr because most rreeffeerr options have equivalent lan-
guage elements that can be specified within the document. See
rreeffeerr(1) for more details.
-ss Preprocess with ssooeelliimm.
-SS Safer mode. Pass the -SS option to ppiicc and disable the following
ttrrooffff requests: ..ooppeenn, ..ooppeennaa, ..ppssoo, ..ssyy, and ..ppii. For security
reasons, safer mode is enabled by default.
-tt Preprocess with ttbbll.
-TT dev Set output device to dev. Contrary to ttrrooffff, ggrrooffff calls a
postprocessor to convert ttrrooffff's intermediate output to its fi-
nal format. Real devices in ggrrooffff are
dvi TeX DVI format (postprocessor is ggrrooddvvii).
html HTML output (preprocessors are ssooeelliimm and
pprree-ggrroohhttmmll, postprocessor is ppoosstt-ggrroohhttmmll).
lbp Canon CAPSL printers (LBP-4 and LBP-8 series laser
printers; postprocessor is ggrroollbbpp).
lj4 HP LaserJet4 compatible (or other PCL5 compatible)
printers (postprocessor is ggrroolljj44).
ps PostScript output (postprocessor is ggrrooppss).
For the following TTY output devices (postprocessor is always
ggrroottttyy), -TT selects the output encoding:
ascii 7bit ASCII.
cp1047 Latin-1 character set for EBCDIC hosts.
latin1 ISO 8859-1.
utf8 Unicode character set in UTF-8 encoding.
The following arguments select ggxxddiittvviieeww as the `postprocessor'
(it is rather a viewing program):
X75 75dpi resolution, 10pt document base font.
X75-12 75dpi resolution, 12pt document base font.
X100 100dpi resolution, 10pt document base font.
X100-12
100dpi resolution, 12pt document base font.
The default device is ppss.
-UU Unsafe mode. Reverts to the (old) unsafe behaviour; see option
-SS.
-vv --vveerrssiioonn
Output version information of ggrrooffff and of all programs that are
run by it; that is, the given command line is parsed in the usu-
al way, passing -vv to all subprograms.
-VV Output the pipeline that would be run by ggrrooffff (as a wrapper
program) on the standard output, but do not execute it. If giv-
en more than once, the commands will be both printed on the
standard error and run.
-XX Use ggxxddiittvviieeww instead of using the usual postprocessor to
(pre)view a document. The printing spooler behavior as outlined
with options -ll and -LL is carried over to ggxxddiittvviieeww(1) by deter-
mining an argument for the -pprriinnttCCoommmmaanndd option of ggxxddiittvviieeww(1).
This sets the default PPrriinntt action and the corresponding menu
entry to that value. -XX only produces good results with -TTppss,
-TTXX7755, -TTXX7755-1122, -TTXX110000, and -TTXX110000-1122. The default resolution
for previewing -TTppss output is 75dpi; this can be changed by
passing the -rreessoolluuttiioonn option to ggxxddiittvviieeww, for example
sh# groff -X -P-resolution -P100 -man foo.1
-zz Suppress output generated by ttrrooffff. Only error messages will be
printed.
-ZZ Do not postprocess the output of ttrrooffff that is normally called
automatically by ggrrooffff. This will print the intermediate output
to standard output; see ggrrooffffoouutt(5).
Transparent Options The following options are transparently handed over to the formatter
program ttrrooffff that is called by groff subsequently. These options are
described in more detail in ttrrooffff(1).
-aa ascii approximation of output.
-bb backtrace on error or warning.
-cc disable color output.
-CC enable compatibility mode.
-dd cs
-dd name=s
define string.
-EE disable ttrrooffff error messages.
-ff fam set default font family.
-FF dir set path for font DESC files.
-ii process standard input after the specified input files.
-mm name
include macro file name..ttmmaacc (or ttmmaacc..name); see also
ggrrooffffttmmaacc(5).
-MM dir path for macro files.
-nn num number the first page num.
-oo list
output only pages in list.
-rr cn
-rr name=n
set number register.
-ww name
enable warning name.
-WW name
disable warning name.
UUSSIINNGG GGRROOFFFF
The groff system implements the infrastructure of classical roff; see
rrooffff(7) for a survey on how a roff system works in general. Due to the
front-end programs available within the groff system, using groff is
much easier than classical roff. This section gives an overview of the
parts that constitute the groff system. It complements rrooffff(7) with
groff-specific features. This section can be regarded as a guide to
the documentation around the groff system.
FFrroonntt-eennddss
The ggrrooffff program is a wrapper around the ttrrooffff(1) program. It allows
to specify the preprocessors by command line options and automatically
runs the postprocessor that is appropriate for the selected device.
Doing so, the sometimes tedious piping mechanism of classical rrooffff(7)
can be avoided.
The ggrroogg(1) program can be used for guessing the correct groff command
line to format a file.
The ggrrooffffeerr(1) program is an allround-viewer for groff files and man
pages.
PPrreepprroocceessssoorrss
The groff preprocessors are reimplementations of the classical pre-
processors with moderate extensions. The preprocessors distributed
with the groff package are
eeqqnn(1) for mathematical formulae,
ggrrnn(1) for including ggrreemmlliinn(1) pictures,
ppiicc(1) for drawing diagrams,
rreeffeerr(1)
for bibliographic references,
ssooeelliimm(1)
for including macro files from standard locations,
and
ttbbll(1) for tables.
Besides these, there are some internal preprocessors that are automati-
cally run with some devices. These aren't visible to the user.
MMaaccrroo PPaacckkaaggeess
Macro packages can be included by option -mm. The groff system imple-
ments and extends all classical macro packages in a compatible way and
adds some packages of its own. Actually, the following macro packages
come with groff:
mmaann The traditional man page format; see ggrrooffffmmaann(7). It can be
specified on the command line as -mmaann or -mm mmaann.
mmaannddoocc The general package for man pages; it automatically recognizes
whether the documents uses the man or the mdoc format and
branches to the corresponding macro package. It can be speci-
fied on the command line as -mmaannddoocc or -mm mmaannddoocc.
mmddoocc The BSD-style man page format; see ggrrooffffmmddoocc(7). It can be
specified on the command line as -mmddoocc or -mm mmddoocc.
mmee The classical me document format; see ggrrooffffmmee(7). It can be
specified on the command line as -mmee or -mm mmee.
mmmm The classical mm document format; see ggrrooffffmmmm(7). It can be
specified on the command line as -mmmm or -mm mmmm.
mmss The classical ms document format; see ggrrooffffmmss(7). It can be
specified on the command line as -mmss or -mm mmss.
wwwwww HTML-like macros for inclusion in arbitrary groff documents; see
ggrrooffffwwwwww(7).
Details on the naming of macro files and their placement can be found
in ggrrooffffttmmaacc(5).
PPrrooggrraammmmiinngg LLaanngguuaaggee
General concepts common to all roff programming languages are described
in rrooffff(7).
The groff extensions to the classical troff language are documented in
ggrrooffffddiiffff(7).
The groff language as a whole is described in the (still incomplete)
groff info file; a short (but complete) reference can be found in
ggrrooffff(7).
FFoorrmmaatttteerrss
The central roff formatter within the groff system is ttrrooffff(1). It
provides the features of both the classical troff and nroff, as well as
the groff extensions. The command line option -CC switches ttrrooffff into
compatibility mode which tries to emulate classical roff as much as
possible.
There is a shell script nnrrooffff(1) that emulates the behavior of classi-
cal nroff. It tries to automatically select the proper output encod-
ing, according to the current locale.
The formatter program generates intermediate output; see ggrrooffffoouutt(7).
DDeevviicceess
In roff, the output targets are called devices. A device can be a
piece of hardware, e.g. a printer, or a software file format. A device
is specified by the option -TT. The groff devices are as follows.
aasscciiii Text output using the aasscciiii(7) character set.
ccpp11004477 Text output using the EBCDIC code page IBM cp1047 (e.g. OS/390
Unix).
ddvvii TeX DVI format.
hhttmmll HTML output.
llaattiinn11 Text output using the ISO Latin-1 (ISO 8859-1) character set;
see iissoo8888559911(7).
llbbpp Output for Canon CAPSL printers (LBP-4 and LBP-8 series laser
printers).
lljj44 HP LaserJet4-compatible (or other PCL5-compatible) printers.
ppss PostScript output; suitable for printers and previewers like
ggvv(1).
uuttff88 Text output using the Unicode (ISO 10646) character set with
UTF-8 encoding; see uunniiccooddee(7).
XX7755 75dpi X Window System output suitable for the previewers
xxddiittvviieeww(1x) and ggxxddiittvviieeww(1). A variant for a 12pt document
base font is XX7755-1122.
XX110000 100dpi X Window System output suitable for the previewers
xxddiittvviieeww(1x) and ggxxddiittvviieeww(1). A variant for a 12pt document
base font is XX110000-1122.
The postprocessor to be used for a device is specified by the ppoossttpprroo
command in the device description file; see ggrrooffffffoonntt(5). This can be
overridden with the -XX option.
The default device is ppss.
PPoossttpprroocceessssoorrss
groff provides 3 hardware postprocessors:
ggrroollbbpp(1)
for some Canon printers,
ggrroolljj44(1)
for printers compatible to the HP LaserJet 4 and PCL5,
ggrroottttyy(1)
for text output using various encodings, e.g. on text-oriented
terminals or line-printers.
Today, most printing or drawing hardware is handled by the operating
system, by device drivers, or by software interfaces, usually accepting
PostScript. Consequently, there isn't an urgent need for more hardware
device postprocessors.
The groff software devices for conversion into other document file for-
mats are
ggrrooddvvii(1)
for the DVI format,
ggrroohhttmmll(1)
for HTML format,
ggrrooppss(1)
for PostScript.
Combined with the many existing free conversion tools this should be
sufficient to convert a troff document into virtually any existing data
format.
UUttiilliittiieess
The following utility programs around groff are available.
aaddddffttiinnffoo(1)
Add information to troff font description files for use with
groff.
aaffmmttooddiitt(1)
Create font description files for PostScript device.
ggrrooffffeerr(1)
General viewer program for groff files and man pages.
ggxxddiittvviieeww(1)
The groff X viewer, the GNU version of xditview.
hhppffttooddiitt(1)
Create font description files for lj4 device.
iinnddxxbbiibb(1)
Make inverted index for bibliographic databases.
llkkbbiibb(1)
Search bibliographic databases.
llooookkbbiibb(1)
Interactively search bibliographic databases.
ppffbbttooppss(1)
Translate a PostScript font in .pfb format to ASCII.
ttffmmttooddiitt(1)
Create font description files for TeX DVI device.
xxddiittvviieeww(1x)
roff viewer distributed with X window.
ENVIRONMENT Normally, the path separator in the following environment variables is
the colon; this may vary depending on the operating system. For exam-
ple, DOS and Windows use a semicolon instead.
GGRROOFFFFBBIINNPPAATTHH
This search path, followed by $$PPAATTHH, will be used for commands
that are executed by ggrrooffff. If it is not set then the directory
where the groff binaries were installed is prepended to PPAATTHH.
GGRROOFFFFCCOOMMMMAANNDDPPRREEFFIIXX
When there is a need to run different roff implementations at
the same time groff provides the facility to prepend a prefix to
most of its programs that could provoke name clashings at run
time (default is to have none). Historically, this prefix was
the character gg, but it can be anything. For example, ggttrrooffff
stood for groff's ttrrooffff, ggttbbll for the groff version of ttbbll. By
setting GGRROOFFFFCCOOMMMMAANNDDPPRREEFFIIXX to different values, the different
roff installations can be addressed. More exactly, if it is set
to prefix xxx then ggrrooffff as a wrapper program will internally
call xxxttrrooffff instead of ttrrooffff. This also applies to the pre-
processors eeqqnn, ggrrnn, ppiicc, rreeffeerr, ttbbll, ssooeelliimm, and to the utili-
ties iinnddxxbbiibb and llooookkbbiibb. This feature does not apply to any
programs different from the ones above (most notably ggrrooffff it-
self) since they are unique to the groff package.
GGRROOFFFFFFOONNTTPPAATTHH
A list of directories in which to search for the ddeevvname direc-
tory in addition to the default ones. See ttrrooffff(1) and
ggrrooffffffoonntt(5) for more details.
GGRROOFFFFTTMMAACCPPAATTHH
A list of directories in which to search for macro files in ad-
dition to the default directories. See ttrrooffff(1) and
ggrrooffffttmmaacc(5) for more details.
GGRROOFFFFTTMMPPDDIIRR
The directory in which temporary files will be created. If this
is not set but the environment variable TTMMPPDDIIRR instead, tempo-
rary files will be created in the directory $$TTMMPPDDIIRR. On MS-DOS
and Windows 32 platforms, the environment variables TTMMPP and TTEEMMPP
(in that order) are searched also, after GGRROOFFFFTTMMPPDDIIRR and
TTMMPPDDIIRR. Otherwise, temporary files will be created in //ttmmpp.
The rreeffeerr(1), ggrrooffffeerr(1), ggrroohhttmmll(1), and ggrrooppss(1) commands use
temporary files.
GGRROOFFFFTTYYPPEESSEETTTTEERR
Preset the default device. If this is not set the ppss device is
used as default. This device name is overwritten by the option
-TT.
FILES There are some directories in which groff installs all of its data
files. Due to different installation habits on different operating
systems, their locations are not absolutely fixed, but their function
is clearly defined and coincides on all systems.
ggrrooffff MMaaccrroo DDiirreeccttoorryy
This contains all information related to macro packages. Note that
more than a single directory is searched for those files as documented
in ggrrooffffttmmaacc(5). For the groff installation corresponding to this
document, it is located at /usr/share/groff/1.19.1/tmac. The following
files contained in the groff macro directory have a special meaning:
ttrrooffffrrcc
Initialization file for troff. This is interpreted by ttrrooffff be-
fore reading the macro sets and any input.
ttrrooffffrrcc-eenndd
Final startup file for troff, it is parsed after all macro sets
have been read.
name..ttmmaacc
ttmmaacc..name
Macro file for macro package name.
ggrrooffff FFoonntt DDiirreeccttoorryy
This contains all information related to output devices. Note that
more than a single directory is searched for those files; see ttrrooffff(1).
For the groff installation corresponding to this document, it is locat-
ed at /usr/share/groff/1.19.1/font. The following files contained in
the groff font directory have a special meaning:
ddeevvname//DDEESSCC
Device description file for device name, see ggrrooffffffoonntt(5).
ddeevvname//F
Font file for font F of device name.
EEXXAAMMPPLLEESS
The following example illustrates the power of the ggrrooffff program as a
wrapper around ttrrooffff.
To process a roff file using the preprocessors ttbbll and ppiicc and the mmee
macro set, classical troff had to be called by
sh# pic foo.me | tbl | troff -me -Tlatin1 | grotty
Using ggrrooffff, this pipe can be shortened to the equivalent command
sh# groff -p -t -me -T latin1 foo.me
An even easier way to call this is to use ggrroogg(1) to guess the pre-
processor and macro options and execute the generated command (by using
backquotes to specify shell command substitution)
sh# `grog -Tlatin1 foo.me`
The simplest way is to view the contents in an automated way by calling
sh# groffer foo.me
BUGS
On EBCDIC hosts (e.g. OS/390 Unix), output devices aasscciiii and llaattiinn11
aren't available. Similarly, output for EBCDIC code page ccpp11004477 is not
available on ASCII based operating systems.
Report bugs to bug-groff@gnu.org. Include a complete, self-contained
example that will allow the bug to be reproduced, and say which version
of groff you are using.
AVAILABILITY Information on how to get groff and related information is available at
the GGNNUU wweebbssiittee . The most recent
released version of groff is available for anonymous ftp at the ggrrooffff
ddeevveellooppmmeenntt ssiittee groff-current.tar.gz>.
Three groff mailing lists are available:
bbuugg-ggrrooffff@@ggnnuu..oorrgg
for reporting bugs,
ggrrooffff@@ggnnuu..oorrgg
for general discussion of groff,
ggrrooffff-ccoommmmiitt@@ffffiiii..oorrgg
a read-only list showing logs of commitments to the CVS reposi-
tory.
Details on CVS access and much more can be found in the file RREEAADDMMEE at
the top directory of the groff source package.
There is a free implementation of the ggrraapp preprocessor, written by
TTeedd FFaabbeerr . The actual version can be found at the
ggrraapp wweebbssiittee .
This is the only grap version supported by groff.
AUTHORS Copyright (C) 1989, 2002, 2003, 2004 Free Software Foundation, Inc.
This document is distributed under the terms of the FDL (GNU Free Docu-
mentation License) version 1.1 or later. You should have received a
copy of the FDL on your system, it is also available on-line at the GGNNUU
ccooppyylleefftt ssiittee .
This document is based on the original groff man page written by
JJaammeess CCllaarrkk . It was rewritten, enhanced, and put un-
der the FDL license by
BBeerrnndd WWaarrkkeenn . It is maintained by
WWeerrnneerr LLeemmbbeerrgg .
groff is a GNU free software project. All parts of the groff package
are protected by GNU copyleft licenses. The software files are dis-
tributed under the terms of the GNU General Public License (GPL), while
the documentation files mostly use the GNU Free Documentation License
(FDL).
SEE ALSO
The groff info file contains all information on the groff system within
a single document. Beneath the detailed documentation of all aspects,
it provides examples and background information. See iinnffoo(1) on how to
read it.
Due to its complex structure, the groff system has many man pages.
They can be read with mmaann(1) or ggrrooffffeerr(1).
Introduction, history and further readings:
rrooffff(7).
Viewer for groff files:
ggrrooffffeerr(1), ggxxddiittvviieeww(1), xxddiittvviieeww(1x).
Wrapper programs for formatters:
ggrrooffff(1), ggrroogg(1).
Roff preprocessors:
eeqqnn(1), ggrrnn(1), ppiicc(1), rreeffeerr(1), ssooeelliimm(1), ttbbll(1), ggrraapp(1).
Roff language with the groff extensions:
ggrrooffff(7), ggrrooffffcchhaarr(7), ggrrooffffddiiffff(7), ggrrooffffffoonntt(5).
Roff formatter programs:
nnrrooffff(1), ttrrooffff(1), ddiittrrooffff(7).
The intermediate output language:
ggrrooffffoouutt(7).
Postprocessors for the output devices:
ggrrooddvvii(1), ggrroohhttmmll(1), ggrroollbbpp(1), ggrroolljj44(1), lljj44ffoonntt(5),
ggrrooppss(1), ggrroottttyy(1).
Groff macro packages and macro-specific utilities:
ggrrooffffttmmaacc(5), ggrrooffffmmaann(7), ggrrooffffmmddoocc(7), ggrrooffffmmee(7),
ggrrooffffmmmm(7), ggrrooffffmmmmssee(7), ggrrooffffmmoomm(7), ggrrooffffmmss(7),
ggrrooffffwwwwww(7), ggrrooffffttrraaccee(7), mmmmrrooffff(7).
The following utilities are available:
aaddddffttiinnffoo(1), aaffmmttooddiitt(1), eeqqnn22ggrraapphh(1), ggrraapp22ggrraapphh(1),
ggrrooffffeerr(1), ggxxddiittvviieeww(1), hhppffttooddiitt(1), iinnddxxbbiibb(1), llooookkbbiibb(1),
ppffbbttooppss(1), ppiicc22ggrraapphh(1), ttffmmttooddiitt(1).
Groff Version 1.19.1 14 January 2004 GROFF(1)