[dragonfly.git] / contrib / groff / doc / groff.texinfo

\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.8 or newer to format this document!
@c

@c %**start of header (This is for running Texinfo on a region.)
@setfilename groff.info
@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.20.1.

Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005, 2006,
2007, 2008, 2009
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.3 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 the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
@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 to start indentation, and if the line
@c starts with @def... (e.g. @deffnx), indentation is started.  We must
@c therefore ensure that a @def... is seen, during macro expansion.
@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
@c 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 Special care is required with 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.
@c Newer versions of texinfo.tex have similar code included already.

@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.20.1
@subtitle Spring 2009
@author by Trent A.@tie{}Fisher
@author and Werner Lemberg (@email{bug-groff@@gnu.org})

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

@contents

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

@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

@ifnottex
@insertcopying
@end ifnottex


@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 used extensively
for some thirty years.  It is well 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.

@code{groff} should not be confused with a @dfn{word processor}, an
integrated system of editor and 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 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 Jerry Saltzer, which ran on the @acronym{CTSS}
(@emph{Compatible Time Sharing System}, a project of MIT, the
Massachusetts Institute of Technology) in the
mid-sixties.@footnote{Jerome H.@: Saltzer, a grad student then, later a
Professor of Electrical Engineering, now retired.  Saltzer's PhD thesis
was the first application for @code{RUNOFF} and is available from the
MIT Libraries.}  The name came from the use of the phrase ``run off a
document'', meaning to print it out.
@c
@c Tom Van Vleck <thvv@multicians.org> writes about the following:
@c
@c I am not sure about this.. I think the BCPL runoff was the port to
@c the 635 architecture, and that the order of events is
@c 1. CTSS runoff
@c 2. BCPL runoff on Multics
@c 3. BCPL runoff on 635
@c 4. rf on PDP-7
@c
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
In 1971, the UNIX developers wanted to get a @w{PDP-11}, and to justify
the cost, proposed the development of 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.@:
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 died by a severe heart attack in a hospital while recovering
from a previous one.

@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} and @acronym{XHTML} 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}),
@acronym{HTML}, and @acronym{XHTML}.


@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
@itemx xhtml
To produce @acronym{HTML} and @acronym{XHTML} output, respectively.
Note that this 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 are 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.20.1/tmac
@endExample

@noindent
assuming that the version of @code{groff} is 1.20.1, 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 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.20.1/font
@endExample

@noindent
assuming that the version of @code{groff} is 1.20.1, 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.  For more detail on this, see @ref{Embedded
Commands}.

The word @dfn{argument} is used in this chapter to mean a word or number
which appears on the same line as a request, and which modifies the
meaning of that request.  For example, the request

@Example
.sp
@endExample

@noindent
spaces one line, but

@Example
.sp 4
@endExample

@noindent
spaces four lines.  The number@tie{}4 is an argument to the @code{sp}
request which says to space four lines instead of one.  Arguments are
separated from the request and from each other by spaces (@emph{no}
tabs).  More details on this can be found in @ref{Request and Macro
Arguments}.

The primary function of @code{gtroff} is to collect words from input
lines, fill output lines with those words, justify the right-hand margin
by inserting extra spaces in the line, and output the result.  For
example, the input:

@Example
Now is the time
for all good men
to come to the aid
of their party.
Four score and seven
years ago, etc.
@endExample

@noindent
is read, packed onto output lines, and justified to produce:

@quotation
Now is the time for all good men to come to the aid of their party.
Four score and seven years ago, etc.
@end quotation

@cindex break
@cindex line break
Sometimes a new output line should be started even though the current
line is not yet full; for example, at the end of a paragraph.  To do
this it is possible to cause a @dfn{break}, which starts a new output
line.  Some requests cause a break automatically, as normally do blank
input lines and input lines beginning with a space.

Not all input lines are text to be formatted.  Some input lines are
requests which describe how to format the text.  Requests always have a
period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
the input line.

The text formatter also does more complex things, such as automatically
numbering pages, skipping over page boundaries, putting footnotes in the
correct place, and so forth.

Here are a few hints for preparing text for input to @code{gtroff}.

@itemize @bullet
@item
First, keep the input lines short.  Short input lines are easier to
edit, and @code{gtroff} packs words onto longer lines anyhow.

@item
In keeping with this, it is helpful to begin a new line after every
comma or phrase, since common corrections are to add or delete sentences
or phrases.

@item
End each sentence with two spaces -- or better, start each sentence on a
new line.  @code{gtroff} recognizes characters that usually end a
sentence, and inserts sentence space accordingly.

@item
Do not hyphenate words at the end of lines -- @code{gtroff} is smart
enough to hyphenate words as needed, but is not smart enough to take
hyphens out and join a word back together.  Also, words such as
``mother-in-law'' should not be broken over a line, since then a space
can occur where not wanted, such as ``@w{mother- in}-law''.
@end itemize

@cindex double-spacing (@code{ls})
@cindex spacing
@code{gtroff} double-spaces output text automatically if you use the
request @w{@samp{.ls 2}}.  Reactivate single-spaced mode by typing
@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the vertical
space, use the @code{pvs} request (@pxref{Changing Type Sizes}).}

A number of requests allow to change the way the output looks, sometimes
called the @dfn{layout} of the output page.  Most of these requests
adjust the placing of @dfn{whitespace} (blank lines or spaces).

@cindex new page (@code{bp})
The @code{bp} request starts a new page, causing a line break.

@cindex blank line (@code{sp})
@cindex empty line (@code{sp})
@cindex line, empty (@code{sp})
The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank
space.  @var{N}@tie{}can be omitted (meaning skip a single line) or can
be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
@var{N}@tie{}centimeters).  For example, the input:

@Example
.sp 1.5i
My thoughts on the subject
.sp
@endExample

@noindent
leaves one and a half inches of space, followed by the line ``My
thoughts on the subject'', followed by a single blank line (more
measurement units are available, see @ref{Measurements}).

@cindex centering lines (@code{ce})
@cindex lines, centering (@code{ce})
Text lines can be centered by using the @code{ce} request.  The line
after @code{ce} is centered (horizontally) on the page.  To center more
than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
of lines to center), followed by the @var{N}@tie{}lines.  To center many
lines without counting them, type:

@Example
.ce 1000
lines to center
.ce 0
@endExample

@noindent
The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
lines, in other words, stop centering.

@cindex line break (@code{br})
@cindex break (@code{br})
All of these requests cause a break; that is, they always start a new
line.  To start a new line without performing any other action, use
@code{br}.


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

@node Common Features,  , Basics, Tutorial for Macro Users
@section Common Features
@cindex common features
@cindex features, common

@code{gtroff} provides very low-level operations for formatting a
document.  There are many common routine operations which are done in
all documents.  These common operations are written into @dfn{macros}
and collected into a @dfn{macro package}.

All macro packages provide certain common capabilities which fall into
the following categories.

@menu
* Paragraphs::
* Sections and Chapters::
* Headers and Footers::
* Page Layout Adjustment::
* Displays::
* Footnotes and Annotations::
* Table of Contents::
* Indices::
* Paper Formats::
* Multiple Columns::
* Font and Size Changes::
* Predefined Strings::
* Preprocessor Support::
* Configuration and Customization::
@end menu

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

@node Paragraphs, Sections and Chapters, Common Features, Common Features
@subsection Paragraphs
@cindex paragraphs

One of the most common and most used capability is starting a paragraph.
There are a number of different types of paragraphs, any of which can be
initiated with macros supplied by the macro package.  Normally,
paragraphs start with a blank line and the first line indented, like the
text in this manual.  There are also block style paragraphs, which omit
the indentation:

@Example
Some   men  look   at  constitutions   with  sanctimonious
reverence, and deem them like the ark of the covenant, too
sacred to be touched.
@endExample

@noindent
And there are also indented paragraphs which begin with a tag or label
at the margin and the remaining text indented.

@Example
one   This is  the first paragraph.  Notice  how the first
      line of  the resulting  paragraph lines up  with the
      other lines in the paragraph.
@endExample
@Example
longlabel
      This  paragraph   had  a  long   label.   The  first
      character of text on the first line does not line up
      with  the  text  on  second  and  subsequent  lines,
      although they line up with each other.
@endExample

A variation of this is a bulleted list.

@Example
.     Bulleted lists start with a bullet.   It is possible
      to use other glyphs instead of the bullet.  In nroff
      mode using the ASCII character set for output, a dot
      is used instead of a real bullet.
@endExample

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

@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
@subsection Sections and Chapters

Most macro packages supply some form of section headers.  The simplest
kind is simply the heading on a line by itself in bold type.  Others
supply automatically numbered section heading or different heading
styles at different levels.  Some, more sophisticated, macro packages
supply macros for starting chapters and appendices.

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

@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
@subsection Headers and Footers

Every macro package gives some way to manipulate the @dfn{headers} and
@dfn{footers} (also called @dfn{titles}) on each page.  This is text put
at the top and bottom of each page, respectively, which contain data
like the current page number, the current chapter title, and so on.  Its
appearance is not affected by the running text.  Some packages allow for
different ones on the even and odd pages (for material printed in a book
form).

The titles are called @dfn{three-part titles}, that is, there is a
left-justified part, a centered part, and a right-justified part.  An
automatically generated page number may be put in any of these fields
with the @samp{%} character (see @ref{Page Layout}, for more details).

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

@node Page Layout Adjustment, Displays, Headers and Footers, Common Features
@subsection Page Layout

Most macro packages let the user specify top and bottom margins and
other details about the appearance of the printed pages.

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

@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
@subsection Displays
@cindex displays

@dfn{Displays} are sections of text to be set off from the body of the
paper.  Major quotes, tables, and figures are types of displays, as are
all the examples used in this document.

@cindex quotes, major
@cindex major quotes
@dfn{Major quotes} are quotes which are several lines long, and hence
are set in from the rest of the text without quote marks around them.

@cindex list
A @dfn{list} is an indented, single-spaced, unfilled display.  Lists
should be used when the material to be printed should not be filled and
justified like normal text, such as columns of figures or the examples
used in this paper.

@cindex keep
A @dfn{keep} is a display of lines which are kept on a single page if
possible.  An example for a keep might be a diagram.  Keeps differ from
lists in that lists may be broken over a page boundary whereas keeps are
not.

@cindex keep, floating
@cindex floating keep
@dfn{Floating keeps} move relative to the text.  Hence, they are good
for things which are referred to by name, such as ``See figure@tie{}3''.
A floating keep appears at the bottom of the current page if it fits;
otherwise, it appears at the top of the next page.  Meanwhile, the
surrounding text `flows' around the keep, thus leaving no blank areas.

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

@node Footnotes and Annotations, Table of Contents, Displays, Common Features
@subsection Footnotes and Annotations
@cindex footnotes
@cindex annotations

There are a number of requests to save text for later printing.

@dfn{Footnotes} are printed at the bottom of the current page.

@cindex delayed text
@dfn{Delayed text} is very similar to a footnote except that it is
printed when called for explicitly.  This allows a list of references to
appear (for example) at the end of each chapter, as is the convention in
some disciplines.

Most macro packages which supply this functionality also supply a means
of automatically numbering either type of annotation.

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

@node Table of Contents, Indices, Footnotes and Annotations, Common Features
@subsection Table of Contents
@cindex table of contents
@cindex contents, table of

@dfn{Tables of contents} are a type of delayed text having a tag
(usually the page number) attached to each entry after a row of dots.
The table accumulates throughout the paper until printed, usually after
the paper has ended.  Many macro packages provide the ability to have
several tables of contents (e.g.@: a standard table of contents, a list
of tables, etc).

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

@node Indices, Paper Formats, Table of Contents, Common Features
@subsection Indices
@cindex index, in macro package

While some macro packages use the term @dfn{index}, none actually
provide that functionality.  The facilities they call indices are
actually more appropriate for tables of contents.

@pindex makeindex
To produce a real index in a document, external tools like the
@code{makeindex} program are necessary.

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

@node Paper Formats, Multiple Columns, Indices, Common Features
@subsection Paper Formats
@cindex paper formats

Some macro packages provide stock formats for various kinds of
documents.  Many of them provide a common format for the title and
opening pages of a technical paper.  The @file{mm} macros in particular
provide formats for letters and memoranda.

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

@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
@subsection Multiple Columns

Some macro packages (but not @file{man}) provide the ability to have two
or more columns on a page.

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

@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
@subsection Font and Size Changes

The built-in font and size functions are not always intuitive, so all
macro packages provide macros to make these operations simpler.

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

@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
@subsection Predefined Strings

Most macro packages provide various predefined strings for a variety of
uses; examples are sub- and superscripts, printable dates, quotes and
various special characters.

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

@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
@subsection Preprocessor Support

All macro packages provide support for various preprocessors and may
extend their functionality.

For example, all macro packages mark tables (which are processed with
@code{gtbl}) by placing them between @code{TS} and @code{TE} macros.
The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that
prints a caption at the top of a new page (when the table is too long to
fit on a single page).

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

@node Configuration and Customization,  , Preprocessor Support, Common Features
@subsection Configuration and Customization

Some macro packages provide means of customizing many of the details of
how the package behaves.  This ranges from setting the default type size
to changing the appearance of section headers.


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

@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
@chapter Macro Packages
@cindex macro packages
@cindex packages, macros

This chapter documents the main macro packages that come with
@code{groff}.

Different main macro packages can't be used at the same time; for
example

@Example
groff -m man foo.man -m ms bar.doc
@endExample

@noindent
doesn't work.  Note that option arguments are processed before
non-option arguments; the above (failing) sample is thus reordered to

@Example
groff -m man -m ms foo.man bar.doc
@endExample

@menu
* man::
* mdoc::
* ms::
* me::
* mm::
@end menu


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

@node man, mdoc, Macro Packages, Macro Packages
@section @file{man}
@cindex manual pages
@cindex man pages
@pindex an.tmac
@pindex man.tmac
@pindex man-old.tmac

This is the most popular and probably the most important macro package
of @code{groff}.  It is easy to use, and a vast majority of manual pages
are based on it.

@menu
* Man options::
* Man usage::
* Man font macros::
* Miscellaneous man macros::
* Predefined man strings::
* Preprocessors in man pages::
* Optional man extensions::
@end menu

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

@node Man options, Man usage, man, man
@subsection Options

The command line format for using the @file{man} macros with
@code{groff} is:

@Example
groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ]
      [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ]
      [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ]
      [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ]
@endExample

@noindent
It is possible to use @samp{-man} instead of @w{@samp{-m man}}.

@table @code
@item -rcR=1
This option (the default if a TTY output device is used) creates a
single, very long page instead of multiple pages.  Use @code{-rcR=0} to
disable it.

@item -rC1
If more than one manual page is given on the command line, number the
pages continuously, rather than starting each at@tie{}1.

@item -rD1
Double-sided printing.  Footers for even and odd pages are formatted
differently.

@item -rFT=@var{dist}
Set the position of the footer text to @var{dist}.  If positive, the
distance is measured relative to the top of the page, otherwise it is
relative to the bottom.  The default is @minus{}0.5@dmn{i}.

@item -rHY=@var{flags}
Set hyphenation flags.  Possible values are 1@tie{}to hyphenate without
restrictions, 2@tie{}to not hyphenate the last word on a page, 4@tie{}to
not hyphenate the last two characters of a word, and 8@tie{}to not
hyphenate the first two characters of a word.  These values are
additive; the default is@tie{}14.

@item -rIN=@var{length}
Set the body text indentation to @var{length}.  If not specified, the
indentation defaults to 7@dmn{n} (7@tie{}characters) in nroff mode and
7.2@dmn{n} otherwise.  For nroff, this value should always be an integer
multiple of unit @samp{n} to get consistent indentation.

@item -rLL=@var{length}
Set line length to @var{length}.  If not specified, the line length is
set to respect any value set by a prior @samp{ll} request (which
@emph{must} be in effect when the @samp{TH} macro is invoked), if this
differs from the built-in default for the formatter; otherwise it
defaults to 78@dmn{n} in nroff mode (this is 78 characters per line) and
6.5@dmn{i} in troff mode.@footnote{Note that the use of a @samp{.ll
@var{length}} request to initialize the line length, prior to use of the
@samp{TH} macro, is supported for backward compatibility with some
versions of the @code{man} program.  @emph{Always} use the
@option{-rLL=@var{length}} option, or an equivalent @samp{.nr LL
@var{length}} request, in preference to such a @samp{.ll @var{length}}
request.  In particular, note that in nroff mode, the request @samp{.ll
65n}, (with any @var{length} expression which evaluates equal to
65@dmn{n}, i.e., the formatter's default line length in nroff mode),
does @emph{not} set the line length to 65@dmn{n} (it is adjusted to the
@code{man} macro package's default setting of 78@dmn{n}), whereas the
use of the @option{-rLL=65n} option, or the @samp{.nr LL 65n} request
@emph{does} establish a line length of 65@dmn{n}.}

@item -rLT=@var{length}
Set title length to @var{length}.  If not specified, the title length
defaults to the line length.

@item -rP@var{nnn}
Page numbering starts with @var{nnn} rather than with@tie{}1.

@item -rS@var{xx}
Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base
document font size instead of the default value of@tie{}10@dmn{pt}.

@item -rSN=@var{length}
Set the indentation for sub-subheadings to @var{length}.  If not
specified, the indentation defaults to 3@dmn{n}.

@item -rX@var{nnn}
After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
@var{nnn}c, etc.  For example, the option @option{-rX2} produces the
following page numbers: 1, 2, 2a, 2b, 2c, etc.
@end table

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

@node Man usage, Man font macros, Man options, man
@subsection Usage
@cindex @code{man} macros
@cindex macros for manual pages [@code{man}]

@pindex man.local
This section describes the available macros for manual pages.  For
further customization, put additional macros and requests into the file
@file{man.local} which is loaded immediately after the @file{man}
package.

@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
Set the title of the man page to @var{title} and the section to
@var{section}, which must have a value between 1 and@tie{}8.  The value
of @var{section} may also have a string appended, e.g.@: @samp{.pm}, to
indicate a specific subsection of the man pages.

Both @var{title} and @var{section} are positioned at the left and right
in the header line (with @var{section} in parentheses immediately
appended to @var{title}.  @var{extra1} is positioned in the middle of
the footer line.  @var{extra2} is positioned at the left in the footer
line (or at the left on even pages and at the right on odd pages if
double-sided printing is active).  @var{extra3} is centered in the
header line.

For @acronym{HTML} and @acronym{XHTML} output, headers and footers are
completely suppressed.

Additionally, this macro starts a new page; the new line number
is@tie{}1 again (except if the @option{-rC1} option is given on the
command line) -- this feature is intended only for formatting multiple
man pages; a single man page should contain exactly one @code{TH} macro
at the beginning of the file.
@endDefmac

@Defmac {SH, [@Var{heading}], man}
Set up an unnumbered section heading sticking out to the left.  Prints
out all the text following @code{SH} up to the end of the line (or the
text in the next line if there is no argument to @code{SH}) in bold face
(or the font specified by the string @code{HF}), one size larger than
the base document size.  Additionally, the left margin and the
indentation for the following text is reset to its default value.
@endDefmac

@Defmac {SS, [@Var{heading}], man}
Set up an unnumbered (sub)section heading.  Prints out all the text
following @code{SS} up to the end of the line (or the text in the next
line if there is no argument to @code{SS}) in bold face (or the font
specified by the string @code{HF}), at the same size as the base
document size.  Additionally, the left margin and the indentation for
the following text is reset to its default value.
@endDefmac

@Defmac {TP, [@Var{nnn}], man}
Set up an indented paragraph with label.  The indentation is set to
@var{nnn} if that argument is supplied (the default unit is @samp{n} if
omitted), otherwise it is set to the previous indentation value
specified with @code{TP}, @code{IP}, or @code{HP} (or to the default
value if none of them have been used yet).

The first line of text following this macro is interpreted as a string
to be printed flush-left, as it is appropriate for a label.  It is not
interpreted as part of a paragraph, so there is no attempt to fill the
first line with text from the following input lines.  Nevertheless, if
the label is not as wide as the indentation the paragraph starts at the
same line (but indented), continuing on the following lines.  If the
label is wider than the indentation the descriptive part of the
paragraph begins on the line following the label, entirely indented.
Note that neither font shape nor font size of the label is set to a
default value; on the other hand, the rest of the text has default font
settings.
@endDefmac

@DefmacList {LP, , man}
@DefmacItem {PP, , man}
@DefmacListEnd {P, , man}
These macros are mutual aliases.  Any of them causes a line break at the
current position, followed by a vertical space downwards by the amount
specified by the @code{PD} macro.  The font size and shape are reset to
the default value (10@dmn{pt} roman if no @option{-rS} option is given
on the command line).  Finally, the current left margin and the
indentation is restored.
@endDefmac

@Defmac {IP, [@Var{designator} [@Var{nnn}]], man}
Set up an indented paragraph, using @var{designator} as a tag to mark
its beginning.  The indentation is set to @var{nnn} if that argument is
supplied (default unit is @samp{n}), otherwise it is set to the previous
indentation value specified with @code{TP}, @code{IP}, or @code{HP} (or
the default value if none of them have been used yet).  Font size and
face of the paragraph (but not the designator) are reset to their
default values.

To start an indented paragraph with a particular indentation but without
a designator, use @samp{""} (two double quotes) as the first argument of
@code{IP}.

For example, to start a paragraph with bullets as the designator and
4@tie{}en indentation, write

@Example
.IP \(bu 4
@endExample
@endDefmac

@Defmac {HP, [@Var{nnn}], man}
@cindex hanging indentation [@code{man}]
@cindex @code{man} macros, hanging indentation
Set up a paragraph with hanging left indentation.  The indentation is
set to @var{nnn} if that argument is supplied (default unit is
@samp{n}), otherwise it is set to the previous indentation value
specified with @code{TP}, @code{IP}, or @code{HP} (or the default value
if non of them have been used yet).  Font size and face are reset to
their default values.
@endDefmac

@Defmac {RS, [@Var{nnn}], man}
@cindex left margin, how to move [@code{man}]
@cindex @code{man} macros, moving left margin
Move the left margin to the right by the value @var{nnn} if specified
(default unit is @samp{n}); otherwise it is set to the previous
indentation value specified with @code{TP}, @code{IP}, or @code{HP} (or
to the default value if none of them have been used yet).  The
indentation value is then set to the default.

Calls to the @code{RS} macro can be nested.
@endDefmac

@Defmac {RE, [@Var{nnn}], man}
Move the left margin back to level @var{nnn}, restoring the previous
left margin.  If no argument is given, it moves one level back.  The
first level (i.e., no call to @code{RS} yet) has number@tie{}1, and each
call to @code{RS} increases the level by@tie{}1.
@endDefmac

@cindex line breaks, with vertical space [@code{man}]
@cindex @code{man} macros, line breaks with vertical space
To summarize, the following macros cause a line break with the insertion
of vertical space (which amount can be changed with the @code{PD}
macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
@code{P}), @code{IP}, and @code{HP}.

@cindex line breaks, without vertical space [@code{man}]
@cindex @code{man} macros, line breaks without vertical space
The macros @code{RS} and @code{RE} also cause a break but do not insert
vertical space.

@cindex default indentation, resetting [@code{man}]
@cindex indentaion, resetting to default [@code{man}]
@cindex @code{man} macros, resetting default indentation
Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP},
@code{P}), and @code{RS} reset the indentation to its default value.

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

@node Man font macros, Miscellaneous man macros, Man usage, man
@subsection Macros to set fonts
@cindex font selection [@code{man}]
@cindex @code{man} macros, how to set fonts

The standard font is roman; the default text size is 10@tie{}point.  If
command line option @option{-rS=@var{n}} is given, use @var{n}@dmn{pt}
as the default text size.

@Defmac {SM, [@Var{text}], man}
Set the text on the same line or the text on the next line in a font
that is one point size smaller than the default font.
@endDefmac

@Defmac {SB, [@Var{text}], man}
@cindex bold face [@code{man}]
@cindex @code{man} macros, bold face
Set the text on the same line or the text on the next line in bold face
font, one point size smaller than the default font.
@endDefmac

@Defmac {BI, text, man}
Set its arguments alternately in bold face and italic, without a space
between the arguments.  Thus,

@Example
.BI this "word and" that
@endExample

@noindent
produces ``thisword andthat'' with ``this'' and ``that'' in bold face,
and ``word and'' in italics.
@endDefmac

@Defmac {IB, text, man}
Set its arguments alternately in italic and bold face, without a space
between the arguments.
@endDefmac

@Defmac {RI, text, man}
Set its arguments alternately in roman and italic, without a space
between the arguments.
@endDefmac

@Defmac {IR, text, man}
Set its arguments alternately in italic and roman, without a space
between the arguments.
@endDefmac

@Defmac {BR, text, man}
Set its arguments alternately in bold face and roman, without a space
between the arguments.
@endDefmac

@Defmac {RB, text, man}
Set its arguments alternately in roman and bold face, without a space
between the arguments.
@endDefmac

@Defmac {B, [@Var{text}], man}
Set @var{text} in bold face.  If no text is present on the line where
the macro is called, then the text of the next line appears in bold
face.
@endDefmac

@Defmac {I, [@Var{text}], man}
@cindex italic fonts [@code{man}]
@cindex @code{man} macros, italic fonts
Set @var{text} in italic.  If no text is present on the line where the
macro is called, then the text of the next line appears in italic.
@endDefmac

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

@node Miscellaneous man macros, Predefined man strings, Man font macros, man
@subsection Miscellaneous macros

@pindex grohtml
@cindex @code{man} macros, default indentation
@cindex default indentation [@code{man}]
The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in
nroff mode except for @code{grohtml} which ignores indentation.

@Defmac {DT, , man}
@cindex tab stops [@code{man}]
@cindex @code{man} macros, tab stops
Set tabs every 0.5@tie{}inches.  Since this macro is always executed
during a call to the @code{TH} macro, it makes sense to call it only if
the tab positions have been changed.
@endDefmac

@Defmac {PD, [@Var{nnn}], man}
@cindex empty space before a paragraph [@code{man}]
@cindex @code{man} macros, empty space before a paragraph
Adjust the empty space before a new paragraph (or section).  The
optional argument gives the amount of space (default unit is @samp{v});
without parameter, the value is reset to its default value (1@tie{}line
in nroff mode, 0.4@dmn{v}@tie{}otherwise).

This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
@endDefmac

The following two macros are included for BSD compatibility.

@Defmac {AT, [@Var{system} [@Var{release}]], man}
@cindex @code{man}macros, BSD compatibility
Alter the footer for use with @acronym{AT&T} manpages.  This command
exists only for compatibility; don't use it.  The first argument
@var{system} can be:

@table @code
@item 3
7th Edition (the default)

@item 4
System III

@item 5
System V
@end table

An optional second argument @var{release} to @code{AT} specifies the
release number (such as ``System V Release 3'').
@endDefmac

@Defmac {UC, [@Var{version}], man}
@cindex @code{man}macros, BSD compatibility
Alters the footer for use with @acronym{BSD} manpages.  This command
exists only for compatibility; don't use it.  The argument can be:

@table @code
@item 3
3rd Berkeley Distribution (the default)

@item 4
4th Berkeley Distribution

@item 5
4.2 Berkeley Distribution

@item 6
4.3 Berkeley Distribution

@item 7
4.4 Berkeley Distribution
@end table
@endDefmac

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

@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
@subsection Predefined strings

The following strings are defined:

@Defstr {S, man}
Switch back to the default font size.
@endDefstr

@Defstr {HF, man}
The typeface used for headings.
The default is @samp{B}.
@endDefstr

@Defstr {R, man}
The `registered' sign.
@endDefstr

@Defstr {Tm, man}
The `trademark' sign.
@endDefstr

@DefstrList {lq, man}
@DefstrListEnd {rq, man}
@cindex @code{lq} glyph, and @code{lq} string [@code{man}]
@cindex @code{rq} glyph, and @code{rq} string [@code{man}]
Left and right quote.  This is equal to @code{\(lq} and @code{\(rq},
respectively.
@endDefstr

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

@node Preprocessors in man pages, Optional man extensions, Predefined man strings, man
@subsection Preprocessors in @file{man} pages

@cindex preprocessor, calling convention
@cindex calling convention of preprocessors
If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
become common usage to make the first line of the man page look like
this:

@Example
'\" @var{word}
@endExample

@pindex geqn@r{, invocation in manual pages}
@pindex grefer@r{, invocation in manual pages}
@pindex gtbl@r{, invocation in manual pages}
@pindex man@r{, invocation of preprocessors}
@noindent
Note the single space character after the double quote.  @var{word}
consists of letters for the needed preprocessors: @samp{e} for
@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
Modern implementations of the @code{man} program read this first line
and automatically call the right preprocessor(s).

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

@node Optional man extensions,  , Preprocessors in man pages, man
@subsection Optional @file{man} extensions

@pindex man.local
Use the file @file{man.local} for local extensions to the @code{man}
macros or for style changes.

@unnumberedsubsubsec Custom headers and footers
@cindex @code{man} macros, custom headers and footers

In groff versions 1.18.2 and later, you can specify custom headers and
footers by redefining the following macros in @file{man.local}.

@Defmac {PT, , man}
Control the content of the headers.  Normally, the header prints the
command name and section number on either side, and the optional fifth
argument to @code{TH} in the center.
@endDefmac

@Defmac {BT, , man}
Control the content of the footers.  Normally, the footer prints the
page number and the third and fourth arguments to @code{TH}.

Use the @code{FT} number register to specify the footer position.  The
default is @minus{}0.5@dmn{i}.
@endDefmac

@unnumberedsubsubsec Ultrix-specific man macros
@cindex Ultrix-specific @code{man} macros
@cindex @code{man} macros, Ultrix-specific

@pindex man.ultrix
The @code{groff} source distribution includes a file named
@file{man.ultrix}, containing macros compatible with the Ultrix variant
of @code{man}.  Copy this file into @file{man.local} (or use the
@code{mso} request to load it) to enable the following macros.

@Defmac {CT, @Var{key}, man}
Print @samp{<CTRL/@var{key}>}.
@endDefmac

@Defmac {CW, , man}
Print subsequent text using the constant width (Courier) typeface.
@endDefmac

@Defmac {Ds, , man}
Begin a non-filled display.
@endDefmac

@Defmac {De, , man}
End a non-filled display started with @code{Ds}.
@endDefmac

@Defmac {EX, [@Var{indent}], man}
Begin a non-filled display using the constant width (Courier) typeface.
Use the optional @var{indent} argument to indent the display.
@endDefmac

@Defmac {EE, , man}
End a non-filled display started with @code{EX}.
@endDefmac

@Defmac {G, [@Var{text}], man}
Set @var{text} in Helvetica.  If no text is present on the line where
the macro is called, then the text of the next line appears in
Helvetica.
@endDefmac

@Defmac {GL, [@Var{text}], man}
Set @var{text} in Helvetica Oblique.  If no text is present on the line
where the macro is called, then the text of the next line appears in
Helvetica Oblique.
@endDefmac

@Defmac {HB, [@Var{text}], man}
Set @var{text} in Helvetica Bold.  If no text is present on the line
where the macro is called, then all text up to the next @code{HB}
appears in Helvetica Bold.
@endDefmac

@Defmac {TB, [@Var{text}], man}
Identical to @code{HB}.
@endDefmac

@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man}
Set a manpage reference in Ultrix format.  The @var{title} is in Courier
instead of italic.  Optional punctuation follows the section number
without an intervening space.
@endDefmac

@Defmac {NT, [@code{C}] [@Var{title}], man}
Begin a note.  Print the optional @Var{title}, or the word ``Note'',
centered on the page.  Text following the macro makes up the body of the
note, and is indented on both sides.  If the first argument is @code{C},
the body of the note is printed centered (the second argument replaces
the word ``Note'' if specified).
@endDefmac

@Defmac {NE, , man}
End a note begun with @code{NT}.
@endDefmac

@Defmac {PN, @Var{path} [@Var{punct}], man}
Set the path name in constant width (Courier), followed by optional
punctuation.
@endDefmac

@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man}
If called with two arguments, identical to @code{PN}.  If called with
three arguments, set the second argument in constant width (Courier),
bracketed by the first and third arguments in the current font.
@endDefmac

@Defmac {R, , man}
Switch to roman font and turn off any underlining in effect.
@endDefmac

@Defmac {RN, , man}
Print the string @samp{<RETURN>}.
@endDefmac

@Defmac {VS, [@code{4}], man}
Start printing a change bar in the margin if the number@tie{}@code{4} is
specified.  Otherwise, this macro does nothing.
@endDefmac

@Defmac {VE, , man}
End printing the change bar begun by @code{VS}.
@endDefmac

@unnumberedsubsubsec Simple example

The following example @file{man.local} file alters the @code{SH} macro
to add some extra vertical space before printing the heading.  Headings
are printed in Helvetica Bold.

@Example
.\" Make the heading fonts Helvetica
.ds HF HB
.
.\" Put more whitespace in front of headings.
.rn SH SH-orig
.de SH
.  if t .sp (u;\\n[PD]*2)
.  SH-orig \\$*
..
@endExample


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

@node mdoc, ms, man, Macro Packages
@section @file{mdoc}
@cindex @code{mdoc} macros

@c XXX documentation
@c XXX this is a placeholder until we get stuff knocked into shape
See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc}
at the command line).


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

@node ms, me, mdoc, Macro Packages
@section @file{ms}
@cindex @code{ms} macros

The @file{-ms} macros are suitable for reports, letters, books, user
manuals, and so forth.  The package provides macros for cover pages,
section headings, paragraphs, lists, footnotes, pagination, and a table
of contents.

@menu
* ms Intro::
* General ms Structure::
* ms Document Control Registers::
* ms Cover Page Macros::
* ms Body Text::
* ms Page Layout::
* Differences from AT&T ms::
* Naming Conventions::
@end menu

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

@node ms Intro, General ms Structure, ms, ms
@subsection Introduction to @file{ms}

The original @file{-ms} macros were included with @acronym{AT&T}
@code{troff} as well as the @file{man} macros.  While the @file{man}
package is intended for brief documents that can be read on-line as well
as printed, the @file{ms} macros are suitable for longer documents that
are meant to be printed rather than read on-line.

The @file{ms} macro package included with @code{groff} is a complete,
bottom-up re-implementation.  Several macros (specific to @acronym{AT&T}
or Berkeley) are not included, while several new commands are.
@xref{Differences from AT&T ms}, for more information.

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

@node General ms Structure, ms Document Control Registers, ms Intro, ms
@subsection General structure of an @file{ms} document
@cindex @code{ms} macros, general structure

The @file{ms} macro package expects a certain amount of structure, but
not as much as packages such as @file{man} or @file{mdoc}.

The simplest documents can begin with a paragraph macro (such as
@code{LP} or @code{PP}), and consist of text separated by paragraph
macros or even blank lines.  Longer documents have a structure as
follows:

@table @strong
@item Document type
If you invoke the @code{RP} (report) macro on the first line of the
document, @code{groff} prints the cover page information on its own
page; otherwise it prints the information on the first page with your
document text immediately following.  Other document formats found in
@acronym{AT&T} @code{troff} are specific to @acronym{AT&T} or Berkeley,
and are not supported in @code{groff}.

@item Format and layout
By setting number registers, you can change your document's type (font
and size), margins, spacing, headers and footers, and footnotes.
@xref{ms Document Control Registers}, for more details.

@item Cover page
A cover page consists of a title, the author's name and institution, an
abstract, and the date.@footnote{Actually, only the title is required.}
@xref{ms Cover Page Macros}, for more details.

@item Body
Following the cover page is your document.  You can use the @file{ms}
macros to write reports, letters, books, and so forth.  The package is
designed for structured documents, consisting of paragraphs interspersed
with headings and augmented by lists, footnotes, tables, and other
common constructs.  @xref{ms Body Text}, for more details.

@item Table of contents
Longer documents usually include a table of contents, which you can
invoke by placing the @code{TC} macro at the end of your document.  The
@file{ms} macros have minimal indexing facilities, consisting of the
@code{IX} macro, which prints an entry on standard error.  Printing the
table of contents at the end is necessary since @code{groff} is a
single-pass text formatter, thus it cannot determine the page number of
each section until that section has actually been set and printed.
Since @file{ms} output is intended for hardcopy, you can manually
relocate the pages containing the table of contents between the cover
page and the body text after printing.
@end table

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

@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
@subsection Document control registers
@cindex @code{ms} macros, document control registers

The following is a list of document control number registers.  For the
sake of consistency, set registers related to margins at the beginning
of your document, or just after the @code{RP} macro.  You can set other
registers later in your document, but you should keep them together at
the beginning to make them easy to find and edit as necessary.

@unnumberedsubsubsec Margin Settings

@Defmpreg {PO, ms}
Defines the page offset (i.e., the left margin).  There is no explicit
right margin setting; the combination of the @code{PO} and @code{LL}
registers implicitly define the right margin width.

Effective: next page.

Default value: 1@dmn{i}.
@endDefmpreg

@Defmpreg {LL, ms}
Defines the line length (i.e., the width of the body text).

Effective: next paragraph.

Default: 6@dmn{i}.
@endDefmpreg

@Defmpreg {LT, ms}
Defines the title length (i.e., the header and footer width).  This
is usually the same as @code{LL}, but not necessarily.

Effective: next paragraph.

Default: 6@dmn{i}.
@endDefmpreg

@Defmpreg {HM, ms}
Defines the header margin height at the top of the page.

Effective: next page.

Default: 1@dmn{i}.
@endDefmpreg

@Defmpreg {FM, ms}
Defines the footer margin height at the bottom of the page.

Effective: next page.

Default: 1@dmn{i}.
@endDefmpreg

@unnumberedsubsubsec Text Settings

@Defmpreg {PS, ms}
Defines the point size of the body text.  If the value is larger than or
equal to 1000, divide it by 1000 to get a fractional point size.  For
example, @samp{.nr PS 10250} sets the document's point size to
10.25@dmn{p}.

Effective: next paragraph.

Default: 10@dmn{p}.
@endDefmpreg

@Defmpreg {VS, ms}
Defines the space between lines (line height plus leading).  If the
value is larger than or equal to 1000, divide it by 1000 to get a
fractional point size.  Due to backwards compatibility, @code{VS} must
be smaller than 40000 (this is 40.0@dmn{p}).

Effective: next paragraph.

Default: 12@dmn{p}.
@endDefmpreg

@Defmpreg {PSINCR, ms}
Defines an increment in point size, which is applied to section headings
at nesting levels below the value specified in @code{GROWPS}.  The value
of @code{PSINCR} should be specified in points, with the @dmn{p} scaling
factor, and may include a fractional component; for example,
@w{@samp{.nr PSINCR 1.5p}} sets a point size increment of 1.5@dmn{p}.

Effective: next section heading.

Default: 1@dmn{p}.
@endDefmpreg

@Defmpreg {GROWPS, ms}
Defines the heading level below which the point size increment set by
@code{PSINCR} becomes effective.  Section headings at and above the
level specified by @code{GROWPS} are printed at the point size set by
@code{PS}; for each level below the value of @code{GROWPS}, the point
size is increased in steps equal to the value of @code{PSINCR}.  Setting
@code{GROWPS} to any value less than@tie{}2 disables the incremental
heading size feature.

Effective: next section heading.

Default: 0.
@endDefmpreg

@Defmpreg {HY, ms}
Defines the hyphenation level.  @code{HY} sets safely the value of the
low-level @code{hy} register.  Setting the value of @code{HY} to@tie{}0
is equivalent to using the @code{nh} request.

Effective: next paragraph.

Default: 14.
@endDefmpreg

@Defmpreg {FAM, ms}
Defines the font family used to typeset the document.

Effective: next paragraph.

Default: as defined in the output device.
@endDefmpreg

@unnumberedsubsubsec Paragraph Settings

@Defmpreg {PI, ms}
Defines the initial indentation of a (@code{PP} macro) paragraph.

Effective: next paragraph.

Default: 5@dmn{n}.
@endDefmpreg

@Defmpreg {PD, ms}
Defines the space between paragraphs.

Effective: next paragraph.

Default: 0.3@dmn{v}.
@endDefmpreg

@Defmpreg {QI, ms}
Defines the indentation on both sides of a quoted (@code{QP} macro)
paragraph.

Effective: next paragraph.

Default: 5@dmn{n}.
@endDefmpreg

@Defmpreg {PORPHANS, ms}
Defines the minimum number of initial lines of any paragraph which
should be kept together, to avoid orphan lines at the bottom of a page.
If a new paragraph is started close to the bottom of a page, and there
is insufficient space to accommodate @code{PORPHANS} lines before an
automatic page break, then the page break is forced, before the start of
the paragraph.

Effective: next paragraph.

Default: 1.
@endDefmpreg

@Defmpreg {HORPHANS, ms}
Defines the minimum number of lines of the following paragraph which
should be kept together with any section heading introduced by the
@code{NH} or @code{SH} macros.  If a section heading is placed close to
the bottom of a page, and there is insufficient space to accommodate
both the heading and at least @code{HORPHANS} lines of the following
paragraph, before an automatic page break, then the page break is forced
before the heading.

Effective: next paragraph.

Default: 1.
@endDefmpreg

@unnumberedsubsubsec Footnote Settings

@Defmpreg {FL, ms}
Defines the length of a footnote.

Effective: next footnote.

Default: @math{@code{@\n[LL]} * 5 / 6}.
@endDefmpreg

@Defmpreg {FI, ms}
Defines the footnote indentation.

Effective: next footnote.

Default: 2@dmn{n}.
@endDefmpreg

@Defmpreg {FF, ms}
The footnote format:
@table @code
@item 0
Print the footnote number as a superscript; indent the footnote
(default).

@item 1
Print the number followed by a period (like 1.@:) and indent the
footnote.

@item 2
Like 1, without an indentation.

@item 3
Like 1, but print the footnote number as a hanging paragraph.
@end table

Effective: next footnote.

Default: 0.
@endDefmpreg

@Defmpreg {FPS, ms}
Defines the footnote point size.  If the value is larger than or equal
to 1000, divide it by 1000 to get a fractional point size.

Effective: next footnote.

Default: @math{@code{@\n[PS]} - 2}.
@endDefmpreg

@Defmpreg {FVS, ms}
Defines the footnote vertical spacing.  If the value is larger than or
equal to 1000, divide it by 1000 to get a fractional point size.

Effective: next footnote.

Default: @math{@code{@\n[FPS]} + 2}.
@endDefmpreg

@Defmpreg {FPD, ms}
Defines the footnote paragraph spacing.

Effective: next footnote.

Default: @math{@code{@\n[PD]} / 2}.
@endDefmpreg

@unnumberedsubsubsec Miscellaneous Number Registers

@Defmpreg {MINGW, ms}
Defines the minimum width between columns in a multi-column document.

Effective: next page.

Default: 2@dmn{n}.
@endDefmpreg

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

@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
@subsection Cover page macros
@cindex @code{ms} macros, cover page
@cindex cover page macros, [@code{ms}]

Use the following macros to create a cover page for your document in the
order shown.

@Defmac {RP, [@code{no}], ms}
Specifies the report format for your document.  The report format
creates a separate cover page.  The default action (no @code{RP} macro)
is to print a subset of the cover page on page@tie{}1 of your document.

If you use the word @code{no} as an optional argument, @code{groff}
prints a title page but does not repeat any of the title page
information (title, author, abstract, etc.@:) on page@tie{}1 of the
document.
@endDefmac

@Defmac {P1, , ms}
(P-one) Prints the header on page@tie{}1.  The default is to suppress
the header.
@endDefmac

@Defmac {DA, [@dots{}], ms}
(optional) Prints the current date, or the arguments to the macro if
any, on the title page (if specified) and in the footers.  This is the
default for @code{nroff}.
@endDefmac

@Defmac {ND, [@dots{}], ms}
(optional) Prints the current date, or the arguments to the macro if
any, on the title page (if specified) but not in the footers.  This is
the default for @code{troff}.
@endDefmac

@Defmac {TL, , ms}
Specifies the document title.  @code{groff} collects text following the
@code{TL} macro into the title, until reaching the author name or
abstract.
@endDefmac

@Defmac {AU, , ms}
Specifies the author's name, which appears on the line (or lines)
immediately following.  You can specify multiple authors as follows:

@Example
.AU
John Doe
.AI
University of West Bumblefuzz
.AU
Martha Buck
.AI
Monolithic Corporation

...
@endExample
@endDefmac

@Defmac {AI, , ms}
Specifies the author's institution.  You can specify multiple
institutions in the same way that you specify multiple authors.
@endDefmac

@Defmac {AB, [@code{no}], ms}
Begins the abstract.  The default is to print the word
@acronym{ABSTRACT}, centered and in italics, above the text of the
abstract.  The word @code{no} as an optional argument suppresses this
heading.
@endDefmac

@Defmac {AE, , ms}
Ends the abstract.
@endDefmac

The following is example mark-up for a title page.
@cindex title page, example markup
@cindex example markup, title page

@Example
@cartouche
.RP
.TL
The Inevitability of Code Bloat
in Commercial and Free Software
.AU
J. Random Luser
.AI
University of West Bumblefuzz
.AB
This report examines the long-term growth
of the code bases in two large, popular software
packages; the free Emacs and the commercial
Microsoft Word.
While differences appear in the type or order
of features added, due to the different
methodologies used, the results are the same
in the end.
.PP
The free software approach is shown to be
superior in that while free software can
become as bloated as commercial offerings,
free software tends to have fewer serious
bugs and the added features are in line with
user demand.
.AE

... the rest of the paper follows ...
@end cartouche
@endExample

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

@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
@subsection Body text
@cindex @code{ms} macros, body text

This section describes macros used to mark up the body of your document.
Examples include paragraphs, sections, and other groups.

@menu
* Paragraphs in ms::
* Headings in ms::
* Highlighting in ms::
* Lists in ms::
* Indentation values in ms::
* Tabstops in ms::
* ms Displays and Keeps::
* ms Insertions::
* Example multi-page table::
* ms Footnotes::
@end menu

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

@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
@subsubsection Paragraphs
@cindex @code{ms} macros, paragraph handling

The following paragraph types are available.

@DefmacList {PP, , ms}
@DefmacListEnd {LP, , ms}
Sets a paragraph with an initial indentation.
@endDefmac

@Defmac {QP, , ms}
Sets a paragraph that is indented at both left and right margins.  The
effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
The next paragraph or heading returns margins to normal.
@endDefmac

@Defmac {XP, , ms}
Sets a paragraph whose lines are indented, except for the first line.
This is a Berkeley extension.
@endDefmac

The following markup uses all four paragraph macros.

@Example
@cartouche
.NH 2
Cases used in the study
.LP
The following software and versions were
considered for this report.
.PP
For commercial software, we chose
.B "Microsoft Word for Windows" ,
starting with version 1.0 through the
current version (Word 2000).
.PP
For free software, we chose
.B Emacs ,
from its first appearance as a standalone
editor through the current version (v20).
See [Bloggs 2002] for details.
.QP
Franklin's Law applied to software:
software expands to outgrow both
RAM and disk space over time.
.LP
Bibliography:
.XP
Bloggs, Joseph R.,
.I "Everyone's a Critic" ,
Underground Press, March 2002.
A definitive work that answers all questions
and criticisms about the quality and usability of
free software.
@end cartouche
@endExample

The @code{PORPHANS} register (@pxref{ms Document Control Registers})
operates in conjunction with each of these macros, to inhibit the
printing of orphan lines at the bottom of any page.

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

@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
@subsubsection Headings
@cindex @code{ms} macros, headings

Use headings to create a hierarchical structure for your document.  The
@file{ms} macros print headings in @strong{bold}, using the same font
family and point size as the body text.

The following describes the heading macros:

@DefmacList {NH, @Var{curr-level}, ms}
@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
Numbered heading.  The argument is either a numeric argument to indicate
the level of the heading, or the letter@tie{}@code{S} followed by
numeric arguments to set the heading level explicitly.

If you specify heading levels out of sequence, such as invoking
@samp{.NH 3} after @samp{.NH 1}, @code{groff} prints a warning on
standard error.
@endDefmac

@DefstrList {SN, ms}
@DefstrItem {SN-DOT, ms}
@DefstrListEnd {SN-NO-DOT, ms}
After invocation of @code{NH}, the assigned section number is made
available in the strings @code{SN-DOT} (as it appears in a printed
section heading with default formatting, followed by a terminating
period), and @code{SN-NO-DOT} (with the terminating period omitted).
The string @code{SN} is also defined, as an alias for @code{SN-DOT}; if
preferred, you may redefine it as an alias for @code{SN-NO-DOT}, by
including the initialization
@Example
.als SN SN-NO-DOT
@endExample

@noindent
at any time @strong{before} you would like the change to take effect.
@endDefstr

@Defstr {SN-STYLE, ms}
You may control the style used to print section numbers, within numbered
section headings, by defining an appropriate alias for the string
@code{SN-STYLE}.  The default style, in which the printed section number
is followed by a terminating period, is obtained by defining the alias
@Example
.als SN-STYLE SN-DOT
@endExample

@noindent
If you prefer to omit the terminating period, from section numbers
appearing in numbered section headings, you may define the alias
@Example
.als SN-STYLE SN-NO-DOT
@endExample

@noindent
Any such change in section numbering style becomes effective from the
next use of @code{.NH}, following redefinition of the alias for
@code{SN-STYLE}.
@endDefstr

@Defmac {SH, [@Var{match-level}], ms}
Unnumbered subheading.

The optional @var{match-level} argument is a GNU extension.  It is a
number indicating the level of the heading, in a manner analogous to the
@var{curr-level} argument to @code{.NH}.  Its purpose is to match the
point size, at which the heading is printed, to the size of a numbered
heading at the same level, when the @code{GROWPS} and @code{PSINCR}
heading size adjustment mechanism is in effect.  @xref{ms Document
Control Registers}.
@endDefmac

The @code{HORPHANS} register (@pxref{ms Document Control Registers})
operates in conjunction with the @code{NH} and @code{SH} macros, to
inhibit the printing of orphaned section headings at the bottom of any
page.

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

@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
@subsubsection Highlighting
@cindex @code{ms} macros, highlighting

The @file{ms} macros provide a variety of methods to highlight or
emphasize text:

@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
Sets its first argument in @strong{bold type}.  If you specify a second
argument, @code{groff} prints it in the previous font after the bold
text, with no intervening space (this allows you to set punctuation
after the highlighted text without highlighting the punctuation).
Similarly, it prints the third argument (if any) in the previous font
@strong{before} the first argument.  For example,

@Example
.B foo ) (
@endExample

prints (@strong{foo}).

If you give this macro no arguments, @code{groff} prints all text
following in bold until the next highlighting, paragraph, or heading
macro.
@endDefmac

@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
Sets its first argument in roman (or regular) type.  It operates
similarly to the @code{B}@tie{}macro otherwise.
@endDefmac

@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
Sets its first argument in @emph{italic type}.  It operates similarly
to the @code{B}@tie{}macro otherwise.
@endDefmac

@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
Sets its first argument in a @code{constant width face}.  It operates
similarly to the @code{B}@tie{}macro otherwise.
@endDefmac

@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
Sets its first argument in bold italic type.  It operates similarly to
the @code{B}@tie{}macro otherwise.
@endDefmac

@Defmac {BX, [@Var{txt}], ms}
Prints its argument and draws a box around it.  If you want to box a
string that contains spaces, use a digit-width space (@code{\0}).
@endDefmac

@Defmac {UL, [@Var{txt} [@Var{post}]], ms}
Prints its first argument with an underline.  If you specify a second
argument, @code{groff} prints it in the previous font after the
underlined text, with no intervening space.
@endDefmac

@Defmac {LG, , ms}
Prints all text following in larger type (two points larger than the
current point size) until the next font size, highlighting, paragraph,
or heading macro.  You can specify this macro multiple times to
enlarge the point size as needed.
@endDefmac

@Defmac {SM, , ms}
Prints all text following in smaller type (two points smaller than the
current point size) until the next type size, highlighting, paragraph,
or heading macro.  You can specify this macro multiple times to reduce
the point size as needed.
@endDefmac

@Defmac {NL, , ms}
Prints all text following in the normal point size (that is, the value
of the @code{PS} register).
@endDefmac

@DefstrList {@Lbrace{}, ms}
@DefstrListEnd {@Rbrace{}, ms}
Text enclosed with @code{\*@{} and @code{\*@}} is printed as a
superscript.
@endDefstr

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

@node Lists in ms, Indentation values in ms, Highlighting in ms, ms Body Text
@subsubsection Lists
@cindex @code{ms} macros, lists

The @code{IP} macro handles duties for all lists.

@Defmac {IP, [@Var{marker} [@Var{width}]], ms}
The @var{marker} is usually a bullet glyph (@code{\[bu]}) for unordered
lists, a number (or auto-incrementing number register) for numbered
lists, or a word or phrase for indented (glossary-style) lists.

The @var{width} specifies the indentation for the body of each list
item; its default unit is @samp{n}.  Once specified, the indentation
remains the same for all list items in the document until specified
again.

The @code{PORPHANS} register (@pxref{ms Document Control Registers})
operates in conjunction with the @code{IP} macro, to inhibit the
printing of orphaned list markers at the bottom of any page.
@endDefmac

The following is an example of a bulleted list.
@cindex example markup, bulleted list [@code{ms}]
@cindex bulleted list, example markup [@code{ms}]

@Example
A bulleted list:
.IP \[bu] 2
lawyers
.IP \[bu]
guns
.IP \[bu]
money
@endExample

Produces:

@Example
A bulleted list:

o lawyers

o guns

o money
@endExample

The following is an example of a numbered list.
@cindex example markup, numbered list [@code{ms}]
@cindex numbered list, example markup [@code{ms}]

@Example
.nr step 1 1
A numbered list:
.IP \n[step] 3
lawyers
.IP \n+[step]
guns
.IP \n+[step]
money
@endExample

Produces:

@Example
A numbered list:

1. lawyers

2. guns

3. money
@endExample

Note the use of the auto-incrementing number register in this example.

The following is an example of a glossary-style list.
@cindex example markup, glossary-style list [@code{ms}]
@cindex glossary-style list, example markup [@code{ms}]

@Example
A glossary-style list:
.IP lawyers 0.4i
Two or more attorneys.
.IP guns
Firearms, preferably
large-caliber.
.IP money
Gotta pay for those
lawyers and guns!
@endExample

Produces:

@Example
A glossary-style list:

lawyers
      Two or more attorneys.

guns  Firearms, preferably large-caliber.

money
      Gotta pay for those lawyers and guns!
@endExample

In the last example, the @code{IP} macro places the definition on the
same line as the term if it has enough space; otherwise, it breaks to
the next line and starts the definition below the term.  This may or may
not be the effect you want, especially if some of the definitions break
and some do not.  The following examples show two possible ways to force
a break.

The first workaround uses the @code{br} request to force a break after
printing the term or label.

@Example
@cartouche
A glossary-style list:
.IP lawyers 0.4i
Two or more attorneys.
.IP guns
.br
Firearms, preferably large-caliber.
.IP money
Gotta pay for those lawyers and guns!
@end cartouche
@endExample

The second workaround uses the @code{\p} escape to force the break.
Note the space following the escape; this is important.  If you omit the
space, @code{groff} prints the first word on the same line as the term
or label (if it fits) @strong{then} breaks the line.

@Example
@cartouche
A glossary-style list:
.IP lawyers 0.4i
Two or more attorneys.
.IP guns
\p Firearms, preferably large-caliber.
.IP money
Gotta pay for those lawyers and guns!
@end cartouche
@endExample

To set nested lists, use the @code{RS} and @code{RE} macros.
@xref{Indentation values in ms}, for more information.
@cindex @code{ms} macros, nested lists
@cindex nested lists [@code{ms}]

For example:

@Example
@cartouche
.IP \[bu] 2
Lawyers:
.RS
.IP \[bu]
Dewey,
.IP \[bu]
Cheatham,
.IP \[bu]
and Howe.
.RE
.IP \[bu]
Guns
@end cartouche
@endExample

Produces:

@Example
o Lawyers:

  o  Dewey,

  o  Cheatham,

  o  and Howe.

o Guns
@endExample

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

@node Indentation values in ms, Tabstops in ms, Lists in ms, ms Body Text
@subsubsection Indentation values

In many situations, you may need to indentation a section of text while
still wrapping and filling.  @xref{Lists in ms}, for an example of
nested lists.

@DefmacList {RS, , ms}
@DefmacListEnd {RE, , ms}
These macros begin and end an indented section.  The @code{PI} register
controls the amount of indentation, allowing the indented text to line
up under hanging and indented paragraphs.
@endDefmac

@xref{ms Displays and Keeps}, for macros to indentation and turn off
filling.

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

@node Tabstops in ms, ms Displays and Keeps, Indentation values in ms, ms Body Text
@subsubsection Tab Stops

Use the @code{ta} request to define tab stops as needed.  @xref{Tabs and
Fields}.

@Defmac {TA, , ms}
Use this macro to reset the tab stops to the default for @file{ms}
(every 5n).  You can redefine the @code{TA} macro to create a different
set of default tab stops.
@endDefmac

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

@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
@subsubsection Displays and keeps
@cindex @code{ms} macros, displays
@cindex @code{ms} macros, keeps
@cindex keeps [@code{ms}]
@cindex displays [@code{ms}]

Use displays to show text-based examples or figures (such as code
listings).

Displays turn off filling, so lines of code are displayed as-is without
inserting @code{br} requests in between each line.  Displays can be
@dfn{kept} on a single page, or allowed to break across pages.

@DefmacList {DS, @t{L}, ms}
@DefmacItem {LD, , ms}
@DefmacListEnd {DE, , ms}
Left-justified display.  The @samp{.DS L} call generates a page break,
if necessary, to keep the entire display on one page.  The @code{LD}
macro allows the display to break across pages.  The @code{DE} macro
ends the display.
@endDefmac

@DefmacList {DS, @t{I}, ms}
@DefmacItem {ID, , ms}
@DefmacListEnd {DE, , ms}
Indents the display as defined by the @code{DI} register.  The @samp{.DS
I} call generates a page break, if necessary, to keep the entire display
on one page.  The @code{ID} macro allows the display to break across
pages.  The @code{DE} macro ends the display.
@endDefmac

@DefmacList {DS, @t{B}, ms}
@DefmacItem {BD, , ms}
@DefmacListEnd {DE, , ms}
Sets a block-centered display: the entire display is left-justified, but
indented so that the longest line in the display is centered on the
page.  The @samp{.DS B} call generates a page break, if necessary, to
keep the entire display on one page.  The @code{BD} macro allows the
display to break across pages.  The @code{DE} macro ends the display.
@endDefmac

@DefmacList {DS, @t{C}, ms}
@DefmacItem {CD, , ms}
@DefmacListEnd {DE, , ms}
Sets a centered display: each line in the display is centered.  The
@samp{.DS C} call generates a page break, if necessary, to keep the
entire display on one page.  The @code{CD} macro allows the display to
break across pages.  The @code{DE} macro ends the display.
@endDefmac

@DefmacList {DS, @t{R}, ms}
@DefmacItem {RD, , ms}
@DefmacListEnd {DE, , ms}
Right-justifies each line in the display.  The @samp{.DS R} call
generates a page break, if necessary, to keep the entire display on one
page.  The @code{RD} macro allows the display to break across pages.
The @code{DE} macro ends the display.
@endDefmac

@DefmacList {Ds, , ms}
@DefmacListEnd {De, , ms}
These two macros were formerly provided as aliases for @code{DS} and
@code{DE}, respectively.  They have been removed, and should no longer
be used.  The original implementations of @code{DS} and @code{DE} are
retained, and should be used instead.  X11 documents which actually use
@code{Ds} and @code{De} always load a specific macro file from the X11
distribution (@file{macros.t}) which provides proper definitions for the
two macros.
@endDefmac

On occasion, you may want to @dfn{keep} other text together on a page.
For example, you may want to keep two paragraphs together, or a
paragraph that refers to a table (or list, or other item) immediately
following.  The @file{ms} macros provide the @code{KS} and @code{KE}
macros for this purpose.

@DefmacList {KS, , ms}
@DefmacListEnd {KE, , ms}
The @code{KS} macro begins a block of text to be kept on a single page,
and the @code{KE} macro ends the block.
@endDefmac

@DefmacList {KF, , ms}
@DefmacListEnd {KE, , ms}
Specifies a @dfn{floating keep}; if the keep cannot fit on the current
page, @code{groff} holds the contents of the keep and allows text
following the keep (in the source file) to fill in the remainder of the
current page.  When the page breaks, whether by an explicit @code{bp}
request or by reaching the end of the page, @code{groff} prints the
floating keep at the top of the new page.  This is useful for printing
large graphics or tables that do not need to appear exactly where
specified.
@endDefmac

You can also use the @code{ne} request to force a page break if there is
not enough vertical space remaining on the page.

Use the following macros to draw a box around a section of text (such as
a display).

@DefmacList {B1, , ms}
@DefmacListEnd {B2, , ms}
Marks the beginning and ending of text that is to have a box drawn
around it.  The @code{B1} macro begins the box; the @code{B2} macro ends
it.  Text in the box is automatically placed in a diversion (keep).
@endDefmac

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

@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
@subsubsection Tables, figures, equations, and references
@cindex @code{ms} macros, tables
@cindex @code{ms} macros, figures
@cindex @code{ms} macros, equations
@cindex @code{ms} macros, references
@cindex tables [@code{ms}]
@cindex figures [@code{ms}]
@cindex equations [@code{ms}]
@cindex references [@code{ms}]

The @file{ms} macros support the standard @code{groff} preprocessors:
@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
@pindex tbl
@pindex pic
@pindex eqn
@pindex refer
You mark text meant for preprocessors by enclosing it in pairs of tags
as follows.

@DefmacList {TS, [@code{H}], ms}
@DefmacListEnd {TE, , ms}
Denotes a table, to be processed by the @code{tbl} preprocessor.  The
optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} to
create a running header with the information up to the @code{TH} macro.
@code{groff} prints the header at the beginning of the table; if the
table runs onto another page, @code{groff} prints the header on the next
page as well.
@endDefmac

@DefmacList {PS, , ms}
@DefmacListEnd {PE, , ms}
Denotes a graphic, to be processed by the @code{pic} preprocessor.  You
can create a @code{pic} file by hand, using the @acronym{AT&T}
@code{pic} manual available on the Web as a reference, or by using a
graphics program such as @code{xfig}.
@endDefmac

@DefmacList {EQ, [@Var{align}], ms}
@DefmacListEnd {EN, , ms}
Denotes an equation, to be processed by the @code{eqn} preprocessor.
The optional @var{align} argument can be @code{C}, @code{L},
or@tie{}@code{I} to center (the default), left-justify, or indent the
equation.
@endDefmac

@DefmacList {[, , ms}
@DefmacListEnd {], , ms}
Denotes a reference, to be processed by the @code{refer} preprocessor.
The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive
reference to the preprocessor and the format of the bibliographic
database.
@endDefmac

@menu
* Example multi-page table::
@end menu

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

@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
@subsubsection An example multi-page table
@cindex example markup, multi-page table [@code{ms}]
@cindex multi-page table, example markup [@code{ms}]

The following is an example of how to set up a table that may print
across two or more pages.

@Example
@cartouche
.TS H
allbox expand;
cb | cb .
Text      ...of heading...
_
.TH
.T&
l | l .
... the rest of the table follows...
.CW
.TE
@end cartouche
@endExample

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

@node ms Footnotes,  , Example multi-page table, ms Body Text
@subsubsection Footnotes
@cindex @code{ms} macros, footnotes
@cindex footnotes [@code{ms}]

The @file{ms} macro package has a flexible footnote system.  You can
specify either numbered footnotes or symbolic footnotes (that is, using
a marker such as a dagger symbol).

@Defstr {*, ms}
Specifies the location of a numbered footnote marker in the text.
@endDefesc

@DefmacList {FS, , ms}
@DefmacListEnd {FE, , ms}
Specifies the text of the footnote.  The default action is to create a
numbered footnote; you can create a symbolic footnote by specifying a
@dfn{mark} glyph (such as @code{\[dg]} for the dagger glyph) in the body
text and as an argument to the @code{FS} macro, followed by the text of
the footnote and the @code{FE} macro.
@endDefmac

You can control how @code{groff} prints footnote numbers by changing the
value of the @code{FF} register.  @xref{ms Document Control Registers}.

@cindex footnotes, and keeps [@code{ms}]
@cindex keeps, and footnotes [@code{ms}]
@cindex footnotes, and displays [@code{ms}]
@cindex displays, and footnotes [@code{ms}]
Footnotes can be safely used within keeps and displays, but you should
avoid using numbered footnotes within floating keeps.  You can set a
second @code{\**} marker between a @code{\**} and its corresponding
@code{.FS} entry; as long as each @code{FS} macro occurs @emph{after}
the corresponding @code{\**} and the occurrences of @code{.FS} are in
the same order as the corresponding occurrences of @code{\**}.

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

@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
@subsection Page layout
@cindex @code{ms} macros, page layout
@cindex page layout [@code{ms}]

The default output from the @file{ms} macros provides a minimalist page
layout: it prints a single column, with the page number centered at the
top of each page.  It prints no footers.

You can change the layout by setting the proper number registers and
strings.

@menu
* ms Headers and Footers::
* ms Margins::
* ms Multiple Columns::
* ms TOC::
* ms Strings and Special Characters::
@end menu

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

@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
@subsubsection Headers and footers
@cindex @code{ms} macros, headers
@cindex @code{ms} macros, footers
@cindex headers [@code{ms}]
@cindex footers [@code{ms}]

For documents that do not distinguish between odd and even pages, set
the following strings:

@DefstrList {LH, ms}
@DefstrItem {CH, ms}
@DefstrListEnd {RH, ms}
Sets the left, center, and right headers.
@endDefstr

@DefstrList {LF, ms}
@DefstrItem {CF, ms}
@DefstrListEnd {RF, ms}
Sets the left, center, and right footers.
@endDefstr

For documents that need different information printed in the even and
odd pages, use the following macros:

@DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
@DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
@DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
@DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
The @code{OH} and @code{EH} macros define headers for the odd and even
pages; the @code{OF} and @code{EF} macros define footers for the odd and
even pages.  This is more flexible than defining the individual strings.

You can replace the quote (@code{'}) marks with any character not
appearing in the header or footer text.
@endDefmac

To specify custom header and footer processing, redefine the following
macros:

@DefmacList {PT,, ms}
@DefmacItem {HD,, ms}
@DefmacListEnd {BT,, ms}
The @code{PT} macro defines a custom header; the @code{BT} macro defines
a custom footer.  These macros must handle odd/even/first page
differences if necessary.

The @code{HD} macro defines additional header processing to take place
after executing the @code{PT} macro.
@endDefmac

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

@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
@subsubsection Margins
@cindex @code{ms} macros, margins

You control margins using a set of number registers.  @xref{ms Document
Control Registers}, for details.

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

@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
@subsubsection Multiple columns
@cindex @code{ms} macros, multiple columns
@cindex multiple columns [@code{ms}]

The @file{ms} macros can set text in as many columns as do reasonably
fit on the page.  The following macros are available; all of them force
a page break if a multi-column mode is already set.  However, if the
current mode is single-column, starting a multi-column mode does
@emph{not} force a page break.

@Defmac {1C, , ms}
Single-column mode.
@endDefmac

@Defmac {2C, , ms}
Two-column mode.
@endDefmac

@Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
Multi-column mode.  If you specify no arguments, it is equivalent to the
@code{2C} macro.  Otherwise, @var{width} is the width of each column and
@var{gutter} is the space between columns.  The @code{MINGW} number
register controls the default gutter width.
@endDefmac

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

@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
@subsubsection Creating a table of contents
@cindex @code{ms} macros, creating table of contents
@cindex table of contents, creating [@code{ms}]

The facilities in the @file{ms} macro package for creating a table of
contents are semi-automated at best.  Assuming that you want the table
of contents to consist of the document's headings, you need to repeat
those headings wrapped in @code{XS} and @code{XE} macros.

@DefmacList {XS, [@Var{page}], ms}
@DefmacItem {XA, [@Var{page}], ms}
@DefmacListEnd {XE, , ms}
These macros define a table of contents or an individual entry in the
table of contents, depending on their use.  The macros are very simple;
they cannot indent a heading based on its level.  The easiest way to
work around this is to add tabs to the table of contents string.  The
following is an example:

@Example
@cartouche
.NH 1
Introduction
.XS
Introduction
.XE
.LP
...
.CW
.NH 2
Methodology
.XS
Methodology
.XE
.LP
...
@end cartouche
@endExample

You can manually create a table of contents by beginning with the
@code{XS} macro for the first entry, specifying the page number for that
entry as the argument to @code{XS}.  Add subsequent entries using the
@code{XA} macro, specifying the page number for that entry as the
argument to @code{XA}.  The following is an example:

@Example
@cartouche
.XS 1
Introduction
.XA 2
A Brief History of the Universe
.XA 729
Details of Galactic Formation
...
.XE
@end cartouche
@endExample
@endDefmac

@Defmac {TC, [@code{no}], ms}
Prints the table of contents on a new page, setting the page number
to@tie{}@strong{i} (Roman lowercase numeral one).  You should usually
place this macro at the end of the file, since @code{groff} is a
single-pass formatter and can only print what has been collected up to
the point that the @code{TC} macro appears.

The optional argument @code{no} suppresses printing the title specified
by the string register @code{TOC}.
@endDefmac

@Defmac {PX, [@code{no}], ms}
Prints the table of contents on a new page, using the current page
numbering sequence.  Use this macro to print a manually-generated table
of contents at the beginning of your document.

The optional argument @code{no} suppresses printing the title specified
by the string register @code{TOC}.
@endDefmac

The @cite{Groff and Friends HOWTO} includes a @code{sed} script that
automatically inserts @code{XS} and @code{XE} macro entries after each
heading in a document.

Altering the @code{NH} macro to automatically build the table of
contents is perhaps initially more difficult, but would save a great
deal of time in the long run if you use @file{ms} regularly.

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

@node ms Strings and Special Characters,  , ms TOC, ms Page Layout
@subsubsection Strings and Special Characters
@cindex @code{ms} macros, strings
@cindex @code{ms} macros, special characters
@cindex @code{ms} macros, accent marks
@cindex accent marks [@code{ms}]
@cindex special characters [@code{ms}]
@cindex strings [@code{ms}]

The @file{ms} macros provide the following predefined strings.  You can
change the string definitions to help in creating documents in languages
other than English.

@Defstr {REFERENCES, ms}
Contains the string printed at the beginning of the references
(bibliography) page.  The default is @samp{References}.
@endDefstr

@Defstr {ABSTRACT, ms}
Contains the string printed at the beginning of the abstract.  The
default is @samp{ABSTRACT}.
@endDefstr

@Defstr {TOC, ms}
Contains the string printed at the beginning of the table of contents.
@endDefstr

@DefstrList {MONTH1, ms}
@DefstrItem {MONTH2, ms}
@DefstrItem {MONTH3, ms}
@DefstrItem {MONTH4, ms}
@DefstrItem {MONTH5, ms}
@DefstrItem {MONTH6, ms}
@DefstrItem {MONTH7, ms}
@DefstrItem {MONTH8, ms}
@DefstrItem {MONTH9, ms}
@DefstrItem {MONTH10, ms}
@DefstrItem {MONTH11, ms}
@DefstrListEnd {MONTH12, ms}
Prints the full name of the month in dates.  The default is
@samp{January}, @samp{February}, etc.
@endDefstr

The following special characters are available@footnote{For an
explanation what special characters are see @ref{Special Characters}.}:

@Defstr {-, ms}
Prints an em dash.
@endDefstr

@DefstrList {Q, ms}
@DefstrListEnd {U, ms}
Prints typographer's quotes in troff, and plain quotes in nroff.
@code{\*Q} is the left quote and @code{\*U} is the right quote.
@endDefstr

Improved accent marks are available in the @file{ms} macros.

@Defmac {AM, , ms}
Specify this macro at the beginning of your document to enable extended
accent marks and special characters.  This is a Berkeley extension.

To use the accent marks, place them @strong{after} the character being
accented.

Note that groff's native support for accents is superior to the
following definitions.
@endDefmac

The following accent marks are available after invoking the @code{AM}
macro:

@Defstr {\', ms}
Acute accent.
@endDefstr

@Defstr {\`, ms}
Grave accent.
@endDefstr

@Defstr {^, ms}
Circumflex.
@endDefstr

@Defstr {\,, ms}
Cedilla.
@endDefstr

@Defstr {~, ms}
Tilde.
@endDefstr

@deffn String @t{\*[:]}
@ifnotinfo
@stindex : @r{[}ms@r{]}
@end ifnotinfo
@ifinfo
@stindex \*[@r{<colon>}] @r{[}ms@r{]}
@end ifinfo
Umlaut.
@end deffn

@Defstr {v, ms}
Hacek.
@endDefstr

@Defstr {_, ms}
Macron (overbar).
@endDefstr

@Defstr {., ms}
Underdot.
@endDefstr

@Defstr {o, ms}
Ring above.
@endDefstr

The following are standalone characters available after invoking the
@code{AM} macro:

@Defstr {?, ms}
Upside-down question mark.
@endDefstr

@Defstr {!, ms}
Upside-down exclamation point.
@endDefstr

@Defstr {8, ms}
German ß ligature.
@endDefstr

@Defstr {3, ms}
Yogh.
@endDefstr

@Defstr {Th, ms}
Uppercase thorn.
@endDefstr

@Defstr {th, ms}
Lowercase thorn.
@endDefstr

@Defstr {D-, ms}
Uppercase eth.
@endDefstr

@Defstr {d-, ms}
Lowercase eth.
@endDefstr

@Defstr {q, ms}
Hooked o.
@endDefstr

@Defstr {ae, ms}
Lowercase æ ligature.
@endDefstr

@Defstr {Ae, ms}
Uppercase Æ ligature.
@endDefstr

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

@node Differences from AT&T ms, Naming Conventions, ms Page Layout, ms
@subsection Differences from @acronym{AT&T} @file{ms}
@cindex @code{ms} macros, differences from @acronym{AT&T}
@cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences

This section lists the (minor) differences between the @code{groff -ms}
macros and @acronym{AT&T} @code{troff -ms} macros.

@itemize @bullet
@item
The internals of @code{groff -ms} differ from the internals of
@acronym{AT&T} @code{troff -ms}.  Documents that depend upon
implementation details of @acronym{AT&T} @code{troff -ms} may not format
properly with @code{groff -ms}.

@item
The general error-handling policy of @code{groff -ms} is to detect and
report errors, rather than silently to ignore them.

@item
@code{groff -ms} does not work in compatibility mode (this is, with the
@option{-C} option).

@item
There is no special support for typewriter-like devices.

@item
@code{groff -ms} does not provide cut marks.

@item
Multiple line spacing is not supported.  Use a larger vertical spacing
instead.

@item
Some @acronym{UNIX} @code{ms} documentation says that the @code{CW} and
@code{GW} number registers can be used to control the column width and
gutter width, respectively.  These number registers are not used in
@code{groff -ms}.

@item
Macros that cause a reset (paragraphs, headings, etc.@:) may change the
indentation.  Macros that change the indentation do not increment or
decrement the indentation, but rather set it absolutely.  This can cause
problems for documents that define additional macros of their own.  The
solution is to use not the @code{in} request but instead the @code{RS}
and @code{RE} macros.

@item
To make @code{groff -ms} use the default page offset (which also
specifies the left margin), the @code{PO} register must stay undefined
until the first @file{-ms} macro is evaluated.  This implies that
@code{PO} should not be used early in the document, unless it is changed
also: Remember that accessing an undefined register automatically
defines it.
@end itemize

@Defmpreg {GS, ms}
This number register is set to@tie{}1 by the @code{groff -ms} macros,
but it is not used by the @code{AT&T} @code{troff -ms} macros.
Documents that need to determine whether they are being formatted with
@code{AT&T} @code{troff -ms} or @code{groff -ms} should use this number
register.
@endDefmpreg

Emulations of a few ancient Bell Labs macros can be re-enabled by
calling the otherwise undocumented @code{SC} section-header macro.
Calling @code{SC} enables @code{UC} for marking up a product or
application name, and the pair @code{P1}/@code{P2} for surrounding code
example displays.

These are not enabled by default because (a)@tie{}they were not
documented, in the original @code{ms} manual, and (b)@tie{}the @code{P1}
and @code{UC} macros collide with different macros with the same names
in the Berkeley version of @code{ms}.

These @code{groff} emulations are sufficient to give back the 1976
Kernighan@tie{}& Cherry paper @cite{Typsetting Mathematics -- User's
Guide} its section headings, and restore some text that had gone missing
as arguments of undefined macros.  No warranty express or implied is
given as to how well the typographic details these produce match the
original Bell Labs macros.

@menu
* Missing ms Macros::
* Additional ms Macros::
@end menu

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

@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
@subsubsection @code{troff} macros not appearing in @code{groff}

Macros missing from @code{groff -ms} are cover page macros specific to
Bell Labs and Berkeley.  The macros known to be missing are:

@table @code
@item .TM
Technical memorandum; a cover sheet style

@item .IM
Internal memorandum; a cover sheet style

@item .MR
Memo for record; a cover sheet style

@item .MF
Memo for file; a cover sheet style

@item .EG
Engineer's notes; a cover sheet style

@item .TR
Computing Science Tech Report; a cover sheet style

@item .OK
Other keywords

@item .CS
Cover sheet information

@item .MH
A cover sheet macro
@end table

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

@node Additional ms Macros,  , Missing ms Macros, Differences from AT&T ms
@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff}

The @code{groff -ms} macros have a few minor extensions compared to the
@acronym{AT&T} @code{troff -ms} macros.

@Defmac {AM, , ms}
Improved accent marks.  @xref{ms Strings and Special Characters}, for
details.
@endDefmac

@Defmac {DS, @t{I}, ms}
Indented display.  The default behavior of @acronym{AT&T} @code{troff
-ms} was to indent; the @code{groff} default prints displays flush left
with the body text.
@endDefmac

@Defmac {CW, , ms}
Print text in @code{constant width} (Courier) font.
@endDefmac

@Defmac {IX, , ms}
Indexing term (printed on standard error).  You can write a script to
capture and process an index generated in this manner.
@endDefmac

The following additional number registers
appear in @code{groff -ms}:

@Defmpreg {MINGW, ms}
Specifies a minimum space between columns (for multi-column output);
this takes the place of the @code{GW} register that was documented but
apparently not implemented in @acronym{AT&T} @code{troff}.
@endDefmpreg

Several new string registers are available as well.  You can change
these to handle (for example) the local language.  @xref{ms Strings and
Special Characters}, for details.

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

@node Naming Conventions,  , Differences from AT&T ms, ms
@subsection Naming Conventions
@cindex @code{ms} macros, naming conventions
@cindex naming conventions, @code{ms} macros

The following conventions are used for names of macros, strings and
number registers.  External names available to documents that use the
@code{groff -ms} macros contain only uppercase letters and digits.

Internally the macros are divided into modules; naming conventions are
as follows:

@itemize @bullet
@item
Names used only within one module are of the form
@var{module}@code{*}@var{name}.

@item
Names used outside the module in which they are defined are of the form
@var{module}@code{@@}@var{name}.

@item
Names associated with a particular environment are of the form
@var{environment}@code{:}@var{name}; these are used only within the
@code{par} module.

@item
@var{name} does not have a module prefix.

@item
Constructed names used to implement arrays are of the form
@var{array}@code{!}@var{index}.
@end itemize

Thus the groff ms macros reserve the following names:

@itemize @bullet
@item
Names containing the characters @code{*}, @code{@@}, and@tie{}@code{:}.

@item
Names containing only uppercase letters and digits.
@end itemize


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

@node me, mm, ms, Macro Packages
@section @file{me}
@cindex @code{me} macro package

@c XXX documentation
@c XXX this is a placeholder until we get stuff knocked into shape
See the @file{meintro.me} and @file{meref.me} documents in groff's
@file{doc} directory.


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

@node mm,  , me, Macro Packages
@section @file{mm}
@cindex @code{mm} macro package

@c XXX documentation
@c XXX this is a placeholder until we get stuff knocked into shape
See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at the
command line).


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

@node gtroff Reference, Preprocessors, Macro Packages, Top
@chapter @code{gtroff} Reference
@cindex reference, @code{gtroff}
@cindex @code{gtroff}, reference

This chapter covers @strong{all} of the facilities of @code{gtroff}.
Users of macro packages may skip it if not interested in details.


@menu
* Text::
* Measurements::
* Expressions::
* Identifiers::
* Embedded Commands::
* Registers::
* Manipulating Filling and Adjusting::
* Manipulating Hyphenation::
* Manipulating Spacing::
* Tabs and Fields::
* Character Translations::
* Troff and Nroff Mode::
* Line Layout::
* Line Control::
* Page Layout::
* Page Control::
* Fonts and Symbols::
* Sizes::
* Strings::
* Conditionals and Loops::
* Writing Macros::
* Page Motions::
* Drawing Requests::
* Traps::
* Diversions::
* Environments::
* Suppressing output::
* Colors::
* I/O::
* Postprocessor Access::
* Miscellaneous::
* Gtroff Internals::
* Debugging::
* Implementation Differences::
@end menu


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

@node Text, Measurements, gtroff Reference, gtroff Reference
@section Text
@cindex text, @code{gtroff} processing

@code{gtroff} input files contain text with control commands
interspersed throughout.  But, even without control codes, @code{gtroff}
still does several things with the input text:

@itemize @bullet
@item
filling and adjusting

@item
adding additional space after sentences

@item
hyphenating

@item
inserting implicit line breaks
@end itemize

@menu
* Filling and Adjusting::
* Hyphenation::
* Sentences::
* Tab Stops::
* Implicit Line Breaks::
* Input Conventions::
* Input Encodings::
@end menu

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

@node Filling and Adjusting, Hyphenation, Text, Text
@subsection Filling and Adjusting
@cindex filling
@cindex adjusting

When @code{gtroff} reads text, it collects words from the input and fits
as many of them together on one output line as it can.  This is known as
@dfn{filling}.

@cindex leading spaces
@cindex spaces, leading and trailing
@cindex extra spaces
@cindex trailing spaces
Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} it.
This means it widens the spacing between words until the text reaches
the right margin (in the default adjustment mode).  Extra spaces between
words are preserved, but spaces at the end of lines are ignored.  Spaces
at the front of a line cause a @dfn{break} (breaks are explained in
@ref{Implicit Line Breaks}).

@xref{Manipulating Filling and Adjusting}.

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

@node Hyphenation, Sentences, Filling and Adjusting, Text
@subsection Hyphenation
@cindex hyphenation

Since the odds are not great for finding a set of words, for every
output line, which fit nicely on a line without inserting excessive
amounts of space between words, @code{gtroff} hyphenates words so that
it can justify lines without inserting too much space between words.  It
uses an internal hyphenation algorithm (a simplified version of the
algorithm used within @TeX{}) to indicate which words can be hyphenated
and how to do so.  When a word is hyphenated, the first part of the word
is added to the current filled line being output (with an attached
hyphen), and the other portion is added to the next line to be filled.

@xref{Manipulating Hyphenation}.

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

@node Sentences, Tab Stops, Hyphenation, Text
@subsection Sentences
@cindex sentences

Although it is often debated, some typesetting rules say there should be
different amounts of space after various punctuation marks.  For
example, the @cite{Chicago typsetting manual} says that a period at the
end of a sentence should have twice as much space following it as would
a comma or a period as part of an abbreviation.

@c XXX exact citation of Chicago manual

@cindex sentence space
@cindex space between sentences
@cindex french-spacing
@code{gtroff} does this by flagging certain characters (normally
@samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
When @code{gtroff} encounters one of these characters at the end of a
line, it appends a normal space followed by a @dfn{sentence space} in
the formatted output.  (This justifies one of the conventions mentioned
in @ref{Input Conventions}.)

@cindex transparent characters
@cindex character, transparent
@cindex @code{dg} glyph, at end of sentence
@cindex @code{rq} glyph, at end of sentence
@cindex @code{"}, at end of sentence
@cindex @code{'}, at end of sentence
@cindex @code{)}, at end of sentence
@cindex @code{]}, at end of sentence
@cindex @code{*}, at end of sentence
In addition, the following characters and symbols are treated
transparently while handling end-of-sentence characters: @samp{"},
@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}.

See the @code{cflags} request in @ref{Using Symbols}, for more details.

@cindex @code{\&}, at end of sentence
To prevent the insertion of extra space after an end-of-sentence
character (at the end of a line), append @code{\&}.

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

@node Tab Stops, Implicit Line Breaks, Sentences, Text
@subsection Tab Stops
@cindex tab stops
@cindex stops, tabulator
@cindex tab character
@cindex character, tabulator

@cindex @acronym{EBCDIC} encoding
@cindex encoding, @acronym{EBCDIC}
@code{gtroff} translates @dfn{tabulator characters}, also called
@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
@acronym{EBCDIC} @code{0x05}), in the input into movements to the next
tabulator stop.  These tab stops are initially located every half inch
across the page.  Using this, simple tables can be made easily.
However, it can often be deceptive as the appearance (and width) of the
text on a terminal and the results from @code{gtroff} can vary greatly.

Also, a possible sticking point is that lines beginning with tab
characters are still filled, again producing unexpected results.  For
example, the following input

@multitable {12345678} {12345678} {12345678} {12345678}
@item
@tab 1 @tab 2 @tab 3
@item
@tab   @tab 4 @tab 5
@end multitable

@noindent
produces

@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
@item
@tab 1 @tab 2 @tab 3 @tab   @tab 4 @tab 5
@end multitable

@xref{Tabs and Fields}.

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

@node Implicit Line Breaks, Input Conventions, Tab Stops, Text
@subsection Implicit Line Breaks
@cindex implicit line breaks
@cindex implicit breaks of lines
@cindex line, implicit breaks
@cindex break, implicit
@cindex line break

An important concept in @code{gtroff} is the @dfn{break}.  When a break
occurs, @code{gtroff} outputs the partially filled line (unjustified),
and resumes collecting and filling text on the next output line.

@cindex blank line
@cindex empty line
@cindex line, blank
@cindex blank line macro (@code{blm})
There are several ways to cause a break in @code{gtroff}.  A blank line
not only causes a break, but it also outputs a one-line vertical space
(effectively a blank line).  Note that this behaviour can be modified
with the blank line macro request @code{blm}.  @xref{Blank Line Traps}.

@cindex fill mode
@cindex mode, fill
A line that begins with a space causes a break and the space is output
at the beginning of the next line.  Note that this space isn't adjusted,
even in fill mode.

The end of file also causes a break -- otherwise the last line of the
document may vanish!

Certain requests also cause breaks, implicitly or explicitly.  This is
discussed in @ref{Manipulating Filling and Adjusting}.

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

@node Input Conventions, Input Encodings, Implicit Line Breaks, Text
@subsection Input Conventions
@cindex input conventions
@cindex conventions for input

Since @code{gtroff} does filling automatically, it is traditional in
@code{groff} not to try and type things in as nicely formatted
paragraphs.  These are some conventions commonly used when typing
@code{gtroff} text:

@itemize @bullet
@item
Break lines after punctuation, particularly at the end of a sentence and
in other logical places.  Keep separate phrases on lines by themselves,
as entire phrases are often added or deleted when editing.

@item
Try to keep lines less than 40-60@tie{}characters, to allow space for
inserting more text.

@item
Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
don't try using spaces to get proper indentation).
@end itemize

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

@node Input Encodings,  , Input Conventions, Text
@subsection Input Encodings

Currently, the following input encodings are available.

@table @asis
@item cp1047
@cindex encoding, input, @acronym{EBCDIC}
@cindex @acronym{EBCDIC}, input encoding
@cindex input encoding, @acronym{EBCDIC}
@cindex encoding, input, cp1047
@cindex cp1047, input encoding
@cindex input encoding, cp1047
@cindex IBM cp1047 input encoding
@pindex cp1047.tmac
This input encoding works only on @acronym{EBCDIC} platforms (and vice
versa, the other input encodings don't work with @acronym{EBCDIC}); the
file @file{cp1047.tmac} is by default loaded at start-up.

@item latin-1
@cindex encoding, input, @w{latin-1} (ISO @w{8859-1})
@cindex @w{latin-1} (ISO @w{8859-1}), input encoding
@cindex ISO @w{8859-1} (@w{latin-1}), input encoding
@cindex input encoding, @w{latin-1} (ISO @w{8859-1})
@pindex latin1.tmac
This is the default input encoding on non-@acronym{EBCDIC} platforms;
the file @file{latin1.tmac} is loaded at start-up.

@item latin-2
@cindex encoding, input, @w{latin-2} (ISO @w{8859-2})
@cindex @w{latin-2} (ISO @w{8859-2}), input encoding
@cindex ISO @w{8859-2} (@w{latin-2}), input encoding
@cindex input encoding, @w{latin-2} (ISO @w{8859-2})
@pindex latin2.tmac
To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very
beginning of your document or use @samp{-mlatin2} as a command line
argument for @code{groff}.

@item latin-5
@cindex encoding, input, @w{latin-5} (ISO @w{8859-9})
@cindex @w{latin-2} (ISO @w{8859-9}), input encoding
@cindex ISO @w{8859-9} (@w{latin-2}), input encoding
@cindex input encoding, @w{latin-2} (ISO @w{8859-9})
@pindex latin2.tmac
For Turkish.  Either say @w{@samp{.mso latin9.tmac}} at the very
beginning of your document or use @samp{-mlatin9} as a command line
argument for @code{groff}.

@item latin-9 (latin-0)
@cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15})
@cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding
@cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding
@cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15})
@pindex latin9.tmac
This encoding is intended (at least in Europe) to replace @w{latin-1}
encoding.  The main difference to @w{latin-1} is that @w{latin-9}
contains the Euro character.  To use this encoding, either say
@w{@samp{.mso latin9.tmac}} at the very beginning of your document or
use @samp{-mlatin9} as a command line argument for @code{groff}.
@end table

Note that it can happen that some input encoding characters are not
available for a particular output device.  For example, saying

@Example
groff -Tlatin1 -mlatin9 ...
@endExample

@noindent
fails if you use the Euro character in the input.  Usually, this
limitation is present only for devices which have a limited set of
output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other
devices it is usually sufficient to install proper fonts which contain
the necessary glyphs.

@pindex freeeuro.pfa
@pindex ec.tmac
Due to the importance of the Euro glyph in Europe, the groff package now
comes with a @sc{PostScript} font called @file{freeeuro.pfa} which
provides various glyph shapes for the Euro.  In other words,
@w{latin-9} encoding is supported for the @option{-Tps} device out of
the box (@w{latin-2} isn't).

By its very nature, @option{-Tutf8} supports all input encodings;
@option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the
command line @option{-mec} is used also to load the file @file{ec.tmac}
(which flips to the EC fonts).


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

@node Measurements, Expressions, Text, gtroff Reference
@section Measurements
@cindex measurements
@cindex scaling indicator
@cindex indicator, scaling

@cindex units of measurement
@cindex basic unit (@code{u})
@cindex machine unit (@code{u})
@cindex measurement unit
@cindex @code{u} unit
@cindex unit, @code{u}
@code{gtroff} (like many other programs) requires numeric parameters to
specify various measurements.  Most numeric parameters@footnote{those
that specify vertical or horizontal motion or a type size} may have a
@dfn{measurement unit} attached.  These units are specified as a single
character which immediately follows the number or expression.  Each of
these units are understood, by @code{gtroff}, to be a multiple of its
@dfn{basic unit}.  So, whenever a different measurement unit is
specified @code{gtroff} converts this into its @dfn{basic units}.  This
basic unit, represented by a @samp{u}, is a device dependent measurement
which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
inch.  The values may be given as fractional numbers; however,
fractional basic units are always rounded to integers.

Some of the measurement units are completely independent of any of the
current settings (e.g.@: type size) of @code{gtroff}.

@table @code
@item i
@cindex inch unit (@code{i})
@cindex @code{i} unit
@cindex unit, @code{i}
Inches.  An antiquated measurement unit still in use in certain
backwards countries with incredibly low-cost computer equipment.  One
inch is equal to@tie{}2.54@dmn{cm}.

@item c
@cindex centimeter unit (@code{c})
@cindex @code{c} unit
@cindex unit, @code{c}
Centimeters.  One centimeter is equal to@tie{}0.3937@dmn{in}.

@item p
@cindex point unit (@code{p})
@cindex @code{p} unit
@cindex unit, @code{p}
Points.  This is a typesetter's measurement used for measure type size.
It is 72@tie{}points to an inch.

@item P
@cindex pica unit (@code{P})
@cindex @code{P} unit
@cindex unit, @code{P}
Pica.  Another typesetting measurement.  6@tie{}Picas to an inch (and
12@tie{}points to a pica).

@item s
@itemx z
@cindex @code{s} unit
@cindex unit, @code{s}
@cindex @code{z} unit
@cindex unit, @code{z}
@xref{Fractional Type Sizes}, for a discussion of these units.

@item f
@cindex @code{f} unit
@cindex unit, @code{f}
Fractions.  Value is 65536.
@xref{Colors}, for usage.
@end table

The other measurements understood by @code{gtroff} depend on settings
currently in effect in @code{gtroff}.  These are very useful for
specifying measurements which should look proper with any size of text.

@table @code
@item m
@cindex em unit (@code{m})
@cindex @code{m} unit
@cindex unit, @code{m}
Ems.  This unit is equal to the current font size in points.  So called
because it is @emph{approximately} the width of the letter@tie{}@samp{m}
in the current font.

@item n
@cindex en unit (@code{n})
@cindex @code{n} unit
@cindex unit, @code{n}
Ens.  In @code{groff}, this is half of an em.

@item v
@cindex vertical space unit (@code{v})
@cindex space, vertical, unit (@code{v})
@cindex @code{v} unit
@cindex unit, @code{v}
Vertical space.  This is equivalent to the current line spacing.
@xref{Sizes}, for more information about this.

@item M
@cindex @code{M} unit
@cindex unit, @code{M}
100ths of an em.
@end table

@menu
* Default Units::
@end menu

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

@node Default Units,  , Measurements, Measurements
@subsection Default Units
@cindex default units
@cindex units, default

Many requests take a default unit.  While this can be helpful at times,
it can cause strange errors in some expressions.  For example, the line
length request expects em units.  Here are several attempts to get a
line length of 3.5@tie{}inches and their results:

@Example
3.5i      @result{}   3.5i
7/2       @result{}   0i
7/2i      @result{}   0i
(7 / 2)u  @result{}   0i
7i/2      @result{}   0.1i
7i/2u     @result{}   3.5i
@endExample

@noindent
Everything is converted to basic units first.  In the above example it
is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m}
equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}).  The value
7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
0.1@dmn{i}.  As can be seen, a scaling indicator after a closing
parenthesis is simply ignored.

@cindex measurements, specifying safely
Thus, the safest way to specify measurements is to always attach a
scaling indicator.  If you want to multiply or divide by a certain
scalar value, use @samp{u} as the unit for that value.


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

@node Expressions, Identifiers, Measurements, gtroff Reference
@section Expressions
@cindex expressions

@code{gtroff} has most arithmetic operators common to other languages:

@itemize @bullet
@item
@cindex arithmetic operators
@cindex operators, arithmetic
@opindex +
@opindex -
@opindex /
@opindex *
@opindex %
Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
(division), @samp{*} (multiplication), @samp{%} (modulo).

@code{gtroff} only provides integer arithmetic.  The internal type used
for computing results is @samp{int}, which is usually a 32@dmn{bit}
signed integer.

@item
@cindex comparison operators
@cindex operators, comparison
@opindex <
@opindex >
@opindex >=
@opindex <=
@opindex =
@opindex ==
Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
(less than or equal), @samp{>=} (greater than or equal), @samp{=}
(equal), @samp{==} (the same as @samp{=}).

@item
@cindex logical operators
@cindex operators, logical
@opindex &
@ifnotinfo
@opindex :
@end ifnotinfo
@ifinfo
@opindex @r{<colon>}
@end ifinfo
Logical: @samp{&} (logical and), @samp{:} (logical or).

@item
@cindex unary operators
@cindex operators, unary
@opindex -
@opindex +
@opindex !
@cindex @code{if} request, and the @samp{!} operator
@cindex @code{while} request, and the @samp{!} operator
Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
(just for completeness; does nothing in expressions), @samp{!} (logical
not; this works only within @code{if} and @code{while}
requests).@footnote{Note that, for example, @samp{!(-1)} evaluates to
`true' because @code{gtroff} treats both negative numbers and zero as
`false'.}  See below for the use of unary operators in motion requests.

@item
@cindex extremum operators (@code{>?}, @code{<?})
@cindex operators, extremum (@code{>?}, @code{<?})
@opindex >?
@opindex <?
Extrema: @samp{>?} (maximum), @samp{<?} (minimum).

Example:

@Example
.nr x 5
.nr y 3
.nr z (\n[x] >? \n[y])
@endExample

@noindent
The register@tie{}@code{z} now contains@tie{}5.

@item
@cindex scaling operator
@cindex operator, scaling
Scaling: @code{(@var{c};@var{e})}.  Evaluate@tie{}@var{e}
using@tie{}@var{c} as the default scaling indicator.  If @var{c} is
missing, ignore scaling indicators in the evaluation of@tie{}@var{e}.
@end itemize

@cindex parentheses
@cindex order of evaluation in expressions
@cindex expression, order of evaluation
@opindex (
@opindex )
Parentheses may be used as in any other language.  However, in
@code{gtroff} they are necessary to ensure order of evaluation.
@code{gtroff} has no operator precedence; expressions are evaluated left
to right.  This means that @code{gtroff} evaluates @samp{3+5*4} as if it
were parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might
be expected.

@cindex @code{+}, and page motion
@cindex @code{-}, and page motion
@cindex motion operators
@cindex operators, motion
For many requests which cause a motion on the page, the unary operators
@samp{+} and @samp{-} work differently if leading an expression.  They
then indicate a motion relative to the current position (down or up,
respectively).

@cindex @code{|}, and page motion
@cindex absolute position operator (@code{|})
@cindex position, absolute, operator (@code{|})
Similarly, a leading @samp{|} operator indicates an absolute position.
For vertical movements, it specifies the distance from the top of the
page; for horizontal movements, it gives the distance from the beginning
of the @emph{input} line.

@cindex @code{bp} request, using @code{+} and@tie{}@code{-}
@cindex @code{in} request, using @code{+} and@tie{}@code{-}
@cindex @code{ll} request, using @code{+} and@tie{}@code{-}
@cindex @code{lt} request, using @code{+} and@tie{}@code{-}
@cindex @code{nm} request, using @code{+} and@tie{}@code{-}
@cindex @code{nr} request, using @code{+} and@tie{}@code{-}
@cindex @code{pl} request, using @code{+} and@tie{}@code{-}
@cindex @code{pn} request, using @code{+} and@tie{}@code{-}
@cindex @code{po} request, using @code{+} and@tie{}@code{-}
@cindex @code{ps} request, using @code{+} and@tie{}@code{-}
@cindex @code{pvs} request, using @code{+} and@tie{}@code{-}
@cindex @code{rt} request, using @code{+} and@tie{}@code{-}
@cindex @code{ti} request, using @code{+} and@tie{}@code{-}
@cindex @code{\H}, using @code{+} and@tie{}@code{-}
@cindex @code{\R}, using @code{+} and@tie{}@code{-}
@cindex @code{\s}, using @code{+} and@tie{}@code{-}
@samp{+} and @samp{-} are also treated differently by the following
requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
@code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}.
Here, leading plus and minus signs indicate increments and decrements.

@xref{Setting Registers}, for some examples.

@Defesc {\\B, ', anything, '}
@cindex numeric expression, valid
@cindex valid numeric expression
Return@tie{}1 if @var{anything} is a valid numeric expression; or@tie{}0
if @var{anything} is empty or not a valid numeric expression.
@endDefesc

@cindex space characters, in expressions
@cindex expressions, and space characters
Due to the way arguments are parsed, spaces are not allowed in
expressions, unless the entire expression is surrounded by parentheses.

@xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}.


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

@node Identifiers, Embedded Commands, Expressions, gtroff Reference
@section Identifiers
@cindex identifiers

Like any other language, @code{gtroff} has rules for properly formed
@dfn{identifiers}.  In @code{gtroff}, an identifier can be made up of
almost any printable character, with the exception of the following
characters:

@itemize @bullet
@item
@cindex whitespace characters
@cindex newline character
@cindex character, whitespace
Whitespace characters (spaces, tabs, and newlines).

@item
@cindex character, backspace
@cindex backspace character
@cindex @acronym{EBCDIC} encoding of backspace
Backspace (@acronym{ASCII}@tie{}@code{0x08} or
@acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}.

@item
@cindex invalid input characters
@cindex input characters, invalid
@cindex characters, invalid input
@cindex Unicode
The following input characters are invalid and are ignored if
@code{groff} runs on a machine based on @acronym{ASCII}, causing a
warning message of type @samp{input} (see @ref{Debugging}, for more
details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
@code{0x80}-@code{0x9F}.

And here are the invalid input characters if @code{groff} runs on an
@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
@code{0x30}-@code{0x3F}.

Currently, some of these reserved codepoints are used internally, thus
making it non-trivial to extend @code{gtroff} to cover Unicode or other
character sets and encodings which use characters of these ranges.

Note that invalid characters are removed before parsing; an identifier
@code{foo}, followed by an invalid character, followed by @code{bar} is
treated as @code{foobar}.
@end itemize

For example, any of the following is valid.

@Example
br
PP
(l
end-list
@@_
@endExample

@cindex @code{]}, as part of an identifier
@noindent
Note that identifiers longer than two characters with a closing bracket
(@samp{]}) in its name can't be accessed with escape sequences which
expect an identifier as a parameter.  For example, @samp{\[foo]]}
accesses the glyph @samp{foo}, followed by @samp{]}, whereas
@samp{\C'foo]'} really asks for glyph @samp{foo]}.

@cindex @code{refer}, and macro names starting with @code{[} or @code{]}
@cindex @code{[}, macro names starting with, and @code{refer}
@cindex @code{]}, macro names starting with, and @code{refer}
@cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
To avoid problems with the @code{refer} preprocessor, macro names should
not start with @samp{[} or @samp{]}.  Due to backwards compatibility,
everything after @samp{.[} and @samp{.]} is handled as a special
argument to @code{refer}.  For example, @samp{.[foo} makes @code{refer}
to start a reference, using @samp{foo} as a parameter.

@Defesc {\\A, ', ident, '}
Test whether an identifier @var{ident} is valid in @code{gtroff}.  It
expands to the character@tie{}1 or@tie{}0 according to whether its
argument (usually delimited by quotes) is or is not acceptable as the
name of a string, macro, diversion, number register, environment, or
font.  It returns@tie{}0 if no argument is given.  This is useful for
looking up user input in some sort of associative table.

@Example
\A'end-list'
    @result{} 1
@endExample
@endDefesc

@xref{Escapes}, for details on parameter delimiting characters.

Identifiers in @code{gtroff} can be any length, but, in some contexts,
@code{gtroff} needs to be told where identifiers end and text begins
(and in different ways depending on their length):

@itemize @bullet
@item
Single character.

@cindex @code{(}, starting a two-character identifier
@item
Two characters.  Must be prefixed with @samp{(} in some situations.

@cindex @code{[}, starting an identifier
@cindex @code{]}, ending an identifier
@item
Arbitrary length (@code{gtroff} only).  Must be bracketed with @samp{[}
and@tie{}@samp{]} in some situations.  Any length identifier can be put
in brackets.
@end itemize

@cindex undefined identifiers
@cindex identifiers, undefined
Unlike many other programming languages, undefined identifiers are
silently ignored or expanded to nothing.  When @code{gtroff} finds an
undefined identifier, it emits a warning, doing the following:

@itemize @bullet
@item
If the identifier is a string, macro, or diversion, @code{gtroff}
defines it as empty.

@item
If the identifier is a number register, @code{gtroff} defines it with a
value of@tie{}0.
@end itemize

@xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}.

Note that macros, strings, and diversions share the same name space.

@Example
.de xxx
.  nop foo
..
.
.di xxx
bar
.br
.di
.
.xxx
    @result{} bar
@endExample

@noindent
As can be seen in the previous example, @code{gtroff} reuses the
identifier @samp{xxx}, changing it from a macro to a diversion.  No
warning is emitted!  The contents of the first macro definition is lost.

@xref{Interpolating Registers}, and @ref{Strings}.


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

@node Embedded Commands, Registers, Identifiers, gtroff Reference
@section Embedded Commands
@cindex embedded commands
@cindex commands, embedded

Most documents need more functionality beyond filling, adjusting and
implicit line breaking.  In order to gain further functionality,
@code{gtroff} allows commands to be embedded into the text, in two ways.

The first is a @dfn{request} which takes up an entire line, and does
some large-scale operation (e.g.@: break lines, start new pages).

The other is an @dfn{escape} which can be usually embedded anywhere in
the text; most requests can accept it even as an argument.  Escapes
generally do more minor operations like sub- and superscripts, print a
symbol, etc.

@menu
* Requests::
* Macros::
* Escapes::
@end menu

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

@node Requests, Macros, Embedded Commands, Embedded Commands
@subsection Requests
@cindex requests

@cindex control character (@code{.})
@cindex character, control (@code{.})
@cindex no-break control character (@code{'})
@cindex character, no-break control (@code{'})
@cindex control character, no-break (@code{'})
A request line begins with a control character, which is either a single
quote (@samp{'}, the @dfn{no-break control character}) or a period
(@samp{.}, the normal @dfn{control character}).  These can be changed;
see @ref{Character Translations}, for details.  After this there may be
optional tabs or spaces followed by an identifier which is the name of
the request.  This may be followed by any number of space-separated
arguments (@emph{no} tabs here).

@cindex structuring source code of documents or macro packages
@cindex documents, structuring the source code
@cindex macro packages, structuring the source code
Since a control character followed by whitespace only is ignored, it is
common practice to use this feature for structuring the source code of
documents or macro packages.

@Example
.de foo
.  tm This is foo.
..
.
.
.de bar
.  tm This is bar.
..
@endExample

@cindex blank line
@cindex blank line macro (@code{blm})
Another possibility is to use the blank line macro request @code{blm} by
assigning an empty macro to it.

@Example
.de do-nothing
..
.blm do-nothing  \" activate blank line macro

.de foo
.  tm This is foo.
..


.de bar
.  tm This is bar.
..

.blm             \" deactivate blank line macro
@endExample

@xref{Blank Line Traps}.

@cindex zero width space character (@code{\&})
@cindex character, zero width space (@code{\&})
@cindex space character, zero width (@code{\&})
@cindex @code{\&}, escaping control characters
To begin a line with a control character without it being interpreted,
precede it with @code{\&}.  This represents a zero width space, which
means it does not affect the output.

In most cases the period is used as a control character.  Several
requests cause a break implicitly; using the single quote control
character prevents this.

@Defreg {.br}
A read-only number register which is set to@tie{}1 if a macro is called
with the normal control character (as defined with the @code{cc}
request), and set to@tie{}0 otherwise.

@cindex modifying requests
@cindex requests, modifying
This allows to reliably modify requests.

@Example
.als bp*orig bp
.de bp
.  tm before bp
.  ie \\n[.br] .bp*orig
.  el 'bp*orig
.  tm after bp
..
@endExample

Using this register outside of a macro makes no sense (it always returns
zero in such cases).

If a macro is called as a string (this is, using @code{\*}), the value
of the @code{.br} register is inherited from the calling macro.
@endDefreg

@menu
* Request and Macro Arguments::
@end menu

@node Request and Macro Arguments,  , Requests, Requests
@subsubsection Request and Macro Arguments
@cindex request arguments
@cindex macro arguments
@cindex arguments to requests and macros

@cindex tabs, and macro arguments
@cindex macro arguments, and tabs
@cindex arguments to macros, and tabs
Arguments to requests and macros are processed much like the shell:
The line is split into arguments according to
spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows
tabs for argument separation -- @code{gtroff} intentionally doesn't
support this.}

@cindex spaces, in a macro argument
An argument to a macro which is intended to contain spaces can either be
enclosed in double quotes, or have the spaces @dfn{escaped} with
backslashes.  This is @emph{not} true for requests.

Here are a few examples for a hypothetical macro @code{uh}:

@Example
.uh The Mouse Problem
.uh "The Mouse Problem"
.uh The\ Mouse\ Problem
@endExample

@cindex @code{\~}, difference to @code{\@key{SP}}
@cindex @code{\@key{SP}}, difference to @code{\~}
@noindent
The first line is the @code{uh} macro being called with 3 arguments,
@samp{The}, @samp{Mouse}, and @samp{Problem}.  The latter two have the
same effect of calling the @code{uh} macro with one argument, @samp{The
Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
is ``classical'' in the sense that it can be found in most @code{troff}
documents.  Nevertheless, it is not optimal in all situations, since
@w{@samp{\ }} inserts a fixed-width, non-breaking space character which
can't stretch.  @code{gtroff} provides a different command @code{\~} to
insert a stretchable, non-breaking space.}

@cindex @code{"}, in a macro argument
@cindex double quote, in a macro argument
A double quote which isn't preceded by a space doesn't start a macro
argument.  If not closing a string, it is printed literally.

For example,

@Example
.xxx a" "b c" "de"fg"
@endExample

@noindent
has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
Don't rely on this obscure behaviour!

There are two possibilities to get a double quote reliably.

@itemize @bullet
@item
Enclose the whole argument with double quotes and use two consecutive
double quotes to represent a single one.  This traditional solution has
the disadvantage that double quotes don't survive argument expansion
again if called in compatibility mode (using the @option{-C} option of
@code{groff}):

@Example
.de xx
.  tm xx: `\\$1' `\\$2' `\\$3'
.
.  yy "\\$1" "\\$2" "\\$3"
..
.de yy
.  tm yy: `\\$1' `\\$2' `\\$3'
..
.xx A "test with ""quotes""" .
    @result{} xx: `A' `test with "quotes"' `.'
    @result{} yy: `A' `test with ' `quotes""'
@endExample

@noindent
If not in compatibility mode, you get the expected result

@Example
xx: `A' `test with "quotes"' `.'
yy: `A' `test with "quotes"' `.'
@endExample

@noindent
since @code{gtroff} preserves the input level.

@item
Use the double quote glyph @code{\(dq}.  This works with and without
compatibility mode enabled since @code{gtroff} doesn't convert
@code{\(dq} back to a double quote input character.

Note that this method won't work with @acronym{UNIX} @code{troff} in
general since the glyph `dq' isn't defined normally.
@end itemize

@cindex @code{ds} request, and double quotes
Double quotes in the @code{ds} request are handled differently.
@xref{Strings}, for more details.

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

@node Macros, Escapes, Requests, Embedded Commands
@subsection Macros
@cindex macros

@code{gtroff} has a @dfn{macro} facility for defining a series of lines
which can be invoked by name.  They are called in the same manner as
requests -- arguments also may be passed basically in the same manner.

@xref{Writing Macros}, and @ref{Request and Macro Arguments}.

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

@node Escapes,  , Macros, Embedded Commands
@subsection Escapes
@cindex escapes

Escapes may occur anywhere in the input to @code{gtroff}.  They usually
begin with a backslash and are followed by a single character which
indicates the function to be performed.  The escape character can be
changed; see @ref{Character Translations}.

Escape sequences which require an identifier as a parameter accept three
possible syntax forms.

@itemize @bullet
@item
The next single character is the identifier.

@cindex @code{(}, starting a two-character identifier
@item
If this single character is an opening parenthesis, take the following
two characters as the identifier.  Note that there is no closing
parenthesis after the identifier.

@cindex @code{[}, starting an identifier
@cindex @code{]}, ending an identifier
@item
If this single character is an opening bracket, take all characters
until a closing bracket as the identifier.
@end itemize

@noindent
Examples:

@Example
\fB
\n(XX
\*[TeX]
@endExample

@cindex @code{'}, delimiting arguments
@cindex argument delimiting characters
@cindex characters, argument delimiting
@cindex delimiting characters for arguments
Other escapes may require several arguments and/or some special format.
In such cases the argument is traditionally enclosed in single quotes
(and quotes are always used in this manual for the definitions of escape
sequences).  The enclosed text is then processed according to what that
escape expects.  Example:

@Example
\l'1.5i\(bu'
@endExample

@cindex @code{\o}, possible quote characters
@cindex @code{\b}, possible quote characters
@cindex @code{\X}, possible quote characters
Note that the quote character can be replaced with any other character
which does not occur in the argument (even a newline or a space
character) in the following escapes: @code{\o}, @code{\b}, and
@code{\X}.  This makes e.g.

@Example
A caf
\o
e\'


in Paris
  @result{} A café in Paris
@endExample

@noindent
possible, but it is better not to use this feature to avoid confusion.

@cindex @code{\%}, used as delimiter
@cindex @code{\@key{SP}}, used as delimiter
@cindex @code{\|}, used as delimiter
@cindex @code{\^}, used as delimiter
@cindex @code{\@{}, used as delimiter
@cindex @code{\@}}, used as delimiter
@cindex @code{\'}, used as delimiter
@cindex @code{\`}, used as delimiter
@cindex @code{\-}, used as delimiter
@cindex @code{\_}, used as delimiter
@cindex @code{\!}, used as delimiter
@cindex @code{\?}, used as delimiter
@cindex @code{\)}, used as delimiter
@cindex @code{\/}, used as delimiter
@cindex @code{\,}, used as delimiter
@cindex @code{\&}, used as delimiter
@ifnotinfo
@cindex @code{\:}, used as delimiter
@end ifnotinfo
@ifinfo
@cindex @code{\@r{<colon>}}, used as delimiter
@end ifinfo
@cindex @code{\~}, used as delimiter
@cindex @code{\0}, used as delimiter
@cindex @code{\a}, used as delimiter
@cindex @code{\c}, used as delimiter
@cindex @code{\d}, used as delimiter
@cindex @code{\e}, used as delimiter
@cindex @code{\E}, used as delimiter
@cindex @code{\p}, used as delimiter
@cindex @code{\r}, used as delimiter
@cindex @code{\t}, used as delimiter
@cindex @code{\u}, used as delimiter
The following escapes sequences (which are handled similarly to
characters since they don't take a parameter) are also allowed as
delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
@code{\?}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, @code{\:},
@code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
@code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.  Again, don't
use these if possible.

@cindex @code{\A}, allowed delimiters
@cindex @code{\B}, allowed delimiters
@cindex @code{\Z}, allowed delimiters
@cindex @code{\C}, allowed delimiters
@cindex @code{\w}, allowed delimiters
No newline characters as delimiters are allowed in the following
escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}.

@cindex @code{\D}, allowed delimiters
@cindex @code{\h}, allowed delimiters
@cindex @code{\H}, allowed delimiters
@cindex @code{\l}, allowed delimiters
@cindex @code{\L}, allowed delimiters
@cindex @code{\N}, allowed delimiters
@cindex @code{\R}, allowed delimiters
@cindex @code{\s}, allowed delimiters
@cindex @code{\S}, allowed delimiters
@cindex @code{\v}, allowed delimiters
@cindex @code{\x}, allowed delimiters
Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and
@code{\x} can't use the following characters as delimiters:

@itemize @bullet
@item
@cindex numbers, and delimiters
@cindex digits, and delimiters
The digits @code{0}-@code{9}.

@item
@cindex operators, as delimiters
@cindex @code{+}, as delimiter
@cindex @code{-}, as delimiter
@cindex @code{/}, as delimiter
@cindex @code{*}, as delimiter
@cindex @code{%}, as delimiter
@cindex @code{<}, as delimiter
@cindex @code{>}, as delimiter
@cindex @code{=}, as delimiter
@cindex @code{&}, as delimiter
@ifnotinfo
@cindex @code{:}, as delimiter
@end ifnotinfo
@ifinfo
@cindex <colon>, as delimiter
@end ifinfo
@cindex @code{(}, as delimiter
@cindex @code{)}, as delimiter
@cindex @code{.}, as delimiter
The (single-character) operators @samp{+-/*%<>=&:().}.

@item
@cindex space character
@cindex character, space
@cindex tab character
@cindex character, tab
@cindex newline character
@cindex character, newline
The space, tab, and newline characters.

@item
@cindex @code{\%}, used as delimiter
@ifnotinfo
@cindex @code{\:}, used as delimiter
@end ifnotinfo
@ifinfo
@cindex @code{\@r{<colon>}}, used as delimiter
@end ifinfo
@cindex @code{\@{}, used as delimiter
@cindex @code{\@}}, used as delimiter
@cindex @code{\'}, used as delimiter
@cindex @code{\`}, used as delimiter
@cindex @code{\-}, used as delimiter
@cindex @code{\_}, used as delimiter
@cindex @code{\!}, used as delimiter
@cindex @code{\/}, used as delimiter
@cindex @code{\c}, used as delimiter
@cindex @code{\e}, used as delimiter
@cindex @code{\p}, used as delimiter
All escape sequences except @code{\%}, @code{\:}, @code{\@{},
@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
@code{\/}, @code{\c}, @code{\e}, and @code{\p}.
@end itemize

@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
To have a backslash (actually, the current escape character) appear in
the output several escapes are defined: @code{\\}, @code{\e} or
@code{\E}.  These are very similar, and only differ with respect to
being used in macros or diversions.  @xref{Character Translations}, for
an exact description of those escapes.

@xref{Implementation Differences}, @ref{Copy-in Mode}, and
@ref{Diversions}, @ref{Identifiers}, for more information.

@menu
* Comments::
@end menu

@node Comments,  , Escapes, Escapes
@subsubsection Comments
@cindex comments

Probably one of the most@footnote{Unfortunately, this is a lie.  But
hopefully future @code{gtroff} hackers will believe it @code{:-)}}
common forms of escapes is the comment.

@Defesc {\\", , , }
Start a comment.  Everything to the end of the input line is ignored.

This may sound simple, but it can be tricky to keep the comments from
interfering with the appearance of the final output.

@cindex @code{ds}, @code{ds1} requests, and comments
@cindex @code{as}, @code{as1} requests, and comments
If the escape is to the right of some text or a request, that portion of
the line is ignored, but the space leading up to it is noticed by
@code{gtroff}.  This only affects the @code{ds} and @code{as} request
and its variants.

@cindex tabs, before comments
@cindex comments, lining up with tabs
One possibly irritating idiosyncracy is that tabs must not be used to
line up comments.  Tabs are not treated as whitespace between the
request and macro arguments.

@cindex undefined request
@cindex request, undefined
A comment on a line by itself is treated as a blank line, because after
eliminating the comment, that is all that remains:

@Example
Test
\" comment
Test
@endExample

@noindent
produces

@Example
Test

Test
@endExample

To avoid this, it is common to start the line with @code{.\"} which
causes the line to be treated as an undefined request and thus ignored
completely.

@cindex @code{'}, as a comment
Another commenting scheme seen sometimes is three consecutive single
quotes (@code{'''}) at the beginning of a line.  This works, but
@code{gtroff} gives a warning about an undefined macro (namely
@code{''}), which is harmless, but irritating.
@endDefesc

@Defesc {\\#, , , }
To avoid all this, @code{gtroff} has a new comment mechanism using the
@code{\#} escape.  This escape works the same as @code{\"} except that
the newline is also ignored:

@Example
Test
\# comment
Test
@endExample

@noindent
produces

@Example
Test Test
@endExample

@noindent
as expected.
@endDefesc

@Defreq {ig, [@Var{end}]}
Ignore all input until @code{gtroff} encounters the macro named
@code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not
specified).  This is useful for commenting out large blocks of text:

@Example
text text text...
.ig
This is part of a large block
of text that has been
temporarily(?) commented out.

We can restore it simply by removing
the .ig request and the ".." at the
end of the block.
..
More text text text...
@endExample

@noindent
produces

@Example
text text text@dots{}  More text text text@dots{}
@endExample

@noindent
Note that the commented-out block of text does not cause a break.

@cindex @code{ig} request, and copy-in mode
@cindex copy-in mode, and @code{ig} request
@cindex mode, copy-in, and @code{ig} request
@cindex @code{ig} request, and auto-increment
@cindex auto-increment, and @code{ig} request
The input is read in copy-mode; auto-incremented registers @emph{are}
affected (@pxref{Auto-increment}).
@endDefreq


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

@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
@section Registers
@cindex registers

Numeric variables in @code{gtroff} are called @dfn{registers}.  There
are a number of built-in registers, supplying anything from the date to
details of formatting parameters.

@xref{Identifiers}, for details on register identifiers.

@menu
* Setting Registers::
* Interpolating Registers::
* Auto-increment::
* Assigning Formats::
* Built-in Registers::
@end menu

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

@node Setting Registers, Interpolating Registers, Registers, Registers
@subsection Setting Registers
@cindex setting registers (@code{nr}, @code{\R})
@cindex registers, setting (@code{nr}, @code{\R})

Define or set registers using the @code{nr} request or the @code{\R}
escape.

@DefreqList {nr, ident value}
@DefescListEnd {\\R, ', ident value, '}
Set number register @var{ident} to @var{value}.  If @var{ident} doesn't
exist, @code{gtroff} creates it.

The argument to @code{\R} usually has to be enclosed in quotes.
@xref{Escapes}, for details on parameter delimiting characters.

The @code{\R} escape doesn't produce an input token in @code{gtroff};
in other words, it vanishes completely after @code{gtroff} has
processed it.
@endDefreq

For example, the following two lines are equivalent:

@Example
.nr a (((17 + (3 * 4))) % 4)
\R'a (((17 + (3 * 4))) % 4)'
    @result{} 1
@endExample

Both @code{nr} and @code{\R} have two additional special forms to
increment or decrement a register.

@DefreqList {nr, ident @t{+}@Var{value}}
@DefreqItem {nr, ident @t{-}@Var{value}}
@DefescItem {\\R, ', ident @t{+}value, '}
@DefescListEnd {\\R, ', ident @t{-}value, '}
Increment (decrement) register @var{ident} by @var{value}.

@Example
.nr a 1
.nr a +1
\na
    @result{} 2
@endExample

@cindex negating register values
To assign the negated value of a register to another register, some care
must be taken to get the desired result:

@Example
.nr a 7
.nr b 3
.nr a -\nb
\na
    @result{} 4
.nr a (-\nb)
\na
    @result{} -3
@endExample

@noindent
The surrounding parentheses prevent the interpretation of the minus sign
as a decrementing operator.  An alternative is to start the assignment
with a @samp{0}:

@Example
.nr a 7
.nr b -3
.nr a \nb
\na
    @result{} 4
.nr a 0\nb
\na
    @result{} -3
@endExample
@endDefreq

@Defreq {rr, ident}
@cindex removing number register (@code{rr})
@cindex number register, removing (@code{rr})
@cindex register, removing (@code{rr})
Remove number register @var{ident}.  If @var{ident} doesn't exist, the
request is ignored.
@endDefreq

@Defreq {rnn, ident1 ident2}
@cindex renaming number register (@code{rnn})
@cindex number register, renaming (@code{rnn})
@cindex register, renaming (@code{rnn})
Rename number register @var{ident1} to @var{ident2}.  If either
@var{ident1} or @var{ident2} doesn't exist, the request is ignored.
@endDefreq

@Defreq {aln, ident1 ident2}
@cindex alias, number register, creating (@code{aln})
@cindex creating alias, for number register (@code{aln})
@cindex number register, creating alias (@code{aln})
@cindex register, creating alias (@code{aln})
Create an alias @var{ident1} for a number register @var{ident2}.  The
new name and the old name are exactly equivalent.  If @var{ident1} is
undefined, a warning of type @samp{reg} is generated, and the request is
ignored.  @xref{Debugging}, for information about warnings.
@endDefreq

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

@node Interpolating Registers, Auto-increment, Setting Registers, Registers
@subsection Interpolating Registers
@cindex interpolating registers (@code{\n})
@cindex registers, interpolating (@code{\n})

Numeric registers can be accessed via the @code{\n} escape.

@DefescList {\\n, , i, }
@DefescItem {\\n, @Lparen{}, id, }
@DefescListEnd {\\n, @Lbrack{}, ident, @Rbrack{}}
@cindex nested assignments
@cindex assignments, nested
@cindex indirect assignments
@cindex assignments, indirect
Interpolate number register with name @var{ident} (one-character
name@tie{}@var{i}, two-character name @var{id}).  This means that the
value of the register is expanded in-place while @code{gtroff} is
parsing the input line.  Nested assignments (also called indirect
assignments) are possible.

@Example
.nr a 5
.nr as \na+\na
\n(as
    @result{} 10
@endExample

@Example
.nr a1 5
.nr ab 6
.ds str b
.ds num 1
\n[a\n[num]]
    @result{} 5
\n[a\*[str]]
    @result{} 6
@endExample
@endDefesc

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

@node Auto-increment, Assigning Formats, Interpolating Registers, Registers
@subsection Auto-increment
@cindex auto-increment
@cindex increment, automatic

Number registers can also be auto-incremented and auto-decremented.  The
increment or decrement value can be specified with a third argument to
the @code{nr} request or @code{\R} escape.

@Defreq {nr, ident value incr}
@cindex @code{\R}, difference to @code{nr}
Set number register @var{ident} to @var{value}; the increment for
auto-incrementing is set to @var{incr}.  Note that the @code{\R} escape
doesn't support this notation.
@endDefreq

To activate auto-incrementing, the escape @code{\n} has a special syntax
form.

@DefescList {\\n, +, i, }
@DefescItem {\\n, -, i, }
@DefescItem {\\n, @Lparen{}+, id, }
@DefescItem {\\n, @Lparen{}-, id, }
@DefescItem {\\n, +@Lparen{}, id, }
@DefescItem {\\n, -@Lparen{}, id, }
@DefescItem {\\n, @Lbrack{}+, ident, @Rbrack{}}
@DefescItem {\\n, @Lbrack{}-, ident, @Rbrack{}}
@DefescItem {\\n, +@Lbrack{}, ident, @Rbrack{}}
@DefescListEnd {\\n, -@Lbrack{}, ident, @Rbrack{}}
Before interpolating, increment or decrement @var{ident} (one-character
name@tie{}@var{i}, two-character name @var{id}) by the auto-increment
value as specified with the @code{nr} request (or the @code{\R} escape).
If no auto-increment value has been specified, these syntax forms are
identical to @code{\n}.
@endDefesc

For example,

@Example
.nr a 0 1
.nr xx 0 5
.nr foo 0 -2
\n+a, \n+a, \n+a, \n+a, \n+a
.br
\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
.br
\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
@endExample

@noindent
produces

@Example
1, 2, 3, 4, 5
-5, -10, -15, -20, -25
-2, -4, -6, -8, -10
@endExample

@cindex increment value without changing the register
@cindex value, incrementing without changing the register
To change the increment value without changing the value of a register
(@var{a} in the example), the following can be used:

@Example
.nr a \na 10
@endExample

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

@node Assigning Formats, Built-in Registers, Auto-increment, Registers
@subsection Assigning Formats
@cindex assigning formats (@code{af})
@cindex formats, assigning (@code{af})

When a register is used, it is always textually replaced (or
interpolated) with a representation of that number.  This output format
can be changed to a variety of formats (numbers, Roman numerals, etc.).
This is done using the @code{af} request.

@Defreq {af, ident format}
Change the output format of a number register.  The first argument
@var{ident} is the name of the number register to be changed, and the
second argument @var{format} is the output format.  The following output
formats are available:

@table @code
@item 1
Decimal arabic numbers.  This is the default format: 0, 1, 2,
3,@tie{}@enddots{}

@item 0@dots{}0
Decimal numbers with as many digits as specified.  So, @samp{00} would
result in printing numbers as 01, 02, 03,@tie{}@enddots{}

In fact, any digit instead of zero does work; @code{gtroff} only counts
how many digits are specified.  As a consequence, @code{af}'s default
format @samp{1} could be specified as @samp{0} also (and exactly this is
returned by the @code{\g} escape, see below).

@item I
@cindex Roman numerals
@cindex numerals, Roman
Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}

@item i
Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}

@item A
Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}

@item a
Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
@end table

Omitting the number register format causes a warning of type
@samp{missing}.  @xref{Debugging}, for more details.  Specifying a
nonexistent format causes an error.

The following example produces @samp{10, X, j, 010}:

@Example
.nr a 10
.af a 1           \" the default format
\na,
.af a I
\na,
.af a a
\na,
.af a 001
\na
@endExample

@cindex Roman numerals, maximum and minimum
@cindex maximum values of Roman numerals
@cindex minimum values of Roman numerals
The largest number representable for the @samp{i} and @samp{I} formats
is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
@code{gtroff}.  Currently, the correct glyphs of Roman numeral five
thousand and Roman numeral ten thousand (Unicode code points
@code{U+2182} and @code{U+2181}, respectively) are not available.

If @var{ident} doesn't exist, it is created.

@cindex read-only register, changing format
@cindex changing format, and read-only registers
Changing the output format of a read-only register causes an error.  It
is necessary to first copy the register's value to a writeable register,
then apply the @code{af} request to this other register.
@endDefreq

@DefescList {\\g, , i, }
@DefescItem {\\g, @Lparen{}, id, }
@DefescListEnd {\\g, @Lbrack{}, ident, @Rbrack{}}
@cindex format of register (@code{\g})
@cindex register, format (@code{\g})
Return the current format of the specified register @var{ident}
(one-character name@tie{}@var{i}, two-character name @var{id}).  For
example, @samp{\ga} after the previous example would produce the string
@samp{000}.  If the register hasn't been defined yet, nothing is
returned.
@endDefesc

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

@node Built-in Registers,  , Assigning Formats, Registers
@subsection Built-in Registers
@cindex built-in registers
@cindex registers, built-in

The following lists some built-in registers which are not described
elsewhere in this manual.  Any register which begins with a @samp{.} is
read-only.  A complete listing of all built-in registers can be found in
@ref{Register Index}.

@table @code
@item \n[.F]
@cindex current input file name register (@code{.F})
@cindex input file name, current, register (@code{.F})
@vindex .F
This string-valued register returns the current input file name.

@item \n[.H]
@cindex horizontal resolution register (@code{.H})
@cindex resolution, horizontal, register (@code{.H})
@vindex .H
Horizontal resolution in basic units.

@item \n[.U]
@cindex safer mode
@cindex mode, safer
@cindex unsafe mode
@cindex mode, unsafe
If @code{gtroff} is called with the @option{-U} command line option to
activate unsafe mode, the number register @code{.U} is set to@tie{}1,
and to zero otherwise.  @xref{Groff Options}.

@item \n[.V]
@cindex vertical resolution register (@code{.V})
@cindex resolution, vertical, register (@code{.V})
@vindex .V
Vertical resolution in basic units.

@item \n[seconds]
@cindex seconds, current time (@code{seconds})
@cindex time, current, seconds (@code{seconds})
@cindex current time, seconds (@code{seconds})
@vindex seconds
The number of seconds after the minute, normally in the range@tie{}0
to@tie{}59, but can be up to@tie{}61 to allow for leap seconds.
Initialized at start-up of @code{gtroff}.

@item \n[minutes]
@cindex minutes, current time (@code{minutes})
@cindex time, current, minutes (@code{minutes})
@cindex current time, minutes (@code{minutes})
@vindex minutes
The number of minutes after the hour, in the range@tie{}0 to@tie{}59.
Initialized at start-up of @code{gtroff}.

@item \n[hours]
@cindex hours, current time (@code{hours})
@cindex time, current, hours (@code{hours})
@cindex current time, hours (@code{hours})
@vindex hours
The number of hours past midnight, in the range@tie{}0 to@tie{}23.
Initialized at start-up of @code{gtroff}.

@item \n[dw]
@cindex day of the week register (@code{dw})
@cindex date, day of the week register (@code{dw})
@vindex dw
Day of the week (1-7).

@item \n[dy]
@cindex day of the month register (@code{dy})
@cindex date, day of the month register (@code{dy})
@vindex dy
Day of the month (1-31).

@item \n[mo]
@cindex month of the year register (@code{mo})
@cindex date, month of the year register (@code{mo})
@vindex mo
Current month (1-12).

@item \n[year]
@cindex date, year register (@code{year}, @code{yr})
@cindex year, current, register (@code{year}, @code{yr})
@vindex year
The current year.

@item \n[yr]
@vindex yr
The current year minus@tie{}1900.  Unfortunately, the documentation of
@acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug:
It incorrectly claimed that @code{yr} contains the last two digits of
the year.  That claim has never been true of either @acronym{AT&T}
@code{troff} or GNU @code{troff}.  Old @code{troff} input that looks
like this:

@Example
'\" The following line stopped working after 1999
This document was formatted in 19\n(yr.
@endExample

@noindent
can be corrected as follows:

@Example
This document was formatted in \n[year].
@endExample

@noindent
or, to be portable to older @code{troff} versions, as follows:

@Example
.nr y4 1900+\n(yr
This document was formatted in \n(y4.
@endExample

@item \n[.c]
@vindex .c
@itemx \n[c.]
@vindex c.
@cindex input line number register (@code{.c}, @code{c.})
@cindex line number, input, register (@code{.c}, @code{c.})
The current @emph{input} line number.  Register @samp{.c} is read-only,
whereas @samp{c.} (a @code{gtroff} extension) is writable also,
affecting both @samp{.c} and @samp{c.}.

@item \n[ln]
@vindex ln
@cindex output line number register (@code{ln})
@cindex line number, output, register (@code{ln})
The current @emph{output} line number after a call to the @code{nm}
request to activate line numbering.

@xref{Miscellaneous}, for more information about line numbering.

@item \n[.x]
@vindex .x
@cindex major version number register (@code{.x})
@cindex version number, major, register (@code{.x})
The major version number.  For example, if the version number is 1.03
then @code{.x} contains@tie{}@samp{1}.

@item \n[.y]
@vindex .y
@cindex minor version number register (@code{.y})
@cindex version number, minor, register (@code{.y})
The minor version number.  For example, if the version number is 1.03
then @code{.y} contains@tie{}@samp{03}.

@item \n[.Y]
@vindex .Y
@cindex revision number register (@code{.Y})
The revision number of @code{groff}.

@item \n[$$]
@vindex $$
@cindex process ID of @code{gtroff} register (@code{$$})
@cindex @code{gtroff}, process ID register (@code{$$})
The process ID of @code{gtroff}.

@item \n[.g]
@vindex .g
@cindex @code{gtroff}, identification register (@code{.g})
@cindex GNU-specific register (@code{.g})
Always@tie{}1.  Macros should use this to determine whether they are
running under GNU @code{troff}.

@item \n[.A]
@vindex .A
@cindex @acronym{ASCII} approximation output register (@code{.A})
If the command line option @option{-a} is used to produce an
@acronym{ASCII} approximation of the output, this is set to@tie{}1, zero
otherwise.  @xref{Groff Options}.

@item \n[.O]
@vindex .O
This read-only register is set to the suppression nesting level (see
escapes @code{\O}).  @xref{Suppressing output}.

@item \n[.P]
@vindex .P
This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current
page is actually being printed, i.e., if the @option{-o} option is being
used to only print selected pages.  @xref{Groff Options}, for more
information.

@item \n[.T]
@vindex .T
If @code{gtroff} is called with the @option{-T} command line option, the
number register @code{.T} is set to@tie{}1, and zero otherwise.
@xref{Groff Options}.

@item \*[.T]
@stindex .T
@cindex output device name string register (@code{.T})
A single read-write string register which contains the current output
device (for example, @samp{latin1} or @samp{ps}).  This is the only
string register defined by @code{gtroff}.
@end table


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

@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
@section Manipulating Filling and Adjusting
@cindex manipulating filling and adjusting
@cindex filling and adjusting, manipulating
@cindex adjusting and filling, manipulating
@cindex justifying text
@cindex text, justifying

@cindex break
@cindex line break
@cindex @code{bp} request, causing implicit linebreak
@cindex @code{ce} request, causing implicit linebreak
@cindex @code{cf} request, causing implicit linebreak
@cindex @code{fi} request, causing implicit linebreak
@cindex @code{fl} request, causing implicit linebreak
@cindex @code{in} request, causing implicit linebreak
@cindex @code{nf} request, causing implicit linebreak
@cindex @code{rj} request, causing implicit linebreak
@cindex @code{sp} request, causing implicit linebreak
@cindex @code{ti} request, causing implicit linebreak
@cindex @code{trf} request, causing implicit linebreak
Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
Breaks}.  The @code{br} request likewise causes a break.  Several other
requests also cause breaks, but implicitly.  These are @code{bp},
@code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, @code{nf},
@code{rj}, @code{sp}, @code{ti}, and @code{trf}.

@Defreq {br, }
Break the current line, i.e., the input collected so far is emitted
without adjustment.

If the no-break control character is used, @code{gtroff} suppresses the
break:

@Example
a
'br
b
    @result{} a b
@endExample
@endDefreq

Initially, @code{gtroff} fills and adjusts text to both margins.
Filling can be disabled via the @code{nf} request and re-enabled with
the @code{fi} request.

@DefreqList {fi, }
@DefregListEnd {.u}
@cindex fill mode (@code{fi})
@cindex mode, fill (@code{fi})
Activate fill mode (which is the default).  This request implicitly
enables adjusting; it also inserts a break in the text currently being
filled.  The read-only number register @code{.u} is set to@tie{}1.

The fill mode status is associated with the current environment
(@pxref{Environments}).

See @ref{Line Control}, for interaction with the @code{\c} escape.
@endDefreq

@Defreq {nf, }
@cindex no-fill mode (@code{nf})
@cindex mode, no-fill (@code{nf})
Activate no-fill mode.  Input lines are output as-is, retaining line
breaks and ignoring the current line length.  This command implicitly
disables adjusting; it also causes a break.  The number register
@code{.u} is set to@tie{}0.

The fill mode status is associated with the current environment
(@pxref{Environments}).

See @ref{Line Control}, for interaction with the @code{\c} escape.
@endDefreq

@DefreqList {ad, [@Var{mode}]}
@DefregListEnd {.j}
Set adjusting mode.

Activation and deactivation of adjusting is done implicitly with calls
to the @code{fi} or @code{nf} requests.

@var{mode} can have one of the following values:

@table @code
@item l
@cindex ragged-right
Adjust text to the left margin.  This produces what is traditionally
called ragged-right text.

@item r
@cindex ragged-left
Adjust text to the right margin, producing ragged-left text.

@item c
@cindex centered text
@cindex @code{ce} request, difference to @samp{.ad@tie{}c}
Center filled text.  This is different to the @code{ce} request which
only centers text without filling.

@item b
@itemx n
Justify to both margins.  This is the default used by @code{gtroff}.
@end table

Finally, @var{mode} can be the numeric argument returned by the
@code{.j} register.

With no argument, @code{gtroff} adjusts lines in the same way it did
before adjusting was deactivated (with a call to @code{na}, for
example).

@Example
text
.ad r
.nr ad \n[.j]
text
.ad c
text
.na
text
.ad         \" back to centering
text
.ad \n[ad]  \" back to right justifying
@endExample

@cindex adjustment mode register (@code{.j})
The current adjustment mode is available in the read-only number
register @code{.j}; it can be stored and subsequently used to set
adjustment.

The adjustment mode status is associated with the current environment
(@pxref{Environments}).
@endDefreq

@Defreq {na, }
Disable adjusting.  This request won't change the current adjustment
mode: A subsequent call to @code{ad} uses the previous adjustment
setting.

The adjustment mode status is associated with the current environment
(@pxref{Environments}).
@endDefreq

@DefreqList {brp, }
@DefescListEnd {\\p, , , }
Adjust the current line and cause a break.

In most cases this produces very ugly results since @code{gtroff}
doesn't have a sophisticated paragraph building algorithm (as @TeX{}
have, for example); instead, @code{gtroff} fills and adjusts a paragraph
line by line:

@Example
This is an uninteresting sentence.
This is an uninteresting sentence.\p
This is an uninteresting sentence.
@endExample

@noindent
is formatted as

@Example
This is  an uninteresting  sentence.   This  is an
uninteresting                            sentence.
This is an uninteresting sentence.
@endExample
@endDefreq

@DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
@DefregItem {.ss}
@DefregListEnd {.sss}
@cindex word space size register (@code{.ss})
@cindex size of word space register (@code{.ss})
@cindex space between words register (@code{.ss})
@cindex sentence space size register (@code{.sss})
@cindex size of sentence space register (@code{.sss})
@cindex space between sentences register (@code{.sss})
Change the size of a space between words.  It takes its units as one
twelfth of the space width parameter for the current font.  Initially
both the @var{word_space_size} and @var{sentence_space_size}
are@tie{}12.  In fill mode, the values specify the minimum distance.

@cindex fill mode
@cindex mode, fill
If two arguments are given to the @code{ss} request, the second argument
sets the sentence space size.  If the second argument is not given,
sentence space size is set to @var{word_space_size}.  The sentence space
size is used in two circumstances: If the end of a sentence occurs at
the end of a line in fill mode, then both an inter-word space and a
sentence space are added; if two spaces follow the end of a sentence in
the middle of a line, then the second space is a sentence space.  If a
second argument is never given to the @code{ss} request, the behaviour
of @acronym{UNIX} @code{troff} is the same as that exhibited by GNU
@code{troff}.  In GNU @code{troff}, as in @acronym{UNIX} @code{troff}, a
sentence should always be followed by either a newline or two spaces.

The read-only number registers @code{.ss} and @code{.sss} hold the
values of the parameters set by the first and second arguments of the
@code{ss} request.

The word space and sentence space values are associated with the current
environment (@pxref{Environments}).

Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not}
ignored if a TTY output device is used; the given values are then
rounded down to a multiple of@tie{}12 (@pxref{Implementation
Differences}).

The request is ignored if there is no parameter.

@cindex discardable horizontal space
@cindex space, discardable, horizontal
@cindex horizontal discardable space
Another useful application of the @code{ss} request is to insert
discardable horizontal space, i.e., space which is discarded at a line
break.  For example, paragraph-style footnotes could be separated this
way:

@Example
.ll 4.5i
1.\ This is the first footnote.\c
.ss 48
.nop
.ss 12
2.\ This is the second footnote.
@endExample

@noindent
The result:

@Example
1. This is the first footnote.        2. This
is the second footnote.
@endExample

@noindent
Note that the @code{\h} escape produces unbreakable space.
@endDefreq

@DefreqList {ce, [@Var{nnn}]}
@DefregListEnd {.ce}
@cindex centering lines (@code{ce})
@cindex lines, centering (@code{ce})
Center text.  While the @w{@samp{.ad c}} request also centers text, it
fills the text as well.  @code{ce} does not fill the text it affects.
This request causes a break.  The number of lines still to be centered
is associated with the current environment (@pxref{Environments}).

The following example demonstrates the differences.  Here the input:

@Example
.ll 4i
.ce 1000
This is a small text fragment which shows the differences
between the `.ce' and the `.ad c' request.
.ce 0

.ad c
This is a small text fragment which shows the differences
between the `.ce' and the `.ad c' request.
@endExample

@noindent
And here the result:

@Example
  This is a small text fragment which
         shows the differences
between the `.ce' and the `.ad c' request.

  This is a small text fragment which
shows the differences between the `.ce'
        and the `.ad c' request.
@endExample

With no arguments, @code{ce} centers the next line of text.  @var{nnn}
specifies the number of lines to be centered.  If the argument is zero
or negative, centering is disabled.

The basic length for centering text is the line length (as set with the
@code{ll} request) minus the indentation (as set with the @code{in}
request).  Temporary indentation is ignored.

As can be seen in the previous example, it is a common idiom to turn on
centering for a large number of lines, and to turn off centering after
text to be centered.  This is useful for any request which takes a
number of lines as an argument.

The @code{.ce} read-only number register contains the number of lines
remaining to be centered, as set by the @code{ce} request.
@endDefreq

@DefreqList {rj, [@Var{nnn}]}
@DefregListEnd {.rj}
@cindex justifying text (@code{rj})
@cindex text, justifying (@code{rj})
@cindex right-justifying (@code{rj})
Justify unfilled text to the right margin.  Arguments are identical to
the @code{ce} request.  The @code{.rj} read-only number register is the
number of lines to be right-justified as set by the @code{rj} request.
This request causes a break.  The number of lines still to be
right-justified is associated with the current environment
(@pxref{Environments}).
@endDefreq


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

@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
@section Manipulating Hyphenation
@cindex manipulating hyphenation
@cindex hyphenation, manipulating

Here a description of requests which influence hyphenation.

@DefreqList {hy, [@Var{mode}]}
@DefregListEnd {.hy}
Enable hyphenation.  The request has an optional numeric argument,
@var{mode}, to restrict hyphenation if necessary:

@table @code
@item 1
The default argument if @var{mode} is omitted.  Hyphenate without
restrictions.  This is also the start-up value of @code{gtroff}.

@item 2
Do not hyphenate the last word on a page or column.

@item 4
Do not hyphenate the last two characters of a word.

@item 8
Do not hyphenate the first two characters of a word.
@end table

Values in the previous table are additive.  For example, the
value@tie{}12 causes @code{gtroff} to neither hyphenate the last two nor
the first two characters of a word.

@cindex hyphenation restrictions register (@code{.hy})
The current hyphenation restrictions can be found in the read-only
number register @samp{.hy}.

The hyphenation mode is associated with the current environment
(@pxref{Environments}).
@endDefreq

@Defreq {nh, }
Disable hyphenation (i.e., set the hyphenation mode to zero).  Note that
the hyphenation mode of the last call to @code{hy} is not remembered.

The hyphenation mode is associated with the current environment
(@pxref{Environments}).
@endDefreq

@DefreqList {hlm, [@Var{nnn}]}
@DefregItem {.hlm}
@DefregListEnd {.hlc}
@cindex explicit hyphen (@code{\%})
@cindex hyphen, explicit (@code{\%})
@cindex consecutive hyphenated lines (@code{hlm})
@cindex lines, consecutive hyphenated (@code{hlm})
@cindex hyphenated lines, consecutive (@code{hlm})
Set the maximum number of consecutive hyphenated lines to @var{nnn}.  If
this number is negative, there is no maximum.  The default value
is@tie{}@minus{}1 if @var{nnn} is omitted.  This value is associated
with the current environment (@pxref{Environments}).  Only lines output
from a given environment count towards the maximum associated with that
environment.  Hyphens resulting from @code{\%} are counted; explicit
hyphens are not.

The current setting of @code{hlm} is available in the @code{.hlm}
read-only number register.  Also the number of immediately preceding
consecutive hyphenated lines are available in the read-only number
register @samp{.hlc}.
@endDefreq

@Defreq {hw, word1 word2 @dots{}}
Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated.  The
words must be given with hyphens at the hyphenation points.  For
example:

@Example
.hw in-sa-lub-rious
@endExample

@noindent
Besides the space character, any character whose hyphenation code value
is zero can be used to separate the arguments of @code{hw} (see the
documentation for the @code{hcode} request below for more information).
In addition, this request can be used more than once.

Hyphenation exceptions specified with the @code{hw} request are
associated with the current hyphenation language; it causes an error if
there is no current hyphenation language.

This request is ignored if there is no parameter.

In old versions of @code{troff} there was a limited amount of space to
store such information; fortunately, with @code{gtroff}, this is no
longer a restriction.
@endDefreq

@DefescList {\\%, , , }
@deffnx Escape @t{\:}
@ifnotinfo
@esindex \:
@end ifnotinfo
@ifinfo
@esindex \@r{<colon>}
@end ifinfo
@cindex hyphenation character (@code{\%})
@cindex character, hyphenation (@code{\%})
@cindex disabling hyphenation (@code{\%})
@cindex hyphenation, disabling (@code{\%})
To tell @code{gtroff} how to hyphenate words on the fly, use the
@code{\%} escape, also known as the @dfn{hyphenation character}.
Preceding a word with this character prevents it from being
hyphenated; putting it inside a word indicates to @code{gtroff} that
the word may be hyphenated at that point.  Note that this mechanism
only affects that one occurrence of the word; to change the
hyphenation of a word for the entire document, use the @code{hw}
request.

The @code{\:} escape inserts a zero-width break point (that is, the word
breaks but without adding a hyphen).

@Example
... check the /var/log/\:httpd/\:access_log file ...
@endExample

@cindex @code{\X}, followed by @code{\%}
@cindex @code{\Y}, followed by @code{\%}
@cindex @code{\%}, following @code{\X} or @code{\Y}
Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%}
escape in (say) @w{@samp{\X'...'\%foobar}} and
@w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts a
hyphenation point at the beginning of @samp{foobar}; most likely this
isn't what you want to do.
@endDefesc

@Defreq {hc, [@Var{char}]}
Change the hyphenation character to @var{char}.  This character then
works the same as the @code{\%} escape, and thus, no longer appears in
the output.  Without an argument, @code{hc} resets the hyphenation
character to be @code{\%} (the default) only.

The hyphenation character is associated with the current environment
(@pxref{Environments}).
@endDefreq

@DefreqList {hpf, pattern_file}
@DefreqItem {hpfa, pattern_file}
@DefreqListEnd {hpfcode, a b [c d @dots{}]}
@cindex hyphenation patterns (@code{hpf})
@cindex patterns for hyphenation (@code{hpf})
Read in a file of hyphenation patterns.  This file is searched for in
the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
searched for if the @option{-m@var{name}} option is specified.

It should have the same format as (simple) @TeX{} patterns files.  More
specifically, the following scanning rules are implemented.

@itemize @bullet
@item
A percent sign starts a comment (up to the end of the line) even if
preceded by a backslash.

@item
No support for `digraphs' like @code{\$}.

@item
@code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}}
(character code of @var{x} in the range 0-127) are recognized; other use
of @code{^} causes an error.

@item
No macro expansion.

@item
@code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
(possibly with whitespace before and after the braces).  Everything
between the braces is taken as hyphenation patterns.  Consequently,
@code{@{} and @code{@}} are not allowed in patterns.

@item
Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
exceptions.

@item
@code{\endinput} is recognized also.

@item
For backwards compatibility, if @code{\patterns} is missing, the whole
file is treated as a list of hyphenation patterns (only recognizing the
@code{%} character as the start of a comment).
@end itemize

If no @code{hpf} request is specified (either in the document or in a
macro package), @code{gtroff} won't hyphenate at all.

The @code{hpfa} request appends a file of patterns to the current list.

The @code{hpfcode} request defines mapping values for character codes in
hyphenation patterns.  @code{hpf} or @code{hpfa} then apply the mapping
(after reading the patterns) before replacing or appending them to the
current list of patterns.  Its arguments are pairs of character codes --
integers from 0 to@tie{}255.  The request maps character
code@tie{}@var{a} to code@tie{}@var{b}, code@tie{}@var{c} to
code@tie{}@var{d}, and so on.  You can use character codes which would
be invalid otherwise.

@pindex troffrc
@pindex troffrc-end
@pindex hyphen.us
@pindex hyphenex.us
The set of hyphenation patterns is associated with the current language
set by the @code{hla} request.  The @code{hpf} request is usually
invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
@file{troffrc} loads hyphenation patterns and exceptions for American
English (in files @file{hyphen.us} and @file{hyphenex.us}).

A second call to @code{hpf} (for the same language) replaces the
hyphenation patterns with the new ones.

Invoking @code{hpf} causes an error if there is no current hyphenation
language.
@endDefreq

@Defreq {hcode, c1 code1 [c2 code2 @dots{}]}
@cindex hyphenation code (@code{hcode})
@cindex code, hyphenation (@code{hcode})
Set the hyphenation code of character @var{c1} to @var{code1}, that of
@var{c2} to @var{code2}, etc.  A hyphenation code must be a single input
character (not a special character) other than a digit or a space.

To make hyphenation work, hyphenation codes must be set up.  At
start-up, groff only assigns hyphenation codes to the letters
@samp{a}-@samp{z} (mapped to themselves) and to the letters
@samp{A}-@samp{Z} (mapped to @samp{a}-@samp{z}); all other hyphenation
codes are set to zero.  Normally, hyphenation patterns contain only
lowercase letters which should be applied regardless of case.  In
other words, the words `FOO' and `Foo' should be hyphenated exactly the
same way as the word `foo' is hyphenated, and this is what @code{hcode}
is good for.  Words which contain other letters won't be hyphenated
properly if the corresponding hyphenation patterns actually do contain
them.  For example, the following @code{hcode} requests are necessary to
assign hyphenation codes to the letters @samp{ÄäÖöÜüß} (this is needed
for German):

@Example
.hcode ä ä  Ä ä
.hcode ö ö  Ö ö
.hcode ü ü  Ü ü
.hcode ß ß
@endExample

Without those assignments, groff treats German words like
@w{`Kindergärten'} (the plural form of `kindergarten') as two substrings
@w{`kinderg'} and @w{`rten'} because the hyphenation code of the
umlaut@tie{}a is zero by default.  There is a German hyphenation pattern
which covers @w{`kinder'}, so groff finds the hyphenation `kin-der'.
The other two hyphenation points (`kin-der-gär-ten') are missed.

This request is ignored if it has no parameter.
@endDefreq

@DefreqList {hym, [@Var{length}]}
@DefregListEnd {.hym}
@cindex hyphenation margin (@code{hym})
@cindex margin for hyphenation (@code{hym})
@cindex @code{ad} request, and hyphenation margin
Set the (right) hyphenation margin to @var{length}.  If the current
adjustment mode is not @samp{b} or @samp{n}, the line is not hyphenated
if it is shorter than @var{length}.  Without an argument, the
hyphenation margin is reset to its default value, which is@tie{}0.  The
default scaling indicator for this request is @samp{m}.  The hyphenation
margin is associated with the current environment
(@pxref{Environments}).

A negative argument resets the hyphenation margin to zero, emitting a
warning of type @samp{range}.

@cindex hyphenation margin register (@code{.hym})
The current hyphenation margin is available in the @code{.hym} read-only
number register.
@endDefreq

@DefreqList {hys, [@Var{hyphenation_space}]}
@DefregListEnd {.hys}
@cindex hyphenation space (@code{hys})
@cindex @code{ad} request, and hyphenation space
Set the hyphenation space to @var{hyphenation_space}.  If the current
adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line if it
can be justified by adding no more than @var{hyphenation_space} extra
space to each word space.  Without argument, the hyphenation space is
set to its default value, which is@tie{}0.  The default scaling
indicator for this request is @samp{m}.  The hyphenation space is
associated with the current environment (@pxref{Environments}).

A negative argument resets the hyphenation space to zero, emitting a
warning of type @samp{range}.

@cindex hyphenation space register (@code{.hys})
The current hyphenation space is available in the @code{.hys} read-only
number register.
@endDefreq

@Defreq {shc, [@Var{glyph}]}
@cindex soft hyphen character, setting (@code{shc})
@cindex character, soft hyphen, setting (@code{shc})
@cindex glyph, soft hyphen (@code{hy})
@cindex soft hyphen glyph (@code{hy})
@cindex @code{char} request, and soft hyphen character
@cindex @code{tr} request, and soft hyphen character
Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft
hyphen character} is a misnomer since it is an output glyph.}  If the
argument is omitted, the soft hyphen character is set to the default
glyph @code{\(hy} (this is the start-up value of @code{gtroff} also).
The soft hyphen character is the glyph that is inserted when a word is
hyphenated at a line break.  If the soft hyphen character does not exist
in the font of the character immediately preceding a potential break
point, then the line is not broken at that point.  Neither definitions
(specified with the @code{char} request) nor translations (specified
with the @code{tr} request) are considered when finding the soft hyphen
character.
@endDefreq

@DefreqList {hla, language}
@DefregListEnd {.hla}
@cindex @code{hpf} request, and hyphenation language
@cindex @code{hw} request, and hyphenation language
@pindex troffrc
@pindex troffrc-end
Set the current hyphenation language to the string @var{language}.
Hyphenation exceptions specified with the @code{hw} request and
hyphenation patterns specified with the @code{hpf} and @code{hpfa}
requests are both associated with the current hyphenation language.  The
@code{hla} request is usually invoked by the @file{troffrc} or the
@file{troffrc-end} files; @file{troffrc} sets the default language to
@samp{us}.

@cindex hyphenation language register (@code{.hla})
The current hyphenation language is available as a string in the
read-only number register @samp{.hla}.

@Example
.ds curr_language \n[.hla]
\*[curr_language]
    @result{} us
@endExample
@endDefreq


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

@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
@section Manipulating Spacing
@cindex manipulating spacing
@cindex spacing, manipulating

@Defreq {sp, [@Var{distance}]}
Space downwards @var{distance}.  With no argument it advances
1@tie{}line.  A negative argument causes @code{gtroff} to move up the
page the specified distance.  If the argument is preceded by a @samp{|}
then @code{gtroff} moves that distance from the top of the page.  This
request causes a line break, and that adds the current line spacing to
the space you have just specified.  The default scaling indicator is
@samp{v}.

For convenience you may wish to use the following macros to set the
height of the next line at a given distance from the top or the bottom
of the page:

@Example
.de y-from-top-down
.  sp |\\$1-\\n[.v]u
..
.
.de y-from-bot-up
.  sp |\\n[.p]u-\\$1-\\n[.v]u
..
@endExample

@noindent
A call to @samp{.y-from-bot-up 10c} means that the bottom of the next
line will be at 10@dmn{cm} from the paper edge at the bottom.

If a vertical trap is sprung during execution of @code{sp}, the amount