GNU troff

1.1 Background

M. Douglas McIlroy, formerly of AT&T Bell Laboratories and present at the creation of the Unix operating system, offers an authoritative historical summary.

The prime reason for Unix was the desire of Ken [Thompson], Dennis [Ritchie], and Joe Ossanna to have a pleasant environment for software development. The fig leaf that got the nod from … management was that an early use would be to develop a “stand-alone” word-processing system for use in typing pools and secretarial offices. Perhaps they had in mind “dedicated”, as distinct from “stand-alone”; that’s what eventuated in various cases, most notably in the legal/patent department and in the AT&T CEO’s office.

Both those systems were targets of opportunity, not foreseen from the start. When Unix was up and running on the PDP-11, Joe got wind of the legal department having installed a commercial word processor. He went to pitch Unix as an alternative and clinched a trial by promising to make roff able to number lines by tomorrow in order to fulfill a patent-office requirement that the commercial system did not support.

Modems were installed so legal-department secretaries could try the Research machine. They liked it and Joe’s superb customer service. Soon the legal department got a system of their own. Joe went on to create nroff and troff. Document preparation became a widespread use of Unix, but no stand-alone word-processing system was ever undertaken.

A history relating groff to its predecessors roff, nroff, and troff is available in the roff(7) man page.

1.2 What Is groff?

groff (GNU roff) is a typesetting system that reads plain text input files that include formatting commands to produce output in PostScript, PDF, HTML, DVI, or other formats, or for display to a terminal. Formatting commands can be low-level typesetting primitives, macros from a supplied package, or user-defined macros. All three approaches can be combined.

A reimplementation and extension of the typesetter from AT&T Unix, groff is present on most POSIX systems owing to its long association with Unix manuals (including man pages). It and its predecessor are notable for their production of several best-selling software engineering texts. groff is capable of producing typographically sophisticated documents while consuming minimal system resources.

1.3 groff Capabilities

GNU troff is a typesetting document formatter; it provides a wide range of low-level text and page operations within the framework of a programming language. These operations compose to generate footnotes, tables of contents, mathematical equations, diagrams, multi-column text, and other elements of typeset works. Here is a survey of formatter features; all are under precise user control.

• text filling, breaking, alignment to the left or right margin; centering
• adjustment of inter-word space size to justify text, and of inter-sentence space size to suit local style conventions
• automatic and manual determination of hyphenation break points
• pagination
• selection of any font available to the output device
• adjustment of type size and vertical spacing (or “leading”)
• configuration of line length and indentation amounts; columnation
• drawing of geometric primitives (lines, arcs, polygons, circles, …)
• setup of stroke and fill colors (where supported by the output device)
• embedding of hyperlinks, images, document metadata, and other inclusions (where supported by the output device)

1.4 Macro Packages

Elemental typesetting functions can be be challenging to use directly with complex documents. A macro facility specifies how certain routine operations, such as starting paragraphs, or printing headers and footers, should be performed in terms of those low-level instructions. Macros can be specific to one document or collected together into a macro package for use by many. Several macro packages available; the most widely used are provided with groff. They are man, mdoc, me, mm, mom, and ms.

1.5 Preprocessors

An alternative approach to complexity management, particularly when constructing tables, setting mathematics, or drawing diagrams, lies in preprocessing. A preprocessor employs a domian-specific language to ease the generation of tables, equations, and so forth in terms that are convenient for human entry. Each preprocessor reads a document and translates the parts of it that apply to it into GNU troff input. Command-line options to groff tell it which preprocessors to use.

groff provides preprocessors for laying out tables (gtbl), typesetting equations (geqn), drawing diagrams (gpic and ggrn), inserting bibliographic references (grefer), and drawing chemical structures (gchem). An associated program that is useful when dealing with preprocessors is gsoelim.¹

groff also supports grap, a preprocessor for drawing graphs. A free implementation of it can be obtained separately.

Unique to groff is the preconv preprocessor that enables groff to handle documents in a variety of input encodings.

Other preprocessors exist, but no free implementations are known. An example is ideal, which draws diagrams using a mathematical constraint language.

1.6 Output Devices

GNU troff’s output is in a device-independent page description language, which is then read by an output driver that translates this language into a file format or byte stream that a piece of (possibly emulated) hardware understands. groff features output drivers for PostScript devices, terminal emulators (and other simple typewriter-like machines), X11 (for previewing), TeX DVI, HP LaserJet 4/PCL5 and Canon LBP printers (which use CaPSL), HTML, XHTML, and PDF.

1.7 Installation

Locate installation instructions in the files INSTALL, INSTALL.extra, and INSTALL.REPO in the groff source distribution. Being a GNU project, groff supports the familiar ‘./configure && make’ command sequence.

1.8 Conventions Used in This Manual

We apply the term “groff” to the language documented here, the GNU implementation of the overall system, the project that develops that system, and the command of that name. In the first sense, groff is an extended dialect of the roff language, for which many similar implementations exist.

The roff language features several major categories for which many items are predefined. Presentations of these items feature the form in which the item is most commonly used on the left, and, aligned to the right margin, the name of the category in brackets.

Register: \n[example] ¶

The register ‘example’ is one that that groff doesn’t predefine. You can create it yourself, though; see Setting Registers.

To make this document useful as a reference and not merely amiable bedtime reading, we tend to present these syntax items in exhaustive detail when they arise. References to topics discussed later in the text are frequent; skip material you don’t understand yet.

We use Texinfo’s “result” (⇒) and error→ notations to present output written to the standard output and standard error streams, respectively. Diagnostic messages from the GNU troff formatter and other programs are examples of the latter, but the formatter can also be directed to write user-specified messages to the standard error stream. The notation then serves to identify the output stream and does not necessarily mean that an error has occurred.²

$ echo "Twelve o'clock and" | groff -Tascii | sed '/^$/d'
    ⇒ Twelve o'clock and
$ echo '.tm all is well.' | groff > /dev/null
    error→ all is well.

Sometimes we use ⇒ somewhat abstractly to represent formatted text that you will need to use a PostScript or PDF viewer program (or a printer) to observe. While arguably an abuse of notation, we think this preferable to requiring the reader to understand the syntax of these page description languages.

We also present diagnostic messages in an abbreviated form, often omitting the name of the program issuing them, the input file name, and line number or other positional information when such data do not serve to illuminate the topic under discussion.

Most examples are of roff language input that would be placed in a text file. Occasionally, we start an example with a ‘$’ character to indicate a shell prompt, as seen above.

You are encouraged to try the examples yourself, and to alter them to better learn groff’s behavior. Our examples frequently need to direct the formatter to set a line length (with ‘.ll’) that will fit within the page margins of this manual. We mention this so that you know why it is there before we discuss the ll request formally.³

1.9 Credits

We adapted portions of this manual from existing documents. James Clark’s man pages were an essential resource; we have updated them in parallel with the development of this manual. We based the tutorial for macro users on Eric Allman’s introduction to his me macro package (which we also provide, little altered from 4.4BSD). Larry Kollar contributed much of the material on the ms macro package.

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 documents only options to the groff front end. Many of the arguments to groff are passed on to gtroff; therefore, those are also included. Arguments to preprocessors and output drivers can be found in the man pages gpic(1), geqn(1), gtbl(1), ggrn(1), grefer(1), gchem(1), gsoelim(1), preconv(1), grotty(1), grops(1), gropdf(1), grohtml(1), grodvi(1), grolj4(1), grolbp(1), and gxditview(1).

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. Whitespace is permitted between an option and its argument.

The grog command can be used to guess the correct groff command to format a file. See its man page grog(1); type ‘man grog’ at the command line to view it.

groff’s command-line options are as follows.

‘-a’ ¶

Generate a plain text approximation of the typeset output. The read-only register .A is set to 1. See Built-in Registers. This option produces a sort of abstract preview of the formatted output.

• Page breaks are marked by a phrase in angle brackets; for example, ‘<beginning of page>’.
• Lines are broken where they would be in the formatted output.
• A horizontal motion of any size is represented as one space. Adjacent horizontal motions are not combined. Inter-sentence space nodes (those arising from the second argument to the ss request) are not represented.
• Vertical motions are not represented.
• Special characters are rendered in angle brackets; for example, the default soft hyphen character appears as ‘<hy>’.

The above description should not be considered a specification; the details of -a output are subject to change.

‘-b’

Write a backtrace reporting the state of gtroff’s input parser to the standard error stream with each diagnostic message. The line numbers given in the backtrace might not always be correct, because gtroff’s idea of line numbers can be confused by requests that append to macros.

‘-c’

Start with color output disabled.

‘-C’

Enable AT&T troff compatibility mode; implies -c. See Implementation Differences, for the list of incompatibilities between groff and AT&T troff.

‘-dctext’

‘-dstring=text’

Define roff string c or string as t or text. c must be one character; string can be of arbitrary length. Such string assignments happen before any macro file is loaded, including the startup file. Due to getopt_long limitations, c cannot be, and string cannot contain, an equals sign, even though that is a valid character in a roff identifier.

‘-Denc’

Set fallback input encoding used by preconv to enc; implies -k.

‘-e’

Run geqn preprocessor.

‘-E’

Inhibit gtroff error messages. This option does not suppress messages sent to the standard error stream by documents or macro packages using tm or related requests.

‘-ffam’

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

‘-Fdir’

Search in directory dir for the selected output device’s directory of device and font description files. See the description of GROFF_FONT_PATH in Environment below for the default search locations and ordering.

‘-g’

Run ggrn preprocessor.

‘-G’

Run grap preprocessor; implies -p.

‘-h’

Display a usage message and exit.

‘-i’

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

‘-Idir’

Search the directory dir for files named in several contexts; implies -g and -s.

• gsoelim replaces so requests with the contents of their file name arguments.
• gtroff searches for files named as operands in its command line and as arguments to psbb, so, and soquiet requests.
• Output drivers may search for files; for instance, grops looks for files named in ‘\X'ps: import …'’, ‘\X'ps: file …'’, and ‘\X'pdf: pdfpic …'’ device control escape sequences.

This option may be specified more than once; the directories are searched in the order specified. If you want to search the current directory before others, add ‘-I .’ at the desired place. The current working directory is otherwise searched last. -I works similarly to, and is named for, the “include” option of Unix C compilers.

-I options are passed to gsoelim, gtroff, and output drivers; with the flag letter changed to -M, they are also passed to ggrn.

‘-j’

Run gchem preprocessor. Implies -p.

‘-k’

Run preconv preprocessor. Refer to its man page for its behavior if neither of groff’s -K or -D options is also specified.

‘-Kenc’

Set input encoding used by preconv to enc; implies -k.

‘-l’

Send the output to a spooler for printing. The print directive in the device description file specifies the default command to be used; see Device and Font Description Files. See options -L and -X.

‘-Larg’

Pass arg to the print spooler program. If multiple args are required, pass each with a separate -L option. groff does not prefix an option dash to arg before passing it to the spooler program.

‘-mname’

Process the file name.tmac prior to any input files. If not found, tmac.name is attempted. name (in both arrangements) is presumed to be a macro file; see the description of GROFF_TMAC_PATH in Environment below for the default search locations and ordering. This option and its argument are also passed to geqn, grap, and ggrn.

‘-Mdir’

Search directory dir for macro files; see the description of GROFF_TMAC_PATH in Environment below for the default search locations and ordering. This option and its argument are also passed to geqn, grap, and ggrn.

‘-nnum’

Number the first page num.

‘-N’

Prohibit newlines between eqn delimiters: pass -N to geqn.

‘-olist’ ¶

Output only pages in list, which is a comma-separated list of page ranges; ‘n’ means page n, ‘m-n’ means every page between m and n, ‘-n’ means every page up to n, ‘n-’ means every page from n on. gtroff stops processing and exits after formatting the last page enumerated in list.

‘-p’

Run gpic preprocessor.

‘-Parg’

Pass arg to the postprocessor. If multiple args are required, pass each with a separate -P option. groff does not prefix an option dash to arg before passing it to the postprocessor.

‘-rcnumeric-expression’

‘-rregister=expr’

Set roff register c or register to the value numeric-expression (see Numeric Expressions). c must be one character; register can be of arbitrary length. Such register assignments happen before any macro file is loaded, including the startup file. Due to getopt_long limitations, c cannot be, and register cannot contain, an equals sign, even though that is a valid character in a roff identifier.

‘-R’

Run grefer preprocessor. No mechanism is provided for passing arguments to grefer because most grefer options have equivalent language elements that can be specified within the document.

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’

Run gsoelim preprocessor.

‘-S’ ¶

Operate in “safer” mode; see -U below for its opposite. For security reasons, safer mode is enabled by default.

‘-t’

Run gtbl preprocessor.

‘-Tdev’

Direct gtroff to format the input for the output device dev. groff then calls an output driver to convert gtroff’s output to a form appropriate for dev. The following output devices are 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 12-point base font in the document.

X100

For a 100dpi X11 previewer.

X100-12

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

ascii ¶

For typewriter-like devices using the (7-bit) ASCII (ISO 646) 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 code page 1047.

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. This driver consists of two parts, a preprocessor (pre-grohtml) and a postprocessor (post-grohtml).

The predefined GNU troff string .T contains the name of the output device; the read-only register .T is set to 1 if this option is used (which is always true if groff is used to call GNU troff). See Built-in Registers.

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

‘-U’ ¶

Operate in unsafe mode, which enables the open, opena, pi, pso, and sy requests. These requests are disabled by default because they allow an untrusted input document to write to arbitrary file names and run arbitrary commands. This option also adds the current directory to the macro package search path; see the -m option above. -U is passed to gpic and gtroff.

‘-v’

Write version information for groff and all programs run by it to the standard output stream; that is, the given command line is processed in the usual way, passing -v to the formatter and any pre- or postprocessors invoked.

‘-V’

Output the pipeline that would be run by groff (as a wrapper program) to the standard output stream, but do not execute it. If given more than once, the pipeline is both written to the standard error stream and run.

‘-wcategory’

Enable warnings in category. Categories are listed in Warnings.

‘-Wcategory’

Inhibit warnings in category. Categories are listed in Warnings.

‘-X’

Use gxditview instead of the usual postprocessor to (pre)view a document on an X11 display. Combining this option with -Tps uses the font metrics of the PostScript device, whereas the -TX75 and -TX100 options use the metrics of X11 fonts.

‘-z’

Suppress formatted output from gtroff.

‘-Z’

Disable postprocessing. gtroff output will appear on the standard output stream (unless suppressed with -z; see gtroff Output for a description of this format.

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 variable is passed to the preconv preprocessor’s -e option to select the character encoding of input files. This variable’s existence implies the groff option -k. If set but empty, groff calls preconv without an -e option. groff’s -K option overrides GROFF_ENCODING. See the preconv(7) man page; type ‘man preconv’ at the command line to view it.

GROFF_FONT_PATH ¶

A list of directories in which to seek the selected output device’s directory of device and font description files. GNU troff will search directories given as arguments to any specified -F options before these, and a built-in list of directories after them. See Font Directories and the troff(1) or gtroff(1) man pages.

GROFF_TMAC_PATH ¶

A list of directories in which to seek macro files. GNU troff will search directories given as arguments to any specified -M options before these, and a built-in list of directories after them. See Macro Directories and the troff(1) or gtroff(1) man pages.

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 ¶

Sets the default output device. If empty or not set, a build-time default (often ps) is used. The -Tdev option overrides GROFF_TYPESETTER.

SOURCE_DATE_EPOCH ¶

A timestamp (expressed as seconds since the Unix epoch) to use as the output creation timestamp in place of the current time. The time is converted to human-readable form using localtime(3) when the formatter starts up and stored in registers usable by documents and macro packages (see Built-in Registers).

TZ ¶

The time zone to use when converting the current time (or value of SOURCE_DATE_EPOCH) to human-readable form; see tzset(3).

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

2.3 Macro Directories

A macro file must have a name in the form name.tmac or tmac.name and be placed in a tmac directory to be found by the -mname command-line option.⁵ Together, these directories constitute the tmac path. Each directory is searched in the following order until the desired macro file is found or the list is exhausted.

• Directories specified with GNU troff’s or groff’s -M command-line option.
• Directories listed in the GROFF_TMAC_PATH environment variable.
• The current working directory (only if in unsafe mode using the -U command-line option).
• The user’s home directory, HOME.
• A platform-dependent directory, a site-local (platform-independent) directory, and the main tmac directory. The locations corresponding to your installation are listed in section “Environment” of gtroff(1). If not otherwise configured, they are as follows.

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

  The foregoing assumes that the version of groff is 1.23.0, and that the installation prefix was /usr/local. It is possible to fine-tune these locations during the source configuration process.

2.4 Font Directories

groff enforces few restrictions on how font description files are named. For its family/style mechanism to work (see Font Families), the names of fonts within a family should start with the family name, followed by the style. For example, the Times family uses ‘T’ for the family name and ‘R’, ‘B’, ‘I’, and ‘BI’ to indicate the styles ‘roman’, ‘bold’, ‘italic’, and ‘bold italic’, respectively. Thus the final font names are ‘TR’, ‘TB’, ‘TI’, and ‘TBI’.

Font description files are kept in font directories, which together constitute the font path. The search procedure always appends the directory devname, where name is the name of the output device. Assuming TeX DVI output, and /foo/bar as a font directory, the font description files for grodvi must be in /foo/bar/devdvi. Each directory in the font path is searched in the following order until the desired font description file is found or the list is exhausted.

• Directories specified with GNU troff’s or groff’s -f command-line option. All output drivers (and some preprocessors) support this option as well, because they require information about the glyphs to be rendered in the document.
• Directories listed in the GROFF_FONT_PATH environment variable.
• A site-local directory and the main font description directory. The locations corresponding to your installation are listed in section “Environment” of gtroff(1). If not otherwise configured, they are as follows.

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

  The foregoing assumes that the version of groff is 1.23.0, and that the installation prefix was /usr/local. It is possible to fine-tune these locations during the source configuration process.

2.5 Paper Format

In groff, the page dimensions for the formatter GNU troff and for output devices are handled separately. See Page Layout, for vertical manipulation of the page size, and See Line Layout, for horizontal changes. The papersize macro package, normally loaded by troffrc at startup, provides an interface for configuring page dimensions by convenient names, like ‘letter’ or ‘a4’; see groff_tmac(5). The default used by the formatter depends on its build configuration, but is usually one of the foregoing, as geographically appropriate.

It is up to each macro package to respect the page dimensions configured in this way.

For each output device, the size of the output medium can be set in its DESC file. Most output drivers also recognize a command-line option -p to override the default dimensions and an option -l to use landscape orientation. See DESC File Format, for a description of the papersize keyword, which takes an argument of the same form as -p. The output driver’s man page, such as grops(1), may also be helpful.

groff uses the command-line option -P to pass options to postprocessors; for example, use the following for PostScript output on A4 paper in landscape orientation.

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

2.6 Invocation Examples

roff systems are best known for formatting man pages. Once a man librarian program has located a man page, it may execute a groff command much like the following.

groff -t -man -Tutf8 /usr/share/man/man1/groff.1

The librarian will also pipe the output through a pager, which might not interpret the SGR terminal escape sequences groff emits for boldface, underlining, or italics; see the grotty(1) man page for a discussion.

To process a roff input file using the preprocessors gtbl and gpic and the me macro package in the way to which AT&T troff users were accustomed, one would type (or script) a pipeline.

gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty

Using groff, this pipe can be shortened to an equivalent command.

groff -p -t -me -T utf8 foo.me

An even easier way to do this is to use grog to guess the preprocessor and macro options and execute the result by using the command substitution feature of the shell.

$(grog -Tutf8 foo.me)

Each command-line option to a postprocessor must be specified with any required leading dashes ‘-’ because groff passes the arguments as-is to the postprocessor; this permits arbitrary arguments to be transmitted. For example, to pass a title to the gxditview postprocessor, the shell commands

groff -X -P -title -P 'trial run' mydoc.t

and

groff -X -Z mydoc.t | gxditview -title 'trial run' -

are equivalent.

3.1 Basics

Let us first survey some basic concepts necessary to use a macro package fruitfully.⁶ References are made throughout to more detailed information.

GNU troff 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 escape sequences), which tell GNU troff how to format the output. See Formatter Instructions.

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 (not tabs). See Invoking Requests.

The primary function of GNU troff is to collect words from input lines, fill output lines with those words, adjust the line to the right-hand margin by widening spaces, 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 force a break, starting a new output line. Some requests cause a break automatically, as do (normally) blank input lines and input lines beginning with a space or tab.

Not all input lines are text lines—words to be formatted. Some are control lines that tell a macro package (or GNU troff directly) how to format the text. Control lines start with a dot (‘.’) or an apostrophe (‘'’) as the first character, and can be followed by a macro call.

The 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 GNU troff.

• First, keep the input lines short. Short input lines are easier to edit, and GNU troff 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. GNU troff recognizes characters that usually end a sentence, and inserts inter-sentence space accordingly.
• Do not hyphenate words at the end of lines—GNU troff 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”.

We offer further advice in Input Conventions.

GNU troff permits alteration of the distance between lines of text. This is termed vertical spacing and is expressed in the same units as the type size—the point. The default is 10-point type on 12-point spacing. To get double-spaced text you would set the vertical spacing to 24 points. Some, but not all, macro packages expose a macro or register to configure the vertical spacing.

A number of requests allow you to change the way the output is arranged on the page, sometimes called the layout of the output page. Most macro packages don’t supply macros for performing these (at least not without performing other actions besides), as they are such basic operations. The macro packages for writing man pages, man and mdoc, don’t encourage explicit use of these requests at all.

The request ‘.sp N’ leaves N lines of blank space. N can be omitted (skipping 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).

If you seek precision in spacing, be advised when using a macro package that it might not honor sp requests as you expect; it can use a formatter feature called no-space mode to prevent excess space from accumulating. Macro packages typically offer registers to control spacing between paragraphs, before section headings, and around displays (discussed below); use these facilities preferentially. See Manipulating Spacing.

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 GNU troff to center zero more lines, in other words, stop centering.

GNU troff also offers the rj request for right-aligning text. It works analogously to ce and is convenient for setting epigraphs.

The bp request starts a new page; this necessarily implies an ordinary (line) break.

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. If you invoke them with the apostrophe ‘'’, the no-break control character, the (initial) break they normally perform is suppressed. ‘'br’ does nothing.

3.2 Common Features

GNU troff provides low-level operations for formatting a document. Many routine operations are undertaken in nearly all documents that require a series of such primitive operations to be performed. These common tasks are grouped into macros, which are then collected into a macro package.

Macro packages come in two varieties: “major” or “full-service” ones that manage page layout, and “minor” or “auxiliary” ones that do not, instead fulfilling narrow, specific tasks. Find a list in the groff_tmac(5) man page. Type ‘man groff_tmac’ at the command line to view it.

We survey several capabilities of full-service macro package below. Each package employs its own macros to exercise them. For details, consult its man page or, for ms, see ms.

• Paragraphs
• Sections and Chapters
• Headers and Footers
• Page Layout
• Displays and Keeps
• Footnotes and Endnotes
• Table of Contents
• Indexing
• Document Formats
• Columnation
• Font and Size Changes
• Predefined Text
• Preprocessor Support
• Configuration and Customization

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

  ⇒ 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
  ⇒      The  label does not align with the subsequent
  ⇒      lines, but they align with each other.

  ⇒ o    This  list  item  starts with a bullet.  When
  ⇒      producing output for a device using the ASCII
  ⇒      character set, an 'o' is formatted instead.

  ⇒ -xyz  This option is recognized but ignored.
  ⇒
  ⇒       It had a security hole that we don't discuss.

4.1 man

The man macro package is the most widely used and probably the most important ever developed for troff. It is easy to use, and a vast majority of manual pages (“man pages”) are written in it.

groff’s implementation is documented in the groff_man(7) man page. Type ‘man groff_man’ at the command line to view it.

• Optional man extensions

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

4.2 mdoc

groff’s implementation of the BSD doc package for man pages is documented in the groff_mdoc(7) man page. Type ‘man groff_mdoc’ at the command line to view it.

4.3 me

groff’s implementation of the BSD me macro package is documented using itself. A tutorial, meintro.me, and reference, meref.me, are available in groff’s documentation directory. A groff_me(7) man page is also available and identifies the installation path for these documents. Type ‘man groff_me’ at the command line to view it.

A French translation of the tutorial is available as meintro_fr.me and installed parallel to the English version.

4.4 mm

groff’s implementation of the AT&T memorandum macro package is documented in the groff_mm(7) man page. Type ‘man groff_mm’ at the command line) to view it.

A Swedish localization of mm is also available; see groff_mmse(7).

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

4.6 ms

The ms (“manuscript”) package is suitable for the preparation of letters, memoranda, reports, and books. These groff macros feature cover page and table of contents generation, automatically numbered headings, several paragraph styles, a variety of text styling options, footnotes, and multi-column page layouts. ms supports the tbl, eqn, pic, and refer preprocessors for inclusion of tables, mathematical equations, diagrams, and standardized bibliographic citations. This implementation is mostly compatible with the documented interface and behavior of AT&T Unix Version 7 ms. Many extensions from 4.2BSD (Berkeley) and Tenth Edition Research Unix have been recreated.

• Introduction
• Document Structure
• Document Control Settings
• Document Description Macros
• Body Text
• Page layout
• Differences from AT&T ms
• Legacy Features
• Naming Conventions

$ editor radical.ms
$ nroff -ww -z -ms radical.ms # check for errors
$ nroff -ms radical.ms | less -R
$ groff -T ps -ms radical.ms > radical.ps
$ see radical.ps

.LP
Radical novelties are so disturbing that they tend to be
suppressed or ignored, to the extent that even the
possibility of their existence in general is more often
denied than admitted.

→That's what Dijkstra said, anyway.

.nr PS 10.5p \" Use 10.5-point type.
.ds FAM P    \" Use Palatino font family.

My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\&
Wallace after the criticality incident.

.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 more in line with user demand.
.AE

…the rest of the paper…

.NH 2
Cases used in the 2001 study
.LP
Two software releases were considered for this report.
.PP
The first is commercial software;
the second is free.
.IP \[bu]
Microsoft Word for Windows,
starting with version 1.0 through the current version
(Word 2000).
.IP \[bu]
GNU 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.
.SH
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.

.NH 1
Animalia
.NH 2
Arthropoda
.NH 3
Crustacea
.NH 2
Chordata
.NH S 6 6 6
Daimonia
.NH 1
Plantae

1.  Animalia
1.1.  Arthropoda
1.1.1.  Crustacea
1.2.  Chordata
6.6.6.  Daimonia
7.  Plantae

.nr PS 10
.nr GROWPS 3
.nr PSINCR 1.5p
.NH 1
Carnivora
.NH 2
Felinae
.NH 3
Felis catus
.SH 2
Machairodontinae

The CS course's students found one C language keyword
.CW static ) \%(
most troublesome.

The CS course’s students found one C language keyword (static)
most troublesome.

The CS course's students found one C language keyword
\%(\c
.CW \%static )
most troublesome.

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

A bulleted list:

• lawyers

• guns

• money

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

A numbered list:

1. lawyers

2. guns

3. money

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!

A glossary-style list:

lawyers
      Two or more attorneys.

guns  Firearms, preferably large-caliber.

money
      Gotta pay for those lawyers and guns!

.IP guns
.br
Firearms,

.IP guns
\p Firearms,

.IP guns\h'0.4i'
Firearms,

A glossary-style list:

lawyers
      Two or more attorneys.

guns
      Firearms, preferably large-caliber.

money
      Gotta pay for those lawyers and guns!

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

• Lawyers:

  •  Dewey,

  •  Cheatham, and

  •  Howe.

• Guns

.LP
.B1
.I Warning:
Happy Fun Ball may suddenly accelerate to dangerous
speeds.
.sp \n[PD]/2 \" space by half the inter-paragraph distance
.B2

.TS H
allbox;
Cb | Cb .
Part→Description
_
.TH
.T&
GH-1978→Fribulating gonkulator
…the rest of the table follows…
.TE

.EQ C (\*[SN-NO-DOT]a)
p ~ = ~ q sqrt { ( 1 + ~ ( x / q sup 2 ) }
.EN

.ds FR 0+3i \" Set footnote line length to 3 inches.

$ groff -ms -mfr bienvenue.ms

.NH 1
Introduction
.XS
Introduction
.XE
…
.NH 2
Methodology
.XS
\h'2n'Methodology
.XA
\h'4n'Fassbinder's Approach
\h'4n'Kahiu's Approach
.XE
…
.NH 1
Findings
.XS
Findings
.XE
…
.TC

.NH 1
.XN Introduction
…
.NH 2
.XN Methodology
.XH 3 "Fassbinder's Approach"
.XH 3 "Kahiu's Approach"
…
.NH 1
.XN Findings
…

.de XN-REPLACEMENT
.XN-INIT
.XH-UPDATE-TOC \\n[nh*hl] \\$@
\&\\*[SN] \\$*
..

.rm UX
.ds UX Unix\"

5.1 Text

AT&T troff was designed to take input as it would be composed on a typewriter, including the teletypewriters used as early computer terminals, and relieve the user drafting a document of concern with details like line length, hyphenation breaking, and the achievement of straight margins. Early in its development, the program gained the ability to prepare output for a phototypesetter; a document could then be prepared for output to either a teletypewriter, a phototypesetter, or both. GNU troff continues this tradition of permitting an author to compose a single master version of a document which can then be rendered for a variety of output formats or devices.

roff input files contain text interspersed with instructions to control the formatter. Even in the absence of such instructions, GNU troff still processes its input in several ways, by filling, hyphenating, breaking, and adjusting it, and supplementing it with inter-sentence space.

• Filling
• Sentences
• Hyphenation
• Breaking
• Adjustment
• Tabs and Leaders
• Requests and Macros
• Macro Packages
• Input Encodings
• Input Conventions

It is a truth universally acknowledged
that a single man in possession of a
good fortune must be in want of a wife.
    ⇒ It is a truth universally acknowledged that a
    ⇒ single man in possession of a good fortune must
    ⇒ be in want of a wife.

Hello, world!
Welcome to groff.
    ⇒ Hello, world!  Welcome to groff.

R. Harper subscribes to a maxim of P. T. Barnum.
    ⇒ R. Harper subscribes to a maxim of P. T. Barnum.

I submit that R. Harper subscribes to a maxim of P. T.
Barnum.
    ⇒ I submit that R. Harper subscribes to a maxim of
    ⇒ P. T.  Barnum.

I submit that R.\& Harper subscribes to a maxim of P.\&
T.\& Barnum.
    ⇒ I submit that R. Harper subscribes to a maxim of
    ⇒ P. T. Barnum.

\[lq]The idea that the poor should have leisure has always
been shocking to the rich.\[rq]
(Bertrand Russell, 1935)
    ⇒ "The idea that the poor should have
    ⇒ leisure has always been shocking to
    ⇒ the rich."  (Bertrand Russell, 1935)

$ perl -e 'print "#" x 80, "\n";' | nroff -z
    error→ warning: cannot break line

1
→ 2 → 3 • 4
→ • 5
⇒ 1         2       3.......4         ........5

.de DATE
2020-11-14
..

.de NAME ENDNAME
Heywood Jabuzzoff
.ENDNAME

.de END
Big Rip
..
.de START END
Big Bang
.END
.START
    ⇒ Big Rip Big Bang

.de DATE
2020-10-05
..
.
.de BOSS
D.\& Kruger,
J.\& Peterman
..
.
.de NOTICE
Approved:
.DATE
by
.BOSS
..
.
Insert tedious regulatory compliance paragraph here.

.NOTICE

Insert tedious liability disclaimer paragraph here.

.NOTICE
    ⇒ Insert tedious regulatory compliance paragraph here.
    ⇒
    ⇒ Approved: 2020-10-05 by D. Kruger, J. Peterman
    ⇒
    ⇒ Insert tedious liability disclaimer paragraph here.
    ⇒
    ⇒ Approved: 2020-10-05 by D. Kruger, J. Peterman

.\"   nroff this_file.roff | less
.\"   groff -T ps this_file.roff > this_file.ps
→The theory of relativity is intimately connected with
the theory of space and time.
.
I shall therefore begin with a brief investigation of
the origin of our ideas of space and time,
although in doing so I know that I introduce a
controversial subject.  \" remainder of paragraph elided
.
.

→The experiences of an individual appear to us arranged
in a series of events;
in this series the single events which we remember
appear to be ordered according to the criterion of
\[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped
which cannot be analysed further.
.
There exists,
therefore,
for the individual,
an I-time,
or subjective time.
.
This itself is not measurable.
.
I can,
indeed,
associate numbers with the events,
in such a way that the greater number is associated with
the later event than with an earlier one;
but the nature of this association may be quite
arbitrary.
.
This association I can define by means of a clock by
comparing the order of events furnished by the clock
with the order of a given series of events.
.
We understand by a clock something which provides a
series of events which can be counted,
and which has other properties of which we shall speak
later.
.\" Albert Einstein, _The Meaning of Relativity_, 1922

5.2 Page Geometry

roff systems format text under certain assumptions about the size of the output medium, or page. For the formatter to correctly break a line it is filling, it must know the line length, which it derives from the page width (see Line Layout). For it to decide whether to write an output line to the current page or wait until the next one, it must know the page length (see Page Layout).

A device’s resolution converts practical units like inches or centimeters to basic units, a convenient length measure for the output device or file format. The formatter and output driver use basic units to reckon page measurements. The device description file defines its resolution and page dimensions (see DESC File Format).

A page is a two-dimensional structure upon which a roff system imposes a rectangular coordinate system with its upper left corner as the origin. Coordinate values are in basic units and increase down and to the right. Useful ones are therefore always positive and within numeric ranges corresponding to the page boundaries.

While the formatter (and, later, output driver) is processing a page, it keeps track of its drawing position, which is the location at which the next glyph will be written, from which the next motion will be measured, or where a geometric object will commence rendering. Notionally, glyphs are drawn from the text baseline upward and to the right.³³ The text baseline is a (usually invisible) line upon which the glyphs of a typeface are aligned. A glyph therefore “starts” at its bottom-left corner. If drawn at the origin, a typical letter glyph would lie partially or wholly off the page, depending on whether, like “g”, it features a descender below the baseline.

Such a situation is nearly always undesirable. It is furthermore conventional not to write or draw at the extreme edges of the page. Therefore the initial drawing position of a roff formatter is not at the origin, but below and to the right of it. This rightward shift from the left edge is known as the page offset.³⁴ The downward shift leaves room for a text output line.

Text is arranged on a one-dimensional lattice of text baselines from the top to the bottom of the page. Vertical spacing is the distance between adjacent text baselines. Typographic tradition sets this quantity to 120% of the type size. The initial drawing position is one unit of vertical spacing below the page top. Typographers term this unit a vee.

Vertical spacing has an impact on page-breaking decisions. Generally, when a break occurs, the formatter moves the drawing position to the next text baseline automatically. If the formatter were already writing to the last line that would fit on the page, advancing by one vee would place the next text baseline off the page. Rather than let that happen, roff formatters instruct the output driver to eject the page, start a new one, and again set the drawing position to one vee below the page top; this is a page break.

When the last line of input text corresponds to the last output line that fits on the page, the break caused by the end of input will also break the page, producing a useless blank one. Macro packages keep users from having to confront this difficulty by setting “traps” (see Traps); moreover, all but the simplest page layouts tend to have headers and footers, or at least bear vertical margins larger than one vee.

5.3 Measurements

The formatter sometimes requires the input of numeric parameters to specify measurements. These are specified as integers or decimal fractions with an optional scaling unit suffixed. A scaling unit is a letter that immediately follows the last digit of a number. Digits after the decimal point are optional. Measurement expressions include ‘10.5p’, ‘11i’, and ‘3.c’.

Measurements are scaled by the scaling unit and stored internally (with any fractional part discarded) in basic units. The device resolution can therefore be obtained by storing a value of ‘1i’ to a register. The only constraint on the basic unit is that it is at least as small as any other unit.

u

Basic unit.

i ¶

Inch; defined as 2.54 centimeters.

c ¶

Centimeter; a centimeter is about 0.3937 inches.

p ¶

Point; a typesetter’s unit used for measuring type size. There are 72 points to an inch.

P ¶

Pica; another typesetter’s unit. There are 6 picas to an inch and 12 points to a pica.

s

z

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

f

GNU troff defines this unit to scale decimal fractions in the interval [0, 1] to 16-bit unsigned integers. It multiplies a quantity by 65,536. See Colors, for usage.

The magnitudes of other scaling units depend on the text formatting parameters in effect. These are useful when specifying measurements that need to scale with the typeface or vertical spacing.

m ¶

Em; an em is equal to the current type size in points. It is named thus because it is approximately the width of the letter ‘M’.

n ¶

En; an en is one-half em.

v ¶

Vee; recall Page Geometry.

M ¶

Hundredth of an em.

• Motion Quanta
• Default Units

.tm \n[.H]
    error→ 24
.nf
\l'36u' 36u
\l'37u' 37u
    ⇒ _ 36u
    ⇒ __ 37u

.ll 3.5i      \" 3.5i (= 840u)
.ll 7/2       \" 7u/2u -> 3u -> 3m -> 0, clamped to 24u
.ll (7 / 2)u  \" 7u/2u -> as above
.ll 7/2i      \" 7u/2i -> 7u/480u -> 0 -> as above
.ll 7i/2      \" 7i/2u -> 1680u/2m -> 1680u/24u -> 35u
.ll 7i/2u     \" 3.5i (= 840u)

5.4 Numeric Expressions

A numeric expression evaluates to an integer: it can be as simple as a literal ‘0’ or it can be a complex sequence of register and string interpolations interleaved with measurements and operators.

GNU troff provides a set of mathematical and logical operators familiar to programmers—as well as some unusual ones—but supports only integer arithmetic.³⁵ The internal data type used for computing results is usually a 32-bit signed integer, which suffices to represent magnitudes within a range of ±2 billion.³⁶

Arithmetic infix operators perform a function on the numeric expressions to their left and right; they are + (addition), - (subtraction), * (multiplication), / (truncating division), and % (modulus). Truncating division rounds to the integer nearer to zero, no matter how large the fractional portion. Overflow and division (or modulus) by zero are errors and abort evaluation of a numeric expression.

Arithmetic unary operators operate on the numeric expression to their right; they are - (negation) and + (assertion—for completeness; it does nothing). The unary minus must often be used with parentheses to avoid confusion with the decrementation operator, discussed below.

Observe the rounding behavior and effect of negative operands on the modulus and truncating division operators.

.nr T 199/100
.nr U 5/2
.nr V (-5)/2
.nr W 5/-2
.nr X 5%2
.nr Y (-5)%2
.nr Z 5%-2
T=\n[T] U=\n[U] V=\n[V] W=\n[W] X=\n[X] Y=\n[Y] Z=\n[Z]
    ⇒ T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1

The sign of the modulus of operands of mixed signs is determined by the sign of the first. Division and modulus operators satisfy the following property: given a dividend a and a divisor b, a quotient q formed by ‘(a / b)’ and a remainder r by ‘(a % b)’, then qb + r = a.

GNU troff’s scaling operator, used with parentheses as (c;e), evaluates a numeric expression e using c as the default scaling unit. If c is omitted, scaling units are ignored in the evaluation of e. This operator can save typing by avoiding the attachment of scaling units to every operand out of caution. Your macros can select a sensible default unit in case the user neglects to supply one.

.\" Indent by amount given in first argument; assume ens.
.de Indent
.  in (n;\\$1)
..

Without the scaling operator, the foregoing macro would, if called with a unitless argument, cause indentation by the in request’s default scaling unit (ems). The result would be twice as much indentation as expected.

GNU troff also provides a pair of operators to compute the extrema of two operands: >? (maximum) and <? (minimum).

.nr slots 5
.nr candidates 3
.nr salaries (\n[slots] <? \n[candidates])
Looks like we'll end up paying \n[salaries] salaries.
    ⇒ Looks like we'll end up paying 3 salaries.

Comparison operators comprise < (less than), > (greater than), <= (less than or equal), >= (greater than or equal), and = (equal). == is a synonym for =. When evaluated, a comparison is replaced with ‘0’ if it is false and ‘1’ if true. In the roff language, positive values are true, others false.

We can operate on truth values with the logical operators & (logical conjunction or “and”) and : (logical disjunction or “or”). They evaluate as comparison operators do.

A logical complementation (“not”) operator, !, works only within if, ie, and while requests. Furthermore, ! is recognized only at the beginning of a numeric expression not contained by another numeric expression. In other words, it must be the “outermost” operator. Including it elsewhere in the expression produces a warning in the ‘number’ category (see Warnings), and its expression evaluates false. This unfortunate limitation maintains compatibility with AT&T troff. Test a numeric expression for falsity by comparing it to a false value.³⁷

.nr X 1
.nr Y 0
.\" This does not work as expected.
.if (\n[X])&(!\n[Y]) .nop A: X is true, Y is false
.
.\" Use this construct instead.
.if (\n[X])&(\n[Y]<=0) .nop B: X is true, Y is false
    error→ warning: expected numeric expression, got '!'
    ⇒ B: X is true, Y is false

The roff language has no operator precedence: expressions are evaluated strictly from left to right, in contrast to schoolhouse arithmetic. Use parentheses ( ) to impose a desired precedence upon subexpressions.

.nr X 3+5*4
.nr Y (3+5)*4
.nr Z 3+(5*4)
X=\n[X] Y=\n[Y] Z=\n[Z]
    ⇒ X=32 Y=32 Z=23

For many requests and escape sequences that cause motion on the page, the unary operators + and - work differently when leading a numeric expression. They then indicate a motion relative to the drawing position: positive is down in vertical contexts, right in horizontal ones.

+ and - are also treated differently by the following requests and escape sequences: bp, in, ll, lt, nm, nr, pl, pn, po, ps, pvs, rt, ti, \H, \R, and \s. Here, leading plus and minus signs serve as incrementation and decrementation operators, respectively. To negate an expression, subtract it from zero or include the unary minus in parentheses with its argument. See Setting Registers, for examples.

A leading | operator indicates a motion relative not to the drawing position but to a boundary. For horizontal motions, the measurement specifies a distance relative to a drawing position corresponding to the beginning of the input line. By default, tab stops reckon movements in this way. Most escape sequences do not; | tells them to do so.

Mind the \h'1.2i'gap.
.br
Mind the \h'|1.2i'gap.
.br
Mind the
\h'|1.2i'gap.
    ⇒ Mind the             gap.
    ⇒ Mind the    gap.
    ⇒ Mind the             gap.

One use of this feature is to define macros whose scope is limited to the output they format.

.\" underline word $1 with trailing punctuation $2
.de Underline
.  nop \\$1\l'|0\[ul]'\\$2
..
Typographical emphasis is best used
.Underline sparingly .

In the above example, ‘|0’ specifies a negative motion from the current position (at the end of the argument just emitted, \$1) to the beginning of the input line. Thus, the \l escape sequence in this case draws a line from right to left. A macro call occurs at the beginning of an input line;³⁸ if the | operator were omitted, then the underline would be drawn at zero distance from the current position, producing device-dependent, and likely undesirable, results. On the ‘ps’ output device, it underlines the period.

For vertical motions, the | operator specifies a distance from the first text baseline on the page or in the current diversion,³⁹ using the current vertical spacing.

A
.br
B \Z'C'\v'|0'D
    ⇒ A D
    ⇒ B C

In the foregoing example, we’ve used the \Z escape sequence (see Page Motions) to restore the drawing position after formatting ‘C’, then moved vertically to the first text baseline on the page.

Escape sequence: \B'anything' ¶

Interpolate 1 if anything is a valid numeric expression, and 0 otherwise. The delimiter need not be a neutral apostrophe; see Delimiters.

You might use \B along with the if request to filter out invalid macro or string arguments. See Conditionals and Loops.

.\" Indent by amount given in first argument; assume ens.
.de Indent
.  if \B'\\$1' .in (n;\\$1)
..

A register interpolated as an operand in a numeric expression must have an Arabic format; luckily, this is the default. See Assigning Register Formats.

Because spaces separate arguments to requests, spaces are not allowed in numeric expressions unless the (sub)expression containing them is surrounded by parentheses. See Invoking Requests, and Conditionals and Loops.

.nf
.nr a 1+2 + 2+1
\na
    error→ expected numeric expression, got a space
    ⇒ 3
.nr a 1+(2 + 2)+1
\na
    ⇒ 6

The nr request (see Setting Registers) expects its second and optional third arguments to be numeric expressions; a bare + does not qualify, so our first attempt got a warning.

5.5 Identifiers

An identifier labels a GNU troff datum such as a register, name (macro, string, or diversion), typeface, color, special character, character class, environment, or stream. Valid identifiers consist of one or more ordinary characters. An ordinary character is an input character that is not the escape character, a leader, tab, newline, or invalid as GNU troff input.

Invalid input characters are a subset of control characters (from the sets “C0 Controls” and “C1 Controls” as Unicode describes them). When GNU troff encounters one in an identifier, it produces a warning in category ‘input’ (see Warnings). They are removed during interpretation: an identifier ‘foo’, followed by an invalid character and then ‘bar’, is processed as ‘foobar’.

On a machine using the ISO 646, 8859, or 10646 character encodings, invalid input characters are 0x00, 0x08, 0x0B, 0x0D–0x1F, and 0x80–0x9F. On an EBCDIC host, they are 0x00–0x01, 0x08, 0x09, 0x0B, 0x0D–0x14, 0x17–0x1F, and 0x30–0x3F.⁴⁰ Some of these code points are used by GNU troff internally, making it non-trivial to extend the program to accept UTF-8 or other encodings that use characters from these ranges.⁴¹

Thus, the identifiers ‘br’, ‘PP’, ‘end-list’, ‘ref*normal-print’, ‘|’, ‘@_’, and ‘!"#$%'()*+,-./’ are all valid. Discretion should be exercised to prevent confusion. Identifiers starting with ‘(’ or ‘[’ require care.

.nr x 9
.nr y 1
.nr (x 2
.nr [y 3
.nr sum1 (\n(x + \n[y])
    error→ a space character is not allowed in an escape
    error→   sequence parameter
A:2+3=\n[sum1]
.nr sum2 (\n((x + \n[[y])
B:2+3=\n[sum2]
.nr sum3 (\n[(x] + \n([y)
C:2+3=\n[sum3]
    ⇒ A:2+3=1 B:2+3=5 C:2+3=5

An identifier with a closing bracket (‘]’) in its name can’t be accessed with bracket-form escape sequences that expect an identifier as a parameter. For example, ‘\[foo]]’ accesses the glyph ‘foo’, followed by ‘]’ in whatever the surrounding context is, whereas ‘\C'foo]'’ formats a glyph named ‘foo]’. Similarly, the identifier ‘(’ can’t be interpolated except with bracket forms.

If you begin a macro, string, or diversion name with either of the characters ‘[’ or ‘]’, you foreclose use of the grefer preprocessor, which recognizes ‘.[’ and ‘.]’ as bibliographic reference delimiters.

Escape sequence: \A'anything' ¶

Interpolate 1 if anything is a valid identifier, and 0 otherwise. The delimiter need not be a neutral apostrophe; see Delimiters. Because invalid input characters are removed (see above), invalid identifiers are empty or contain spaces, tabs, or newlines.

You can employ \A to validate a macro argument before using it to construct another escape sequence or identifier.

.\" usage: .init-coordinate-pair name val1 val2
.\" Create a coordinate pair where name!x=val1 and
.\" name!y=val2.
.de init-coordinate-pair
.  if \A'\\$1' \{\
.    if \B'\\$2' .nr \\$1!x \\$2
.    if \B'\\$3' .nr \\$1!y \\$3
.  \}
..
.init-coordinate-pair center 5 10
The center is at (\n[center!x], \n[center!y]).
.init-coordinate-pair "poi→nt" trash garbage \" ignored
.init-coordinate-pair point trash garbage \" ignored
    ⇒ The center is at (5, 10).

In this example, we also validated the numeric arguments; the registers ‘point!x’ and ‘point!y’ remain undefined. See Numeric Expressions for the \B escape sequence.

How GNU troff handles the interpretation of an undefined identifier depends on the context. There is no way to invoke an undefined request; such syntax is interpreted as a macro call instead. If the identifier is interpreted as a string, macro, or diversion, GNU troff emits a warning in category ‘mac’, defines it as empty, and interpolates nothing. If the identifier is interpreted as a register, GNU troff emits a warning in category ‘reg’, initializes it to zero, and interpolates that value. See Warnings, Interpolating Registers, and Strings. Attempting to use an undefined typeface, special character, color, character class, environment, or stream generally provokes an error diagnostic.

Identifiers for requests, macros, strings, and diversions share one name space; special characters and character classes another. No other object types do.

.de xxx
.  nop foo
..
.di xxx
bar
.br
.di
.
.xxx
    ⇒ bar

The foregoing example shows that GNU troff reuses the identifier ‘xxx’, changing it from a macro to a diversion. No warning is emitted, and the previous contents of ‘xxx’ are lost.

5.6 Formatter Instructions

To support documents that require more than filling, automatic line breaking and hyphenation, adjustment, and supplemental inter-sentence space, the roff language offers two means of embedding instructions to the formatter.

One is a request, which begins with a control character and takes up the remainder of the input line. Requests often perform relatively large-scale operations such as setting the page length, breaking the line, or starting a new page. They also conduct internal operations like defining macros.

The other is an escape sequence, which begins with the escape character and can be embedded anywhere in the input, even in arguments to requests and other escape sequences. Escape sequences interpolate special characters, strings, or registers, and handle comparatively minor formatting tasks like sub- and superscripting.

Some operations, such as font selection and type size alteration, are available via both requests and escape sequences.

• Control Characters
• Invoking Requests
• Calling Macros
• Using Escape Sequences
• Delimiters

.de center
.  if \\n[.br] \
.    br
.  ce \\$1
..
.
.
.de right-align
.→if \\n[.br] \
.→→br
.→rj \\$1
..

.de do-nothing
..
.blm do-nothing  \" activate blank line trap

.de center
.  if \\n[.br] \
.    br
.  ce \\$1
..


.de right-align
.→if \\n[.br] \
.→→br
.→rj \\$1
..

.blm             \" deactivate blank line trap

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

.de eq
.  tm arg1:\\$1 arg2:\\$2 arg3:\\$3
.  tm arg4:\\$4 arg5:\\$5 arg6:\\$6
.. \" 4 backslashes on the next line
.eq a" "b c" "de"f\\\\g" h""i "j""k"
    error→ arg1:a" arg2:b c arg3:de
    error→ arg4:f\g" arg5:h""i arg6:j"k

.cp 1
.de eq
.  tm arg1:\\$1 arg2:\\$2 arg3:\\$3
.  tm arg4:\\$4 arg5:\\$5 arg6:\\$6
..
.de xe
.  eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6
.. \" 8 backslashes on the next line
.xe a" "b c" "de"f\\\\\\\\g" h""i "j""k"
    error→ arg1:a" arg2:b arg3:c
    error→ arg4:de arg5:f\g" arg6:h""i

$ groff -Tps -ww
.nr N 12
.ds co white
.ds animal elephant
I have \fI\nN \*(co \*[animal]s,\f[]
said \P.\&\~Pseudo Pachyderm.
    error→ warning: escape character ignored before 'P'
    ⇒ I have 12 white elephants, said P. Pseudo Pachyderm.

.ds family C\" Courier
.ds style I\" oblique
Choice a typeface \f(\*[family]\*[style]wisely.
    ⇒ Choose a typeface wisely.