The GNU Troff Manual

GNU troff

This manual documents GNU troff version 1.18.

Copyright © 1994-2000, 2001, 2002 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.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being `A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled `GNU Free Documentation License.”

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

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

1 Introduction

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

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

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.

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

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

• They must be used on a graphics display to work on a document.
• Most of the WYSIWYG systems are either non-free or are not very portable.
• troff is firmly entrenched in all UNIX systems.
• It is difficult to have a wide range of capabilities available within the confines of a GUI/window system.
• It is more difficult to make global changes to a document.

“GUIs normally make it simple to accomplish simple actions and impossible to accomplish complex actions.” –Doug Gwyn (22/Jun/91 in comp.unix.wizards)

1.2 History

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

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

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

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

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

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

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

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

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

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

• A replacement for ditroff with many extensions.
• The soelim, pic, tbl, and eqn preprocessors.
• Postprocessors for character devices, PostScript, TeX DVI, and X Windows. GNU troff also eliminated the need for a separate nroff program with a postprocessor which would produce ASCII output.
• A version of the me macros and an implementation of the man macros.

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

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

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

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

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 which understand their own language and produce the necessary groff operations. These preprocessors are able to differentiate their own input from the rest of the document via markers.

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

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

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

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

1.6 Output Devices

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

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

• Groff Options
• Environment
• Macro Directories
• Font Directories
• Invocation Examples

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

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

The command line format for groff is:

     
     groff [ -abceghilpstvzCEGNRSUVXZ ] [ -Fdir ] [ -mname ]
           [ -Tdef ] [ -ffam ] [ -wname ] [ -Wname ]
           [ -Mdir ] [ -dcs ] [ -rcn ] [ -nnum ]
           [ -olist ] [ -Parg ] [ -Larg ] [ -Idir ]
           [ files... ]

The command line format for gtroff is as follows.

     
     gtroff [ -abcivzCERU ] [ -wname ] [ -Wname ] [ -dcs ]
            [ -ffam ] [ -mname ] [ -nnum ]
            [ -olist ] [ -rcn ] [ -Tname ]
            [ -Fdir ] [ -Mdir ] [ files... ]

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

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

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

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

-h

Print a help message.

-e

Preprocess with geqn.

-t

Preprocess with gtbl.

-g

Preprocess with ggrn.

-G

Preprocess with grap.

-p

Preprocess with gpic.

-s

Preprocess with gsoelim.

-c

Suppress color output.

-R

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

-v

Make programs run by groff print out their version number.

-V

Print the pipeline on stdout instead of executing it.

-z

Suppress output from gtroff. Only error messages are printed.

-Z

Do not postprocess the output of gtroff. Normally groff automatically runs the appropriate postprocessor.

-Parg

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

-l

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

-Larg

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

-Tdev

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

ps

For PostScript printers and previewers.

dvi

For TeX DVI format.

X75

For a 75dpi X11 previewer.

X75-12

For a 75dpi X11 previewer with a 12pt base font in the document.

X100

For a 100dpi X11 previewer.

X100-12

For a 100dpi X11 previewer with a 12pt base font in the document.

ascii

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

latin1

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

utf8

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

cp1047

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

lj4

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

lbp

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

html

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

The predefined gtroff string register .T contains the current output device; the read-only number register .T is set to 1 if this option is used (which is always true if groff is used to call gtroff). 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.

-X

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

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

-N

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

-S

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

-U

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

-a

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

-i

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

-wname

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

-Wname

Inhibit warning name. Multiple -W options are allowed.

-E

Inhibit all error messages.

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

-ffam

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

-mname

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

-nnum

Number the first page num.

-olist

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

Within gtroff, this information can be extracted with the .P register. 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.

-rcn

-rname=n

Set number register c or name to the value n. c must be a one-letter name; name can be of arbitrary length. n can be any gtroff numeric expression. All register assignments happen before loading any macro file (including the start-up file).

-Fdir

Search dir for subdirectories devname (name is the name of the device), for the DESC file, and for font files before looking in the standard directories (see Font Directories). This option is passed to all pre- and postprocessors using the GROFF_FONT_PATH environment variable.

-Mdir

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

-Idir

This option is as described in gsoelim. It implies the -s option.

2.2 Environment

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

GROFF_COMMAND_PREFIX

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

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

GROFF_TMAC_PATH

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

GROFF_TYPESETTER

The default output device.

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_BIN_PATH

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

GROFF_TMPDIR

The directory in which groff creates temporary files. If this is not set and TMPDIR is set, temporary files are created in that directory. Otherwise temporary files are created in a system-dependent default directory (on Unix and GNU/Linux systems, this is usually /tmp). grops, grefer, pre-grohtml, and post-grohtml can create temporary files in this directory.

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

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.18/tmac
       

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

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 will 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.18/font
       

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

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

• grog

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

• Basics
• Common Features

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 which appears on the same line as a request, and which modifies the meaning of that request. For example, the request

     
     .sp

spaces one line, but

     
     .sp 4

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

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

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

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

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

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

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

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

Here are a few hints for preparing text for input to gtroff.

• First, keep the input lines short. Short input lines are easier to edit, and gtroff packs words onto longer lines anyhow.
• In keeping with this, it is helpful to begin a new line after every comma or phrase, since common corrections are to add or delete sentences or phrases.
• End each sentence with two spaces – or better, start each sentence on a new line. gtroff recognizes characters that usually end a sentence, and inserts sentence space accordingly.
• Do not hyphenate words at the end of lines – gtroff is smart enough to hyphenate words as needed, but is not smart enough to take hyphens out and join a word back together. Also, words such as “mother-in-law” should not be broken over a line, since then a space can occur where not wanted, such as “mother- in-law”.

gtroff double-spaces output text automatically if you use the request .ls 2. Reactivate single-spaced mode by typing .ls 1.⁴

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 which are done in all documents. These common operations are written into macros and collected into a macro package.

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

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

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 which are several lines long, and hence are set in from the rest of the text without quote marks around them.

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

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

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

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

• man
• mdoc
• ms
• me
• mm

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.

• Man options
• Man usage
• Man font macros
• Miscellaneous man macros
• Predefined man strings
• Preprocessors in man pages

4.1.1 Options

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

     
     groff -m man [ -rLL=length ] [ -rLT=length ]
           [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rPnnn ]
           [ -rSxx ] [ -rXnnn ] [ files... ]

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

-rLL=length

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

-rLT=length

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

-rcR=1

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

-rC1

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

-rD1

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

-rPnnn

Page numbering starts with nnn rather than with 1.

-rSxx

Use xx (which can be 10, 11, or 12pt) as the base document font size instead of the default value of 10pt.

-rXnnn

After page nnn, number pages as nnna, nnnb, nnnc, etc. For example, the option -rX2 produces the following page numbers: 1, 2, 2a, 2b, 2c, etc.

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.

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 point. If command line option -rS=n is given, use npt as the default text size.

4.1.4 Miscellaneous macros

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

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

4.1.5 Predefined strings

The following strings are defined:

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

• ms Intro
• General ms Structure
• ms Document Control Registers
• ms Cover Page Macros
• ms Body Text
• ms Page Layout
• Differences from AT&T ms

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

Text Settings

Paragraph Settings

Footnote Settings

Miscellaneous Number Registers

4.3.4 Cover page macros

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

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.

• Paragraphs in ms
• Headings in ms
• Highlighting in ms
• Lists in ms
• Indents in ms
• Tabstops in ms
• ms Displays and Keeps
• ms Insertions
• Example multi-page table
• ms Footnotes

4.3.5.1 Paragraphs

The following paragraph types are available.

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.
     
     

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:

4.3.5.3 Highlighting

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

4.3.5.4 Lists

The .IP macro handles duties for all lists.

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

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

     
     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!
     

     
     

     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!
     

     
     

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

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

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

4.3.5.6 Tab Stops

Use the ta request to define tab stops as needed. See Tabs and Fields.

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.

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

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.

• Example multi-page table

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

You can control how groff prints footnote numbers by changing the value of the FF register. See ms Document Control Registers.

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.

• ms Headers and Footers
• ms Margins
• ms Multiple Columns
• ms TOC
• ms Strings and Special Characters

4.3.6.1 Headers and footers

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

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 will reasonably fit on the page. The following macros are available; all of them force a page break if a multi-column mode is already set. However, if the current mode is single-column, starting a multi-column mode does not force a page break.

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.

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.

The following special characters are available⁶:

Improved accent marks are available in the ms macros.

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

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

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.

• Missing ms Macros
• Additional ms Macros

4.3.7.1 troff macros not appearing in groff

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

.TM

Technical memorandum; a cover sheet style

.IM

Internal memorandum; a cover sheet style

.MR

Memo for record; a cover sheet style

.MF

Memo for file; a cover sheet style

.EG

Engineer's notes; a cover sheet style

.TR

Computing Science Tech Report; a cover sheet style

.OK

Other keywords

.CS

Cover sheet information

.MH

A cover sheet macro

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.

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

5 gtroff Reference

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

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

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

• Filling and Adjusting
• Hyphenation
• Sentences
• Tab Stops
• 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 typsetting manual says that a period at the end of a sentence should have twice as much space following it as would a comma or a period as part of an abbreviation.

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

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

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

	1	2	3
		4	5

produces

1

2

3

4

5

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.

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.2 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.3 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 which immediately follows the number or expression. Each of these units are understood, by gtroff, to be a multiple of its basic unit. So, whenever a different measurement unit is specified gtroff converts this into its basic units. This basic unit, represented by a u, is a device dependent measurement which is quite small, ranging from 1/75th to 1/72000th of an inch. The values may be given as fractional numbers; however, fractional basic units are always rounded to integers.

Some of the measurement units are completely independent of any of the current settings (e.g. type size) of gtroff.

i

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

c

Centimeters. One centimeter is equal to 0.3937in.

p

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

P

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

s

z

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 which should look proper with any size of text.

m

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

n

Ens. In groff, this is half of an em.

v

Vertical space. This is equivalent to the current line spacing. See Sizes, for more information about this.

M

100ths of an em.

• Default Units

5.3.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.4 Expressions

gtroff has most arithmetic operators common to other languages:

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

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

• Comparison: < (less than), > (greater than), <= (less than or equal), >= (greater than or equal), = (equal), == (the same as =).
• Logical: & (logical and), : (logical or).
• Unary operators: - (negating, i.e. changing the sign), + (just for completeness; does nothing in expressions), ! (logical not; this works only within if and while requests). See below for the use of unary operators in motion requests.
• Extrema: >? (maximum), <? (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 which cause a motion on the page, the unary operators + and - work differently if leading an expression. They then indicate a motion relative to the current position (down or up, respectively).

Similarly, a leading | operator indicates an absolute position. For vertical movements, it specifies the distance from the top of the page; for horizontal movements, it gives the distance from the beginning of the input line.

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

See Setting Registers, for some examples.

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

See Request Arguments, and Conditionals and Loops.

5.5 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 which use characters of these ranges.

  Note that invalid characters are removed before parsing; an identifier foo, followed by an invalid character, followed by bar is treated as foobar.

For example, any of the following is valid.

     
     br
     PP
     (l
     end-list
     @_

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

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

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.6 Embedded Commands

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

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

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

• Requests
• Macros
• Escapes

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

• Request Arguments

5.6.1.1 Request Arguments

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

Here are a few examples:

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

The first line is the uh macro being called with 3 arguments, The, Mouse, and Problem. The latter two have the same effect of calling the uh macro with one argument, The Mouse Problem.⁹

A double quote which isn't preceded by a space doesn't start a macro argument. If not closing a string, it is printed literally.

For example,

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

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

There are two possibilities to get a double quote reliably.

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

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

  If not in compatibility mode, you get the expected result

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

  since gtroff preserves the input level.

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

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

Double quotes in the ds request are handled differently. See Strings, for more details.

5.6.2 Macros

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

See Writing Macros, and Request Arguments.

5.6.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 which require an identifier as a parameter accept three possible syntax forms.

• The next single character is the identifier.

• If this single character is an opening parenthesis, take the following two characters as the identifier. Note that there is no closing parenthesis after the identifier.

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

Examples:

     
     \fB
     \n(XX
     \*[TeX]

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

     
     \l'1.5i\(bu'

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

     
     A caf
     \o
     e\'
     
     
     in Paris
       => A café in Paris

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

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

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

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

• The digits 0-9.
• The (single-character) operators +-/*%<>=&:()..
• The space, tab, and newline characters.
• All escape sequences except \%, \:, \{, \}, \', \`, \-, \_, \!, \@, \/, \c, \e, and \p.

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

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

• Comments

5.6.3.1 Comments

Probably one of the most¹⁰ common forms of escapes is the comment.

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

• Setting Registers
• Interpolating Registers
• Auto-increment
• Assigning Formats
• Built-in Registers

5.7.1 Setting Registers

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

For example, the following two lines are equivalent:

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

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

5.7.2 Interpolating Registers

Numeric registers can be accessed via the \n escape.

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

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

For example,

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

produces

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

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

     
     .nr a \na 10

5.7.4 Assigning Formats

When a register is used in the text of an input file (as opposed to part of an expression), it is textually replaced (or interpolated) with a representation of that number. This output format can be changed to a variety of formats (numbers, Roman numerals, etc.). This is done using the af request.

5.7.5 Built-in Registers

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

.F

This string-valued register returns the current input file name.

.H

Horizontal resolution in basic units.

.V

Vertical resolution in basic units.

seconds

The number of seconds after the minute, normally in the range 0 to 59, but can be up to 61 to allow for leap seconds. Initialized at start-up of gtroff.

minutes

The number of minutes after the hour, in the range 0 to 59. Initialized at start-up of gtroff.

hours

The number of hours past midnight, in the range 0 to 23. Initialized at start-up of gtroff.

dw

Day of the week (1-7).

dy

Day of the month (1-31).

mo

Current month (1-12).

year

The current year.

yr

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

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

can be corrected as follows:

          
          This document was formatted in \n[year].
     

or, to be portable to older troff versions, as follows:

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

.c

c.

The current input line number. Register .c is read-only, whereas c. (a gtroff extension) is writable also, affecting both .c and c..

ln

The current output line number after a call to the nm request to activate line numbering.

See Miscellaneous, for more information about line numbering.

.x

The major version number. For example, if the version number is 1.03 then .x contains 1.

.y

The minor version number. For example, if the version number is 1.03 then .y contains 03.

.Y

The revision number of groff.

$$

The process ID of gtroff.

.g

Always 1. Macros should use this to determine whether they are running under GNU troff.

.A

If the command line option -a is used to produce an ASCII approximation of the output, this is set to 1, zero otherwise. See Groff Options.

.P

This register is set to 1 (and to 0 otherwise) if the current page is actually being printed, i.e., if the -o option is being used to only print selected pages. See Groff Options, for more information.

.T

If gtroff is called with the -T command line option, the number register .T is set to 1, and zero otherwise. See Groff Options.

Additionally, gtroff predefines a single read-write string register .T which contains the current output device (for example, latin1 or ps).

5.8 Manipulating Filling and Adjusting

Various ways of causing breaks were given in Implicit Line Breaks. The br request likewise causes a break. Several other requests also cause breaks, but implicitly. These are bp, ce, cf, fi, fl, in, nf, rj, sp, ti, and trf.

Initially, gtroff fills and adjusts text to both margins. Filling can be disabled via the nf request and re-enabled with the fi request.

5.9 Manipulating Hyphenation

As discussed in Hyphenation, gtroff hyphenates words. There are a number of ways to influence hyphenation.

5.10 Manipulating Spacing

See Changing Type Sizes, for the requests vs and pvs as alternatives to ls.

5.11 Tabs and Fields

A tab character (ASCII char 9, EBCDIC char 5) causes a horizontal movement to the next tab stop (much like it did on a typewriter).

• Leaders
• Fields

5.11.1 Leaders

Sometimes it may may be desirable to use the tc request to fill a particular tab stop with a given glyph (for example dots in a table of contents), but also normal tab stops on the rest of the line. For this gtroff provides an alternate tab mechanism, called leaders which does just that.

A leader character (character code 1) behaves similarly to a tab character: It moves to the next tab stop. The only difference is that for this movement, the fill glyph defaults to a period character and not to space.

For a table of contents, to name an example, tab stops may be defined so that the section number is one tab stop, the title is the second with the remaining space being filled with a line of dots, and then the page number slightly separated from the dots.

     
     .ds entry 1.1\tFoo\a\t12
     .lc .
     .ta 1i 5i +.25i
     \*[entry]

This produces

     
     1.1  Foo..........................................  12

5.11.2 Fields

Fields are a more general way of laying out tabular data. A field is defined as the data between a pair of delimiting characters. It contains substrings which are separated by padding characters. The width of a field is the distance on the input line from the position where the field starts to the next tab stop. A padding character inserts stretchable space similar to TeX's \hss command (thus it can even be negative) to make the sum of all substring lengths plus the stretchable space equal to the field width. If more than one padding character is inserted, the available space is evenly distributed among them.

5.12 Character Translations

The control character (.) and the no-break control character (') can be changed with the cc and c2 requests, respectively.

A translation is a mapping of an input character to an output glyph. The mapping occurs at output time, i.e., the input character gets assigned the metric information of the mapped output character right before input tokens are converted to nodes (see Gtroff Internals, for more on this process).

5.13 Troff and Nroff Mode

Originally, nroff and troff were two separate programs, the former for TTY output, the latter for everything else. With GNU troff, both programs are merged into one executable, sending its output to a device driver (grotty for TTY devices, grops for PostScript, etc.) which interprets the intermediate output of gtroff. For UNIX troff it makes sense to talk about Nroff mode and Troff mode since the differences are hardcoded. For GNU troff, this distinction is not appropriate because gtroff simply takes the information given in the font files for a particular device without handling requests specially if a TTY output device is used.

Usually, a macro package can be used with all output devices. Nevertheless, it is sometimes necessary to make a distinction between TTY and non-TTY devices: gtroff provides two built-in conditions n and t for the if, ie, and while requests to decide whether gtroff shall behave like nroff or like troff.

See Conditionals and Loops, for more details on built-in conditions.

5.14 Line Layout

The following drawing shows the dimensions which gtroff uses for placing a line of output onto the page. They are labeled with the request which manipulates each dimension.

     
                     -->| in |<--
                        |<-----------ll------------>|
                   +----+----+----------------------+----+
                   |    :    :                      :    |
                   +----+----+----------------------+----+
                -->| po |<--
                   |<--------paper width---------------->|

These dimensions are:

po

Page offset – this is the leftmost position of text on the final output, defining the left margin.

in

Indentation – this is the distance from the left margin where text is printed.

ll

Line length – this is the distance from the left margin to right margin.

A simple demonstration:

     
     .ll 3i
     This is text without indentation.
     The line length has been set to 3\~inch.
     .in +.5i
     .ll -.5i
     Now the left and right margins are both increased.
     .in
     .ll
     Calling .in and .ll without parameters restore
     the previous values.

Result:

     
     This  is text without indenta-
     tion.   The  line  length  has
     been set to 3 inch.
          Now   the  left  and
          right  margins   are
          both increased.
     Calling  .in  and  .ll without
     parameters restore the  previ-
     ous values.