\input texinfo   @c -*-texinfo-*-

@c
@c Please convert this manual with `texi2dvi -e groff.texinfo' due to
@c problems in texinfo regarding expansion of user-defined macros.
@c
@c You need texinfo 4.6 or newer to format this document!
@c

@c %**start of header (This is for running Texinfo on a region.)
@setfilename groff
@settitle The GNU Troff Manual
@setchapternewpage odd
@footnotestyle separate
@c %**end of header (This is for running Texinfo on a region.)

@documentlanguage en
@documentencoding ISO-8859-1


@smallbook

@finalout


@copying
This manual documents GNU @code{troff} version 1.19.2.

Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005
Free Software Foundation, Inc.

@quotation
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 no
Invariant Sections, with the Front-Cover texts being `A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled `GNU Free Documentation
License.''

(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying


@c We use the following indices:
@c
@c   cindex: concepts
@c   rqindex: requests
@c   esindex: escapes
@c   vindex: registers
@c   kindex: commands in font files
@c   pindex: programs and files
@c   tindex: environment variables
@c   maindex: macros
@c   stindex: strings
@c   opindex: operators
@c
@c tindex and cindex are merged.

@defcodeindex rq
@defcodeindex es
@defcodeindex ma
@defcodeindex st
@defcodeindex op
@syncodeindex tp cp


@c To avoid uppercasing in @deffn while converting to info, we define
@c our special @Var{}.

@macro Var{arg}
@r{@slanted{\arg\}}
@end macro


@c To assure correct HTML translation, some ugly hacks are necessary.
@c While processing a @def... request, the HTML translator looks at the
@c next line to decide whether it should start indentation or not.  If
@c it is something starting with @def... (e.g. @deffnx), it doesn't.
@c So we must assure during macro expansion that a @def... is seen.
@c
@c The following macros have to be used:
@c
@c One item:
@c
@c   @Def...
@c
@c Two items:
@c
@c   @Def...List
@c   @Def...ListEnd
@c
@c More than two:
@c
@c   @Def...List
@c   @Def...Item
@c   @Def...Item
@c   ...
@c   @Def...ListEnd
@c
@c The definition block must end with
@c
@c   @endDef...
@c
@c The above is valid for texinfo 4.0f and above.


@c a dummy macro to assure the `@def...'

@macro defdummy
@c
@end macro


@c definition of requests

@macro Defreq{name, arg}
@deffn Request @t{.\name\} \arg\
@rqindex \name\
@c
@end macro

@macro DefreqList{name, arg}
@deffn Request @t{.\name\} \arg\
@defdummy
@rqindex \name\
@c
@end macro

@macro DefreqItem{name, arg}
@deffnx Request @t{.\name\} \arg\
@defdummy
@rqindex \name\
@c
@end macro

@macro DefreqListEnd{name, arg}
@deffnx Request @t{.\name\} \arg\
@rqindex \name\
@c
@end macro

@macro endDefreq
@end deffn
@end macro


@c definition of escapes

@macro Defesc{name, delimI, arg, delimII}
@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
@esindex \name\
@c
@end macro

@macro DefescList{name, delimI, arg, delimII}
@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
@defdummy
@esindex \name\
@c
@end macro

@macro DefescItem{name, delimI, arg, delimII}
@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
@defdummy
@esindex \name\
@c
@end macro

@macro DefescListEnd{name, delimI, arg, delimII}
@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
@esindex \name\
@c
@end macro

@macro endDefesc
@end deffn
@end macro


@c definition of registers

@macro Defreg{name}
@deffn Register @t{\\n[\name\]}
@vindex \name\
@c
@end macro

@macro DefregList{name}
@deffn Register @t{\\n[\name\]}
@defdummy
@vindex \name\
@c
@end macro

@macro DefregItem{name}
@deffnx Register @t{\\n[\name\]}
@defdummy
@vindex \name\
@c
@end macro

@macro DefregListEnd{name}
@deffnx Register @t{\\n[\name\]}
@vindex \name\
@c
@end macro

@macro endDefreg
@end deffn
@end macro


@c definition of registers specific to macro packages, preprocessors, etc.

@macro Defmpreg{name, package}
@deffn Register @t{\\n[\name\]}
@vindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefmpregList{name, package}
@deffn Register @t{\\n[\name\]}
@defdummy
@vindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefmpregItem{name, package}
@deffnx Register @t{\\n[\name\]}
@defdummy
@vindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefmpregListEnd{name, package}
@deffnx Register @t{\\n[\name\]}
@vindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro endDefmpreg
@end deffn
@end macro


@c definition of macros

@macro Defmac{name, arg, package}
@defmac @t{.\name\} \arg\
@maindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefmacList{name, arg, package}
@defmac @t{.\name\} \arg\
@defdummy
@maindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefmacItem{name, arg, package}
@defmacx @t{.\name\} \arg\
@defdummy
@maindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefmacListEnd{name, arg, package}
@defmacx @t{.\name\} \arg\
@maindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro endDefmac
@end defmac
@end macro


@c definition of strings

@macro Defstr{name, package}
@deffn String @t{\\*[\name\]}
@stindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefstrList{name, package}
@deffn String @t{\\*[\name\]}
@defdummy
@stindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefstrItem{name, package}
@deffnx String @t{\\*[\name\]}
@defdummy
@stindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro DefstrListEnd{name, package}
@deffnx String @t{\\*[\name\]}
@stindex \name\ @r{[}\package\@r{]}
@c
@end macro

@macro endDefstr
@end deffn
@end macro


@c our example macro

@macro Example
@example
@group
@end macro

@macro endExample
@end group
@end example
@end macro


@c <text>

@tex
\gdef\Langlemacro{\angleleft}
\gdef\Ranglemacro{\angleright}
@end tex

@iftex
@set Langlemacro @Langlemacro
@set Ranglemacro @Ranglemacro
@end iftex

@ifnottex
@set Langlemacro <
@set Ranglemacro >
@end ifnottex

@macro angles{text}
@value{Langlemacro}@r{\text\}@value{Ranglemacro}
@end macro


@c a <= sign
@c
@c A value defined with @set is embedded into three group levels if
@c called with @value, so we need seven \aftergroup to put \le outside
@c of the groups -- this is necessary to get proper mathematical spacing.

@tex
\gdef\LEmacro{\aftergroup\aftergroup\aftergroup\aftergroup
              \aftergroup\aftergroup\aftergroup\le}
@end tex

@iftex
@set LEmacro @LEmacro
@end iftex

@ifnottex
@set LEmacro <=
@end ifnottex

@macro LE
@value{LEmacro}
@end macro


@c We need special parentheses, brackets, and braces:
@c
@c . Real parentheses in @deffn produce an error while compiling with
@c   TeX.
@c . Real brackets use the wrong font in @deffn, overriding @t{}.
@c
@c . @{ and @} fail with info if used in a macro.
@c
@c Since macros aren't expanded in @deffn during -E, the following
@c definitions are for non-TeX only.
@c
@c This is true for texinfo 4.0 and above.

@iftex
@set Lparenmacro @lparen
@set Rparenmacro @rparen
@set Lbrackmacro @lbrack
@set Rbrackmacro @rbrack
@set Lbracemacro @{
@set Rbracemacro @}
@end iftex

@ifnottex
@set Lparenmacro (
@set Rparenmacro )
@set Lbrackmacro [
@set Rbrackmacro ]
@set Lbracemacro @{
@set Rbracemacro @}
@end ifnottex

@macro Lparen{}
@value{Lparenmacro}
@end macro
@macro Rparen{}
@value{Rparenmacro}
@end macro
@macro Lbrack{}
@value{Lbrackmacro}
@end macro
@macro Rbrack{}
@value{Rbrackmacro}
@end macro
@macro Lbrace{}
@value{Lbracemacro}
@end macro
@macro Rbrace{}
@value{Rbracemacro}
@end macro


@c This suppresses the word `Appendix' in the appendix headers.

@tex
\gdef\gobblefirst#1#2{#2}
\gdef\putwordAppendix{\gobblefirst}
@end tex


@c We map some latin-1 characters to corresponding texinfo macros.

@tex
\global\catcode`^^e4\active % ä
\gdef^^e4{\"a}
\global\catcode`^^c4\active % Ä
\gdef^^c4{\"A}
\global\catcode`^^e9\active % é
\gdef^^e9{\'e}
\global\catcode`^^c9\active % É
\gdef^^c9{\'E}
\global\catcode`^^f6\active % ö
\gdef^^f6{\"o}
\global\catcode`^^d6\active % Ö
\gdef^^d6{\"O}
\global\catcode`^^fc\active % ü
\gdef^^fc{\"u}
\global\catcode`^^dc\active % Ü
\gdef^^dc{\"U}
\global\catcode`^^e6\active % ć
\gdef^^e6{\ae}
\global\catcode`^^c6\active % Ć
\gdef^^c6{\AE}
\global\catcode`^^df\active % ß
\gdef^^df{\ss}
@end tex


@c Note: We say `Roman numerals' but `roman font'.


@dircategory Typesetting
@direntry
* Groff: (groff).               The GNU troff document formatting system.
@end direntry


@titlepage
@title groff
@subtitle The GNU implementation of @code{troff}
@subtitle Edition 1.19.2
@subtitle Summer 2005
@author by Trent A.@tie{}Fisher
@author and Werner Lemberg (@email{bug-groff@@gnu.org})

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@contents

@ifinfo
@node Top, Introduction, (dir), (dir)
@top GNU troff

@insertcopying
@end ifinfo

@ifhtml
@menu
* Introduction::
* Invoking groff::
* Tutorial for Macro Users::
* Macro Packages::
* gtroff Reference::
* Preprocessors::
* Output Devices::
* File formats::
* Installation::
* Copying This Manual::
* Request Index::
* Escape Index::
* Operator Index::
* Register Index::
* Macro Index::
* String Index::
* Glyph Name Index::
* Font File Keyword Index::
* Program and File Index::
* Concept Index::
@end menu

@node Top, Introduction, (dir), (dir)
@top GNU troff

@insertcopying
@end ifhtml

@menu
* Introduction::
* Invoking groff::
* Tutorial for Macro Users::
* Macro Packages::
* gtroff Reference::
* Preprocessors::
* Output Devices::
* File formats::
* Installation::
* Copying This Manual::
* Request Index::
* Escape Index::
* Operator Index::
* Register Index::
* Macro Index::
* String Index::
* Glyph Name Index::
* Font File Keyword Index::
* Program and File Index::
* Concept Index::
@end menu



@c =====================================================================
@c =====================================================================

@node Introduction, Invoking groff, Top, Top
@chapter Introduction
@cindex introduction

GNU @code{troff} (or @code{groff}) is a system for typesetting
documents.  @code{troff} is very flexible and has been in existence (and
use) for about 3@tie{}decades.  It is quite widespread and firmly
entrenched in the @acronym{UNIX} community.

@menu
* What Is groff?::
* History::
* groff Capabilities::
* Macro Package Intro::
* Preprocessor Intro::
* Output device intro::
* Credits::
@end menu


@c =====================================================================

@node What Is groff?, History, Introduction, Introduction
@section What Is @code{groff}?
@cindex what is @code{groff}?
@cindex @code{groff} -- what is it?

@code{groff} belongs to an older generation of document preparation
systems, which operate more like compilers than the more recent
interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
systems.  @code{groff} and its contemporary counterpart, @TeX{}, both
work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
normal text files with embedded formatting commands.  These files can
then be processed by @code{groff} to produce a typeset document on a
variety of devices.

Likewise, @code{groff} should not be confused with a @dfn{word
processor}, since that term connotes an integrated system that includes
an editor and a text formatter.  Also, many word processors follow the
@acronym{WYSIWYG} paradigm discussed earlier.

Although @acronym{WYSIWYG} systems may be easier to use, they have a
number of disadvantages compared to @code{troff}:

@itemize @bullet
@item
They must be used on a graphics display to work on a document.

@item
Most of the @acronym{WYSIWYG} systems are either non-free or are not
very portable.

@item
@code{troff} is firmly entrenched in all @acronym{UNIX} systems.

@item
It is difficult to have a wide range of capabilities available within
the confines of a GUI/window system.

@item
It is more difficult to make global changes to a document.
@end itemize

@quotation
``GUIs normally make it simple to accomplish simple actions and
impossible to accomplish complex actions.''  --Doug Gwyn (22/Jun/91 in
@code{comp.unix.wizards})
@end quotation


@c =====================================================================

@node History, groff Capabilities, What Is groff?, Introduction
@section History
@cindex history

@cindex @code{runoff}, the program
@cindex @code{rf}, the program
@code{troff} can trace its origins back to a formatting program called
@code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS
operating system in the mid-sixties.  This name came from the common
phrase of the time ``I'll run off a document.''  Bob Morris ported it to
the 635 architecture and called the program @code{roff} (an abbreviation
of @code{runoff}).  It was rewritten as @code{rf} for the @w{PDP-7}
(before having @acronym{UNIX}), and at the same time (1969), Doug
McIllroy rewrote an extended and simplified version of @code{roff} in
the @acronym{BCPL} programming language.

@cindex @code{roff}, the program
The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
was sitting around Bell Labs.  In 1971 the developers wanted to get a
@w{PDP-11} for further work on the operating system.  In order to
justify the cost for this system, they proposed that they would
implement a document formatting system for the @acronym{AT&T} patents
division.  This first formatting program was a reimplementation of
McIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna.

@cindex @code{nroff}, the program
When they needed a more flexible language, a new version of @code{roff}
called @code{nroff} (``Newer @code{roff}'') was written.  It had a much
more complicated syntax, but provided the basis for all future versions.
When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
version of @code{nroff} that would drive it.  It was dubbed
@code{troff}, for ``typesetter @code{roff}'', although many people have
speculated that it actually means ``Times @code{roff}'' because of the
use of the Times font family in @code{troff} by default.  As such, the
name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.

With @code{troff} came @code{nroff} (they were actually the same program
except for some @samp{#ifdef}s), which was for producing output for line
printers and character terminals.  It understood everything @code{troff}
did, and ignored the commands which were not applicable (e.g.@: font
changes).

Since there are several things which cannot be done easily in
@code{troff}, work on several preprocessors began.  These programs would
transform certain parts of a document into @code{troff}, which made a
very natural use of pipes in @acronym{UNIX}.

The @code{eqn} preprocessor allowed mathematical formulć to be
specified in a much simpler and more intuitive manner.  @code{tbl} is a
preprocessor for formatting tables.  The @code{refer} preprocessor (and
the similar program, @code{bib}) processes citations in a document
according to a bibliographic database.

Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
language and produced output specifically for the CAT phototypesetter.
He rewrote it in C, although it was now 7000@tie{}lines of uncommented
code and still dependent on the CAT.  As the CAT became less common, and
was no longer supported by the manufacturer, the need to make it support
other devices became a priority.  However, before this could be done,
Ossanna was killed in a car accident.

@pindex ditroff
@cindex @code{ditroff}, the program
So, Brian Kernighan took on the task of rewriting @code{troff}.  The
newly rewritten version produced device independent code which was
very easy for postprocessors to read and translate to the appropriate
printer codes.  Also, this new version of @code{troff} (called
@code{ditroff} for ``device independent @code{troff}'') had several
extensions, which included drawing functions.

Due to the additional abilities of the new version of @code{troff},
several new preprocessors appeared.  The @code{pic} preprocessor
provides a wide range of drawing functions.  Likewise the @code{ideal}
preprocessor did the same, although via a much different paradigm.  The
@code{grap} preprocessor took specifications for graphs, but, unlike
other preprocessors, produced @code{pic} code.

James Clark began work on a GNU implementation of @code{ditroff} in
early@tie{}1989.  The first version, @code{groff}@tie{}0.3.1, was released
June@tie{}1990.  @code{groff} included:

@itemize @bullet
@item
A replacement for @code{ditroff} with many extensions.

@item
The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.

@item
Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
X@tie{}Windows.  GNU @code{troff} also eliminated the need for a
separate @code{nroff} program with a postprocessor which would produce
@acronym{ASCII} output.

@item
A version of the @file{me} macros and an implementation of the
@file{man} macros.
@end itemize

Also, a front-end was included which could construct the, sometimes
painfully long, pipelines required for all the post- and preprocessors.

Development of GNU @code{troff} progressed rapidly, and saw the
additions of a replacement for @code{refer}, an implementation of the
@file{ms} and @file{mm} macros, and a program to deduce how to format a
document (@code{grog}).

It was declared a stable (i.e.@: non-beta) package with the release of
version@tie{}1.04 around November@tie{}1991.

Beginning in@tie{}1999, @code{groff} has new maintainers (the package was
an orphan for a few years).  As a result, new features and programs like
@code{grn}, a preprocessor for gremlin images, and an output device to
produce @acronym{HTML} output have been added.


@c =====================================================================

@node groff Capabilities, Macro Package Intro, History, Introduction
@section @code{groff} Capabilities
@cindex @code{groff} capabilities
@cindex capabilities of @code{groff}

So what exactly is @code{groff} capable of doing?  @code{groff} provides
a wide range of low-level text formatting operations.  Using these, it
is possible to perform a wide range of formatting tasks, such as
footnotes, table of contents, multiple columns, etc.  Here's a list of
the most important operations supported by @code{groff}:

@itemize @bullet
@item
text filling, adjusting, and centering

@item
hyphenation

@item
page control

@item
font and glyph size control

@item
vertical spacing (e.g.@: double-spacing)

@item
line length and indenting

@item
macros, strings, diversions, and traps

@item
number registers

@item
tabs, leaders, and fields

@item
input and output conventions and character translation

@item
overstrike, bracket, line drawing, and zero-width functions

@item
local horizontal and vertical motions and the width function

@item
three-part titles

@item
output line numbering

@item
conditional acceptance of input

@item
environment switching

@item
insertions from the standard input

@item
input/output file switching

@item
output and error messages
@end itemize


@c =====================================================================

@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
@section Macro Packages
@cindex macro packages

Since @code{groff} provides such low-level facilities, it can be quite
difficult to use by itself.  However, @code{groff} provides a
@dfn{macro} facility to specify how certain routine operations
(e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@:
should be done.  These macros can be collected together into a @dfn{macro
package}.  There are a number of macro packages available; the most
common (and the ones described in this manual) are @file{man},
@file{mdoc}, @file{me}, @file{ms}, and @file{mm}.


@c =====================================================================

@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
@section Preprocessors
@cindex preprocessors

Although @code{groff} provides most functions needed to format a
document, some operations would be unwieldy (e.g.@: to draw pictures).
Therefore, programs called @dfn{preprocessors} were written which
understand their own language and produce the necessary @code{groff}
operations.  These preprocessors are able to differentiate their own
input from the rest of the document via markers.

To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
from the preprocessor into @code{groff}.  Any number of preprocessors
may be used on a given document; in this case, the preprocessors are
linked together into one pipeline.  However, with @code{groff}, the user
does not need to construct the pipe, but only tell @code{groff} what
preprocessors to use.

@code{groff} currently has preprocessors for producing tables
(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
(@code{pic} and @code{grn}), and for processing bibliographies
(@code{refer}).  An associated program which is useful when dealing with
preprocessors is @code{soelim}.

A free implementation of @code{grap}, a preprocessor for drawing graphs,
can be obtained as an extra package; @code{groff} can use @code{grap}
also.

There are other preprocessors in existence, but, unfortunately, no free
implementations are available.  Among them are preprocessors for drawing
mathematical pictures (@code{ideal}) and chemical structures
(@code{chem}).


@c =====================================================================

@node Output device intro, Credits, Preprocessor Intro, Introduction
@section Output Devices
@cindex postprocessors
@cindex output devices
@cindex devices for output

@code{groff} actually produces device independent code which may be
fed into a postprocessor to produce output for a particular device.
Currently, @code{groff} has postprocessors for @sc{PostScript}
devices, character terminals, X@tie{}Windows (for previewing), @TeX{}
DVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use
@acronym{CAPSL}), and @acronym{HTML}.


@c =====================================================================

@node Credits,  , Output device intro, Introduction
@section Credits
@cindex credits

Large portions of this manual were taken from existing documents, most
notably, the manual pages for the @code{groff} package by James Clark,
and Eric Allman's papers on the @file{me} macro package.

The section on the @file{man} macro package is partly based on
Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the
Debian GNU/Linux system.

Larry Kollar contributed the section in the @file{ms} macro package.



@c =====================================================================
@c =====================================================================

@node Invoking groff, Tutorial for Macro Users, Introduction, Top
@chapter Invoking @code{groff}
@cindex invoking @code{groff}
@cindex @code{groff} invocation

This section focuses on how to invoke the @code{groff} front end.  This
front end takes care of the details of constructing the pipeline among
the preprocessors, @code{gtroff} and the postprocessor.

It has become a tradition that GNU programs get the prefix @samp{g} to
distinguish it from its original counterparts provided by the host (see
@ref{Environment}, for more details).  Thus, for example, @code{geqn} is
GNU @code{eqn}.  On operating systems like GNU/Linux or the Hurd, which
don't contain proprietary versions of @code{troff}, and on
MS-DOS/MS-Windows, where @code{troff} and associated programs are not
available at all, this prefix is omitted since GNU @code{troff} is the
only used incarnation of @code{troff}.  Exception: @samp{groff} is never
replaced by @samp{roff}.

In this document, we consequently say @samp{gtroff} when talking about
the GNU @code{troff} program.  All other implementations of @code{troff}
are called @acronym{AT&T} @code{troff} which is the common origin of
all @code{troff} derivates (with more or less compatible changes).
Similarly, we say @samp{gpic}, @samp{geqn}, etc.

@menu
* Groff Options::
* Environment::
* Macro Directories::
* Font Directories::
* Paper Size::
* Invocation Examples::
@end menu


@c =====================================================================

@node Groff Options, Environment, Invoking groff, Invoking groff
@section Options
@cindex options

@pindex groff
@pindex gtroff
@pindex gpic
@pindex geqn
@pindex ggrn
@pindex grap
@pindex gtbl
@pindex grefer
@pindex gsoelim
@code{groff} normally runs the @code{gtroff} program and a postprocessor
appropriate for the selected device.  The default device is @samp{ps}
(but it can be changed when @code{groff} is configured and built).  It
can optionally preprocess with any of @code{gpic}, @code{geqn},
@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.

This section only documents options to the @code{groff} front end.  Many
of the arguments to @code{groff} are passed on to @code{gtroff},
therefore those are also included.  Arguments to pre- or postprocessors
can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
grolbp}, and @ref{Invoking gxditview}.

The command line format for @code{groff} is:

@Example
groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
      [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
      [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
      [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
      [ @var{files}@dots{} ]
@endExample

The command line format for @code{gtroff} is as follows.

@Example
gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
       [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
       [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
       [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
@endExample

@noindent
Obviously, many of the options to @code{groff} are actually passed on to
@code{gtroff}.

Options without an argument can be grouped behind a single@tie{}@option{-}.
A filename of@tie{}@file{-} denotes the standard input.  It is possible to
have whitespace between an option and its parameter.

The @code{grog} command can be used to guess the correct @code{groff}
command to format a file.

Here's the description of the command-line options:

@cindex command-line options
@table @samp
@item -h
Print a help message.

@item -e
Preprocess with @code{geqn}.

@item -t
Preprocess with @code{gtbl}.

@item -g
Preprocess with @code{ggrn}.

@item -G
Preprocess with @code{grap}.

@item -p
Preprocess with @code{gpic}.

@item -s
Preprocess with @code{gsoelim}.

@item -c
Suppress color output.

@item -R
Preprocess with @code{grefer}.  No mechanism is provided for passing
arguments to @code{grefer} because most @code{grefer} options have
equivalent commands which can be included in the file.  @xref{grefer},
for more details.

@pindex troffrc
@pindex troffrc-end
Note that @code{gtroff} also accepts a @option{-R} option, which is not
accessible via @code{groff}.  This option prevents the loading of the
@file{troffrc} and @file{troffrc-end} files.

@item -v
Make programs run by @code{groff} print out their version number.

@item -V
Print the pipeline on @code{stdout} instead of executing it.  If specified
more than once, print the pipeline on @code{stderr} and execute it.

@item -z
Suppress output from @code{gtroff}.  Only error messages are printed.

@item -Z
Do not postprocess the output of @code{gtroff}.  Normally @code{groff}
automatically runs the appropriate postprocessor.

@item -P@var{arg}
Pass @var{arg} to the postprocessor.  Each argument should be passed
with a separate @option{-P} option.  Note that @code{groff} does not
prepend @samp{-} to @var{arg} before passing it to the postprocessor.

@item -l
Send the output to a spooler for printing.  The command used for this is
specified by the @code{print} command in the device description file
(see @ref{Font Files}, for more info).  If not present, @option{-l} is
ignored.

@item -L@var{arg}
Pass @var{arg} to the spooler.  Each argument should be passed with a
separate @option{-L} option.  Note that @code{groff} does not prepend
a @samp{-} to @var{arg} before passing it to the postprocessor.
If the @code{print} keyword in the device description file is missing,
@option{-L} is ignored.

@item -T@var{dev}
Prepare output for device @var{dev}.  The default device is @samp{ps},
unless changed when @code{groff} was configured and built.  The
following are the output devices currently available:

@table @code
@item ps
For @sc{PostScript} printers and previewers.

@item dvi
For @TeX{} DVI format.

@item X75
For a 75@dmn{dpi} X11 previewer.

@item X75-12
For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
document.

@item X100
For a 100@dmn{dpi} X11 previewer.

@item X100-12
For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the
document.

@item ascii
@cindex encoding, output, @acronym{ASCII}
@cindex @acronym{ASCII}, output encoding
@cindex output encoding, @acronym{ASCII}
For typewriter-like devices using the (7-bit) @acronym{ASCII}
character set.

@item latin1
@cindex encoding, output, @w{latin-1} (ISO @w{8859-1})
@cindex @w{latin-1} (ISO @w{8859-1}), output encoding
@cindex ISO @w{8859-1} (@w{latin-1}), output encoding
@cindex output encoding, @w{latin-1} (ISO @w{8859-1})
For typewriter-like devices that support the @w{Latin-1}
(ISO@tie{}@w{8859-1}) character set.

@item utf8
@cindex encoding, output, @w{utf-8}
@cindex @w{utf-8}, output encoding
@cindex output encoding, @w{utf-8}
For typewriter-like devices which use the Unicode (ISO@tie{}10646)
character set with @w{UTF-8} encoding.

@item cp1047
@cindex encoding, output, @acronym{EBCDIC}
@cindex @acronym{EBCDIC}, output encoding
@cindex output encoding, @acronym{EBCDIC}
@cindex encoding, output, cp1047
@cindex cp1047, output encoding
@cindex output encoding, cp1047
@cindex IBM cp1047 output encoding
For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
cp1047.

@item lj4
For HP LaserJet4-compatible (or other PCL5-compatible) printers.

@item lbp
For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
printers).

@pindex pre-grohtml
@pindex post-grohtml
@cindex @code{grohtml}, the program
@item html
To produce @acronym{HTML} output.  Note that the @acronym{HTML} driver
consists of two parts, a preprocessor (@code{pre-grohtml}) and a
postprocessor (@code{post-grohtml}).
@end table

@cindex output device name string register (@code{.T})
@cindex output device usage number register (@code{.T})
The predefined @code{gtroff} string register @code{.T} contains the
current output device; the read-only number register @code{.T} is set
to@tie{}1 if this option is used (which is always true if @code{groff} is
used to call @code{gtroff}).  @xref{Built-in Registers}.

The postprocessor to be used for a device is specified by the
@code{postpro} command in the device description file.  (@xref{Font
Files}, for more info.)  This can be overridden with the @option{-X}
option.

@item -X
Preview with @code{gxditview} instead of using the usual postprocessor.
This is unlikely to produce good results except with @option{-Tps}.

Note that this is not the same as using @option{-TX75} or
@option{-TX100} to view a document with @code{gxditview}: The former
uses the metrics of the specified device, whereas the latter uses
X-specific fonts and metrics.

@item -N
Don't allow newlines with @code{eqn} delimiters.  This is the same as
the @option{-N} option in @code{geqn}.

@item -S
@cindex @code{open} request, and safer mode
@cindex @code{opena} request, and safer mode
@cindex @code{pso} request, and safer mode
@cindex @code{sy} request, and safer mode
@cindex @code{pi} request, and safer mode
@cindex safer mode
@cindex mode, safer
Safer mode.  Pass the @option{-S} option to @code{gpic} and disable the
@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
requests.  For security reasons, this is enabled by default.

@item -U
@cindex mode, unsafe
@cindex unsafe mode
Unsafe mode.  This enables the @code{open}, @code{opena}, @code{pso},
@code{sy}, and @code{pi} requests.

@item -a
@cindex @acronym{ASCII} approximation output register (@code{.A})
Generate an @acronym{ASCII} approximation of the typeset output.  The
read-only register @code{.A} is then set to@tie{}1.  @xref{Built-in
Registers}.  A typical example is

@Example
groff -a -man -Tdvi troff.man | less
@endExample

@noindent
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.

@item -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: @code{gtroff} can get
confused by @code{as} or @code{am} requests while counting line numbers.

@item -i
Read the standard input after all the named input files have been
processed.

@item -w@var{name}
Enable warning @var{name}.  Available warnings are described in
@ref{Debugging}.  Multiple @option{-w} options are allowed.

@item -W@var{name}
Inhibit warning @var{name}.  Multiple @option{-W} options are allowed.

@item -E
Inhibit all error messages.

@item -C
Enable compatibility mode.  @xref{Implementation Differences}, for the
list of incompatibilities between @code{groff} and @acronym{AT&T}
@code{troff}.

@item -d@var{c}@var{s}
@itemx -d@var{name}=@var{s}
Define @var{c} or @var{name} to be a string@tie{}@var{s}.  @var{c}@tie{}must
be a one-letter name; @var{name} can be of arbitrary length.  All string
assignments happen before loading any macro file (including the start-up
file).

@item -f@var{fam}
Use @var{fam} as the default font family.  @xref{Font Families}.

@item -m@var{name}
Read in the file @file{@var{name}.tmac}.  Normally @code{groff} searches
for this in its macro directories.  If it isn't found, it tries
@file{tmac.@var{name}} (searching in the same directories).

@item -n@var{num}
Number the first page @var{num}.

@item -o@var{list}
@cindex print current page register (@code{.P})
Output only pages in @var{list}, which is a comma-separated list of page
ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}}
means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}}
means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every
page beginning with@tie{}@var{n}.  @code{gtroff} exits after printing the
last page in the list.  All the ranges are inclusive on both ends.

Within @code{gtroff}, this information can be extracted with the
@samp{.P} register.  @xref{Built-in Registers}.

If your document restarts page numbering at the beginning of each
chapter, then @code{gtroff} prints the specified page range for each
chapter.

@item -r@var{c}@var{n}
@itemx -r@var{name}=@var{n}
Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}.
@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
length.  @var{n}@tie{}can be any @code{gtroff} numeric expression.  All
register assignments happen before loading any macro file (including
the start-up file).

@item -F@var{dir}
Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
(@var{name} is the name of the device), for the @file{DESC} file, and
for font files before looking in the standard directories (@pxref{Font
Directories}).  This option is passed to all pre- and postprocessors
using the @env{GROFF_FONT_PATH} environment variable.

@item -M@var{dir}
Search directory @file{@var{dir}} for macro files before the standard
directories (@pxref{Macro Directories}).

@item -I@var{dir}
This option may be used to specify a directory to search for files.
It is passed to the following programs:

@itemize
@item
@code{gsoelim} (see @ref{gsoelim} for more details);
it also implies @code{groff}'s @option{-s} option.

@item
@code{gtroff}; it is used to search files named in the @code{psbb} and
@code{so} requests.

@item
@code{grops}; it is used to search files named in the
@w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes.
@end itemize

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.
@end table


@c =====================================================================

@node Environment, Macro Directories, Groff Options, Invoking groff
@section Environment
@cindex environment variables
@cindex variables in environment

There are also several environment variables (of the operating system,
not within @code{gtroff}) which can modify the behavior of @code{groff}.

@table @code
@item GROFF_COMMAND_PREFIX
@tindex GROFF_COMMAND_PREFIX@r{, environment variable}
@cindex command prefix
@cindex prefix, for commands
If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff}
instead of @code{gtroff}.  This also applies to @code{tbl}, @code{pic},
@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}.  It does not
apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
@code{post-grohtml}, @code{grolj4}, and @code{gxditview}.

The default command prefix is determined during the installation process.
If a non-GNU troff system is found, prefix @samp{g} is used, none
otherwise.

@item GROFF_TMAC_PATH
@tindex GROFF_TMAC_PATH@r{, environment variable}
A colon-separated list of directories in which to search for macro files
(before the default directories are tried).  @xref{Macro Directories}.

@item GROFF_TYPESETTER
@tindex GROFF_TYPESETTER@r{, environment variable}
The default output device.

@item GROFF_FONT_PATH
@tindex GROFF_FONT_PATH@r{, environment variable}
A colon-separated list of directories in which to search for the
@code{dev}@var{name} directory (before the default directories are
tried).  @xref{Font Directories}.

@item GROFF_BIN_PATH
@tindex GROFF_BIN_PATH@r{, environment variable}
This search path, followed by @code{PATH}, is used for commands executed
by @code{groff}.

@item GROFF_TMPDIR
@tindex GROFF_TMPDIR@r{, environment variable}
@tindex TMPDIR@r{, environment variable}
The directory in which @code{groff} creates temporary files.  If this is
not set and @env{TMPDIR} is set, temporary files are created in that
directory.  Otherwise temporary files are created in a system-dependent
default directory (on Unix and GNU/Linux systems, this is usually
@file{/tmp}).  @code{grops}, @code{grefer}, @code{pre-grohtml}, and
@code{post-grohtml} can create temporary files in this directory.
@end table

Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
rather than colons, to separate the directories in the lists described
above.


@c =====================================================================

@node Macro Directories, Font Directories, Environment, Invoking groff
@section Macro Directories
@cindex macro directories
@cindex directories for macros
@cindex searching macros
@cindex macros, searching

All macro file names must be named @code{@var{name}.tmac} or
@code{tmac.@var{name}} to make the @option{-m@var{name}} command line
option work.  The @code{mso} request doesn't have this restriction; any
file name can be used, and @code{gtroff} won't try to append or prepend
the @samp{tmac} string.

@cindex tmac, directory
@cindex directory, for tmac files
@cindex tmac, path
@cindex path, for tmac files
@cindex searching macro files
@cindex macro files, searching
@cindex files, macro, searching
Macro files are kept in the @dfn{tmac directories}, all of which
constitute the @dfn{tmac path}.  The elements of the search path for
macro files are (in that order):

@itemize @bullet
@item
The directories specified with @code{gtroff}'s or @code{groff}'s
@option{-M} command line option.

@item
@tindex GROFF_TMAC_PATH@r{, environment variable}
The directories given in the @env{GROFF_TMAC_PATH} environment
variable.

@item
@cindex safer mode
@cindex mode, safer
@cindex unsafe mode
@cindex mode, unsafe
@cindex current directory
@cindex directory, current
The current directory (only if in unsafe mode using the @option{-U}
command line switch).

@item
@cindex home directory
@cindex directory, home
The home directory.

@item
@cindex site-specific directory
@cindex directory, site-specific
@cindex platform-specific directory
@cindex directory, platform-specific
A platform-dependent directory, a site-specific (platform-independent)
directory, and the main tmac directory; the default locations are

@Example
/usr/local/lib/groff/site-tmac
/usr/local/share/groff/site-tmac
/usr/local/share/groff/1.18.2/tmac
@endExample

@noindent
assuming that the version of @code{groff} is 1.18.2, and the installation
prefix was @file{/usr/local}.  It is possible to fine-tune those
directories during the installation process.
@end itemize


@c =====================================================================

@node Font Directories, Paper Size, Macro Directories, Invoking groff
@section Font Directories
@cindex font directories
@cindex directories for fonts
@cindex searching fonts
@cindex fonts, searching

Basically, there is no restriction how font files for @code{groff} are
named and how long font names are; however, to make the font family
mechanism work (@pxref{Font Families}), fonts within a family should
start with the family name, followed by the shape.  For example, the
Times family uses @samp{T} for the family name and @samp{R}, @samp{B},
@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold',
`italic', and `bold italic', respectively.  Thus the final font names
are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}.

@cindex font path
@cindex path, for font files
All font files are kept in the @dfn{font directories} which constitute
the @dfn{font path}.  The file search functions will always append the
directory @code{dev}@var{name}, where @var{name} is the name of the
output device.  Assuming, say, DVI output, and @file{/foo/bar} as a
font directory, the font files for @code{grodvi} must be in
@file{/foo/bar/devdvi}.

The elements of the search path for font files are (in that order):

@itemize @bullet
@item
The directories specified with @code{gtroff}'s or @code{groff}'s
@option{-F} command line option.  All device drivers and some
preprocessors also have this option.

@item
@tindex GROFF_FONT_PATH@r{, environment variable}
The directories given in the @env{GROFF_FONT_PATH} environment
variable.

@item
@cindex site-specific directory
@cindex directory, site-specific
A site-specific directory and the main font directory; the default
locations are

@Example
/usr/local/share/groff/site-font
/usr/local/share/groff/1.18.2/font
@endExample

@noindent
assuming that the version of @code{groff} is 1.18.2, and the installation
prefix was @file{/usr/local}.  It is possible to fine-tune those
directories during the installation process.
@end itemize


@c =====================================================================

@node Paper Size, Invocation Examples, Font Directories, Invoking groff
@section Paper Size
@cindex paper size
@cindex size, paper
@cindex landscape page orientation
@cindex orientation, landscape
@cindex page orientation, landscape

In groff, the page size for @code{gtroff} and for output devices are
handled separately.  @xref{Page Layout}, for vertical manipulation of
the page size.  @xref{Line Layout}, for horizontal changes.

A default paper size can be set in the device's @file{DESC} file.  Most
output devices also have a command line option @option{-p} to override
the default paper size and option @option{-l} to use landscape
orientation.  @xref{DESC File Format}, for a description of the
@code{papersize} keyword which takes the same argument as @option{-p}.

@pindex papersize.tmac
@pindex troffrc
A convenient shorthand to set a particular paper size for @code{gtroff}
is command line option @option{-dpaper=@var{size}}.  This defines string
@code{paper} which is processed in file @file{papersize.tmac} (loaded in
the start-up file @file{troffrc} by default).  Possible values for
@var{size} are the same as the predefined values for the
@code{papersize} keyword (but only in lowercase) except
@code{a7}-@code{d7}.  An appended @samp{l} (ell) character denotes
landscape orientation.

For example, use the following for PS output on A4 paper in landscape
orientation:

@Example
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
@endExample

Note that it is up to the particular macro package to respect default
page dimensions set in this way (most do).


@c =====================================================================

@node Invocation Examples,  , Paper Size, Invoking groff
@section Invocation Examples
@cindex invocation examples
@cindex examples of invocation

This section lists several common uses of @code{groff} and the
corresponding command lines.

@Example
groff file
@endExample

@noindent
This command processes @file{file} without a macro package or a
preprocessor.  The output device is the default, @samp{ps}, and the
output is sent to @code{stdout}.

@Example
groff -t -mandoc -Tascii file | less
@endExample

@noindent
This is basically what a call to the @code{man} program does.
@code{gtroff} processes the manual page @file{file} with the
@file{mandoc} macro file (which in turn either calls the @file{man} or
the @file{mdoc} macro package), using the @code{tbl} preprocessor and
the @acronym{ASCII} output device.  Finally, the @code{less} pager
displays the result.

@Example
groff -X -m me file
@endExample

@noindent
Preview @file{file} with @code{gxditview}, using the @file{me} macro
package.  Since no @option{-T} option is specified, use the default
device (@samp{ps}).  Note that you can either say @w{@samp{-m me}} or
@w{@samp{-me}}; the latter is an anachronism from the early days of
@acronym{UNIX}.@footnote{The same is true for the other main macro
packages that come with @code{groff}: @file{man}, @file{mdoc},
@file{ms}, @file{mm}, and @file{mandoc}.  This won't work in general;
for example, to load @file{trace.tmac}, either @samp{-mtrace} or
@w{@samp{-m trace}} must be used.}

@Example
groff -man -rD1 -z file
@endExample

@noindent
Check @file{file} with the @file{man} macro package, forcing
double-sided printing -- don't produce any output.

@menu
* grog::
@end menu

@c ---------------------------------------------------------------------

@node grog,  , Invocation Examples, Invocation Examples
@subsection @code{grog}

@pindex grog
@code{grog} reads files, guesses which of the @code{groff} preprocessors
and/or macro packages are required for formatting them, and prints the
@code{groff} command including those options on the standard output.  It
generates one or more of the options @option{-e}, @option{-man},
@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc},
@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
@option{-s}, and @option{-t}.

A special file name@tie{}@file{-} refers to the standard input.  Specifying
no files also means to read the standard input.  Any specified options
are included in the printed command.  No space is allowed between
options and their arguments.  The only options recognized are
@option{-C} (which is also passed on) to enable compatibility mode, and
@option{-v} to print the version number and exit.

For example,

@Example
grog -Tdvi paper.ms
@endExample

@noindent
guesses the appropriate command to print @file{paper.ms} and then prints
it to the command line after adding the @option{-Tdvi} option.  For
direct execution, enclose the call to @code{grog} in backquotes at the
@acronym{UNIX} shell prompt:

@Example
`grog -Tdvi paper.ms` > paper.dvi
@endExample

@noindent
As seen in the example, it is still necessary to redirect the output to
something meaningful (i.e.@: either a file or a pager program like
@code{less}).



@c =====================================================================
@c =====================================================================

@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
@chapter Tutorial for Macro Users
@cindex tutorial for macro users
@cindex macros, tutorial for users
@cindex user's tutorial for macros
@cindex user's macro tutorial

Most users tend to use a macro package to format their papers.  This
means that the whole breadth of @code{groff} is not necessary for most
people.  This chapter covers the material needed to efficiently use a
macro package.

@menu
* Basics::
* Common Features::
@end menu


@c =====================================================================

@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
@section Basics
@cindex basics of macros
@cindex macro basics

This section covers some of the basic concepts necessary to understand
how to use a macro package.@footnote{This section is derived from
@cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.}
References are made throughout to more detailed information, if desired.

@code{gtroff} reads an input file prepared by the user and outputs a
formatted document suitable for publication or framing.  The input
consists of text, or words to be printed, and embedded commands
(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
format the output…