- NAME
- SYNOPSIS
- ortOpt[] abcegilpstzCEGNRSUVXZ
- ortOpt[] d cs
- ortOpt[] f fam
- ortOpt[] F dir
- ortOpt[] I dir
- ortOpt[] L arg
- ortOpt[] m name
- ortOpt[] M dir
- ortOpt[] n num
- ortOpt[] o list
- ortOpt[] P arg
- ortOpt[] r cn
- ortOpt[] T dev
- ortOpt[] w name
- ortOpt[] W name
- ortOpt h
- ortOpt v
- ortOpt
- DESCRIPTION
- OPTIONS
- ortOpt s
- ortOpt L
- ortOpt X .
- ortOpt N
- ellCommand groff -X -P -title -P 'groff it' I]foo]
- ellCommand groff -X -Z I]foo] | gxditview -title 'groff it' -
- ortOpt S
- ortOpt S .
- ortOpt l
- ortOpt L
- ortOpt X
- ortOpt Tps ,
- ortOpt TX75 ,
- ortOpt TX75-12 ,
- ortOpt TX100 ,
- ortOpt TX100-12 .
- ortOpt Tps
- ortOpt resolution
- ellCommand groff -X -P-resolution -P100 -man foo.1
- USING GROFF
- ortOpt m .
- ortOpt man
- ortOpt m
- ortOpt mandoc
- ortOpt mdoc
- ortOpt me
- ortOpt mm
- ortOpt ms
- ortOpt C
- ortOpt T .
- ENVIRONMENT
- FILES
- EXAMPLES
- ellCommand pic foo.me | tbl | troff -me -Tlatin1 | grotty
- ellCommand groff -p -t -me -T latin1 foo.me
- ellCommand `grog -Tlatin1 foo.me`
- ellCommand groffer foo.me
- BUGS
- AVAILABILITY
- AUTHORS
- SEE ALSO
groff
groff.man
Last update: 14 July 2002
Copyright (C) 1989, 2002 Free Software Foundation, Inc.
Rewritten in 2002 by Bernd Warken <bwarken@mayn.de>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being this .ig-section and AUTHOR, with no
Front-Cover Texts, and with no Back-Cover Texts.
A copy of the Free Documentation License is included as a file called
FDL in the main directory of the groff source package.
A copy of the GNU Free Documentation License is also available in this
Debian package as /usr/share/doc/groff-base/copyright.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
NAME
groff - front-end for the groff document formatting system
.
.
SYNOPSIS
.
ortOpt[] abcegilpstzCEGNRSUVXZ
ortOpt[] d cs
ortOpt[] f fam
ortOpt[] F dir
ortOpt[] I dir
ortOpt[] L arg
ortOpt[] m name
ortOpt[] M dir
ortOpt[] n num
ortOpt[] o list
ortOpt[] P arg
ortOpt[] r cn
ortOpt[] T dev
ortOpt[] w name
ortOpt[] W name
[file
.
ortOpt h
|
.
ortOpt v
|
[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
ortOpt
(minus character).
.
A filename of
ortOpt
(minus character) denotes the standard input.
.
.
DESCRIPTION
.
This document describes the
groff
program, the main front-end for the
groff
document formatting system.
.
The
groff
program and macro suite is the implementation of a
roff(7)
system within the free software collection
"GNU".
.
The
groff
system has all features of the classical
R roff ,
but adds many extensions.
.
The
groff
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).
.
.
OPTIONS
.
As
groff
is a wrapper program for
troff
both programs share a set of options.
.
But the
groff
program has some additional, native options and gives a new meaning to
some
troff
options.
.
On the other hand, not all
troff
options can be fed into
R groff .
.
.
Native groff Options
. The following options either do not exist for troff or are differently interpreted by R groff . . . Preprocess with R eqn . . . Preprocess with R grn . . . Preprocess with R grap . . . Print a help message. . . Add search directory for soelim(1). This option implies theortOpt s
option.
.
.
Send the output to a spooler program for printing.
.
The command that should be used for this is specified by the
print
command in the device description file, see
groff_font(5).
If this command is not present, the output is piped into the
lpr(1)
program by default.
.
See options
ortOpt L
and
ortOpt X .
.
.
Pass
arg
to the spooler program.
Several arguments should be passed with a separate
ortOpt L
option each.
.
Note that
groff
does not prepend
(a minus sign) to
arg
before passing it to the spooler program.
.
.
Don't allow newlines within
eqn
delimiters.
.
This is the same as the
ortOpt N
option in
R eqn .
.
.
Preprocess with
R pic .
.
.
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
ellCommand groff -X -P -title -P 'groff it' I]foo]
is equivalent to
ellCommand groff -X -Z I]foo] | gxditview -title 'groff it' -
.
.
Preprocess with
R refer .
.
No mechanism is provided for passing arguments to
refer
because most
refer
options have equivalent language elements that can be specified within
the document.
.
See
refer(1)
for more details.
.
.
Preprocess with
R soelim .
.
.
Safer mode.
.
Pass the
ortOpt S
option to
pic
and disable the following
troff
requests:
R .open ,
R .opena ,
R .pso ,
R .sy ,
and
R .pi .
For security reasons, safer mode is enabled by default.
.
.
Preprocess with
R tbl .
.
.
Set output device to
R dev .
The possible values in
groff
are
R ascii ,
R cp1047 ,
R dvi ,
R html ,
R latin1 ,
R lbp ,
R lj4 ,
R ps ,
R utf8 ,
R X75 ,
and
R X100 .
.
Additionally,
X75-12
and
X100-12
are available for documents which use 12pt as the base document size.
.
The default device is
R ps .
.
.
Unsafe mode.
.
Reverts to the (old) unsafe behaviour; see option
ortOpt S .
.
.
Output version information of
groff
and of all programs that are run by it; that is, the given command line
is parsed in the usual way, passing
ortOpt v
to all subprograms.
.
.
Output the pipeline that would be run by
R groff
(as a wrapper program), but do not execute it.
.
.
Use
gxditview
instead of using the usual postprocessor to (pre)view a document.
.
The printing spooler behavior as outlined with options
ortOpt l
and
ortOpt L
is carried over to
gxditview(1)
by determining an argument for the
-printCommand
option of
gxditview(1).
.
This sets the default
Print
action and the corresponding menu entry to that value.
.
ortOpt X
only produces good results with
ortOpt Tps ,
ortOpt TX75 ,
ortOpt TX75-12 ,
ortOpt TX100 ,
and
ortOpt TX100-12 .
.
The default resolution for previewing
ortOpt Tps
output is 75dpi; this can be changed by passing the
ortOpt resolution
option to
R gxditview ,
for example
.
ellCommand groff -X -P-resolution -P100 -man foo.1
.
.
Suppress output generated by
R troff .
Only error messages will be printed.
.
.
Do not postprocess the output of
troff
that is normally
called automatically by
R groff .
This will print the intermediate output to standard output; see
groff_out(5).
.
.
Transparent Options
. The following options are transparently handed over to the formatter program troff that is called by groff subsequently. . These options are described in more detail in troff(1). . ascii approximation of output. . backtrace on error or warning. . disable color output. . enable compatibility mode. . define string. . disable troff error messages. . set default font family. . set path for font DESC files. . process standard input after the specified input files. . include macro file I]name]B].tmac] (or B]tmac.]I]name]); see also groff_tmac(5). . path for macro files. . number the first page R num . . output only pages in R list . . set number register. . enable warning R name . . disable warning R name . . .USING GROFF
.
The
groff system
implements the infrastructure of classical roff; see
roff(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
R classical roff .
.
This section gives an overview of the parts that constitute the groff
system.
.
It complements
roff(7)
with groff-specific features.
.
This section can be regarded as a guide to the documentation around
the groff system.
.
.
Front-ends
. The groff program is a wrapper around the troff(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 roff(7) can be avoided. .The
grog(1)
program can be used for guessing the correct groff command line to
format a file.
.
The
groffer(1)
program is an allround-viewer for groff files and man pages.
.
.
Preprocessors
. The groff preprocessors are reimplementations of the classical preprocessors with moderate extensions. . The preprocessors distributed with the groff package are .eqn(1)
for mathematical formul,
pic(1)
for drawing diagrams,
refer(1)
for bibliographic references,
soelim(1)
for including macro files from standard locations,
.
and
tbl(1)
for tables.
.
Besides these, there are some internal preprocessors that are
automatically run with some devices.
.
These aren't visible to the user.
.
.
Macro Packages
. Macro packages can be included by optionortOpt m .
.
The groff system implements and extends all classical macro packages
in a compatible way and adds some packages of its own.
.
Actually, the following macro packages come with
R groff :
.
man
The traditional man page format; see
groff_man(7).
It can be specified on the command line as
ortOpt man
or
ortOpt m
R man .
.
mandoc
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 specified on the command line as
ortOpt mandoc
or
ortOpt m
R mandoc .
.
mdoc
The BSD-style man page format; see
groff_mdoc(7).
It can be specified on the command line as
ortOpt mdoc
or
ortOpt m
R mdoc .
.
me
The classical
me
document format; see
groff_me(7).
It can be specified on the command line as
ortOpt me
or
ortOpt m
R me .
.
mm
The classical
mm
document format; see
groff_mm(7).
It can be specified on the command line as
ortOpt mm
or
ortOpt m
R mm .
.
ms
The classical
ms
document format; see
groff_ms(7).
It can be specified on the command line as
ortOpt ms
or
ortOpt m
R ms .
.
www
HTML-like macros for inclusion in arbitrary groff documents; see
groff_www(7).
.
Details on the naming of macro files and their placement can be found
in
groff_tmac(5).
.
.
Programming Language
. General concepts common to all roff programming languages are described in roff(7). .The groff extensions to the classical troff language are documented in
groff_diff(7).
.
The groff language as a whole is described in the (still incomplete)
R groff info file ;
a short (but complete) reference can be found in
groff(7).
.
.
Formatters
. The central roff formatter within the groff system is troff(1). It provides the features of both the classical troff and nroff, as well as the groff extensions. . The command line optionortOpt C
switches
troff
into
compatibility mode
which tries to emulate classical roff as much as possible.
.
There is a shell script
nroff(1)
that emulates the behavior of classical nroff.
.
It tries to automatically select the proper output encoding, according to
the current locale.
.
The formatter program generates
R intermediate output ;
see
groff_out(7).
.
.
Devices
. In roff, the output targets are called R devices . A device can be a piece of hardware, e.g. a printer, or a software file format. . A device is specified by the optionortOpt T .
The groff devices are as follows.
.
ascii
Text output using the
ascii(7)
character set.
.
cp1047
Text output using the EBCDIC code page IBM cp1047 (e.g. OS/390 Unix).
.
nippon
Text output using the Japanese-EUC character set.
.
dvi
TeX DVI format.
.
html
HTML output.
.
ascii8
For typewriter-like devices. Unlike
R ascii ,
this device is 8 bit clean. This device is intended to be used
for codesets other than ASCII and ISO-8859-1.
latin1
Text output using the ISO Latin-1 (ISO 8859-1) character set; see
iso_8859_1(7).
.
lbp
Output for Canon CAPSL printers (LBP-4 and LBP-8 series laser printers).
.
lj4
HP LaserJet4-compatible (or other PCL5-compatible) printers.
.
ps
PostScript output; suitable for printers and previewers like
gv(1).
.
utf8
Text output using the Unicode (ISO 10646) character set with UTF-8
encoding; see
unicode(7).
.
X75
75dpi X Window System output suitable for the previewers
R xditview (1x)
and
gxditview(1).
A variant for a 12pt document base font is
R X75-12 .
.
X100
100dpi X Window System output suitable for the previewers
R xditview (1x)
and
gxditview(1).
A variant for a 12pt document base font is
R X100-12 .
.
The postprocessor to be used for a device is specified by the
postpro
command in the device description file; see
groff_font(5).
.
This can be overridden with the
-X
option.
.
grolbp(1)
for some Canon printers,
grolj4(1)
for printers compatible to the HP LaserJet\~4 and PCL5,
grotty(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
formats are
.
grodvi(1)
for the DVI format,
grohtml(1)
for HTML format,
grops(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.
.
.
Utilities
. The following utility programs around groff are available. .addftinfo(1)
Add information to troff font description files for use with groff.
.
afmtodit(1)
Create font description files for PostScript device.
.
groffer(1)
General viewer program for groff files and man pages.
.
gxditview(1)
The groff X viewer, the GNU version of xditview.
.
hpftodit(1)
Create font description files for lj4 device.
.
indxbib(1)
Make inverted index for bibliographic databases.
.
lkbib(1)
Search bibliographic databases.
.
lookbib(1)
Interactively search bibliographic databases.
.
pfbtops(1)
Translate a PostScript font in .pfb format to ASCII.
.
tfmtodit(1)
Create font description files for TeX DVI device.
.
R xditview (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 example, DOS and Windows use a semicolon instead.
.
This search path, followed by
will be used for commands that are executed by
R groff .
.
If it is not set then the directory where the groff binaries were
installed is prepended to
.
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
R g ,
but it can be anything.
.
For example,
R gtroff
stood for
R groff 's
R troff ,
R gtbl
for the
groff
version of
R tbl .
.
By setting
to different values, the different roff installations can be
addressed.
.
More exactly, if it is set to prefix
xxx
then
groff
as a wrapper program will internally call
B xxx troff
instead of
R troff .
This also applies to the preprocessors
R eqn ,
R grn ,
R pic ,
R refer ,
R tbl ,
R soelim ,
and to the utilities
indxbib
and
R lookbib .
.
This feature does not apply to any programs different from the ones
above (most notably
groff
itself) since they are unique to the groff package.
.
.
A list of directories in which to search for the
I dev name
directory in addition to the default ones.
.
See
troff(1)
and
groff_font(5)
for more details.
.
.
A list of directories in which to search for macro files in addition to
the default directories.
.
See
troff(1)
and
groff_tmac(5)
for more details.
.
.
The directory in which temporary files will be created.
.
If this is not set but the environment variable
instead, temporary files will be created in the directory
.
Otherwise temporary files will be created in
R /tmp .
The
refer(1),
groffer(1),
grohtml(1),
and
grops(1)
commands use temporary files.
.
.
Preset the default device.
.
If this is not set the
ps
device is used as default.
.
This device name is overwritten by the option
ortOpt T .
.
.
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.
.
.
groff Macro Directory
. This contains all information related to macro packages. . Note that more than a single directory is searched for those files as documented in groff_tmac(5). . For the groff installation corresponding to this document, it is located at R /usr/share/groff/1.18.1/tmac . . The following files contained in the groff macro directory have a special meaning: . .troffrc
Initialization file for troff.
.
This is interpreted by
troff
before reading the macro sets and any input.
.
.
troffrc-end
Final startup file for troff, it is parsed after all macro sets have
been read.
.
.
B name .tmac
I tmac. name
Macro file for macro package
R name .
.
.
groff Font Directory
. This contains all information related to output devices. . Note that more than a single directory is searched for those files; see troff(1). . For the groff installation corresponding to this document, it is located at R /usr/share/groff/1.18.1/font . . The following files contained in the groff font directory have a special meaning: . .I dev name /DESC
Device description file for device
R name ,
see
groff_font(5).
.
.
I dev name / F
Font file for font
F
of device
R name .
.
.
EXAMPLES
.
The following example illustrates the power of the
groff
program as a wrapper around
R troff .
.
To process a roff file using the preprocessors
tbl
and
pic
and the
me
macro set, classical troff had to be called by
.
ellCommand pic foo.me | tbl | troff -me -Tlatin1 | grotty
.
Using
R groff ,
this pipe can be shortened to the equivalent command
ellCommand groff -p -t -me -T latin1 foo.me
.
An even easier way to call this is to use
grog(1)
to guess the preprocessor and macro options and execute the generated
command (by specifying shell left quotes)
ellCommand `grog -Tlatin1 foo.me`
.
The simplest way is to view the contents in an automated way by
calling
.
ellCommand groffer foo.me
.
.
BUGS
.
On EBCDIC hosts (e.g. OS/390 Unix), output devices
ascii
and
latin1
aren't available.
.
Similarly, output for EBCDIC code page
cp1047
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
The most recent released version of groff is available for anonymous
ftp at the
\
"groff development site" .
.
Three groff mailing lists are available:
for reporting bugs,
.
for general discussion of groff,
.
a read-only list showing logs of commitments to the CVS repository.
.
Details on CVS access and much more can be found in the file
README
at the top directory of the groff source package.
.
There is a free implementation of the
grap
preprocessor, written by
.
The actual version can be found at the
.
\
"grap website" .
This is the only grap version supported by groff.
.
.
AUTHORS
.
Copyright 1989, 2002 Free Software Foundation, Inc.
.
This document is distributed under the terms of the FDL (GNU Free
Documentation 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
.
This document is based on the original groff man page written by
.
It was rewritten, enhanced, and put under the FDL license by
.
It is maintained by
.
groff
is a GNU free software project.
.
All parts of the
groff package
are protected by GNU copyleft licenses.
.
The software files are distributed 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
R 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
info(1)
on how to read it.
.
Due to its complex structure, the groff system has many man pages.
.
They can be read with
man(1)
or
groffer(1).
.
Introduction, history and further readings:
roff(7).
.
Roff language with the groff extensions:
The intermediate output language:
groff_out(7).
.
Postprocessors for the output devices:
Groff macro packages and macro-specific utilities:
groff_tmac(5),
groff_man(7),
groff_mdoc(7),
groff_me(7),
groff_mm(7),
groff_mmse(7),
groff_mom(7),
groff_ms(7),
groff_www(7),
mmroff(7).
.
ČLÁNKY DO MAILU