The GNU Troff Manual

Table of Contents

GNU troff

This manual documents GNU troff version 1.22.4.

Copyright © 1994–2018 Free Software Foundation, Inc.

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

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”

1 Introduction

GNU troff (or groff) is a system for typesetting documents. troff is very flexible and has been used extensively for some thirty years. It is well entrenched in the Unix community.

1.1 What Is groff?

groff belongs to an older generation of document preparation systems, which operate more like compilers than the more recent interactive WYSIWYG¹ 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.

groff should not be confused with a word processor, an integrated system of editor and 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 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)

1.2 History

troff can trace its origins back to a formatting program called RUNOFF, written by Jerry Saltzer, which ran on the CTSS (Compatible Time Sharing System, a project of MIT, the Massachusetts Institute of Technology) in the mid-sixties.² The name came from the use of the phrase “run off a document”, meaning to print it out. 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 McIlroy rewrote an extended and simplified version of roff in the BCPL programming language.

In 1971, the Unix developers wanted to get a PDP-11, and to justify the cost, proposed the development of a document formatting system for the AT&T patents division. This first formatting program was a reimplementation of McIlroy’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 that were not applicable (e.g. font changes).

Since there are several things that 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 died by a severe heart attack in a hospital while recovering from a previous one.

So, Brian Kernighan took on the task of rewriting troff. The newly rewritten version produced device independent code that 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 that would produce ASCII output.
• A version of the me macros and an implementation of the man macros.

Also, a front-end was included that 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 and XHTML have been added.

1.3 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

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

1.5 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 that 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), processing bibliographies (refer), and drawing chemical structures (chem). An associated program that 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.

Unique to groff is the preconv preprocessor that enables groff to handle documents in various input encodings.

There are other preprocessors in existence, but, unfortunately, no free implementations are available. Among them is a preprocessor for drawing mathematical pictures (ideal).

1.6 Output Devices

groff actually produces device independent code that 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), HTML, XHTML, and PDF.

1.7 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 on the ms macro package.

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

2.1 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, gchem, grefer, gsoelim, or preconv.

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 Invoking gpic, Invoking geqn, Invoking gtbl, Invoking ggrn, Invoking grefer, Invoking gchem, Invoking gsoelim, Invoking preconv, Invoking grotty, Invoking grops, Invoking gropdf, Invoking grohtml, Invoking grodvi, Invoking grolj4, Invoking grolbp, and Invoking gxditview.

The command-line format for groff is:

groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dcs ] [ -Darg ]
      [ -ffam ] [ -Fdir ] [ -Idir ] [ -Karg ]
      [ -Larg ] [ -mname ] [ -Mdir ] [ -nnum ]
      [ -olist ] [ -Parg ] [ -rcn ] [ -Tdev ]
      [ -wname ] [ -Wname ] [ files… ]

The command-line format for gtroff is as follows.

gtroff [ -abcivzCERU ] [ -dcs ] [ -ffam ] [ -Fdir ]
       [ -mname ] [ -Mdir ] [ -nnum ] [ -olist ]
       [ -rcn ] [ -Tname ] [ -wname ] [ -Wname ]
       [ 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:

‘-a’

Generate an ASCII approximation of the typeset output. The read-only register .A is then set to 1. See 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.

‘-c’

Suppress color output.

‘-C’

Enable compatibility mode. See 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).

‘-Darg’

Set default input encoding used by preconv to arg. Implies -k.

‘-e’

Preprocess with geqn.

‘-E’

Inhibit all error messages.

‘-ffam’

Use fam as the default font family. See Font Families.

‘-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 (see Font Directories). This option is passed to all pre- and postprocessors using the GROFF_FONT_PATH environment variable.

‘-g’

Preprocess with ggrn.

‘-G’

Preprocess with grap. Implies -p.

‘-h’

Print a help message.

‘-i’

Read the standard input after all the named input files have been processed.

‘-Idir’

This option may be used to specify a directory to search for files. It is passed to the following programs:

• gsoelim (see gsoelim for more details); it also implies groff’s -s option.
• gtroff; it is used to search files named in the psbb and so requests.
• grops; it is used to search files named in the \X'ps: import and \X'ps: file escapes.

The current directory is always searched first. This option may be specified more than once; the directories are searched in the order specified. No directory search is performed for files specified using an absolute path.

‘-j’

Preprocess with gchem. Implies -p.

‘-k’

Preprocess with preconv. This is run before any other preprocessor. Please refer to preconv’s manual page for its behaviour if no -K (or -D) option is specified.

‘-Karg’

Set input encoding used by preconv to arg. Implies -k.

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

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

‘-Mdir’

Search directory dir for macro files before the standard directories (see Macro Directories).

‘-nnum’

Number the first page num.

‘-N’

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

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

‘-p’

Preprocess with gpic.

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

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

‘-R’

Preprocess with grefer. No mechanism is provided for passing arguments to grefer because most grefer options have equivalent commands that can be included in the file. See 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.

‘-s’

Preprocess with gsoelim.

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

‘-t’

Preprocess with gtbl.

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

pdf

For PDF viewers or printers.

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 that use the Unicode (ISO 10646) character set with UTF-8 encoding.

cp1047

For typewriter-like devices that 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

xhtml

To produce HTML and XHTML output, respectively. Note that this 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). See Built-in Registers.

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

‘-U’

Unsafe mode. This enables the open, opena, pso, sy, and pi requests.

‘-wname’

Enable warning name. Available warnings are described in Debugging. Multiple -w options are allowed.

‘-Wname’

Inhibit warning name. Multiple -W options are allowed.

‘-v’

Make programs run by groff print out their version number.

‘-V’

Print the pipeline on stdout instead of executing it. If specified more than once, print the pipeline on stderr and execute it.

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

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

2.2 Environment

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

GROFF_BIN_PATH

This search path, followed by PATH, is used for commands executed by 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, chem, refer, and soelim. It does not apply to grops, grodvi, grotty, pre-grohtml, post-grohtml, preconv, grolj4, gropdf, 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_ENCODING

The value of this environment value is passed to the preconv preprocessor to select the encoding of input files. Setting this option implies groff’s command-line option -k (that is, groff actually always calls preconv). If set without a value, groff calls preconv without arguments. An explicit -K command-line option overrides the value of GROFF_ENCODING. See the manual page of preconv for details.

GROFF_FONT_PATH

A colon-separated list of directories in which to search for the devname directory (before the default directories are tried). See Font Directories.

GROFF_TMAC_PATH

A colon-separated list of directories in which to search for macro files (before the default directories are tried). See Macro Directories.

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.

GROFF_TYPESETTER

The default output device.

SOURCE_DATE_EPOCH

A timestamp (expressed as seconds since the Unix epoch) to use in place of the current time when initializing time-based built-in registers such as \n[seconds].

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.

2.3 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.22.3/tmac
  

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

2.4 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 (see 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 always append the directory devname, 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.22.3/font
  

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

2.5 Paper Size

In groff, the page size for gtroff and for output devices are handled separately. See Page Layout, for vertical manipulation of the page size. See Line Layout, for horizontal changes.

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

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

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

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

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

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

groff -man -rD1 -z file

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

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

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

3.1 Basics

This section covers some of the basic concepts necessary to understand how to use a macro package.⁴ 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 Embedded Commands.

The word argument is used in this chapter to mean a word or number that 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 Request and Macro 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 that 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’.⁵

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

3.2 Common Features

gtroff provides very low-level operations for formatting a document. There are many common routine operations that 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 that fall into the following categories.

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

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

3.2.3 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 Page Layout, for more details).

3.2.4 Page Layout

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

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

3.2.6 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 that supply this functionality also supply a means of automatically numbering either type of annotation.

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

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

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

3.2.10 Multiple Columns

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

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

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

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

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

4 Macro Packages

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

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

groff -m man foo.man -m ms bar.doc

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

groff -m man -m ms foo.man bar.doc

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

4.1.1 Options

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

groff -m man [ -rLL=length ] [ -rLT=length ] [ -rFT=dist ]
      [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=flags ]
      [ -rPnnn ] [ -rSxx ] [ -rXnnn ]
      [ -rIN=length ] [ -rSN=length ] [ files… ]

It is possible to use ‘-man’ instead of ‘-m man’.

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

-rFT=dist

Set the position of the footer text to dist. If positive, the distance is measured relative to the top of the page, otherwise it is relative to the bottom. The default is -0.5i.

-rHY=flags

Set hyphenation flags. Possible values are 1 to hyphenate without restrictions, 2 to not hyphenate the last word on a page, 4 to not hyphenate the last two characters of a word, and 8 to not hyphenate the first two characters of a word. These values are additive; the default is 8.

-rIN=length

Set the body text indentation to length. If not specified, the indentation defaults to 7n (7 characters) in nroff mode and 7.2n otherwise. For nroff, this value should always be an integer multiple of unit ‘n’ to get consistent indentation.

-rLL=length

Set line length to length. If not specified, the line length is set to respect any value set by a prior ‘ll’ request (which must be in effect when the ‘TH’ macro is invoked), if this differs from the built-in default for the formatter; otherwise it defaults to 78n in nroff mode (this is 78 characters per line) and 6.5i in troff mode.⁶

-rLT=length

Set title length to length. If not specified, the title length defaults to the line length.

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

-rSN=length

Set the indentation for sub-subheadings to length. If not specified, the indentation defaults to 3n.

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

4.1.2 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 and XHTML 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 (or the font specified by the string HF), one size larger than the base document size. Additionally, the left margin and the indentation for the following text is reset to its default value.

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 (or the font specified by the string HF), at the same size as the base document size. Additionally, the left margin and the indentation for the following text is reset to its default value.

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 previous indentation value specified with TP, IP, or HP (or to the default value if none of them have been used yet).

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

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 and the indentation 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 it is set to the previous indentation value specified with TP, IP, or HP (or the default value if none of them have been used yet). Font size and face of the paragraph (but not the designator) are reset to their default values.

To start an indented paragraph with a particular indentation but without a designator, use ‘""’ (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 it is set to the previous indentation value specified with TP, IP, or HP (or the default value if non of them have been used yet). 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 it is set to the previous indentation value specified with TP, IP, or HP (or to the default value if none of them have been used yet). The indentation value is then set to the default.

Calls to the RS macro can be nested.

Macro: .RE [nnn]

Move the left margin back to level nnn, restoring the previous left margin. 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.

4.1.3 Macros to set fonts

The standard font is roman; the default text size is 10 points. If command-line option -rS=n is given, use n points 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, without a space between the arguments. Thus,

.BI this "word and" that

produces “thisword andthat” with “this” and “that” in bold face, and “word and” in italics.

Macro: .IB text

Set its arguments alternately in italic and bold face, without a space between the arguments.

Macro: .RI text

Set its arguments alternately in roman and italic, without a space between the arguments.

Macro: .IR text

Set its arguments alternately in italic and roman, without a space between the arguments.

Macro: .BR text

Set its arguments alternately in bold face and roman, without a space between the arguments.

Macro: .RB text

Set its arguments alternately in roman and bold face, without a space between the arguments.

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.

4.1.4 Miscellaneous macros

The default indentation is 7.2n in troff mode and 7n in nroff mode 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 in nroff mode, 0.4v otherwise).

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

The following two macros are included for BSD compatibility.

Macro: .AT [system [release]]

Alter the footer for use with AT&T manpages. This command exists only for compatibility; don’t use it. The first argument system can be:

3

7th Edition (the default)

4

System III

5

System V

An optional second argument release to AT specifies the release number (such as “System V Release 3”).

Macro: .UC [version]

Alters the footer for use with BSD manpages. This command exists only for compatibility; don’t use it. The argument can be:

3

3rd Berkeley Distribution (the default)

4

4th Berkeley Distribution

5

4.2 Berkeley Distribution

6

4.3 Berkeley Distribution

7

4.4 Berkeley Distribution

4.1.5 Predefined strings

The following strings are defined:

String: \*[S]

Switch back to the default font size.

String: \*[HF]

The typeface used for headings. The default is ‘B’.

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.

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

4.1.7 Optional man extensions

Use the file man.local for local extensions to the man macros or for style changes.

Custom headers and footers

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

Macro: .PT

Control the content of the headers. Normally, the header prints the command name and section number on either side, and the optional fifth argument to TH in the center.

Macro: .BT

Control the content of the footers. Normally, the footer prints the page number and the third and fourth arguments to TH.

Use the FT number register to specify the footer position. The default is -0.5i.

Ultrix-specific man macros

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

Macro: .CT key

Print ‘<CTRL/key>’.

Macro: .CW

Print subsequent text using the constant width (Courier) typeface.

Macro: .Ds

Begin a non-filled display.

Macro: .De

End a non-filled display started with Ds.

Macro: .EX [indent]

Begin a non-filled display using the constant width (Courier) typeface. Use the optional indent argument to indent the display.

Macro: .EE

End a non-filled display started with EX.

Macro: .G [text]

Set text in Helvetica. If no text is present on the line where the macro is called, then the text of the next line appears in Helvetica.

Macro: .GL [text]

Set text in Helvetica Oblique. If no text is present on the line where the macro is called, then the text of the next line appears in Helvetica Oblique.

Macro: .HB [text]

Set text in Helvetica Bold. If no text is present on the line where the macro is called, then all text up to the next HB appears in Helvetica Bold.

Macro: .TB [text]

Identical to HB.

Macro: .MS title sect [punct]

Set a manpage reference in Ultrix format. The title is in Courier instead of italic. Optional punctuation follows the section number without an intervening space.

Macro: .NT [C] [title]

Begin a note. Print the optional title, or the word “Note”, centered on the page. Text following the macro makes up the body of the note, and is indented on both sides. If the first argument is C, the body of the note is printed centered (the second argument replaces the word “Note” if specified).

Macro: .NE

End a note begun with NT.

Macro: .PN path [punct]

Set the path name in constant width (Courier), followed by optional punctuation.

Macro: .Pn [punct] path [punct]

If called with two arguments, identical to PN. If called with three arguments, set the second argument in constant width (Courier), bracketed by the first and third arguments in the current font.

Macro: .R

Switch to roman font and turn off any underlining in effect.

Macro: .RN

Print the string ‘<RETURN>’.

Macro: .VS [4]

Start printing a change bar in the margin if the number 4 is specified. Otherwise, this macro does nothing.

Macro: .VE

End printing the change bar begun by VS.

Simple example

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

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

4.2 mdoc

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

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

4.3.1 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. See Differences from AT&T ms, for more information.

4.3.2 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. See 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.⁷ See 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. See 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.

4.3.3 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. If the value is larger than or equal to 1000, divide it by 1000 to get a fractional point size. For example, ‘.nr PS 10250’ sets the document’s point size to 10.25p.

Effective: next paragraph.

Default: 10p.

Register: \n[VS]

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

Effective: next paragraph.

Default: 12p.

Register: \n[PSINCR]

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

Effective: next section heading.

Default: 1p.

Register: \n[GROWPS]

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

Effective: next section heading.

Default: 0.

Register: \n[HY]

Defines the hyphenation level. HY sets safely the value of the low-level hy register. Setting the value of HY to 0 is equivalent to using the nh request.

Effective: next paragraph.

Default: 6.

Register: \n[FAM]

Defines the font family used to typeset the document.

Effective: next paragraph.

Default: as defined in the output device.

Paragraph Settings

Register: \n[PI]

Defines the initial indentation of a (PP macro) 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 indentation on both sides of a quoted (QP, QS, and QE macros) paragraph.

Effective: next paragraph.

Default: 5n.

Register: \n[PORPHANS]

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

Effective: next paragraph.

Default: 1.

Register: \n[HORPHANS]

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

Effective: next paragraph.

Default: 1.

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

Effective: next footnote.

Default: 2n.

Register: \n[FF]

The footnote format:

0

Print the footnote number as a superscript; indent the footnote (default).

1

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

2

Like 1, without an indentation.

3

Like 1, but print the footnote number as a hanging paragraph.

Effective: next footnote.

Default: 0.

Register: \n[FPS]

Defines the footnote point size. If the value is larger than or equal to 1000, divide it by 1000 to get a fractional point size.

Effective: next footnote.

Default: \n[PS] - 2.

Register: \n[FVS]

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

Effective: next footnote.

Default: \n[FPS] + 2.

Register: \n[FPD]

Defines the footnote paragraph spacing.

Effective: next footnote.

Default: \n[PD] / 2.

Miscellaneous Number Registers

Register: \n[MINGW]

Defines the minimum width between columns in a multi-column document.

Effective: next page.

Default: 2n.

Register: \n[DD]

Sets the vertical spacing before and after a display, a tbl table, an eqn equation, or a pic image.

Effective: next paragraph.

Default: 0.5v.

4.3.4 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: .P1

(P-one) Prints the header on page 1. The default is to suppress the header.

Macro: .DA […]

(optional) Prints the current date, or the arguments to the macro if any, on the title page (if specified) and in the footers. This is the default for nroff.

Macro: .ND […]

(optional) Prints the current date, or the arguments to the macro if any, on the title page (if specified) but not in the footers. This is the default for 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

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

4.3.5 Body text

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

4.3.5.1 Paragraphs

The following paragraph types are available.

Macro: .PP

Sets a paragraph with an initial indentation.

Macro: .LP

Sets a paragraph without an initial indentation.

Macro: .QP

Sets a paragraph that is indented at both left and right margins by the amount of the register QI. The effect is identical to the HTML <BLOCKQUOTE> element. The next paragraph or heading returns margins to normal. QP inserts vertical space of amount set by register PD before the paragraph.

Macro: .QS

Macro: .QE

These macros begin and end a quoted section. The QI register controls the amount of indentation. Both QS and QE insert inter-paragraph vertical space set by register PD. The text between QS and QE can be structured further by use of the macros LP or PP.

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.

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

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

String: \*[SN]

String: \*[SN-DOT]

String: \*[SN-NO-DOT]

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

.als SN SN-NO-DOT

at any time before you would like the change to take effect.

String: \*[SN-STYLE]

You may control the style used to print section numbers, within numbered section headings, by defining an appropriate alias for the string SN-STYLE. The default style, in which the printed section number is followed by a terminating period, is obtained by defining the alias

.als SN-STYLE SN-DOT

If you prefer to omit the terminating period, from section numbers appearing in numbered section headings, you may define the alias

.als SN-STYLE SN-NO-DOT

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

Macro: .SH [match-level]

Unnumbered subheading.

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

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

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

String: \*[{]

String: \*[}]

Text enclosed with \*{ and \*} is printed as a superscript.

4.3.5.4 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 indentation for the body of each list item; its default unit is ‘n’. Once specified, the indentation remains the same for all list items in the document until specified again.

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

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. See Indentation values 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

4.3.5.5 Indentation values

In many situations, you may need to indentation a section of text while still wrapping and filling. See 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 indentation, allowing the indented text to line up under hanging and indented paragraphs.

See ms Displays and Keeps, for macros to indentation and turn off filling.

4.3.5.6 Tab Stops

Use the ta request to define tab stops as needed. See 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.

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

Macro: .Ds

Macro: .De

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

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

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

4.3.5.9 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

4.3.5.10 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. See ms Document Control Registers.

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

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

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

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

Macro: .PT

Macro: .HD

Macro: .BT

The PT macro defines a custom header; the BT macro defines a custom footer. These macros must handle odd/even/first page differences if necessary.

The HD macro defines additional header processing to take place after executing the PT macro.

4.3.6.2 Margins

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

4.3.6.3 Multiple columns

The ms macros can set text in as many columns as do reasonably fit on the page. The following macros are available; all of them force a page break if a multi-column mode is already set. However, if the current mode is single-column, starting a multi-column mode does 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.

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

4.3.6.5 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⁸:

String: \*[-]

Prints an em dash.

String: \*[Q]

String: \*[U]

Prints typographer’s quotes in troff, and 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.

Note that groff’s native support for accents is superior to the following definitions.

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 ß 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 æ ligature.

String: \*[Ae]

Uppercase Æ ligature.

4.3.7 Differences from AT&T ms

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

• The internals of groff -ms differ from the internals of AT&T troff -ms. Documents that depend upon implementation details of AT&T troff -ms may not format properly with groff -ms.
• The general error-handling policy of groff -ms is to detect and report errors, rather than silently to ignore them.
• groff -ms does not work in compatibility mode (that is, with the -C option).
• There is no special support for typewriter-like devices.
• groff -ms does not provide cut marks.
• Multiple line spacing is not supported. Use a larger vertical spacing instead.
• Some Unix ms documentation says that the CW and GW number registers can be used to control the column width and gutter width, respectively. These number registers are not used in groff -ms.
• Macros that cause a reset (paragraphs, headings, etc.) may change the indentation. Macros that change the indentation do not increment or decrement the indentation, but rather set it absolutely. This can cause problems for documents that define additional macros of their own. The solution is to use not the in request but instead the RS and RE macros.
• To make groff -ms use the default page offset (which also specifies the left margin), the PO register must stay undefined until the first -ms macro is evaluated. This implies that PO should not be used early in the document, unless it is changed also: Remember that accessing an undefined register automatically defines it.

Register: \n[GS]

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

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

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

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

4.3.7.1 troff macros not appearing in groff

Macros missing from groff -ms are cover page macros specific to Bell Labs and Berkeley. 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

4.3.7.2 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. See 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. See ms Strings and Special Characters, for details.

4.3.8 Naming Conventions

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

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

• Names used only within one module are of the form module*name.
• Names used outside the module in which they are defined are of the form module@name.
• Names associated with a particular environment are of the form environment:name; these are used only within the par module.
• name does not have a module prefix.
• Constructed names used to implement arrays are of the form array!index.

Thus the groff ms macros reserve the following names:

• Names containing the characters *, @, and :.
• Names containing only uppercase letters and digits.

4.4 me

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

4.5 mm

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

4.6 mom

The main documentation files for the mom macros are in HTML format. Additional, useful documentation is in PDF format. See the groff(1) man page, section “Installation Directories”, for their location.

• toc.html Entry point to the full mom manual.
• macrolist.html Hyperlinked index of macros with brief descriptions, arranged by category.
• mom-pdf.pdf PDF features and usage.

The mom macros are in active development between groff releases. The most recent version, along with up-to-date documentation, is available at http://www.schaffter.ca/mom/mom-05.html.

The groff_mom(7) man page (type man groff_mom at the command line) contains a partial list of available macros, however their usage is best understood by consulting the HTML documentation.

5 gtroff Reference

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

5.1 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

5.1.1 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 Implicit Line Breaks).

See Manipulating Filling and Adjusting.

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

See Manipulating Hyphenation.

5.1.3 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 typesetting 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 Input Conventions.)

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

See the cflags request in 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 \&.

5.1.4 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

produces

See Tabs and Fields.

5.1.5 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. See 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; however, the behaviour can be modified with the leading spaces macro request lsm. See Leading Spaces Traps.

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

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

5.1.7 Input Encodings

Currently, the following input encodings are available.

cp1047

This input encoding works only on EBCDIC platforms (and vice versa, the other input encodings don’t work with EBCDIC); the file cp1047.tmac is by default loaded at start-up.

latin-1

This is the default input encoding on non-EBCDIC platforms; the file latin1.tmac is loaded at start-up.

latin-2

To use this encoding, either say ‘.mso latin2.tmac’ at the very beginning of your document or use ‘-mlatin2’ as a command-line argument for groff.

latin-5

For Turkish. Either say ‘.mso latin5.tmac’ at the very beginning of your document or use ‘-mlatin5’ as a command-line argument for groff.

latin-9 (latin-0)

This encoding is intended (at least in Europe) to replace latin-1 encoding. The main difference to latin-1 is that latin-9 contains the Euro character. To use this encoding, either say ‘.mso latin9.tmac’ at the very beginning of your document or use ‘-mlatin9’ as a command-line argument for groff.

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

groff -Tlatin1 -mlatin9 ...

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

Due to the importance of the Euro glyph in Europe, the groff package now comes with a POSTSCRIPT font called freeeuro.pfa, which provides various glyph shapes for the Euro. In other words, latin-9 encoding is supported for the -Tps device out of the box (latin-2 isn’t).

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

5.2 Measurements

gtroff (like many other programs) requires numeric parameters to specify various measurements. Most numeric parameters⁹ may have a measurement unit attached. These units are specified as a single character that 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.

Although groff’s basic unit is device-dependent, it may still be smaller than the smallest unit the device is capable of producing. The register .H specifies how many groff basic units constitute the current device’s basic unit horizontally, and the register .V specifies this value vertically.

i

Inches. An antiquated measurement unit still in use in certain backwards countries with incredibly low-cost computer equipment. One inch is defined to be 2.54 cm (worldwide since 1964).

c

Centimeters. One centimeter is about 0.3937 in.

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

See Fractional Type Sizes, for a discussion of these units.

f

Fractions. Value is 65536. See Colors, for usage.

The other measurements understood by gtroff depend on settings currently in effect in gtroff. These are very useful for specifying measurements that 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. See Sizes, for more information about this.

M

100ths of an em.

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

5.3 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 32-bit 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.

  The logical not operator, as described above, works only within if and while requests. Furthermore, it may appear only at the beginning of an expression, and negates the entire expression. Attempting to insert the ‘!’ operator within the expression results in a ‘numeric expression expected’ warning. This maintains compatibility with old versions of troff.

  Example:

  .nr X 1
  .nr Y 0
  .\" This does not work as expected
  .if (\n[X])&(!\n[Y]) .nop X only
  .
  .\" Use this construct instead
  .if (\n[X]=1)&(\n[Y]=0) .nop X only
  

• Extrema: ‘>?’ (maximum), ‘<?’ (minimum).

  Example:

  .nr x 5
  .nr y 3
  .nr z (\n[x] >? \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 that 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.

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

See Request and Macro Arguments, and Conditionals and Loops.

5.4 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 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 that 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 that 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

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

See Warnings., Interpolating Registers, and 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.

See Interpolating Registers, and Strings.

5.5 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 that takes up an entire line, and does some large-scale operation (e.g. break lines, start new pages).

The other is an escape that 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.

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

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

Register: \n[.br]

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

This allows reliable modification of requests.

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

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

If a macro is called as a string (that is, using \*), the value of the .br register is inherited from the caller.

5.5.1.1 Request and Macro Arguments

Arguments to requests and macros are processed much like the shell: The line is split into arguments according to spaces.¹¹

An argument to a macro that is intended to contain spaces can either be enclosed in double quotes, or have the spaces escaped with backslashes. This is not true for requests.

Here are a few examples for a hypothetical macro uh:

.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’.¹²

A double quote that 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.

  Note 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. See Strings, for more details.

5.5.2 Macros

gtroff has a macro facility for defining a series of lines that can be invoked by name. They are called in the same manner as requests – arguments also may be passed basically in the same manner.

See Writing Macros, and Request and Macro Arguments.

5.5.3 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 Character Translations.

Escape sequences that 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 that 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 café in Paris

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

The following escape 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. See Character Translations, for an exact description of those escapes.

See Implementation Differences, Copy-in Mode, and Diversions, Identifiers, for more information.

5.5.3.1 Comments

Probably one of the most¹³ 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

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 [end]

Ignore all input until gtroff encounters the macro named .end on a line by itself (or .. if end 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 (see Auto-increment).

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

See Identifiers, for details on register identifiers.

5.6.1 Setting Registers

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

Although the following requests and escapes can be used to create registers, simply using an undefined register will cause it to be set to zero.

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. See Escapes, for details on parameter delimiting characters.

The \R escape doesn’t produce an input token in gtroff; in 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

Note that the complete transparency of \R can cause surprising effects if you use number registers like .k, which get evaluated at the time they are accessed.

.ll 1.6i
.
aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]'
.tm :k == \n[:k]
    ⇒ :k == 126950
.
.br
.
aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]'
.tm :k == \n[:k]
    ⇒ :k == 15000

If you process this with the POSTSCRIPT device (-Tps), there will be a line break eventually after ggg in both input lines. However, after processing the space after ggg, the partially collected line is not overfull yet, so troff continues to collect input until it sees the space (or in this case, the newline) after hhh. At this point, the line is longer than the line length, and the line gets broken.

In the first input line, since the \R escape leaves no traces, the check for the overfull line hasn’t been done yet at the point where \R gets handled, and you get a value for the .k number register that is even greater than the current line length.

In the second input line, the insertion of \h'0' to emit an invisible zero-width space forces troff to check the line length, which in turn causes the start of a new output line. Now .k returns the expected value.

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. See Debugging, for information about warnings.

5.6.2 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

5.6.3 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+[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.