groff - Online Manual Page Of Unix/Linux

Our Recommended Sites:

File: groff, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)

GNU troff
*********

This manual documents GNU `troff' version 1.18.

Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being `A GNU Manual," and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
`GNU Free Documentation License."

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

* 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::

File: groff, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top

Introduction
************

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

* Menu:

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

File: groff, Node: What Is groff?, Next: History, Prev: Introduction, Up: Introduction

What Is `groff'?
================

`groff' belongs to an older generation of document preparation
systems, which operate more like compilers than the more recent
interactive WYSIWYG(1) (*note What Is groff?-Footnote-1::) systems.
`groff' and its contemporary counterpart, TeX, both work using a
"batch" paradigm: The input (or "source") files are normal text files
with embedded formatting commands. These files can then be processed
by `groff' to produce a typeset document on a variety of devices.

Likewise, `groff' should not be confused with a "word processor",
since that term connotes an integrated system that includes an editor
and a text formatter. Also, many word processors follow the WYSIWYG
paradigm discussed earlier.

Although WYSIWYG systems may be easier to use, they have a number of
disadvantages compared to `troff':

* They must be used on a graphics display to work on a document.

* Most of the WYSIWYG systems are either non-free or are not very
portable.

* `troff' is firmly entrenched in all UNIX systems.

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

* It is more difficult to make global changes to a document.

"GUIs normally make it simple to accomplish simple actions and
impossible to accomplish complex actions." -Doug Gwyn (22/Jun/91
in `comp.unix.wizards')

File: groff, Node: History, Next: groff Capabilities, Prev: What Is groff?, Up: Introduction

History
=======

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

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

When they needed a more flexible language, a new version of `roff'
called `nroff' ("Newer `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 `nroff' that would drive it. It was dubbed `troff', for
"typesetter `roff'", although many people have speculated that it
actually means "Times `roff'" because of the use of the Times font
family in `troff' by default. As such, the name `troff' is pronounced
`t-roff' rather than `trough'.

With `troff' came `nroff' (they were actually the same program
except for some `#ifdef's), which was for producing output for line
printers and character terminals. It understood everything `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
`troff', work on several preprocessors began. These programs would
transform certain parts of a document into `troff', which made a very
natural use of pipes in UNIX.

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

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

So, Brian Kernighan took on the task of rewriting `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 `troff' (called `ditroff' for
"device independent `troff'") had several extensions, which included
drawing functions.

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

James Clark began work on a GNU implementation of `ditroff' in
early 1989. The first version, `groff' 0.3.1, was released June 1990.
`groff' included:

* A replacement for `ditroff' with many extensions.

* The `soelim', `pic', `tbl', and `eqn' preprocessors.

* Postprocessors for character devices, POSTSCRIPT, TeX DVI, and
X Windows. GNU `troff' also eliminated the need for a separate
`nroff' program with a postprocessor which would produce ASCII
output.

* A version of the `me' macros and an implementation of the `man'
macros.

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

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

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

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

File: groff, Node: groff Capabilities, Next: Macro Package Intro, Prev: History, Up: Introduction

`groff' Capabilities
====================

So what exactly is `groff' capable of doing? `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 `groff':

* text filling, adjusting, and centering

* hyphenation

* page control

* font and glyph size control

* vertical spacing (e.g. double-spacing)

* line length and indenting

* macros, strings, diversions, and traps

* number registers

* tabs, leaders, and fields

* input and output conventions and character translation

* overstrike, bracket, line drawing, and zero-width functions

* local horizontal and vertical motions and the width function

* three-part titles

* output line numbering

* conditional acceptance of input

* environment switching

* insertions from the standard input

* input/output file switching

* output and error messages

File: groff, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction

Macro Packages
==============

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

File: groff, Node: Preprocessor Intro, Next: Output device intro, Prev: Macro Package Intro, Up: Introduction

Preprocessors
=============

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

To use a preprocessor, UNIX pipes are used to feed the output from
the preprocessor into `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 `groff', the user does not
need to construct the pipe, but only tell `groff' what preprocessors to
use.

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

A free implementation of `grap', a preprocessor for drawing graphs,
can be obtained as an extra package; `groff' can use `grap' also.

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

File: groff, Node: Output device intro, Next: Credits, Prev: Preprocessor Intro, Up: Introduction

Output Devices
==============

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

File: groff, Node: Credits, Prev: Output device intro, Up: Introduction

Credits
=======

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

The section on the `man' macro package is partly based on Susan G.
Kleinmann's `groff_man' manual page written for the Debian GNU/Linux
system.

Larry Kollar contributed the section in the `ms' macro package.

File: groff, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top

Invoking `groff'
****************

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

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

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

* Menu:

* Groff Options::
* Environment::
* Macro Directories::
* Font Directories::
* Invocation Examples::

File: groff, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff

Options
=======

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

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

The command line format for `groff' is:

groff [ -abceghilpstvzCEGNRSUVXZ ] [ -FDIR ] [ -mNAME ]
[ -TDEF ] [ -fFAM ] [ -wNAME ] [ -WNAME ]
[ -MDIR ] [ -dCS ] [ -rCN ] [ -nNUM ]
[ -oLIST ] [ -PARG ] [ -LARG ] [ -IDIR ]
[ FILES... ]

The command line format for `gtroff' is as follows.

gtroff [ -abcivzCERU ] [ -wNAME ] [ -WNAME ] [ -dCS ]
[ -fFAM ] [ -mNAME ] [ -nNUM ]
[ -oLIST ] [ -rCN ] [ -TNAME ]
[ -FDIR ] [ -MDIR ] [ FILES... ]

Obviously, many of the options to `groff' are actually passed on to
`gtroff'.

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

The `grog' command can be used to guess the correct `groff' command
to format a file.

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

`-h'
Print a help message.

`-e'
Preprocess with `geqn'.

`-t'
Preprocess with `gtbl'.

`-g'
Preprocess with `ggrn'.

`-G'
Preprocess with `grap'.

`-p'
Preprocess with `gpic'.

`-s'
Preprocess with `gsoelim'.

`-c'
Suppress color output.

`-R'
Preprocess with `grefer'. No mechanism is provided for passing
arguments to `grefer' because most `grefer' options have
equivalent commands which can be included in the file. *Note
grefer::, for more details.

Note that `gtroff' also accepts a `-R' option, which is not
accessible via `groff'. This option prevents the loading of the
`troffrc' and `troffrc-end' files.

`-v'
Make programs run by `groff' print out their version number.

`-V'
Print the pipeline on `stdout' instead of executing it.

`-z'
Suppress output from `gtroff'. Only error messages are printed.

`-Z'
Do not postprocess the output of `gtroff'. Normally `groff'
automatically runs the appropriate postprocessor.

`-PARG'
Pass ARG to the postprocessor. Each argument should be passed
with a separate `-P' option. Note that `groff' does not prepend
`-' to ARG before passing it to the postprocessor.

`-l'
Send the output to a spooler for printing. The command used for
this is specified by the `print' command in the device description
file (see *Note Font Files::, for more info). If not present,
`-l' is ignored.

`-LARG'
Pass ARG to the spooler. Each argument should be passed with a
separate `-L' option. Note that `groff' does not prepend a `-' to
ARG before passing it to the postprocessor. If the `print'
keyword in the device description file is missing, `-L' is ignored.

`-TDEV'
Prepare output for device DEV. The default device is `ps', unless
changed when `groff' was configured and built. The following are
the output devices currently available:

`ps'
For POSTSCRIPT printers and previewers.

`dvi'
For TeX DVI format.

`X75'
For a 75dpi X11 previewer.

`X75-12'
For a 75dpi X11 previewer with a 12pt base font in the
document.

`X100'
For a 100dpi X11 previewer.

`X100-12'
For a 100dpi X11 previewer with a 12pt base font in the
document.

`ascii'
For typewriter-like devices using the (7-bit) ASCII character
set.

`latin1'
For typewriter-like devices that support the Latin-1
(ISO 8859-1) character set.

`utf8'
For typewriter-like devices which use the Unicode (ISO 10646)
character set with UTF-8 encoding.

`cp1047'
For typewriter-like devices which use the EBCDIC encoding IBM
cp1047.

`lj4'
For HP LaserJet4-compatible (or other PCL5-compatible)
printers.

`lbp'
For Canon CAPSL printers (LBP-4 and LBP-8 series laser
printers).

`html'
To produce HTML output. Note that the HTML driver consists
of two parts, a preprocessor (`pre-grohtml') and a
postprocessor (`post-grohtml').

The predefined `gtroff' string register `.T' contains the current
output device; the read-only number register `.T' is set to 1 if
this option is used (which is always true if `groff' is used to
call `gtroff'). *Note Built-in Registers::.

The postprocessor to be used for a device is specified by the
`postpro' command in the device description file. (*Note Font
Files::, for more info.) This can be overridden with the `-X'
option.

`-X'
Preview with `gxditview' instead of using the usual postprocessor.
This is unlikely to produce good results except with `-Tps'.

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

`-N'
Don't allow newlines with `eqn' delimiters. This is the same as
the `-N' option in `geqn'.

`-S'
Safer mode. Pass the `-S' option to `gpic' and disable the
`open', `opena', `pso', `sy', and `pi' requests. For security
reasons, this is enabled by default.

`-U'
Unsafe mode. This enables the `open', `opena', `pso', `sy', and
`pi' requests.

`-a'
Generate an ASCII approximation of the typeset output. The
read-only register `.A' is then set to 1. *Note Built-in
Registers::. A typical example is

groff -a -man -Tdvi troff.man | less

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.

`-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: `gtroff'
can get confused by `as' or `am' requests while counting line
numbers.

`-i'
Read the standard input after all the named input files have been
processed.

`-wNAME'
Enable warning NAME. Available warnings are described in *Note
Debugging::. Multiple `-w' options are allowed.

`-WNAME'
Inhibit warning NAME. Multiple `-W' options are allowed.

`-E'
Inhibit all error messages.

`-C'
Enable compatibility mode. *Note Implementation Differences::,
for the list of incompatibilities between `groff' and AT&T `troff'.

`-dCS'
`-dNAME=S'
Define C or NAME to be a string S. C must be a one-letter name;
NAME can be of arbitrary length. All string assignments happen
before loading any macro file (including the start-up file).

`-fFAM'
Use FAM as the default font family. *Note Font Families::.

`-mNAME'
Read in the file `NAME.tmac'. Normally `groff' searches for this
in its macro directories. If it isn't found, it tries `tmac.NAME'
(searching in the same directories).

`-nNUM'
Number the first page NUM.

`-oLIST'
Output only pages in LIST, which is a comma-separated list of page
ranges; `N' means print page N, `M-N' means print every page
between M and N, `-N' means print every page up to N, `N-' means
print every page beginning with N. `gtroff' exits after printing
the last page in the list. All the ranges are inclusive on both
ends.

Within `gtroff', this information can be extracted with the `.P'
register. *Note Built-in Registers::.

If your document restarts page numbering at the beginning of each
chapter, then `gtroff' prints the specified page range for each
chapter.

`-rCN'
`-rNAME=N'
Set number register C or NAME to the value N. C must be a
one-letter name; NAME can be of arbitrary length. N can be any
`gtroff' numeric expression. All register assignments happen
before loading any macro file (including the start-up file).

`-FDIR'
Search `DIR' for subdirectories `devNAME' (NAME is the name of the
device), for the `DESC' file, and for font files before looking in
the standard directories (*note Font Directories::). This option
is passed to all pre- and postprocessors using the
`GROFF_FONT_PATH' environment variable.

`-MDIR'
Search directory `DIR' for macro files before the standard
directories (*note Macro Directories::).

`-IDIR'
This option is as described in *Note gsoelim::. It implies the
`-s' option.

File: groff, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff

Environment
===========

There are also several environment variables (of the operating
system, not within `gtroff') which can modify the behavior of `groff'.

`GROFF_COMMAND_PREFIX'
If this is set to X, then `groff' runs `Xtroff' instead of
`gtroff'. This also applies to `tbl', `pic', `eqn', `grn',
`refer', and `soelim'. It does not apply to `grops', `grodvi',
`grotty', `pre-grohtml', `post-grohtml', `grolj4', and `gxditview'.

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

`GROFF_TMAC_PATH'
A colon-separated list of directories in which to search for macro
files (before the default directories are tried). *Note Macro
Directories::.

`GROFF_TYPESETTER'
The default output device.

`GROFF_FONT_PATH'
A colon-separated list of directories in which to search for the
`dev'NAME directory (before the default directories are tried).
*Note Font Directories::.

`GROFF_BIN_PATH'
This search path, followed by `PATH', is used for commands executed
by `groff'.

`GROFF_TMPDIR'
The directory in which `groff' creates temporary files. If this is
not set and `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 `/tmp'). `grops', `grefer', `pre-grohtml', and
`post-grohtml' can create temporary files in this directory.

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

File: groff, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff

Macro Directories
=================

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

Macro files are kept in the "tmac directories", all of which
constitute the "tmac path". The elements of the search path for macro
files are (in that order):

* The directories specified with `gtroff''s or `groff''s `-M'
command line option.

* The directories given in the `GROFF_TMAC_PATH' environment
variable.

* The current directory (only if in unsafe mode using the `-U'
command line switch).

* The home directory.

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

/usr/local/lib/groff/site-tmac
/usr/local/share/groff/site-tmac
/usr/local/share/groff/1.18/tmac

assuming that the version of `groff' is 1.18, and the installation
prefix was `/usr/local'. It is possible to fine-tune those
directories during the installation process.

File: groff, Node: Font Directories, Next: Invocation Examples, Prev: Macro Directories, Up: Invoking groff

Font Directories
================

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

All font files are kept in the "font directories" which constitute
the "font path". The file search functions will always append the
directory `dev'NAME, where NAME is the name of the output device.
Assuming, say, DVI output, and `/foo/bar' as a font directory, the font
files for `grodvi' must be in `/foo/bar/devdvi'.

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

* The directories specified with `gtroff''s or `groff''s `-F'
command line option. All device drivers and some preprocessors
also have this option.

* The directories given in the `GROFF_FONT_PATH' environment
variable.

* A site-specific directory and the main font directory; the default
locations are

/usr/local/share/groff/site-font
/usr/local/share/groff/1.18/font

assuming that the version of `groff' is 1.18, and the installation
prefix was `/usr/local'. It is possible to fine-tune those
directories during the installation process.

File: groff, Node: Invocation Examples, Prev: Font Directories, Up: Invoking groff

Invocation Examples
===================

This section lists several common uses of `groff' and the
corresponding command lines.

groff file

This command processes `file' without a macro package or a
preprocessor. The output device is the default, `ps', and the output
is sent to `stdout'.

groff -t -mandoc -Tascii file | less

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

groff -X -m me file

Preview `file' with `gxditview', using the `me' macro package. Since
no `-T' option is specified, use the default device (`ps'). Note that
you can either say `-m me' or `-me'; the latter is an anachronism from
the early days of UNIX.(1) (*note Invocation Examples-Footnote-1::)

groff -man -rD1 -z file

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

* Menu:

* grog::

File: groff, Node: grog, Prev: Invocation Examples, Up: Invocation Examples

`grog'
------

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

A special file name `-' 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 `-C' (which is
also passed on) to enable compatibility mode, and `-v' to print the
version number and exit.

For example,

grog -Tdvi paper.ms

guesses the appropriate command to print `paper.ms' and then prints it
to the command line after adding the `-Tdvi' option. For direct
execution, enclose the call to `grog' in backquotes at the UNIX shell
prompt:

`grog -Tdvi paper.ms` > paper.dvi

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
`less').

File: groff, Node: Tutorial for Macro Users, Next: Macro Packages, Prev: Invoking groff, Up: Top

Tutorial for Macro Users
************************

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

* Menu:

* Basics::
* Common Features::

File: groff, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users

Basics
======

This section covers some of the basic concepts necessary to
understand how to use a macro package.(1) (*note Basics-Footnote-1::)
References are made throughout to more detailed information, if desired.

`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
("requests" and "escapes"), which tell `gtroff' how to format the
output. For more detail on this, see *Note Embedded Commands::.

The word "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

.sp

spaces one line, but

.sp 4

spaces four lines. The number 4 is an argument to the `sp' request
which says to space four lines instead of one. Arguments are separated
from the request and from each other by spaces (_no_ tabs). More
details on this can be found in *Note Request Arguments::.

The primary function of `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:

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

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

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

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 "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 (`.') or an apostrophe (`'') 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 `gtroff'.

* First, keep the input lines short. Short input lines are easier to
edit, and `gtroff' packs words onto longer lines anyhow.

* 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.

* End each sentence with two spaces - or better, start each sentence
on a new line. `gtroff' recognizes characters that usually end a
sentence, and inserts sentence space accordingly.

* Do not hyphenate words at the end of lines - `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 "mother- in-law".

`gtroff' double-spaces output text automatically if you use the
request `.ls 2'. Reactivate single-spaced mode by typing `.ls 1'.(2)
(*note Basics-Footnote-2::)

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

The `bp' request starts a new page, causing a line break.

The request `.sp N' leaves N lines of blank space. N can be omitted
(meaning skip a single line) or can be of the form Ni (for N inches) or
Nc (for N centimeters). For example, the input:

.sp 1.5i
My thoughts on the subject
.sp

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 *Note Measurements::).

Text lines can be centered by using the `ce' request. The line
after `ce' is centered (horizontally) on the page. To center more than
one line, use `.ce N' (where N is the number of lines to center),
followed by the N lines. To center many lines without counting them,
type:

.ce 1000
lines to center
.ce 0

The `.ce 0' request tells `groff' to center zero more lines, in other
words, stop centering.

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
`br'.

File: groff, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users

Common Features
===============

`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 "macros" and
collected into a "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::

File: groff, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features

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:

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

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

one This is the first paragraph. Notice how the first
line of the resulting paragraph lines up with the
other lines in the paragraph.

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.

A variation of this is a bulleted list.

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

File: groff, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features

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.

File: groff, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features

Headers and Footers
-------------------

Every macro package gives some way to manipulate the "headers" and
"footers" (also called "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 "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 `%' character (see *Note Page Layout::, for more details).

File: groff, Node: Page Layout Adjustment, Next: Displays, Prev: Headers and Footers, Up: Common Features

Page Layout
-----------

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

File: groff, Node: Displays, Next: Footnotes and Annotations, Prev: Page Layout Adjustment, Up: Common Features

Displays
--------

"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.

"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.

A "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.

A "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.

"Floating keeps" move relative to the text. Hence, they are good for
things which are referred to by name, such as "See figure 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.

File: groff, Node: Footnotes and Annotations, Next: Table of Contents, Prev: Displays, Up: Common Features

Footnotes and Annotations
-------------------------

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

"Footnotes" are printed at the bottom of the current page.

"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.

File: groff, Node: Table of Contents, Next: Indices, Prev: Footnotes and Annotations, Up: Common Features

Table of Contents
-----------------

"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).

File: groff, Node: Indices, Next: Paper Formats, Prev: Table of Contents, Up: Common Features

Indices
-------

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

To produce a real index in a document, external tools like the
`makeindex' program are necessary.

File: groff, Node: Paper Formats, Next: Multiple Columns, Prev: Indices, Up: Common Features

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 `mm' macros in particular
provide formats for letters and memoranda.

File: groff, Node: Multiple Columns, Next: Font and Size Changes, Prev: Paper Formats, Up: Common Features

Multiple Columns
----------------

Some macro packages (but not `man') provide the ability to have two
or more columns on a page.

File: groff, Node: Font and Size Changes, Next: Predefined Strings, Prev: Multiple Columns, Up: Common Features

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.

File: groff, Node: Predefined Strings, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features

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.

File: groff, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Strings, Up: Common Features

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
`gtbl') by placing them between `TS' and `TE' macros. The `ms' macro
package has an option, `.TS H', that prints a caption at the top of a
new page (when the table is too long to fit on a single page).

File: groff, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features

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.

File: groff, Node: Macro Packages, Next: gtroff Reference, Prev: Tutorial for Macro Users, Up: Top

Macro Packages
**************

This chapter documents the main macro packages that come with
`groff'.

* Menu:

* man::
* mdoc::
* ms::
* me::
* mm::

File: groff, Node: man, Next: mdoc, Prev: Macro Packages, Up: Macro Packages

`man'
=====

This is the most popular and probably the most important macro
package of `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::

File: groff, Node: Man options, Next: Man usage, Prev: man, Up: man

Options
-------

The command line format for using the `man' macros with `groff' is:

groff -m man [ -rLL=LENGTH ] [ -rLT=LENGTH ]
[ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rPNNN ]
[ -rSXX ] [ -rXNNN ] [ FILES... ]

It is possible to use `-man' instead of `-m man'.

`-rLL=LENGTH'
Set line length to LENGTH. If not specified, the line length
defaults to 78 en in nroff mode (this is 78 characters per line)
and 6.5 inch otherwise.

`-rLT=LENGTH'
Set title length to LENGTH. If not specified, the title length
defaults to 78 en in nroff mode (this is 78 characters per line)
and 6.5 inch otherwise.

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

`-rC1'
If more than one manual page is given on the command line, number
the pages continuously, rather than starting each at 1.

`-rD1'
Double-sided printing. Footers for even and odd pages are
formatted differently.

`-rPNNN'
Page numbering starts with NNN rather than with 1.

`-rSXX'
Use XX (which can be 10, 11, or 12pt) as the base document font
size instead of the default value of 10pt.

`-rXNNN'
After page NNN, number pages as NNNa, NNNb, NNNc, etc. For
example, the option `-rX2' produces the following page numbers: 1,
2, 2a, 2b, 2c, etc.

File: groff, Node: Man usage, Next: Man font macros, Prev: Man options, Up: man

Usage
-----

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

- Macro: .TH title section [extra1 [extra2 [extra3]]]
Set the title of the man page to TITLE and the section to SECTION,
which must have a value between 1 and 8. The value of SECTION may
also have a string appended, e.g. `.pm', to indicate a specific
subsection of the man pages.

Both TITLE and SECTION are positioned at the left and right in the
header line (with SECTION in parentheses immediately appended to
TITLE. EXTRA1 is positioned in the middle of the footer line.
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). EXTRA3 is centered in the header line.

For HTML output, headers and footers are completely suppressed.

Additionally, this macro starts a new page; the new line number
is 1 again (except if the `-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 `TH' macro at
the beginning of the file.

- Macro: .SH [heading]
Set up an unnumbered section heading sticking out to the left.
Prints out all the text following `SH' up to the end of the line
(or the text in the next line if there is no argument to `SH') in
bold face, one size larger than the base document size.
Additionally, the left margin for the following text is reset to
its default value.

- Macro: .SS [heading]
Set up an unnumbered (sub)section heading. Prints out all the text
following `SS' up to the end of the line (or the text in the next
line if there is no argument to `SS') in bold face, at the same
size as the base document size. Additionally, the left margin for
the following text is reset to its default value.

- Macro: .TP [nnn]
Set up an indented paragraph with label. The indentation is set to
NNN if that argument is supplied (the default unit is `n' if
omitted), otherwise it is set to the default indentation value.

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, then the paragraph starts at the same line (but
indented), continuing on the following lines. If the label is
wider than the indentation, then 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.

- Macro: .LP
- Macro: .PP
- Macro: .P
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 `PD' macro. The font size and shape
are reset to the default value (10pt roman if no `-rS' option is
given on the command line). Finally, the current left margin is
restored.

- Macro: .IP [designator [nnn]]
Set up an indented paragraph, using DESIGNATOR as a tag to mark
its beginning. The indentation is set to NNN if that argument is
supplied (default unit is `n'), otherwise the default indentation
value is used. 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 `""' (two double quotes) as the first argument of
`IP'.

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

.IP \(bu 4

- Macro: .HP [nnn]
Set up a paragraph with hanging left indentation. The indentation
is set to NNN if that argument is supplied (default unit is `n'),
otherwise the default indentation value is used. Font size and
face are reset to their default values.

- Macro: .RS [nnn]
Move the left margin to the right by the value NNN if specified
(default unit is `n'); otherwise the default indentation value is
used. Calls to the `RS' macro can be nested.

- Macro: .RE [nnn]
Move the left margin back to level NNN; if no argument is given,
it moves one level back. The first level (i.e., no call to `RS'
yet) has number 1, and each call to `RS' increases the level by 1.

To summarize, the following macros cause a line break with the
insertion of vertical space (which amount can be changed with the `PD'
macro): `SH', `SS', `TP', `LP' (`PP', `P'), `IP', and `HP'.

The macros `RS' and `RE' also cause a break but do not insert
vertical space.

Finally, the macros `SH', `SS', `LP' (`PP', `P'), and `RS' reset the
indentation to its default value.

File: groff, Node: Man font macros, Next: Miscellaneous man macros, Prev: Man usage, Up: man

Macros to set fonts
-------------------

The standard font is roman; the default text size is 10 point. If
command line option `-rS=N' is given, use Npt as the default text size.

- Macro: .SM [text]
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.

- Macro: .SB [text]
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.

- Macro: .BI text
Set its arguments alternately in bold face and italic. Thus,

.BI this "word and" that

would set "this" and "that" in bold face, and "word and" in
italics.

- Macro: .IB text
Set its arguments alternately in italic and bold face.

- Macro: .RI text
Set its arguments alternately in roman and italic.

- Macro: .IR text
Set its arguments alternately in italic and roman.

- Macro: .BR text
Set its arguments alternately in bold face and roman.

- Macro: .RB text
Set its arguments alternately in roman and bold face.

- Macro: .B [text]
Set 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.

- Macro: .I [text]
Set 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.

File: groff, Node: Miscellaneous man macros, Next: Predefined man strings, Prev: Man font macros, Up: man

Miscellaneous macros
--------------------

The default indentation is 7.2 en for all output devices except for
`grohtml' which ignores indentation.

- Macro: .DT
Set tabs every 0.5 inches. Since this macro is always executed
during a call to the `TH' macro, it makes sense to call it only if
the tab positions have been changed.

- Macro: .PD [nnn]
Adjust the empty space before a new paragraph (or section). The
optional argument gives the amount of space (default unit is `v');
without parameter, the value is reset to its default value (1 line
for TTY devices, 0.4v otherwise).

This affects the macros `SH', `SS', `TP', `LP' (as well as `PP' and
`P'), `IP', and `HP'.

File: groff, Node: Predefined man strings, Next: Preprocessors in man pages, Prev: Miscellaneous man macros, Up: man

Predefined strings
------------------

The following strings are defined:

- String: \*[S]
Switch back to the default font size.

- String: \*[R]
The `registered' sign.

- String: \*[Tm]
The `trademark' sign.

- String: \*[lq]
- String: \*[rq]
Left and right quote. This is equal to `\(lq' and `\(rq',
respectively.

File: groff, Node: Preprocessors in man pages, Prev: Predefined man strings, Up: man

Preprocessors in `man' pages
----------------------------

If a preprocessor like `gtbl' or `geqn' is needed, it has become
common usage to make the first line of the man page look like this:

'\" WORD

Note the single space character after the double quote. WORD consists
of letters for the needed preprocessors: `e' for `geqn', `r' for
`grefer', `t' for `gtbl'. Modern implementations of the `man' program
read this first line and automatically call the right preprocessor(s).

File: groff, Node: mdoc, Next: ms, Prev: man, Up: Macro Packages

`mdoc'
======

See the `groff_mdoc(7)' man page (type `man groff_mdoc' at the
command line).

File: groff, Node: ms, Next: me, Prev: mdoc, Up: Macro Packages

`ms'
====

The `-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::

File: groff, Node: ms Intro, Next: General ms Structure, Prev: ms, Up: ms

Introduction to `ms'
--------------------

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

The `ms' macro package included with `groff' is a complete,
bottom-up re-implementation. Several macros (specific to AT&T or
Berkeley) are not included, while several new commands are. *Note
Differences from AT&T ms::, for more information.

File: groff, Node: General ms Structure, Next: ms Document Control Registers, Prev: ms Intro, Up: ms

General structure of an `ms' document
-------------------------------------

The `ms' macro package expects a certain amount of structure, but
not as much as packages such as `man' or `mdoc'.

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

*Document type*
If you invoke the `RP' (report) macro on the first line of the
document, `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 AT&T `troff' are specific to AT&T or Berkeley, and are
not supported in `groff'.

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

*Cover page*
A cover page consists of a title, the author's name and
institution, an abstract, and the date. (1) (*note General ms
Structure-Footnote-1::) *Note ms Cover Page Macros::, for more
details.

*Body*
Following the cover page is your document. You can use the `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. *Note ms Body
Text::, for more details.

*Table of contents*
Longer documents usually include a table of contents, which you
can invoke by placing the `TC' macro at the end of your document.
The `ms' macros have minimal indexing facilities, consisting of the
`IX' macro, which prints an entry on standard error. Printing the
table of contents at the end is necessary since `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 `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.

File: groff, Node: ms Document Control Registers, Next: ms Cover Page Macros, Prev: General ms Structure, Up: ms

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 `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.

Margin Settings
...............

- Register: \n[PO]
Defines the page offset (i.e. the left margin). There is no
explicit right margin setting; the combination of the `PO' and
`LL' registers implicitly define the right margin width.

Effective: next page.

Default value: 1i.

- Register: \n[LL]
Defines the line length (i.e. the width of the body text).

Effective: next paragraph.

Default: 6i.

- Register: \n[LT]
Defines the title length (i.e. the header and footer width). This
is usually the same as `LL', but not necessarily.

Effective: next paragraph.

Default: 6i.

- Register: \n[HM]
Defines the header margin height at the top of the page.

Effective: next page.

Default: 1i.

- Register: \n[FM]
Defines the footer margin height at the bottom of the page.

Effective: next page.

Default: 1i.

Text Settings
.............

- Register: \n[PS]
Defines the point size of the body text.

Effective: next paragraph.

Default: 10p.

- Register: \n[VS]
Defines the space between lines (line height plus leading).

Effective: next paragraph.

Default: 12p.

Paragraph Settings
..................

- Register: \n[PI]
Defines the initial indent of a `.PP' paragraph.

Effective: next paragraph.

Default: 5n.

- Register: \n[PD]
Defines the space between paragraphs.

Effective: next paragraph.

Default: 0.3v.

- Register: \n[QI]
Defines the indent on both sides of a quoted (`.QP') paragraph.

Effective: next paragraph.

Default: 5n.

Footnote Settings
.................

- Register: \n[FL]
Defines the length of a footnote.

Effective: next footnote.

Default: `\n[LL]' * 5 / 6.

- Register: \n[FI]
Defines the footnote indent.

Effective: next footnote.

Default: 2n.

- Register: \n[FF]
The footnote format:
`0'
Prints the footnote number as a superscript; indents the
footnote (default).

`1'
Prints the number followed by a period (like 1.) and indents
the footnote.

`2'
Like 1, without an indent.

`3'
Like 1, but prints the footnote number as a hanging paragraph.

Effective: next footnote.

Default: 0.

Miscellaneous Number Registers
..............................

- Register: \n[MINGW]
Defines the minimum width between columns in a multi-column
document.

Effective: next page.

Default: 2n.

File: groff, Node: ms Cover Page Macros, Next: ms Body Text, Prev: ms Document Control Registers, Up: ms

Cover page macros
-----------------

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

- Macro: .RP [`no']
Specifies the report format for your document. The report format
creates a separate cover page. The default action (no `.RP'
macro) is to print a subset of the cover page on page 1 of your
document.

If you use the word `no' as an optional argument, `groff' prints a
title page but does not repeat any of the title page information
(title, author, abstract, etc.) on page 1 of the document.

- Macro: .DA [...]
(optional) Print 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 `nroff'.

- Macro: .ND [...]
(optional) Print 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 `troff'.

- Macro: .TL
Specifies the document title. `groff' collects text following the
`.TL' macro into the title, until reaching the author name or
abstract.

- Macro: .AU
Specifies the author's name, which appears on the line (or lines)
immediately following. You can specify multiple authors as
follows:

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

...

- Macro: .AI
Specifies the author's institution. You can specify multiple
institutions in the same way that you specify multiple authors.

- Macro: .AB [`no']
Begins the abstract. The default is to print the word ABSTRACT,
centered and in italics, above the text of the abstract. The word
`no' as an optional argument suppresses this heading.

- Macro: .AE
End the abstract.

The following is example mark-up for a title page.

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

File: groff, Node: ms Body Text, Next: ms Page Layout, Prev: ms Cover Page Macros, Up: ms

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::
* Indents in ms::
* Tabstops in ms::
* ms Displays and Keeps::
* ms Insertions::
* Example multi-page table::
* ms Footnotes::

File: groff, Node: Paragraphs in ms, Next: Headings in ms, Prev: ms Body Text, Up: ms Body Text

Paragraphs
..........

The following paragraph types are available.

- Macro: .PP
Sets a paragraph with an initial indent.

- Macro: .LP
Sets a paragraph with no initial indent.

- Macro: .QP
Sets a paragraph that is indented at both left and right margins.
The effect is identical to the HTML `' element. The
next paragraph or heading returns margins to normal.

- Macro: .XP
Sets a paragraph whose lines are indented, except for the first
line. This is a Berkeley extension.

The following markup uses all four paragraph macros.

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

File: groff, Node: Headings in ms, Next: Highlighting in ms, Prev: Paragraphs in ms, Up: ms Body Text

Headings
........

Use headings to create a hierarchical structure for your document.
The `ms' macros print headings in *bold*, using the same font family
and point size as the body text.

The following describes the heading macros:

- Macro: .NH curr-level
- Macro: .NH S level0 ...
Numbered heading. The argument is either a numeric argument to
indicate the level of the heading, or the letter `S' followed by
numeric arguments to set the heading level explicitly.

If you specify heading levels out of sequence, such as invoking
`.NH 3' after `.NH 1', `groff' prints a warning on standard error.

- Macro: .SH
Unnumbered subheading.

File: groff, Node: Highlighting in ms, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text

Highlighting
............

The `ms' macros provide a variety of methods to highlight or
emphasize text:

- Macro: .B [txt [post [pre]]]
Sets its first argument in *bold type*. If you specify a second
argument, `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 *before* the first argument. For example,

.B foo ) (

prints (*foo*).

If you give this macro no arguments, `groff' prints all text
following in bold until the next highlighting, paragraph, or
heading macro.

- Macro: .R [txt [post [pre]]]
Sets its first argument in roman (or regular) type. It operates
similarly to the `B' macro otherwise.

- Macro: .I [txt [post [pre]]]
Sets its first argument in _italic type_. It operates similarly
to the `B' macro otherwise.

- Macro: .CW [txt [post [pre]]]
Sets its first argument in a `constant width face'. It operates
similarly to the `B' macro otherwise.

- Macro: .BI [txt [post [pre]]]
Sets its first argument in bold italic type. It operates
similarly to the `B' macro otherwise.

- Macro: .BX [txt]
Prints its argument and draws a box around it. If you want to box
a string that contains spaces, use a digit-width space (`\0').

- Macro: .UL [txt [post]]
Prints its first argument with an underline. If you specify a
second argument, `groff' prints it in the previous font after the
underlined text, with no intervening space.

- Macro: .LG
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.

- Macro: .SM
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.

- Macro: .NL
Prints all text following in the normal point size (that is, the
value of the `PS' register).

File: groff, Node: Lists in ms, Next: Indents in ms, Prev: Highlighting in ms, Up: ms Body Text

Lists
.....

The `.IP' macro handles duties for all lists.

- Macro: .IP [marker [width]]
The MARKER is usually a bullet glyph (`\[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 WIDTH specifies the indent for the body of each list item; its
default unit is `n'. Once specified, the indent remains the same
for all list items in the document until specified again.

The following is an example of a bulleted list.

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

Produces:

A bulleted list:

o lawyers

o guns

o money

The following is an example of a numbered list.

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

Produces:

A numbered list:

1. lawyers

2. guns

3. money

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

The following is an example of a glossary-style list.

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!

Produces:

A glossary-style list:

lawyers
Two or more attorneys.

guns Firearms, preferably large-caliber.

money
Gotta pay for those lawyers and guns!

In the last example, the `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 `br' request to force a break after
printing the term or label.

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!

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

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!

To set nested lists, use the `RS' and `RE' macros. *Note Indents in
ms::, for more information.

For example:

.IP \[bu] 2
Lawyers:
.RS
.IP \[bu]
Dewey,
.IP \[bu]
Cheatham,
.IP \[bu]
and Howe.
.RE
.IP \[bu]
Guns

Produces:

o Lawyers:

o Dewey,

o Cheatham,

o and Howe.

o Guns

File: groff, Node: Indents in ms, Next: Tabstops in ms, Prev: Lists in ms, Up: ms Body Text

Indents
.......

In many situations, you may need to indent a section of text while
still wrapping and filling. *Note Lists in ms::, for an example of
nested lists.

- Macro: .RS
- Macro: .RE
These macros begin and end an indented section. The `PI' register
controls the amount of indent, allowing the indented text to line
up under hanging and indented paragraphs.

*Note ms Displays and Keeps::, for macros to indent and turn off
filling.

File: groff, Node: Tabstops in ms, Next: ms Displays and Keeps, Prev: Indents in ms, Up: ms Body Text

Tab Stops
.........

Use the `ta' request to define tab stops as needed. *Note Tabs and
Fields::.

- Macro: .TA
Use this macro to reset the tab stops to the default for `ms'
(every 5n). You can redefine the `TA' macro to create a different
set of default tab stops.

File: groff, Node: ms Displays and Keeps, Next: ms Insertions, Prev: Tabstops in ms, Up: ms Body Text

Displays and keeps
..................

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 `br' requests in between each line. Displays can be
"kept" on a single page, or allowed to break across pages.

- Macro: .DS L
- Macro: .LD
- Macro: .DE
Left-justified display. The `.DS L' call generates a page break,
if necessary, to keep the entire display on one page. The `LD'
macro allows the display to break across pages. The `DE' macro
ends the display.

- Macro: .DS I
- Macro: .ID
- Macro: .DE
Indents the display as defined by the `DI' register. The `.DS I'
call generates a page break, if necessary, to keep the entire
display on one page. The `ID' macro allows the display to break
across pages. The `DE' macro ends the display.

- Macro: .DS B
- Macro: .BD
- Macro: .DE
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 `.DS B' call generates a
page break, if necessary, to keep the entire display on one page.
The `BD' macro allows the display to break across pages. The `DE'
macro ends the display.

- Macro: .DS C
- Macro: .CD
- Macro: .DE
Sets a centered display: each line in the display is centered.
The `.DS C' call generates a page break, if necessary, to keep the
entire display on one page. The `CD' macro allows the display to
break across pages. The `DE' macro ends the display.

- Macro: .DS R
- Macro: .RD
- Macro: .DE
Right-justifies each line in the display. The `.DS R' call
generates a page break, if necessary, to keep the entire display
on one page. The `RD' macro allows the display to break across
pages. The `DE' macro ends the display.

On occasion, you may want to "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 `ms' macros provide the `KS' and `KE' macros for this
purpose.

- Macro: .KS
- Macro: .KE
The `KS' macro begins a block of text to be kept on a single page,
and the `KE' macro ends the block.

- Macro: .KF
- Macro: .KE
Specifies a "floating keep"; if the keep cannot fit on the current
page, `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
`bp' request or by reaching the end of the page, `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.

You can also use the `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).

- Macro: .B1
- Macro: .B2
Marks the beginning and ending of text that is to have a box drawn
around it. The `B1' macro begins the box; the `B2' macro ends it.
Text in the box is automatically placed in a diversion (keep).

File: groff, Node: ms Insertions, Next: Example multi-page table, Prev: ms Displays and Keeps, Up: ms Body Text

Tables, figures, equations, and references
..........................................

The `ms' macros support the standard `groff' preprocessors: `tbl',
`pic', `eqn', and `refer'. You mark text meant for preprocessors by
enclosing it in pairs of tags as follows.

- Macro: .TS [`H']
- Macro: .TE
Denotes a table, to be processed by the `tbl' preprocessor. The
optional argument `H' to `TS' instructs `groff' to create a
running header with the information up to the `TH' macro. `groff'
prints the header at the beginning of the table; if the table runs
onto another page, `groff' prints the header on the next page as
well.

- Macro: .PS
- Macro: .PE
Denotes a graphic, to be processed by the `pic' preprocessor. You
can create a `pic' file by hand, using the AT&T `pic' manual
available on the Web as a reference, or by using a graphics
program such as `xfig'.

- Macro: .EQ [align]
- Macro: .EN
Denotes an equation, to be processed by the `eqn' preprocessor.
The optional ALIGN argument can be `C', `L', or `I' to center (the
default), left-justify, or indent the equation.

- Macro: .[
- Macro: .]
Denotes a reference, to be processed by the `refer' preprocessor.
The GNU `refer(1)' man page provides a comprehensive reference to
the preprocessor and the format of the bibliographic database.

* Menu:

* Example multi-page table::

File: groff, Node: Example multi-page table, Next: ms Footnotes, Prev: ms Insertions, Up: ms Body Text

An example multi-page table
...........................

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

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

File: groff, Node: ms Footnotes, Prev: Example multi-page table, Up: ms Body Text

Footnotes
.........

The `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).

- String: \*[*]
Specifies the location of a numbered footnote marker in the text.

- Macro: .FS
- Macro: .FE
Specifies the text of the footnote. The default action is to
create a numbered footnote; you can create a symbolic footnote by
specifying a "mark" glyph (such as `\[dg]' for the dagger glyph)
in the body text and as an argument to the `FS' macro, followed by
the text of the footnote and the `FE' macro.

You can control how `groff' prints footnote numbers by changing the
value of the `FF' register. *Note ms Document Control Registers::.

File: groff, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms

Page layout
-----------

The default output from the `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::

File: groff, Node: ms Headers and Footers, Next: ms Margins, Prev: ms Page Layout, Up: ms Page Layout

Headers and footers
...................

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

- String: \*[LH]
- String: \*[CH]
- String: \*[RH]
Sets the left, center, and right headers.

- String: \*[LF]
- String: \*[CF]
- String: \*[RF]
Sets the left, center, and right footers.

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

- Macro: .OH 'left'center'right'
- Macro: .EH 'left'center'right'
- Macro: .OF 'left'center'right'
- Macro: .EF 'left'center'right'
The `OH' and `EH' macros define headers for the odd and even pages;
the `OF' and `EF' macros define footers for the odd and even pages.
This is more flexible than defining the individual strings.

You can replace the quote (`'') marks with any character not
appearing in the header or footer text.

File: groff, Node: ms Margins, Next: ms Multiple Columns, Prev: ms Headers and Footers, Up: ms Page Layout

Margins
.......

You control margins using a set of number registers. *Note ms
Document Control Registers::, for details.

File: groff, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout

Multiple columns
................

The `ms' macros can set text in as many columns as will 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 *not*
force a page break.

- Macro: .1C
Single-column mode.

- Macro: .2C
Two-column mode.

- Macro: .MC [width [gutter]]
Multi-column mode. If you specify no arguments, it is equivalent
to the `2C' macro. Otherwise, WIDTH is the width of each column
and GUTTER is the space between columns. The `MINGW' number
register controls the default gutter width.

File: groff, Node: ms TOC, Next: ms Strings and Special Characters, Prev: ms Multiple Columns, Up: ms Page Layout

Creating a table of contents
............................

The facilities in the `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 `XS' and `XE' macros.

- Macro: .XS [page]
- Macro: .XA [page]
- Macro: .XE
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:

.NH 1
Introduction
.XS
Introduction
.XE
.LP
...
.CW
.NH 2
Methodology
.XS
Methodology
.XE
.LP
...

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

.XS 1
Introduction
.XA 2
A Brief History of the Universe
.XA 729
Details of Galactic Formation
...
.XE

- Macro: .TC [`no']
Prints the table of contents on a new page, setting the page
number to *i* (Roman numeral one). You should usually place this
macro at the end of the file, since `groff' is a single-pass
formatter and can only print what has been collected up to the
point that the `TC' macro appears.

The optional argument `no' suppresses printing the title specified
by the string register `TOC'.

- Macro: .PX [`no']
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 `no' suppresses printing the title specified
by the string register `TOC'.

The `Groff and Friends HOWTO' includes a `sed' script that
automatically inserts `XS' and `XE' macro entries after each heading in
a document.

Altering the `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 `ms' regularly.

File: groff, Node: ms Strings and Special Characters, Prev: ms TOC, Up: ms Page Layout

Strings and Special Characters
..............................

The `ms' macros provide the following predefined strings. You can
change the string definitions to help in creating documents in
languages other than English.

- String: \*[REFERENCES]
Contains the string printed at the beginning of the references
(bibliography) page. The default is `References'.

- String: \*[ABSTRACT]
Contains the string printed at the beginning of the abstract. The
default is `ABSTRACT'.

- String: \*[TOC]
Contains the string printed at the beginning of the table of
contents.

- String: \*[MONTH1]
- String: \*[MONTH2]
- String: \*[MONTH3]
- String: \*[MONTH4]
- String: \*[MONTH5]
- String: \*[MONTH6]
- String: \*[MONTH7]
- String: \*[MONTH8]
- String: \*[MONTH9]
- String: \*[MONTH10]
- String: \*[MONTH11]
- String: \*[MONTH12]
Prints the full name of the month in dates. The default is
`January', `February', etc.

The following special characters are available(1) (*note ms Strings
and Special Characters-Footnote-1::):

- String: \*[-]
Prints an em dash.

- String: \*[*Q]
- String: \*[*U]
Prints typographer's quotes in troff, plain quotes in nroff. `*Q'
is the left quote and `*U' is the right quote.

Improved accent marks are available in the `ms' macros.

- Macro: .AM
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 *after* the character being
accented.

The following accent marks are available after invoking the `AM'
macro:

- String: \*[']
Acute accent.

- String: \*[`]
Grave accent.

- String: \*[^]
Circumflex.

- String: \*[,]
Cedilla.

- String: \*[~]
Tilde.

- String: \*[:]
Umlaut.

- String: \*[v]
Hacek.

- String: \*[_]
Macron (overbar).

- String: \*[.]
Underdot.

- String: \*[o]
Ring above.

The following are standalone characters available after invoking the
`AM' macro:

- String: \*[?]
Upside-down question mark.

- String: \*[!]
Upside-down exclamation point.

- String: \*[8]
German ss ligature.

- String: \*[3]
Yogh.

- String: \*[Th]
Uppercase thorn.

- String: \*[th]
Lowercase thorn.

- String: \*[D-]
Uppercase eth.

- String: \*[d-]
Lowercase eth.

- String: \*[q]
Hooked o.

- String: \*[ae]
Lowercase ae ligature.

- String: \*[Ae]
Uppercase AE ligature.

File: groff, Node: Differences from AT&T ms, Prev: ms Page Layout, Up: ms

Differences from AT&T `ms'
--------------------------

This section lists the (minor) differences between the `groff -ms'
macros and AT&T `troff -ms' macros.

* Menu:

* Missing ms Macros::
* Additional ms Macros::

File: groff, Node: Missing ms Macros, Next: Additional ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms

`troff' macros not appearing in `groff'
.......................................

Macros missing from `groff -ms' are cover page macros specific to
Bell Labs. The macros known to be missing are:

`.TM'
Technical memorandum; a cover sheet style

`.IM'
Internal memorandum; a cover sheet style

`.MR'
Memo for record; a cover sheet style

`.MF'
Memo for file; a cover sheet style

`.EG'
Engineer's notes; a cover sheet style

`.TR'
Computing Science Tech Report; a cover sheet style

`.OK'
Other keywords

`.CS'
Cover sheet information

`.MH'
A cover sheet macro

File: groff, Node: Additional ms Macros, Prev: Missing ms Macros, Up: Differences from AT&T ms

`groff' macros not appearing in AT&T `troff'
............................................

The `groff -ms' macros have a few minor extensions compared to the
AT&T `troff -ms' macros.

- Macro: .AM
Improved accent marks. *Note ms Strings and Special Characters::,
for details.

- Macro: .DS I
Indented display. The default behavior of AT&T `troff -ms' was to
indent; the `groff' default prints displays flush left with the
body text.

- Macro: .CW
Print text in `constant width' (Courier) font.

- Macro: .IX
Indexing term (printed on standard error). You can write a script
to capture and process an index generated in this manner.

The following additional number registers appear in `groff -ms':

- Register: \n[MINGW]
Specifies a minimum space between columns (for multi-column
output); this takes the place of the `GW' register that was
documented but apparently not implemented in AT&T `troff'.

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

File: groff, Node: me, Next: mm, Prev: ms, Up: Macro Packages

`me'
====

See the `meintro.me' and `meref.me' documents in groff's `doc'
directory.

File: groff, Node: mm, Prev: me, Up: Macro Packages

`mm'
====

See the `groff_mm(7)' man page (type `man groff_mm' at the command
line).

File: groff, Node: gtroff Reference, Next: Preprocessors, Prev: Macro Packages, Up: Top

`gtroff' Reference
******************

This chapter covers *all* of the facilities of `gtroff'. Users of
macro packages may skip it if not interested in details.

* Menu:

* Text::
* Input Conventions::
* 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::
* 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::

File: groff, Node: Text, Next: Input Conventions, Prev: gtroff Reference, Up: gtroff Reference

Text
====

`gtroff' input files contain text with control commands interspersed
throughout. But, even without control codes, `gtroff' still does
several things with the input text:

* filling and adjusting

* adding additional space after sentences

* hyphenating

* inserting implicit line breaks

* Menu:

* Filling and Adjusting::
* Hyphenation::
* Sentences::
* Tab Stops::
* Implicit Line Breaks::

File: groff, Node: Filling and Adjusting, Next: Hyphenation, Prev: Text, Up: Text

Filling and Adjusting
---------------------

When `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
"filling".

Once `gtroff' has a "filled" line, it tries to "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 "break" (breaks are explained in
*Note Implicit Line Breaks::).

*Note Manipulating Filling and Adjusting::.

File: groff, Node: Hyphenation, Next: Sentences, Prev: Filling and Adjusting, Up: Text

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, `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.

*Note Manipulating Hyphenation::.

File: groff, Node: Sentences, Next: Tab Stops, Prev: Hyphenation, Up: Text

Sentences
---------

Although it is often debated, some typesetting rules say there
should be different amounts of space after various punctuation marks.
For example, the `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.

`gtroff' does this by flagging certain characters (normally `!',
`?', and `.') as "end-of-sentence" characters. When `gtroff'
encounters one of these characters at the end of a line, it appends a
normal space followed by a "sentence space" in the formatted output.
(This justifies one of the conventions mentioned in *Note Input
Conventions::.)

In addition, the following characters and symbols are treated
transparently while handling end-of-sentence characters: `"', `'', `)',
`]', `*', `\[dg]', and `\[rq]'.

See the `cflags' request in *Note Using Symbols::, for more details.

To prevent the insertion of extra space after an end-of-sentence
character (at the end of a line), append `\&'.

File: groff, Node: Tab Stops, Next: Implicit Line Breaks, Prev: Sentences, Up: Text

Tab Stops
---------

`gtroff' translates "tabulator characters", also called "tabs"
(normally code point ASCII `0x09' or EBCDIC `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 `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

1 2 3
4 5

produces

1 2 3 4 5

*Note Tabs and Fields::.

File: groff, Node: Implicit Line Breaks, Prev: Tab Stops, Up: Text

Implicit Line Breaks
--------------------

An important concept in `gtroff' is the "break". When a break
occurs, `gtroff' outputs the partially filled line (unjustified), and
resumes collecting and filling text on the next output line.

There are several ways to cause a break in `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 `blm'. *Note Blank Line Traps::.

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 *Note Manipulating Filling and Adjusting::.

File: groff, Node: Input Conventions, Next: Measurements, Prev: Text, Up: gtroff Reference

Input Conventions
=================

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

* 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.

* Try to keep lines less than 40-60 characters, to allow space for
inserting more text.

* Do not try to do any formatting in a WYSIWYG manner (i.e., don't
try using spaces to get proper indentation).

File: groff, Node: Measurements, Next: Expressions, Prev: Input Conventions, Up: gtroff Reference

Measurements
============

`gtroff' (like many other programs) requires numeric parameters to
specify various measurements. Most numeric parameters(1) (*note
Measurements-Footnote-1::) may have a "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 `gtroff', to be a multiple of its "basic unit". So, whenever a
different measurement unit is specified `gtroff' converts this into its
"basic units". This basic unit, represented by a `u', is a device
dependent measurement which is quite small, ranging from 1/75th to
1/72000th 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 `gtroff'.

`i'
Inches. An antiquated measurement unit still in use in certain
backwards countries with incredibly low-cost computer equipment.
One inch is equal to 2.54cm.

`c'
Centimeters. One centimeter is equal to 0.3937in.

`p'
Points. This is a typesetter's measurement used for measure type
size. It is 72 points to an inch.

`P'
Pica. Another typesetting measurement. 6 Picas to an inch (and
12 points to a pica).

`s'
`z'
*Note Fractional Type Sizes::, for a discussion of these units.

`f'
Fractions. Value is 65536. *Note Colors::, for usage.

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

`m'
Ems. This unit is equal to the current font size in points. So
called because it is _approximately_ the width of the letter `m'
in the current font.

`n'
Ens. In `groff', this is half of an em.

`v'
Vertical space. This is equivalent to the current line spacing.
*Note Sizes::, for more information about this.

`M'
100ths of an em.

* Menu:

* Default Units::

File: groff, Node: Default Units, Prev: Measurements, Up: Measurements

Default Units
-------------

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 inches and their results:

3.5i => 3.5i
7/2 => 0i
7/2i => 0i
(7 / 2)u => 0i
7i/2 => 0.1i
7i/2u => 3.5i

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

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 `u' as the unit for that value.

File: groff, Node: Expressions, Next: Identifiers, Prev: Measurements, Up: gtroff Reference

Expressions
===========

`gtroff' has most arithmetic operators common to other languages:

* Arithmetic: `+' (addition), `-' (subtraction), `/' (division), `*'
(multiplication), `%' (modulo).

`gtroff' only provides integer arithmetic. The internal type used
for computing results is `int', which is usually a 32bit signed
integer.

* Comparison: `<' (less than), `>' (greater than), `<=' (less than
or equal), `>=' (greater than or equal), `=' (equal), `==' (the
same as `=').

* Logical: `&' (logical and), `:' (logical or).

* Unary operators: `-' (negating, i.e. changing the sign), `+' (just
for completeness; does nothing in expressions), `!' (logical not;
this works only within `if' and `while' requests). See below for
the use of unary operators in motion requests.

* Extrema: `>?' (maximum), `? \n[y])

The register `z' now contains 5.

* Scaling: `(C;E)'. Evaluate E using C as the default scaling
indicator. If C is missing, ignore scaling indicators in the
evaluation of E.

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

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

Similarly, a leading `|' 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 _input_ line.

`+' and `-' are also treated differently by the following requests
and escapes: `bp', `in', `ll', `lt', `nm', `nr', `pl', `pn', `po', `ps',
`pvs', `rt', `ti', `\H', `\R', and `\s'. Here, leading plus and minus
signs indicate increments and decrements.

*Note Setting Registers::, for some examples.

- Escape: \B'ANYTHING'
Return 1 if ANYTHING is a valid numeric expression; or 0 if
ANYTHING is empty or not a valid numeric expression.

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

*Note Request Arguments::, and *Note Conditionals and Loops::.

File: groff, Node: Identifiers, Next: Embedded Commands, Prev: Expressions, Up: gtroff Reference

Identifiers
===========

Like any other language, `gtroff' has rules for properly formed
"identifiers". In `gtroff', an identifier can be made up of almost any
printable character, with the exception of the following characters:

* Whitespace characters (spaces, tabs, and newlines).

* Backspace (ASCII `0x08' or EBCDIC `0x16') and character code
`0x01'.

* The following input characters are invalid and are ignored if
`groff' runs on a machine based on ASCII, causing a warning
message of type `input' (see *Note Debugging::, for more details):
`0x00', `0x0B', `0x0D'-`0x1F', `0x80'-`0x9F'.

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

Currently, some of these reserved codepoints are used internally,
thus making it non-trivial to extend `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 `foo', followed by an invalid character, followed by
`bar' is treated as `foobar'.

For example, any of the following is valid.

br
PP
(l
end-list
@_

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

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

- Escape: \A'IDENT'
Test whether an identifier IDENT is valid in `gtroff'. It expands
to the character 1 or 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 0 if no argument is given. This is useful for looking
up user input in some sort of associative table.

\A'end-list'
=> 1

*Note Escapes::, for details on parameter delimiting characters.

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

* Single character.

* Two characters. Must be prefixed with `(' in some situations.

* Arbitrary length (`gtroff' only). Must be bracketed with `['
and `]' in some situations. Any length identifier can be put in
brackets.

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

* If the identifier is a string, macro, or diversion, `gtroff'
defines it as empty.

* If the identifier is a number register, `gtroff' defines it with a
value of 0.

*Note Warnings::., *Note Interpolating Registers::, and *Note
Strings::.

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

.de xxx
. nop foo
..
.
.di xxx
bar
.br
.di
.
.xxx
=> bar

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

*Note Interpolating Registers::, and *Note Strings::.

File: groff, Node: Embedded Commands, Next: Registers, Prev: Identifiers, Up: gtroff Reference

Embedded Commands
=================

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

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

The other is an "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::

File: groff, Node: Requests, Next: Macros, Prev: Embedded Commands, Up: Embedded Commands

Requests
--------

A request line begins with a control character, which is either a
single quote (`'', the "no-break control character") or a period (`.',
the normal "control character"). These can be changed; see *Note
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 (_no_ tabs here).

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.

.de foo
. tm This is foo.
..
.
.
.de bar
. tm This is bar.
..

Another possibility is to use the blank line macro request `blm' by
assigning an empty macro to it.

.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

*Note Blank Line Traps::.

To begin a line with a control character without it being
interpreted, precede it with `\&'. 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.

* Menu:

* Request Arguments::

File: groff, Node: Request Arguments, Prev: Requests, Up: Requests

Request Arguments
.................

Arguments to requests (and macros) are processed much like the shell:
The line is split into arguments according to spaces.(1) (*note Request
Arguments-Footnote-1::) An argument which is intended to contain
spaces can either be enclosed in double quotes, or have the spaces
"escaped" with backslashes.

Here are a few examples:

.uh The Mouse Problem
.uh "The Mouse Problem"
.uh The\ Mouse\ Problem

The first line is the `uh' macro being called with 3 arguments, `The',
`Mouse', and `Problem'. The latter two have the same effect of calling
the `uh' macro with one argument, `The Mouse Problem'.(2) (*note
Request Arguments-Footnote-2::)

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,

.xxx a" "b c" "de"fg"

has the arguments `a"', `b c', `de', and `fg"'. Don't rely on this
obscure behaviour!

There are two possibilities to get a double quote reliably.

* 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 `-C' option of `groff'):

.de xx
. tm xx: `\\$1' `\\$2' `\\$3'
.
. yy "\\$1" "\\$2" "\\$3"
..
.de yy
. tm yy: `\\$1' `\\$2' `\\$3'
..
.xx A "test with ""quotes""" .
=> xx: `A' `test with "quotes"' `.'
=> yy: `A' `test with ' `quotes""'

If not in compatibility mode, you get the expected result

xx: `A' `test with "quotes"' `.'
yy: `A' `test with "quotes"' `.'

since `gtroff' preserves the input level.

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

Not that this method won't work with UNIX `troff' in general since
the glyph `dq' isn't defined normally.

Double quotes in the `ds' request are handled differently. *Note
Strings::, for more details.

File: groff, Node: Macros, Next: Escapes, Prev: Requests, Up: Embedded Commands

Macros
------

`gtroff' has a "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 in the same manner.

*Note Writing Macros::, and *Note Request Arguments::.

File: groff, Node: Escapes, Prev: Macros, Up: Embedded Commands

Escapes
-------

Escapes may occur anywhere in the input to `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 *Note Character Translations::.

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

* The next single character is the identifier.

* 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.

* If this single character is an opening bracket, take all characters
until a closing bracket as the identifier.

Examples:

\fB
\n(XX
\*[TeX]

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:

\l'1.5i\(bu'

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: `\o', `\b', and `\X'. This
makes e.g.

A caf
\o
e\'

in Paris
=> A cafe' in Paris

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

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

No newline characters as delimiters are allowed in the following
escapes: `\A', `\B', `\Z', `\C', and `\w'.

Finally, the escapes `\D', `\h', `\H', `\l', `\L', `\N', `\R', `\s',
`\S', `\v', and `\x' can't use the following characters as delimiters:

* The digits `0'-`9'.

* The (single-character) operators `+-/*%<>=&:().'.

* The space, tab, and newline characters.

* All escape sequences except `\%', `\:', `\{', `\}', `\'', `\`',
`\-', `\_', `\!', `\@', `\/', `\c', `\e', and `\p'.

To have a backslash (actually, the current escape character) appear
in the output several escapes are defined: `\\', `\e' or `\E'. These
are very similar, and only differ with respect to being used in macros
or diversions. *Note Character Translations::, for an exact
description of those escapes.

*Note Implementation Differences::, *Note Copy-in Mode::, and *Note
Diversions::, *Note Identifiers::, for more information.

* Menu:

* Comments::

File: groff, Node: Comments, Prev: Escapes, Up: Escapes

Comments
........

Probably one of the most(1) (*note Comments-Footnote-1::) common
forms of escapes is the comment.

- Escape: \"
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.

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 `gtroff'. This only affects the `ds' and `as' request
and its variants.

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.

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

Test
\" comment
Test

produces

Test

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

Another commenting scheme seen sometimes is three consecutive
single quotes (`'''') at the beginning of a line. This works, but
`gtroff' gives a warning about an undefined macro (namely `'''),
which is harmless, but irritating.

- Escape: \#
To avoid all this, `gtroff' has a new comment mechanism using the
`\#' escape. This escape works the same as `\"' except that the
newline is also ignored:

Test
\# comment
Test

produces

Test Test

as expected.

- Request: .ig yy
Ignore all input until `gtroff' encounters the macro named `.'YY
on a line by itself (or `..' if YY is not specified). This is
useful for commenting out large blocks of text:

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

produces

text text text... More text text text...

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

The input is read in copy-mode; auto-incremented registers _are_
affected (*note Auto-increment::).

File: groff, Node: Registers, Next: Manipulating Filling and Adjusting, Prev: Embedded Commands, Up: gtroff Reference

Registers
=========

Numeric variables in `gtroff' are called "registers". There are a
number of built-in registers, supplying anything from the date to
details of formatting parameters.

*Note Identifiers::, for details on register identifiers.

* Menu:

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

File: groff, Node: Setting Registers, Next: Interpolating Registers, Prev: Registers, Up: Registers

Setting Registers
-----------------

Define or set registers using the `nr' request or the `\R' escape.

- Request: .nr ident value
- Escape: \R'IDENT VALUE'
Set number register IDENT to VALUE. If IDENT doesn't exist,
`gtroff' creates it.

The argument to `\R' usually has to be enclosed in quotes. *Note
Escapes::, for details on parameter delimiting characters.

The `\R' escape doesn't produce an input token in `gtroff'; with
other words, it vanishes completely after `gtroff' has processed
it.

For example, the following two lines are equivalent:

.nr a (((17 + (3 * 4))) % 4)
\R'a (((17 + (3 * 4))) % 4)'
=> 1

Both `nr' and `\R' have two additional special forms to increment or
decrement a register.

- Request: .nr ident +value
- Request: .nr ident -value
- Escape: \R'IDENT +VALUE'
- Escape: \R'IDENT -VALUE'
Increment (decrement) register IDENT by VALUE.

.nr a 1
.nr a +1
\na
=> 2

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

.nr a 7
.nr b 3
.nr a -\nb
\na
=> 4
.nr a (-\nb)
\na
=> -3

The surrounding parentheses prevent the interpretation of the
minus sign as a decrementing operator. An alternative is to start
the assignment with a `0':

.nr a 7
.nr b -3
.nr a \nb
\na
=> 4
.nr a 0\nb
\na
=> -3

- Request: .rr ident
Remove number register IDENT. If IDENT doesn't exist, the request
is ignored.

- Request: .rnn ident1 ident2
Rename number register IDENT1 to IDENT2. If either IDENT1 or
IDENT2 doesn't exist, the request is ignored.

- Request: .aln ident1 ident2
Create an alias IDENT1 for a number register IDENT2. The new name
and the old name are exactly equivalent. If IDENT1 is undefined,
a warning of type `reg' is generated, and the request is ignored.
*Note Debugging::, for information about warnings.

File: groff, Node: Interpolating Registers, Next: Auto-increment, Prev: Setting Registers, Up: Registers

Interpolating Registers
-----------------------

Numeric registers can be accessed via the `\n' escape.

- Escape: \nI
- Escape: \n(ID
- Escape: \n[IDENT]
Interpolate number register with name IDENT (one-character name I,
two-character name ID). This means that the value of the register
is expanded in-place while `gtroff' is parsing the input line.
Nested assignments (also called indirect assignments) are possible.

.nr a 5
.nr as \na+\na
\n(as
=> 10

.nr a1 5
.nr ab 6
.ds str b
.ds num 1
\n[a\n[num]]
=> 5
\n[a\*[str]]
=> 6

File: groff, Node: Auto-increment, Next: Assigning Formats, Prev: Interpolating Registers, Up: Registers

Auto-increment
--------------

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

- Request: .nr ident value incr
Set number register IDENT to VALUE; the increment for
auto-incrementing is set to INCR. Note that the `\R' escape
doesn't support this notation.

To activate auto-incrementing, the escape `\n' has a special syntax
form.

- Escape: \n+I
- Escape: \n-I
- Escape: \n(+ID
- Escape: \n(-ID
- Escape: \n+(ID
- Escape: \n-(ID
- Escape: \n[+IDENT]
- Escape: \n[-IDENT]
- Escape: \n+[IDENT]
- Escape: \n-[IDENT]
Before interpolating, increment or decrement IDENT (one-character
name I, two-character name ID) by the auto-increment value as
specified with the `nr' request (or the `\R' escape). If no
auto-increment value has been specified, these syntax forms are
identical to `\n'.

For 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]

produces

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

To change the increment value without changing the value of a
register (A in the example), the following can be used:

.nr a \na 10

File: groff, Node: Assigning Formats, Next: Built-in Registers, Prev: Auto-increment, Up: Registers

Assigning Formats
-----------------

When a register is used in the text of an input file (as opposed to
part of an expression), it is 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 `af' request.

- Request: .af ident format
Change the output format of a number register. The first argument
IDENT is the name of the number register to be changed, and the
second argument FORMAT is the output format. The following output
formats are available:

`1'
Decimal arabic numbers. This is the default format: 0, 1, 2,
3, ....

`0...0'
Decimal numbers with as many digits as specified. So, `00'
would result in printing numbers as 01, 02, 03, ....

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

`I'
Upper-case Roman numerals: 0, I, II, III, IV, ....

`i'
Lower-case Roman numerals: 0, i, ii, iii, iv, ....

`A'
Upper-case letters: 0, A, B, C, ..., Z, AA, AB, ....

`a'
Lower-case letters: 0, a, b, c, ..., z, aa, ab, ....

Omitting the number register format causes a warning of type
`missing'. *Note Debugging::, for more details. Specifying a
nonexistent format causes an error.

The following example produces `10, X, j, 010':

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

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

If IDENT doesn't exist, it is created.

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 `af' request to this other
register.

- Escape: \gI
- Escape: \g(ID
- Escape: \g[IDENT]
Return the current format of the specif