The GNU troff Manual

Table of Contents

GNU troff

This manual documents GNU troff version 1.24.0.rc2.

Copyright © 1994–2018 Free Software Foundation, Inc.
Copyright © 2018–2026 G. Branden Robinson

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

1 Introduction

GNU roff (or groff) is a programming system for typesetting documents. It is highly flexible and has been used extensively for over thirty years.

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 forerunners roff, nroff, and troff is available in roff(7).

1.2 What Is groff?

groff (GNU roff) is a typesetting system that reads plain text input that includes formatting commands to produce output in PostScript, PDF, HTML, 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 troff and other programs from AT&T Unix, groff is widely available on POSIX and other systems owing to its long association with Unix manuals, including man pages. It and its predecessor have produced several best-selling software engineering texts. groff can create typographically sophisticated documents while consuming minimal system resources.

Like its predecessor “troff”, the term “groff” affords two popular pronunciations: as one syllable (like the surname), rhyming with “trough”, or as “jee-roff”, in analogy to the Bell Labs pronunciation “tee-roff”. Little risk of confusion exists; use whichever suits you.

The architecture of the GNU roff system follows that of other device-independent roff implementations, comprising preprocessors, macro packages, output drivers (or “postprocessors”), and a suite of utilities, with the formatter program troff at its heart.

The front end programs available in the GNU roff system easier to use than traditional roffs that required the construction of pipelines or use of temporary files to carry a source document from maintainable form to device-ready output.

1.3 GNU troff Capabilities

GNU troff is a typesetting document formatting program; 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 laborious 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. One then calls the macro to make it perform its task. Macros can be specific to one document or collected together into a macro package for use by many. groff supplies versions of the widely used macro packages 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 relevant portions of 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 GNU troff to handle documents in a variety of input encodings, including UTF-8. Unlike most preprocessors, preconv operates on its entire enput rather than transforming specially marked regions of a document.

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. An output driver 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 printers, Canon LBP (CaPSL-using printers), 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. We say “the formatter” when speaking of behavior that is generally true of troff and nroff programs.

A tradition has arisen that GNU programs’ names bear a prefix ‘g’ where necessary to distinguish them from other implementations on the host system (see Environment). Thus, for example, geqn is GNU eqn. On operating systems that lack a troff of different provenance, this prefix is omitted; GNU troff is the only troff available. Exceptionally, ‘groff’ always retains its leading ‘g’.

We call non-GNU troff systems AT&T troff because that is the common origin of almost all troff implementations³ (with more or less compatible changes). Similarly, we say ‘gpic’, ‘geqn’, and so on.

This manual employs Emacs names for non-graphic keycap engravings on the alphabetic section of the keyboard. “RET” is Return or Enter, and “SPC” is the space bar.

The roff language features several major syntactical categories within which many items are predefined. Presentations of these items comprise the name of the category followed by a colon and the form in which the item is most commonly used.

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; skim material you haven’t mastered 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 -T ascii | sed '/^$/d'
    ⇒ Twelve o'clock and
$ echo '.tm all is well.' | groff > /dev/null
    error→ all is well.

Sometimes we use ⇒ 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.

We encourage you to to try the examples yourself, and to alter them to better learn groff’s behavior. Our examples sometimes need to direct the formatter to set a line length (with ‘.ll’) that fits 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.⁵

We refer occasionally to man pages, in which aspects of the groff system or of its operating environment are further documented.⁶ When you see a citation like groff_man(7), understand that you can type ‘man groff_man’ at the command line to view it. The numbered category distinguishes pages by their purpose. You can try ‘man 'groff(1)'’ and ‘man 'groff(7)'’ to observe this distinction.⁷ Your system likely offers an intro(1) page that will help you make the most of this resource.

1.9 Credits

We adapted portions of this manual from existing documents. James Clark’s man pages were an invaluable foundation; we have updated them in parallel with the development of this manual. We based the tutorial for macro package 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 Invoking groff

This chapter focuses on how to invoke the groff front end, which constructs a pipeline connecting desired preprocessors, the GNU troff formatter program, and a postprocessor.

2.1 Options

groff runs the GNU troff program and, normally, a postprocessor appropriate to the selected device. The default device is ‘ps’, unless changed at groff’s build-time configuration. groff can preprocess input with any of gpic, geqn, gtbl, ggrn, grap, gchem, grefer, gsoelim, or preconv.

This section documents only options to the groff front end. Since it passes many of its arguments to GNU troff, we describe many of the latter’s options here. 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).

A summary of groff’s usage follows.

groff [-abcCeEgGijklNpRsStUVXzZ] [-d cs] [-d string=text]
      [-D fallback-encoding] [-f font-family]
      [-F font-directory] [-I inclusion-directory]
      [-K input-encoding] [-L spooler-argument]
      [-m macro-package] [-M macro-directory]
      [-n page-number] [-o page-list]
      [-P postprocessor-argument] [-r cnumeric-expression]
      [-r register=numeric-expression] [-T output-device]
      [-w warning-category] [-W warning-category]
      [file …]

troff shares much of this interface; groff passes relevant options and operands to it.

troff [-abcCEiRSUz] [-f font-family] [-F font-directory]
      [-I inclusion-directory] [-m macro-package]
      [-M macro-directory] [-n page-number] [-o page-list]
      [-r cnumeric-expression]
      [-r register=numeric-expression] [-T output-device]
      [-w warning-category] [-W warning-category]
      [file …]

Options that don’t take arguments can be clustered after a single -. A file operand of  - denotes the standard input stream.

All groff commands accept a --help option, which summarizes usage similarly to the foregoing, and --version, which discloses release information. Both exit with a successful status after reporting.

The rest of 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 formatted output.
• Vertical motion, apart from that implied by a break, is not represented.
• A horizontal motion of any size is represented as one space. Adjacent horizontal motions are not combined. Supplemental inter-sentence space (configured by the second argument to the ss request) is not represented.
• A special character is rendered as its identifier between angle brackets; for example, a hyphen 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 troff’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 troff’s idea of line numbers can be confused by requests that append to macros.

‘-c’

Disable multi-color output and color request’s ability to enable it.

‘-C’

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

‘-d ctext’

‘-d string=text’

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

‘-D enc’

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

‘-e’

Run geqn preprocessor.

‘-E’

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

‘-f fam’

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

‘-F dir’

Search in directory dir for the selected output device’s directory of device and font description files. See Font Directories.

‘-g’

Run ggrn preprocessor.

‘-G’

Run grap preprocessor; implies -p.

‘-h’

Display a usage message and exit.

‘-i’

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

‘-I dir’

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.
• troff 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 extension 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.

groff passes -I options and their arguments to gsoelim, troff, and output drivers; with the option letter changed to -M, it passes the same arguments 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.

‘-K enc’

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.

‘-L arg’

Pass arg to the print spooler. 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.

‘-m mac’

Search for the macro package mac.tmac and read it prior to any input. If not found, tmac.mac is attempted. See Macro Directories. groff passes -m options and their arguments to geqn, grap, and ggrn.

‘-M dir’

Search directory dir for macro files. See Macro Directories. groff passes -M options and their arguments to geqn, grap, and ggrn.

‘-n num’

Begin numbering pages at num. The default is ‘1’.

‘-N’

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

‘-o list’

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. troff stops processing and exits after formatting the last page enumerated in list.

‘-p’

Run gpic preprocessor.

‘-P arg’

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.

‘-r cnumeric-expression’

‘-r register=numeric-expression’

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

‘-R’

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

troff also accepts a -R option, which is not accessible via groff. This option facilitates troubleshooting by preventing the loading of the troffrc and troffrc-end files.

‘-s’

Run gsoelim preprocessor.

‘-S’

Operate in “safer” mode; see -U below for its opposite. Safer mode is enabled by default. Explicitly specifying -S causes troff to ignore any subsequent -U option.

‘-t’

Run gtbl preprocessor.

‘-T dev’

Prepare output for device dev. groff passes the -T option and its argument to troff, then (unless the -Z option is used) runs an output driver to convert troff’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) ISO 646:1991 IRV (US-ASCII) character set.

latin1

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

utf8

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

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 run 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 selection can be overridden with the -X option.

‘-U’

Operate in unsafe mode, enabling the cf, open, opena, pi, pso, and sy requests, which are disabled by default because they allow an untrusted input document to run arbitrary commands, put arbitrary content into troff output, or write to arbitrary file names.⁸ This option also adds the current directory to the macro package search path; see the -m and -M option above. groff passes -U to gpic and GNU troff.

‘-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 groff would run to the standard output stream and exit. If given more than once, groff both writes the pipeline to the standard error stream and runs it.

‘-w cat’

‘-W cat’

Enable and inhibit, respectively, warnings in category cat. See Warnings.

‘-X’

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

‘-z’

Suppress formatted output from troff.

‘-Z’

Disable postprocessing. troff output appears on the standard output stream (unless suppressed with -z); see GNU troff Output for a description of this format.

2.2 Environment

Environment variables in the host system affect the behavior of programs supplied by groff as follows. Normally, the path separator in environment variables ending with ‘PATH’ is the colon; this may vary depending on the operating system. For example, Windows uses a semicolon instead.

GROFF_BIN_PATH

Locate groff commands in these directories, followed by those in PATH. If not set, the installation directory of GNU roff executables, documented in groff(1), is searched before PATH.

GROFF_COMMAND_PREFIX

Apply a prefix to certain GNU roff commands. groff can be configured at compile time to apply a prefix to the names of programs it provides that had counterparts in AT&T troff, so that name collisions are avoided at run time. The default prefix is empty.

When used, this prefix is conventionally the letter ‘g’. For example, GNU troff would be installed as troff. Besides troff, the prefix applies to the formatter wrapper nroff; the preprocessors eqn, grn, pic, refer, tbl, and soelim; and the utilities indxbib and lookbib.

GROFF_ENCODING

Specify the assumed character encoding of the input. groff passes its value as an argument to the preconv preprocessor’s -e option. This variable’s existence implies the groff option -k. If set but empty, groff runs preconv without an -e option. groff’s -K option overrides GROFF_ENCODING. See preconv(7).

GROFF_FONT_PATH

Seek the selected output device’s directory of device and font description files in this list of directories. See Font Directories, troff(1), and groff_font(5).

GROFF_TMAC_PATH

Seek macro packages in this list of directories. See Macro Directories, troff(1), and groff_tmac(5).

GROFF_TMPDIR

Create temporary files in this directory. If not set, but TMPDIR is, the latter is used instead. On Windows systems, if neither of the foregoing are set, the environment variables TMP and TEMP (in that order) are checked also. Otherwise, temporary files are created in a system-dependent default directory (on Unix and GNU/Linux systems, usually /tmp). The grefer, grohtml, and grops commands use temporary files.

GROFF_TYPESETTER

Set the default output device. The -T dev option overrides it. If empty or unset, a default configured at build time, and documented in groff(1), is used.

SOURCE_DATE_EPOCH

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

TZ

Declare the time zone to use when converting the current time to human-readable form; see tzset(3). If SOURCE_DATE_EPOCH is used, it is always converted to human-readable form using UTC.

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 -m mac command-line option.⁹ Such naming and placement makes a macro file into a macro package; when requested, it is sought in several directories. Together, these locations constitute the tmac path. Each directory is searched in the following order until the desired package is found or the list is exhausted.

• Directories specified with the -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, found in the HOME environment variable.
• A site-local platform-dependent directory, a site-local platform-independent directory, and a stock directory. Locations corresponding to your installation are listed in section “Environment” of troff(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. These locations can be customized as part of the build-time configuration process.

2.4 Font Directories

The GNU troff formatter and groff’s output drivers read device and font description files that detail the output device and the typefaces available to it, including their glyph repertoires and the metrics (dimensions) of each glyph. This information permits the formatter to accurately place glyphs with respect to each other. The device description file is always named DESC; fonts are typically described in files with short names like TR, CR, HBI, or S.¹⁰

Device and 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 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 description file is found or the list is exhausted.

• Directories specified with the -f command-line option. All output drivers (and some preprocessors) support this option as well, because they require information about glyphs to be rendered in the document.
• Directories listed in the GROFF_FONT_PATH environment variable.
• A site-local directory and a stock directory. Locations corresponding to your installation are listed in section “Environment” of troff(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. These locations can be customized as part of the build-time configuration process.

2.5 Paper Format

The formatter reads the device description file DESC for the selected output device when it starts; page dimensions declared there are used if present.

groff’s build process configures a default page format and writes it to typesetters’ DESC files. This installation defaults to ‘letter’. If the DESC file lacks this information, the formatter and output driver use a page length of ‘11i’ (eleven inches) for compatibility with AT&T troff.

In the formatter, the pl request changes the page length, but macro packages often do not support alteration of the paper format within a document. One might, for instance, want to switch between portrait and landscape orientations. Macro packages lack a consistent approach to configuration of parameters dependent on the paper format; some, like ms, benefit from a preamble in the document prior to the first macro call, while others, like mm, instead require the specification of registers on the command line, or otherwise before its macro file is interpreted, to configure page dimensions.

Output drivers for typesetters also recognize command-line options -p to override the default page dimensions and -l to use landscape orientation. The output driver’s man page, such as grops(1), may be helpful.

groff’s -d paper command-line option is a convenient means of setting the paper format; see groff_tmac(5). Combine it with appropriate -P options for the output driver, overriding its defaults. The following command formats for PostScript on A4 paper in landscape orientation.

$ groff -T ps -d paper=a4l -P -pa4 -P -l -m s my.ms >my.ps

2.6 Invocation Examples

roff systems are best known for formatting man pages. A man librarian program, having located a page, might render it with a groff command.

$ groff -t -m an -T utf8 /usr/share/man/man1/groff.1

The librarian may also pipe the output through a pager, which might not interpret terminal escape sequences groff emits for boldface, underlining, italics, or hyperlinking; 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.

$ pic foo.me | tbl | troff -m e -T utf8 | grotty

Shorten this pipeline to an equivalent command using groff.

$ groff -p -t -m e -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 -T utf8 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, permitting transmission of arbitrary arguments. 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 Tutorial for Macro Package Users

Most users of the roff language employ a macro package to format their documents. Successful macro packages ease the composition process; their users need not master the full formatting language, nor understand features like diversions, traps, and environments. This chapter aims to familiarize you with basic concepts and mechanisms common to many macro packages (like “displays”). If you prefer a meticulous and comprehensive presentation of the language and its formatter, peruse GNU troff Reference instead.

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 input 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 primary function of GNU troff is to collect words from its input, fill output lines with those words, break the line at or near the right-hand margin (possibly by hyphenating a word), adjust the line to reach that margin (if necessary) by widening spaces between words, and output the result.

In fact, we know full well today that it is futile to
speak of liberty as long as economic slavery exists.
(Kropotkin)
  ⇒ In  fact,  we know full well today that it
  ⇒ is futile to speak of liberty as  long  as
  ⇒ economic slavery exists.  (Kropotkin)

Sometimes a new output line should start even though the current line is not yet full—for example, at the end of a paragraph. GNU troff will do this for us automatically at the end of input, but we often want a break sooner, and more frequently. We wish to instruct the formatter.

To that end, not all input lines are text lines containing words to be formatted. Control lines start with a dot (‘.’) or an apostrophe (‘'’) as the first character, and are followed by a request or macro name that tells a macro package (or GNU troff directly) how to format the text.

We can command a break with the br request. Some requests cause a break automatically, as do (normally) blank input lines and input lines beginning with a space or tab.

A macro bundles text and/or control lines into a named collection that can be called like a request. A macro can also be called by a trap that is set to “go off” automatically at certain places on the page. Thus, while requests perform primitive operations, macros handle complex ones, like arranging the output into columns, collecting and writing out footnotes, or managing page headers and footers.

Many requests and macros accept arguments that influence their behavior. A “plain” sp request breaks and puts a blank line on the output. But

.sp 4

spaces four lines instead. Spaces (but not tabs) separate arguments from the request or macro name and from each other.

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, when filling, GNU troff packs words onto longer lines anyhow.
• Second, it is helpful to begin a new line after every sentence, comma, semicolon, or colon, since common revisions are to add, delete, or replace sentences, clauses, phrases, or members of lists.
• If you don’t start a sentence on a new line, put two spaces after the previous sentence. GNU troff then recognizes punctuation that ends a sentence, and inserts inter-sentence space accordingly.

We offer further advice in Input Conventions.

Vertical spacing is the distance between lines of text; it 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 its layout. 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, discourage explicit use of these requests altogether.

Arguments to requests and macro calls can often be measurements rather than simple integers. For instance,

.sp 1.5i
My thoughts on the subject
.sp

outputs one and a half inches of vertical space, followed by the line “My thoughts on the subject”, followed by a single blank line (more measurement units are available; see Measurements). Excess vertical space is normally discarded at page or column breaks. If the above example appears one inch from the bottom of the page, the half inch of space “left over” does not appear at the top of the next.

If you desire precise spacing control when using a macro package, be advised 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. See Manipulating Spacing. Use the facilities the package offers to control spacing between paragraphs, before section headings, and around displays (discussed below).

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, try the following technique.

.ce 1000
up to one thousand lines of input
.ce 0

The ‘.ce 0’ request tells GNU troff to center zero more text lines—in other words, to 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.

All of these requests cause a break, starting a new line. 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.

Some macro packages (“major” or “full-service”) assume responsibility for page layout and other critical functions; others (“supplemental” or “auxiliary”) do not.

We present several capabilities of full-service macro packages below. Each package employs its own macro names to exercise them. For details, consult the package’s man page or, for ms, see ms.

3.2.1 Paragraphs

Paragraphs can be formatted in various ways. Some indent their first line. Block paragraphs like the following example omit this indentation, and must be separated with vertical space for readability. Separation can be configured for other paragraph types as well.

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

We also frequently encounter tagged paragraphs, which begin with a label, or tag, at the left margin, and indent the remaining text.

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

If the tag is too wide for the indentation amount, the line is broken.

  ⇒ longlabel
  ⇒      The  long  tag  does  not  align  with subsequent
  ⇒      lines, but those lines align with each other.

A variation of the tagged paragraph is the itemized or enumerated paragraph, which might use punctuation or a digit for a tag, respectively. These are frequently used to construct lists.

  ⇒ *    This list item starts with a bullet.  If a bullet
  ⇒      glyph  is unavailable, groff produces an asterisk
  ⇒      instead.

Often, use of the same macro without a tag continues such a discussion.

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

3.2.2 Sections and Chapters

A simple kind of section heading is unnumbered, set in a bold or italic style, and occupies a line by itself. Others possess automatically numbered multi-level headings and/or different typeface styles or sizes at different levels. More sophisticated macro packages supply macros for designating chapters and appendices, and permit run-in headings, where there is no break between the end of the heading text and the start of the subsequent paragraph.

3.2.3 Headers and Footers

Headers and footers occupy the top and bottom of each page, respectively, and contain data like the page number and the article or chapter title. Their appearance is not affected by the running text. Some packages allow for different titles on even- and odd-numbered pages (for printed, bound material).

Headers and footers are together called titles, and comprise three parts: left-aligned, centered, and right-aligned. A ‘%’ character appearing anywhere in a title is automatically replaced by the page number. See Page Layout.

3.2.4 Page Layout

Most macro packages let the user specify the size of the page margins. The top and bottom margins are typically handled differently than the left and right margins; the latter are derived from the page offset, indentation, and line length. See Line Layout. Commonly, packages support registers to tune these values.

3.2.5 Displays and Keeps

Displays are sections of text set off from the surrounding material (typically paragraphs), often differing in indentation and/or spacing. Tables, block quotations, and figures are displayed. Equations and code examples, when not much shorter than an output line, often are. Lists may or may not be.

A keep is a group of output lines, often a display, that is formatted on a single page if possible; it causes a page break to happen early if necessary to not interrupt the kept material. Packages for setting man pages support example displays but not keeps.

Floating keeps can move, or “float”, relative to the text around them in the input. They are useful for displays that are captioned and referred to by name, as with “See figure 3”. A floating keep might appear at the bottom of the current page if it fits, and at the top of the next otherwise. Alternatively, it might be deferred to the end of a section. Use of a floating keep can prevent a large vertical space from appearing before a tall keep of the ordinary sort when it won’t fit on the page.

3.2.6 Footnotes and Endnotes

Footnotes and endnotes are forms of delayed formatting. They are recorded at their points of relevance in the input, but not formatted there. Instead, a mark cues the reader to check the “foot”, or bottom, of the current page, or in the case of endnotes, an annotation list later in the document. Macro packages that support these features also supply a means of automatically numbering either type of annotation.

3.2.7 Table of Contents

A package may handle a table of contents by directing section heading macros to save the heading’s text and the page number where it occurs for use in a later entry for a table of contents. It writes the collected entries at the end of the document, once all are known, upon request. A leader, a row of dots, bridges the text on the left with its location on the right. Other collections might work in this manner, providing lists of figures or tables.

A table of contents is often found at the end of a GNU troff document because the formatter processes the document in a single pass. The gropdf output driver supports a PDF feature that relocates pages at the time the document is rendered; see gropdf(1).

3.2.8 Indexing

An index is similar to a table of contents, in that entry labels and locations must be collected, but poses a greater challenge because it needs to be sorted before it is output. Here, processing the document in multiple passes is inescapable, and tools like the makeindex(1) program become necessary.

3.2.9 Document Formats

Some macro packages supply stock configurations of certain types of documents, like business letters and memoranda. These often also have provision for a cover sheet, which may be rigid in its format. With these features, it is even more important to use the package’s macros in preference to the formatter requests presented earlier, where possible.

3.2.10 Columnation

Macro packages apart from man and mdoc for man page formatting offer a facility for setting multiple text columns on the page.

3.2.11 Font and Size Changes

The formatter’s requests and escape sequences for setting the typeface and size are not always intuitive in their behavior, so all full-service packages provide macros to simplify input of these operations. They can also make mid-word font style changes more convenient, and can handle italic corrections automatically. See Italic Corrections.

3.2.12 Predefined Text

Most macro packages supply predefined strings to set computed text like the date, or to perform operations like super- and subscripting.

3.2.13 Preprocessor Support

All macro packages provide support for various preprocessors and may extend their functionality by defining macros to caption their output and/or set it in a display. Examples include TS and TE for gtbl, EQ and EN for geqn, and PS and PE for gpic. Another preprocessor, grefer, facilitates the inclusion of bibliographic citations in a consistent format.

3.2.14 Configuration and Customization

Each package provides means of customizing details of its behavior. Often, this is achieved with register and string definitions. Such parameters include the default type size and the appearance of section headings.

4 Macro Packages

This chapter surveys the “major” macro packages that come with groff. One, ms, is presented in detail.

Major macro packages are also sometimes described as full-service due to the breadth of features they provide and because more than one cannot be used by the same document; for example

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

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

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

Many auxiliary, or supplemental, macro packages are also available. They may in general be used with any full-service macro package and handle a variety of tasks from character encoding selection, to language localization, to inlining of raster images. See groff_tmac(5) for a list.

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

4.1.1 Optional man extensions

Use the file man.local to configure its rendering parameters on a persistent basis. With care, its macros can be redefined there (except for TH, to which one should, at most, append with the am family of requests).

Custom headers and footers

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

Macro: .PT

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

Macro: .BT

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

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

Ultrix-specific man macros

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

Macro: .CT key

Print ‘<CTRL/key>’.

Macro: .CW

Print subsequent text using a “constant-width” (monospaced) typeface (Courier roman).

Macro: .Ds

Begin a non-filled display.

Macro: .De

End a non-filled display started with Ds.

Macro: .EX [indent]

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

Macro: .EE

End a non-filled display started with EX.

Macro: .G [text]

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

Macro: .GL [text]

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

Macro: .HB [text]

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

Macro: .TB [text]

Identical to HB.

Macro: .MS title sect [punct]

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

Macro: .NT [C] [title]

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

Macro: .NE

End a note begun with NT.

Macro: .PN path [punct]

Set the path name in a monospaced typeface (Courier roman), followed by optional punctuation.

Macro: .Pn [punct] path [punct]

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

Macro: .R

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

Macro: .RN

Print the string ‘<RETURN>’.

Macro: .VS [4]

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

Macro: .VE

End printing the change bar begun by VS.

Simple example

The following example man.local file alters the behavior of the SH macro.

.\" Make the heading font Helvetica bold.
.ds HF HB
.
.\" Add vertical space prior to headings on typesetters.
.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 groff_mdoc(7).

Use the file mdoc.local to configure its rendering parameters on a persistent basis. With care, its macros can be redefined there (except for Dd, to which one should, at most, append with the am family of requests).

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. groff_me(7) identifies the installation path for these documents.

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

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

4.5 mom

The mom package’s primary documentation is in HTML. Model documents illustrating many features are offered in PDF. 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

Use the ms (“manuscript”) package to compose 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 consistently formatted bibliographic citations. groff ms is mostly compatible with the documented interface and behavior of AT&T Unix Version 7 ms. It recreates most extensions from 4.2BSD (Berkeley) and Research Tenth Edition Unix.

4.6.1 Introduction

The ms macros are the oldest surviving package for roff systems.¹² Whereas man suits brief references, ms can handle long or complex works intended for printing and possible publication.

Macro, register, and string descriptions frequently mention each other; most references are to macros. Where a register or string is referenced, we annotate its type. ms’s identifiers use only capital letters, numerals, and ‘-’.

4.6.1.1 Basic information

Prepare an ms document with your preferred text editor. Call an ms macro early in the document to initialize the package. A macro is a formatting instruction to ms. Put a macro call on a line by itself with a dot before its name. Use ‘.PP’ if you want your paragraph’s first line indented, or ‘.LP’ if you don’t. Then type text normally. It is a good practice to start each sentence on a new line, or to put two spaces after sentence-ending punctuation, so that the formatter knows where the sentence boundaries are. You can separate paragraphs with further paragraphing macros, or with blank lines, and you can indent with tabs. When you need one of the features mentioned earlier (see ms), return to this subsection.

Format the document with the groff command. nroff can be useful for previewing.

$ editor radical.ms # vim, emacs, nano, …
$ 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 # or your favorite PDF viewer

Our radical.ms document might look like this.

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

ms exposes many aspects of document layout to user control via groff’s registers and strings, which store numbers and text, respectively. Measurements in groff are expressed with a suffix called a scaling unit.

i

inches

c

centimeters

p

points (1/72 inch)

P

picas (1/6 inch)

v

vees; current vertical spacing

m

ems; width of an “M” in the current font

n

ens; one-half em (same as m on terminals)

Set registers with the nr request and strings with the ds request. Requests are like macro calls; they go on lines by themselves and start with the control character, a dot (.). The difference is that they directly instruct the formatter program, rather than the macro package. We’ll discuss a few as applicable. It is wise to specify a scaling unit when setting any register that represents a length, size, or distance.

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

In the foregoing, we see that \" begins a comment. This is an example of an escape sequence, the other kind of formatting instruction. Escape sequences can appear almost anywhere. They begin with the escape character (\) and are followed by at least one more character. ms documents tend to use only a few of groff’s many requests and escape sequences; see Request Index and Escape Sequence Index or the groff(7) man page for complete lists.

\"

Begin comment; ignore remainder of line.

\n[reg]

Interpolate value of register reg.

\nr

abbreviation of \n[r]; the name r must be only one character

\*[str]

Interpolate contents of string str.

\*s

abbreviation of \*[s]; the name s must be only one character

\[char]

Interpolate glyph of special character named char.

\&

dummy character

\~

Insert an unbreakable space that is adjustable like a normal space.

\|

Move horizontally by one-sixth em (“thin space”).

Prefix any words that start with a dot ‘.’ or neutral apostrophe ‘'’ with \& if they are at the beginning of an input line (or might become that way in editing) to prevent them from being interpreted as macro calls or requests. Suffix ‘.’, ‘?’, and ‘!’ with \& when needed to cancel end-of-sentence detection.

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

4.6.2 Document Structure

The ms macro package expects a certain amount of structure: a well-formed document contains at least one paragraphing or heading macro call. Organize longer documents as follows.

Document type

Calling the RP macro at the beginning of your document puts the document description (see below) on a cover page. Otherwise, ms places the information (if any) on the first page, followed immediately by the body text. Some document types found in other ms implementations are specific to AT&T or Berkeley, and are not supported by groff ms.

Format and layout

By setting registers and strings, you can configure your document’s typeface, margins, spacing, headers and footers, and footnote arrangement. See ms Document Control Settings.

Document description

A document description consists of any of: a title, one or more authors’ names and affiliated institutions, an abstract, and a date or other identifier. See ms Document Description Macros.

Body text

The main matter of your document follows its description (if any). ms supports highly structured text consisting of paragraphs interspersed with multi-level headings (chapters, sections, subsections, and so forth) and augmented by lists, footnotes, tables, diagrams, and similar material. See ms Body Text.

Tables of contents

Macros enable the collection of entries for a table of contents (or index) as the material they discuss appears in the document. A macro call at the end of the document emits the collected entries. This material necessarily follows the rest of the text since troff is a single-pass formatter; it cannot determine the page number of a division of the text until it has been set and output. Since ms output was designed for the production of hard copy, the traditional procedure was to manually relocate the pages containing the table of contents between the cover page and the body text. Today, page resequencing is more often done in the digital domain. An index works similarly, but because it typically needs to be sorted after collection, its preparation requires separate processing.

4.6.3 Document Control Settings

ms exposes many aspects of document layout to user control via groff requests. To use them, you must understand how to define registers and strings.

Request: .nr reg value

Set register reg to value.

Request: .ds name contents

Set string name to contents.

A list of document control registers and strings follows. For any parameter whose default is unsatisfactory, define its register or string before calling any ms macro other than RP.

Margin settings

Register: \n[PO]

Defines the page offset (i.e., the left margin).

Effective: next page.

Default: Varies by output device and paper format; 1i is used for typesetters using U.S. letter paper, and zero for terminals. See Paper Format.

Register: \n[LL]

Defines the line length (i.e., the width of the body text).

Effective: next paragraph.

Default: Varies by output device and paper format; 6.5i is used for typesetters using U.S. letter paper (see Paper Format) and 65n on terminals.

Register: \n[LT]

Defines the title line length (i.e., the header and footer width). This is usually the same as LL, but need not be.

Effective: next paragraph.

Default: Varies by output device and paper format; 6.5i is used for typesetters using U.S. letter paper (see Paper Format) and 65n on terminals.

Register: \n[HM]

Defines the header margin height at the top of the page.

Effective: next page.

Default: 1i.

Register: \n[FM]

Defines the footer margin height at the bottom of the page.

Effective: next page.

Default: 1i.

Titles (headers, footers)

String: \*[LH]

Defines the text displayed in the left header position.

Effective: next header.

Default: empty.

String: \*[CH]

Defines the text displayed in the center header position.

Effective: next header.

Default: ‘-\n[%]-’.

String: \*[RH]

Defines the text displayed in the right header position.

Effective: next header.

Default: empty.

String: \*[LF]

Defines the text displayed in the left footer position.

Effective: next footer.

Default: empty.

String: \*[CF]

Defines the text displayed in the center footer position.

Effective: next footer.

Default: empty.

String: \*[RF]

Defines the text displayed in the right footer position.

Effective: next footer.

Default: empty.

Text settings

Register: \n[PS]

Defines the type size of the body text.

Effective: next paragraph.

Default: 10p.

Register: \n[VS]

Defines the vertical spacing (type size plus leading).

Effective: next paragraph.

Default: 12p.

Register: \n[HY]

Defines the automatic hyphenation mode used with the hy request. Setting HY to 0 disables automatic hyphenation. This is a Research Tenth Edition Unix extension.

Effective: next paragraph.

Default: 6.

String: \*[FAM]

Defines the font family used to typeset the document. This is a GNU extension.

Effective: next paragraph.

Default: defined by the output device; often ‘T’ (see ms Body Text)

Paragraph settings

Register: \n[PI]

Defines the indentation amount used by the PP, IP (unless overridden by an optional argument), XP, and RS macros.

Effective: next paragraph.

Default: 5n.

Register: \n[PD]

Defines the space between paragraphs.

Effective: next paragraph.

Default: 0.3v (1v on low-resolution devices).

Register: \n[QI]

Defines the indentation amount used on both sides of a paragraph set with the QP or between the QS and QE macros.

Effective: next paragraph.

Default: 5n.

Register: \n[PORPHANS]

Defines the minimum number of initial lines of any paragraph that must be kept together to avoid isolated lines at the bottom of a page. If a new paragraph is started close to the bottom of a page, and there is insufficient space to accommodate PORPHANS groff ms forces a page break before formatting the paragraph. This is a GNU extension.

Effective: next paragraph.

Default: 1.

Heading settings

Register: \n[PSINCR]

Defines an increment in type size to be applied to a heading at a lesser depth than that specified in GROWPS. The value of PSINCR should be specified in points with the p scaling unit and may include a fractional component; for example, ‘.nr PSINCR 1.5p’ sets a type size increment of 1.5p. This is a GNU extension.

Effective: next heading.

Default: 1p.

Register: \n[GROWPS]

Defines the heading depth above which the type size increment set by PSINCR becomes effective. For each heading depth less than the value of GROWPS, the type size is increased by PSINCR. Setting GROWPS to any value less than 2 disables the incremental heading size feature. This is a GNU extension.

Effective: next heading.

Default: 0.

Register: \n[HORPHANS]

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

Effective: next paragraph.

Default: 1.

String: \*[SN-STYLE]

Defines the style used to print numbered headings. See Headings in ms. This is a GNU extension.

Effective: next heading.

Default: alias of SN-DOT

Footnote settings

Register: \n[FI]

Defines the footnote indentation. This is a Berkeley extension.

Effective: next footnote.

Default: 2n.

Register: \n[FF]

Defines the format of automatically numbered footnotes, and those for which the FS request is given a mark argument, at the bottom of a column or page. This is a Berkeley extension.

0

Set an automatic number¹³ as a superscript (on typesetters) or surrounded by square brackets (on terminals). The footnote paragraph is indented as with PP if there is an FS argument or an automatic number, and as with LP otherwise. This is the default.

1

As 0, but set mark as regular text, and follow an automatic number with a period.

2

As 1, but without indentation (like LP).

3

As 1, but set the footnote paragraph with mark hanging (like IP).

Effective: next footnote.

Default: 0.

Register: \n[FPS]

Defines the footnote type size.

Effective: next footnote.

Default: \n[PS] - 2p.

Register: \n[FVS]

Defines the footnote vertical spacing.

Effective: next footnote.

Default: \n[FPS] + 2p.

Register: \n[FPD]

Defines the footnote paragraph spacing. This is a GNU extension.

Effective: next footnote.

Default: \n[PD] / 2.

String: \*[FR]

Defines the ratio of the footnote line length to the current line length. This is a GNU extension.

Effective: next footnote if single-column layout, next page otherwise.

Default: 11/12.

Display settings

Register: \n[DD]

Sets the display distance—the vertical spacing before and after a display, a tbl table, an eqn equation, or a pic image. This is a Berkeley extension.

Effective: next display boundary.

Default: 0.5v (1v on low-resolution devices).

Register: \n[DI]

Sets the default amount by which to indent a display started with DS and ID without arguments, to ‘.DS I’ without an indentation argument, and to equations set with ‘.EQ I’. This is a GNU extension.

Effective: next indented display.

Default: 0.5i.

Other settings

Register: \n[MINGW]

Defines the default minimum width between columns in a multi-column document. This is a GNU extension.

Effective: next page.

Default: 2n.

Register: \n[TC-MARGIN]

Defines the width of the field in which page numbers are set in a table of contents entry; the right margin thus moves inboard by this amount. This is a GNU extension.

Effective: next PX call.

Default: \w'000'

4.6.4 Document Description Macros

Only the simplest document lacks a title.¹⁴ As its level of sophistication (or complexity) increases, it tends to acquire a date of revision, explicitly identified authors, sponsoring institutions for authors, and, at the rarefied heights, an abstract of its content. Define these data by calling the macros below in the order shown; DA or ND can be called to set the document date (or other identifier) at any time before (a) the abstract, if present, or (b) its information is required in a header or footer. Use of these macros is optional, except that TL is mandatory if any of RP, AU, AI, or AB is called, and AE is mandatory if AB is called.

Macro: .RP [no-repeat-info] [no-renumber]

Use the “report” (AT&T: “released paper”) format for your document, creating a separate cover page. The default arrangement is to place most of the document description (title, author names and institutions, and abstract, but not the date) at the top of the first page. If the optional no-repeat-info argument is given, ms produces a cover page but does not repeat any of its information subsequently (but see the DA macro below regarding the date). Normally, RP sets the page number following the cover page to 1. Specifying the optional no-renumber argument suppresses this alteration. Optional arguments can occur in any order. ms recognizes no as a synonym of no-repeat-info to maintain AT&T compatibility. Options other than no are GNU extensions.

Macro: .TL

Specify the document title. ms collects text on input lines following this call into the title until reaching AU, AB, or a heading or paragraphing macro call.

Macro: .AU

Specify an author’s name. ms collects text on input lines following this call into the author’s name until reaching AI, AB, another AU, or a heading or paragraphing macro call. Call it repeatedly to specify multiple authors.

Macro: .AI

Specify the preceding author’s institutional affiliation. An AU call is usefully followed by at most one AI call; if there are more, the last AI call controls. ms collects text on input lines following this call into the author’s institution until reaching AU, AB, or a heading or paragraphing macro call.

Macro: .DA [x …]

Typeset the current date, or any arguments x, in the center footer, and, if RP is also called, left-aligned at the end of the description information on the cover page.

Macro: .ND [x …]

Typeset the current date, or any arguments x, if RP is also called, left-aligned at the end of the document description on the cover page. This is groff ms’s default.

Macro: .AB [no]

Begin the abstract. ms collects text on input lines following this call into the abstract until reaching an AE call. By default, ms places the word “ABSTRACT” centered and in italics above the text of the abstract. The optional argument no suppresses this heading.

Macro: .AE

End the abstract.

An example document description, using a cover page, follows.

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

4.6.5 Body Text

A variety of macros, registers, and strings can be used to structure and style the body of your document. They organize your text into paragraphs, headings, footnotes, and inclusions of material such as tables and figures.

4.6.5.1 Text settings

The FAM string, a GNU extension, sets the font family for body text; the default is ‘T’. The PS and VS registers set the type size and vertical spacing (distance between text baselines), respectively. The font family and type size are ignored on terminals. Set these parameters before the first call of a heading, paragraphing, or (non-date) document description macro to apply them to headers, footers, and (for FAM) footnotes.

Which font families are available depends on the output device; as a convention, T selects a serif family (“Times”), H a sans-serif family (“Helvetica”), and C a monospaced family (“Courier”). The man page for the output driver documents its font repertoire. Consult the groff(1) man page for lists of available output devices and their drivers.

The hyphenation mode (as used by the hy request) is set from the HY register. Setting HY to ‘0’ is equivalent to using the nh request. This is a Research Tenth Edition Unix extension.

4.6.5.2 Typographical symbols

ms provides a few strings to obtain typographical symbols not easily entered with the keyboard. These and many others are available as special character escape sequences—see the groff_char(7) man page.

String: \*[-]

Interpolate an em dash.

String: \*[Q]

String: \*[U]

Interpolate typographer’s quotation marks where available, and neutral double quotes otherwise. \*Q is the left quote and \*U the right.

4.6.5.3 Paragraphs

Paragraphing macros break, or terminate, any pending output line so that a new paragraph can begin. Several paragraph types are available, differing in how indentation applies to them: to left, right, or both margins; to the first output line of the paragraph, all output lines, or all but the first. These calls insert vertical space in the amount stored in the PD register, except at page or column breaks. Alternatively, a blank input line breaks the output line and vertically spaces by one vee.

Macro: .LP

Set a paragraph without any (additional) indentation.

Macro: .PP

Set a paragraph with a first-line left indentation in the amount stored in the PI register.

Macro: .IP [mark [width]]

Set a paragraph with a left indentation. The optional mark is not indented and is empty by default. It has several applications; see Lists in ms. width overrides the indentation amount stored in the PI register; its default unit is ‘n’. Once specified, width applies to further IP calls until specified again or a heading or different paragraphing macro is called.

Macro: .QP

Set a paragraph indented from both left and right margins by the amount stored in the QI register.

Macro: .QS

Macro: .QE

Begin (QS) and end (QE) a region where each paragraph is indented from both margins by the amount stored in the QI register. The text between QS and QE can be structured further by use of other paragraphing macros.

Macro: .XP

Set an “exdented” paragraph—one with a left indentation in the amount stored in the PI register on every line except the first (also known as a hanging indent). This is a Berkeley extension.

The following example illustrates the use of paragraphing macros.

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

4.6.5.4 Headings

Use headings to create a sequential or hierarchical structure for your document. The ms macros print headings in bold using the same font family and, by default, type size as the body text. Headings are available with and without automatic numbering. Text on input lines following the macro call becomes the heading’s title. Call a paragraphing macro to end the heading text and start the section’s content.

Macro: .NH [depth]

Macro: .NH S heading-depth-index …

Set an automatically numbered heading.

ms produces a numbered heading the form a.b.c…, to any depth desired, with the numbering of each depth increasing automatically and being reset to zero when a more significant level is increased. “1” is the most significant or coarsest division of the document. Only non-zero values are output. If depth is omitted, ms assumes ‘1’.

If you specify depth such that an ascending gap occurs relative to the previous NH call—that is, you “skip a depth”, as by ‘.NH 1’ and then ‘.NH 3’—groff ms emits a warning on the standard error stream.

Alternatively, you can give NH a first argument of S, followed by integers to number the heading depths explicitly. Further automatic numbering, if used, resumes using the specified indices as their predecessors. This feature is a Berkeley extension.

An example may be illustrative.

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

The above results in numbering as follows; the vertical space that normally precedes each heading is omitted.

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

String: \*[SN-STYLE]

String: \*[SN-DOT]

String: \*[SN-NO-DOT]

String: \*[SN]

After NH is called, the assigned number is made available in the strings SN-DOT (as it appears in a printed heading with default formatting, followed by a terminating period) and SN-NO-DOT (with the terminating period omitted). These (and SN-STYLE) are GNU extensions.

You can control the style used to print numbered headings by defining an appropriate alias for the string SN-STYLE. By default, SN-STYLE is aliased to SN-DOT. If you prefer to omit the terminating period from numbers appearing in numbered headings, you may define the alias as follows.

.als SN-STYLE SN-NO-DOT

Any such change in numbering style becomes effective from the next use of NH following redefinition of the alias for SN-STYLE. The formatted number of the current heading is available in the SN string (a feature first documented by Berkeley), which facilitates its inclusion in, for example, table captions, equation labels, and XS/XA/XE table of contents entries.

Macro: .SH [depth]

Set an unnumbered heading.

The optional depth argument is a GNU extension indicating the heading depth corresponding to the depth argument of NH. It matches the type size at which the heading is set to that of a numbered heading at the same depth when the GROWPS and PSINCR heading size adjustment mechanism is in effect.

If the GROWPS register is set to a value greater than the level argument to NH or SH, the type size of a heading produced by these macros increases by PSINCR units over the size specified by PS multiplied by the difference of GROWPS and level. The value stored in PSINCR is interpreted in groff basic units; the p scaling unit should be employed when assigning a value specified in points.

The input

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

causes “1. Carnivora” to be printed in 13-point type, followed by “1.1. Felinae” in 11.5-point type, while “1.1.1. Felis catus” and all more deeply nested heading levels remains in the 10-point type specified by the PS register. “Machairodontinae” is printed at 11.5 points, since it corresponds to heading level 2.

In groff ms, the NH and SH macros consult the HORPHANS register to prevent the output of isolated headings at the bottom of a page; it specifies the minimum number of lines of an immediately subsequent paragraph that must be kept on the same page as the heading. If insufficient space remains on the current page to accommodate the heading and this number of lines of paragraph text, groff ms forces a page break before setting the heading. Any display macro call or tbl, pic, or eqn region between the heading and the subsequent paragraph suppresses this grouping. See ms keeps and displays and ms Insertions.

4.6.5.5 Typeface and decoration

The ms macros provide a variety of ways to style text. Attend closely to the ordering of arguments labeled pre and post, which is not intuitive. Support for pre arguments is a GNU extension.¹⁵

Macro: .B [text [post [pre]]]

Style text in bold, followed by post in the previous font style without intervening space, and preceded by pre similarly. Without arguments, ms styles subsequent text in bold until the next paragraphing, heading, or no-argument typeface macro call.

Macro: .R [text [post [pre]]]

As B, but use the roman style (upright text of normal weight) instead of bold. Argument recognition is a GNU extension.

Macro: .I [text [post [pre]]]

As B, but use an italic or oblique style instead of bold.

Macro: .BI [text [post [pre]]]

As B, but use a bold italic or bold oblique style instead of upright bold. This is a Research Tenth Edition Unix extension.

Macro: .CW [text [post [pre]]]

As B, but use a constant-width (monospaced) roman typeface instead of bold. This is a Research Tenth Edition Unix extension.

Macro: .BX [text]

Typeset text and draw a box around it. On terminals, reverse video or another means of highlighting is used instead. If you want text to contain space, use unbreakable space or horizontal motion escape sequences (\~, \SPC, \^, \|, \0 or \h).

Macro: .UL [text [post]]

Typeset text with an underline. On terminals, text is bracketed with underscores ‘_’. post, if present, is set after text with no intervening space.

Macro: .LG

Set subsequent text in larger type (two points larger than the current size) until the next type size, paragraphing, or heading macro call. Call the macro multiple times to enlarge the type size further.

Macro: .SM

Set subsequent text in smaller type (two points smaller than the current size) until the next type size, paragraphing, or heading macro call. Call the macro multiple times to reduce the type size further.

Macro: .NL

Set subsequent text at the normal type size (the amount in register PS).

pre and post arguments are typically used to simplify the attachment of punctuation to styled words. When pre is used, a hyphenation control escape sequence \% that would ordinarily start text must start pre instead to have the desired effect.

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

The foregoing example produces output as follows.

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

You can use the output line continuation escape sequence \c to achieve the same result (see Line Continuation). It is also portable to older ms implementations.

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

groff ms also offers strings to begin and end super- and subscripting. These are GNU extensions.

String: \*[{]

String: \*[}]

Begin and end superscripting, respectively.

String: \*[<]

String: \*[>]

Begin and end subscripting, respectively.

Rather than calling the CW macro, in groff ms you might prefer to change the font family to Courier by setting the FAM string to ‘C’. You can then use all four style macros above, returning to the default family (Times) with ‘.ds FAM T’. Because changes to FAM take effect only at the next paragraph, CW remains useful to “inline” a change to the font family, similarly to the practice of this document in noting syntactical elements of ms and groff.

4.6.5.6 Lists

The mark argument to the IP macro can be employed to present a variety of lists; for instance, you can use a bullet glyph (\[bu]) for unordered lists, a number (or auto-incrementing register) for numbered lists, or a word or phrase for glossary-style or definition lists. If you set the paragraph indentation register PI before calling IP, you can later reorder the items in the list without having to ensure that a width argument remains affixed to the first call.

The following is an example of a bulleted list.

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

A bulleted list:

• lawyers

• guns

• money

The following is an example of a numbered list.

.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

Here we have employed the nr request to create a register of our own, ‘step’. We initialized it to zero and assigned it an auto-increment of 1. Each time we use the escape sequence ‘\n+[step]’ (note the plus sign), the formatter applies the increment just before interpolating the register’s value. Preparing the PI register as well enables us to rearrange the list without the tedium of updating macro calls.

The next example illustrates a glossary-style list.

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

A glossary-style list:

lawyers
      Two or more attorneys.

guns  Firearms, preferably large-caliber.

money
      Gotta pay for those lawyers and guns!

In the previous example, observe how the IP macro places the definition on the same line as the term if it has enough space. If this is not what you want, there are a few workarounds we illustrate by modifying the example. First, you can use a br request to force a break after printing the term or label.

.IP guns
.br
Firearms,

Second, you could apply the \p escape sequence to force a break. The space following the escape sequence is important; if you omit it, groff prints the first word of the paragraph text on the same line as the term or label (if it fits) then breaks the line.

.IP guns
\p Firearms,

Finally, you may append a horizontal motion to the mark with the \h escape sequence; using the same amount as the indentation ensures that the mark is too wide for groff to treat it as “fitting” on the same line as the paragraph text.

.IP guns\h'0.4i'
Firearms,

In each case, the result is the same.

A glossary-style list:

lawyers
      Two or more attorneys.

guns
      Firearms, preferably large-caliber.

money
      Gotta pay for those lawyers and guns!

4.6.5.7 Indented regions

You can indent a region of text while otherwise formatting it normally. Such indented regions can be nested; change \n[PI] before each call to vary the amount of inset.

Macro: .RS

Begin a region where headings, paragraphs, and displays are indented (further) by the amount stored in the PI register.

Macro: .RE

End the (next) most recent indented region.

This feature enables you to easily line up text under hanging and indented paragraphs. For example, you may wish to structure lists hierarchically.

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

• Lawyers:

  •  Dewey,

  •  Cheatham, and

  •  Howe.

• Guns

4.6.5.8 Keeps, boxed keeps, and displays

On occasion, you may want to keep several lines of text, or a region of a document, together on a single page, preventing an automatic page break within certain boundaries. This can cause a page break to occur earlier than it normally would. For example, you may want to keep two paragraphs together, or a paragraph that refers to a table, list, or figure adjacent to the item it discusses. ms provides the KS and KE macros for this purpose.

You can alternatively specify a floating keep: if a keep cannot fit on the current page, ms holds it, allowing material following the keep (in the source document) to fill the remainder of the current page. When the page breaks by reaching its bottom or by bp request, ms puts the floating keep at the beginning of the next page. Use floating keeps to house large graphics or tables that do not need to appear exactly where they occur in the source document.

Macro: .KS

Macro: .KF

Macro: .KE

KS begins a keep, KF a floating keep, and KE ends a keep of either kind.

As an alternative to the keep mechanism, the ne request forces a page break if there is not at least the amount of vertical space specified in its argument remaining on the page (see Page Control). One application of ne is to reserve space on the page for a figure or illustration to be included later.

A boxed keep has a frame drawn around it.

Macro: .B1

Macro: .B2

B1 begins a keep with a box drawn around it. B2 ends a boxed keep.

Boxed keep macros cause breaks; to box words within a line, recall BX in Typeface and decoration. ms draws box lines close to the text they enclose so that they are usable within paragraphs. When boxing entire paragraphs thus, you may improve their appearance by calling B1 after the first paragraphing macro, and invoking the sp request before calling B2.

.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

If you want a boxed keep to float, enclose the B1 and B2 calls within a pair of KF and KE calls.

Displays turn off filling; lines of verse or program code are shown with their lines broken as in the source document without requiring br requests between lines. Displays can be kept on a single page or allowed to break across pages. The DS macro begins a kept display of the layout specified in its first argument; non-kept displays are begun with dedicated macros corresponding to their layout.

Macro: .DS L

Macro: .LD

Begin (DS: kept) left-aligned display.

Macro: .DS [I [indent]]

Macro: .ID [indent]

Begin (DS: kept) display indented by indent if specified, and by the amount of the DI register otherwise.

Macro: .DS B

Macro: .BD

Begin a (DS: kept) a block display: the entire display is left-aligned, but indented such that the longest line in the display is centered on the page.

Macro: .DS C

Macro: .CD

Begin a (DS: kept) centered display: each line in the display is centered.

Macro: .DS R

Macro: .RD

Begin a (DS: kept) right-aligned display. This is a GNU extension.

Macro: .DE

End any display.

groff ms inserts the distance stored in the DD register before and after each pair of display macros; this is a Berkeley extension. This distance replaces any adjacent inter-paragraph distance or subsequent spacing prior to a section heading. The DI register is a GNU extension; its value is an indentation applied to displays created with ‘.DS’ and ‘.ID’ without arguments, to ‘.DS I’ without an indentation argument, and to indented equations set with ‘.EQ’. Changes to either register take effect at the next display boundary.

The display distance applies even in footnotes (discussed below), which may cause a footnote with a display at its end to “emptily” spill to the next page. Consider the following tactic to compensate.

.FS
Recall the ideal gas law.
.nr DD-saved \n[DD] \" stash display distance
.nr DD 0       \" eliminate automatic space around display
.sp \n[DD-saved]u   \" manually put space before it
.EQ
P V = n R T
.EN
.FE
.nr DD \n[DD-saved] \" restore previous setting

4.6.5.9 Tables, figures, equations, and references

ms often sees use with the tbl, pic, eqn, and refer preprocessors. Mark text meant for preprocessors by enclosing it in pairs of tokens as follows, with nothing between the dot and the macro name. Preprocessors match these tokens only at the start of an input line. The formatter interprets them as macro calls.

Macro: .TS [H]

Macro: .TE

Demarcate a table to be processed by the tbl preprocessor. The optional argument H to TS instructs ms to repeat table rows (often column headings) at the top of each new page the table spans, if applicable; calling the TH macro marks the end of such rows. The GNU tbl(1) man page provides a comprehensive reference to the preprocessor and offers examples of its use.

Macro: .PS h v

Macro: .PE

Macro: .PF

PS begins a picture to be processed by the gpic preprocessor; either of PE or PF ends it, the latter with “flyback” to the vertical position at its top. Create pic input manually or with a program such as xfig. h and v are the horizontal and vertical dimensions of the picture; gpic supplies them automatically.

Macro: .EQ [align [label]]

Macro: .EN

Demarcate an equation to be processed by the eqn preprocessor. The equation is centered by default; align can be ‘C’, ‘L’, or ‘I’ to (explicitly) center, left-align, or indent it by the amount stored in the DI register, respectively. If specified, label is set right-aligned.

Macro: .[

Macro: .]

Demarcate a bibliographic citation to be processed by the refer preprocessor. grefer(1) provides a comprehensive reference to the preprocessor and the format of its bibliographic database.

When refer emits collected references (as might be done on a “Works Cited” page), it interpolates the REFERENCES string as an unnumbered heading (SH).

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

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

Attempting to place a multi-page table inside a keep can lead to unpleasant results, particularly if the tbl allbox option is used.

Mathematics can be typeset using the language of the eqn preprocessor.

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

This input formats a labelled equation. We used the SN-NO-DOT string to base the equation label on the current heading number, giving us more flexibility to reorganize the document.

Create diagrams with gpic.

.PS
circle "input";
arrow;
box width 1.5i "\f[CR]groff -Rept -ms\f[]";
arrow;
circle "output";
.PE

groff options run preprocessors on the input: -e for geqn, -p for gpic, -R for grefer, and -t for gtbl.

4.6.5.10 Footnotes

A footnote is typically anchored to a place in the text with a mark, which is a small integer, a symbol such as a dagger, or arbitrary user-specified text.

String: \*[*]

Place an automatic number, an automatically generated numeric footnote mark, in the text. Each time this string is interpolated, the number it produces increments by one. Automatic numbers start at 1. This is a Berkeley extension.

Enclose the footnote text in FS and FE macro calls to set it at the nearest available “foot”, or bottom, of a text column or page.

Macro: .FS [mark]

Macro: .FE

Begin (FS) and end (FE) a footnote. FS calls FS-MARK with any supplied mark argument, which is then also placed at the beginning of the footnote text. If mark is omitted, the next pending automatic number enqueued by interpolation of the * string is used, and if none exists, nothing is prefixed.

You may not desire automatically numbered footnotes in spite of their convenience. You can indicate a footnote with a symbol or other text by specifying its mark at the appropriate place (for example, by using \[dg] for the dagger glyph) and as an argument to the FS macro. Such manual marks should be repeated as arguments to FS or as part of the footnote text to disambiguate their correspondence. You may wish to use \*{ and \*} to superscript the mark at the anchor point, in the footnote text, or both.

groff ms provides a hook macro, FS-MARK, for user-determined operations to be performed when the FS macro is called. It is passed the same arguments as FS itself. An application of FS-MARK is anchor placement for a hyperlink reference, so that a footnote can link back to its referential context. By default, this macro has an empty definition. FS-MARK is a GNU extension.

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

Footnote text is formatted as paragraphs are, using analogous parameters. The registers FI, FPD, FPS, and FVS correspond to PI, PD, PS, and CS, respectively; FPD, FPS, and FVS are GNU extensions.

The FF register controls the formatting of automatically numbered footnote paragraphs, and those for which FS is given a mark argument, See ms Document Control Settings.

The default footnote line length is 11/12ths of the normal line length for compatibility with the expectations of historical ms documents; you may wish to set the FR string to ‘1’ to align with contemporary typesetting practices. In the past,¹⁶ an FL register was used for the line length in footnotes; however, setting this register at document initialization time had no effect on the footnote line length in multi-column arrangements.¹⁷

Prefer the FR string over the FL register in contemporary documents. The footnote line length is effectively computed as ‘column-width * \*[FR]’. If you require an absolute footnote line length, recall that roff formatters evaluate numeric expressions strictly from left to right, without operator precedence (parentheses are honored).

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

4.6.5.11 Language and localization

groff ms provides several strings that you can customize for your own purposes, or redefine to adapt the macro package to languages other than English. It is already localized for Czech, German, Spanish, French, Italian, Russian, and Swedish. Load the desired localization macro package after ms; see groff_tmac(5).

$ groff -ms -mfr bienvenue.ms

The following strings are available.

String: \*[REFERENCES]

Contains the string printed at the beginning of a references (bibliography) page produced with GNU refer(1). The default is ‘References’.

String: \*[ABSTRACT]

Contains the string printed at the beginning of the abstract. The default is ‘\f[I]ABSTRACT\f[]’; it includes font selection escape sequences to set the word in italics.

String: \*[TOC]

Contains the string printed at the beginning of the table of contents. The default is ‘Table of Contents’.

String: \*[MONTH1]

String: \*[MONTH2]

String: \*[MONTH3]

String: \*[MONTH4]

String: \*[MONTH5]

String: \*[MONTH6]

String: \*[MONTH7]

String: \*[MONTH8]

String: \*[MONTH9]

String: \*[MONTH10]

String: \*[MONTH11]

String: \*[MONTH12]

Contain the full names of the calendar months. The defaults are in English: ‘January’, ‘February’, and so on.

4.6.6 Page layout

ms’s default page layout arranges text in a single column with the page number between hyphens centered in a header on each page except the first, and produces no footers. You can customize this arrangement.

4.6.6.1 Headers and footers

There are multiple ways to produce headers and footers. One is to define the strings LH, CH, and RH to set the left, center, and right headers, respectively; and LF, CF, and RF to set the left, center, and right footers. This approach suffices for documents that do not distinguish odd- and even-numbered pages.

Another method is to call macros that set headers or footers for odd- or even-numbered pages. Each such macro takes a delimited argument separating the left, center, and right header or footer texts from each other. You can replace the neutral apostrophes (') shown below with any character not appearing in the header or footer text. These macros are Berkeley extensions.

Macro: .OH 'left'center'right'

Macro: .EH 'left'center'right'

Macro: .OF 'left'center'right'

Macro: .EF 'left'center'right'

The OH and EH macros define headers for odd- (recto) and even-numbered (verso) pages, respectively; the OF and EF macros define footers for them.

With either method, a percent sign % in header or footer text is replaced by the current page number. By default, ms places no header on a page numbered “1” (regardless of its number format).

Macro: .P1

Typeset the header even on page 1. To be effective, this macro must be called before the header trap is sprung on any page numbered “1”; in practice, unless your page numbering is unusual, this means that you should call it early, before TL or any heading or paragraphing macro. This is a Berkeley extension.

For even greater flexibility, ms is designed to permit the redefinition of the macros that are called when formatter traps that ordinarily cause the headers and footers to be output are sprung. PT (“page trap”) is called by ms when the header is to be written, and BT (“bottom trap”) when the footer is to be. The groff page location trap that ms sets up to format the header also calls the (normally undefined) HD macro after PT; you can define HD if you need additional processing after setting the header (for example, to draw a line below it). The HD hook is a Berkeley extension. Any such macros you (re)define must implement any desired specialization for odd-, even-, or first numbered pages.

4.6.6.2 Tab stops

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

Macro: .TA

Reset the tab stops to the ms default (every 5 ens). Redefine this macro to create a different set of default tab stops.

4.6.6.3 Margins

Control margins using the registers summarized in “Margin settings” in ms Document Control Settings above. There is no setting for the right margin; the combination of page offset \n[PO] and line length \n[LL] determines it.

4.6.6.4 Multiple columns

ms can set text in as many columns as reasonably fit on the page. The following macros force a page break if a multi-column layout is active when they are called. The MINGW register stores the default minimum gutter width; it is a GNU extension. When multiple columns are in use, keeps and the HORPHANS and PORPHANS registers work with respect to column breaks instead of page breaks.

Macro: .1C

Arrange page text in a single column (the default).

Macro: .2C

Arrange page text in two columns.

Macro: .MC [column-width [gutter-width]]

Arrange page text in multiple columns. If you specify no arguments, it is equivalent to the 2C macro. Otherwise, column-width is the width of each column and gutter-width is the minimum distance between columns.

4.6.6.5 Creating a table of contents

Because roff formatters process their input in a single pass, material on page 50, for example, cannot influence what appears on page 1—this poses a challenge for a table of contents at its traditional location in front matter, if you wish to avoid manually maintaining it. ms enables the collection of material to be presented in the table of contents as it appears, saving its page number along with it, and then emitting the collected contents on demand toward the end of the document. The table of contents can then be resequenced to its desired location by physically rearranging the pages of a printed document, or as part of post-processing—with a sed(1) script to reorder the pages in troff’s output, with pdfjam(1), or with gropdf(1)’s pdfswitchtopage macro, for example.

Define an entry to appear in the table of contents by bracketing its text between calls to the XS and XE macros. A typical application is to call them immediately after NH or SH and repeat the heading text within them. The XA macro, used within ‘.XS’/‘.XE’ pairs, supplements an entry—for instance, when it requires multiple output lines, whether because a heading is too long to fit or because style dictates that page numbers not be repeated. You may wish to indent the text thus wrapped to correspond to its heading depth; this can be done in the entry text by prefixing it with tabs or horizontal motion escape sequences, or by providing a second argument to the XA macro. XS and XA automatically associate the page number where they are called with the text following them, but they accept arguments to override this behavior. At the end of the document, call TC or PX to emit the table of contents; TC resets the page number to ‘i’ (Roman numeral one), and then calls PX. All of these macros are Berkeley extensions.

Macro: .XS [page-number]

Macro: .XA [page-number [indentation]]

Macro: .XE

Begin, supplement, and end a table of contents entry. Each entry is associated with page-number (otherwise the current page number); a page-number of ‘no’ prevents a leader and page number from being emitted for that entry. Use of XA within XS/XE is optional; it can be repeated. If indentation is present, a supplemental entry is indented by that amount; ens are assumed if no unit is indicated. Text on input lines between XS and XE is stored for later recall by PX.

Macro: .PX [no]

Switch to single-column layout. Unless no is specified, center and interpolate the TOC string in bold and two points larger than the body text. Emit the table of contents entries.

Macro: .TC [no]

Set the page number to 1, the page number format to lowercase Roman numerals, and call PX (with a no argument, if present).

Here’s an example of typical ms table of contents preparation. We employ horizontal escape sequences \h to indent the entries by sectioning depth.

.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

The remaining features in this subsubsection are GNU extensions. groff ms obviates the need to repeat heading text after XS calls. Call XN and XH after NH and SH, respectively.

Macro: .XN heading-text

Macro: .XH depth heading-text

Format heading-text and create a corresponding table of contents entry. XN computes the indentation from the depth of the preceding NH call; XH requires a depth argument to do so.

groff ms encourages customization of table of contents entry production.

Macro: .XN-REPLACEMENT heading-text

Macro: .XH-REPLACEMENT depth heading-text

These hook macros implement XN and XH, respectively. They call XN-INIT and pass their heading-text arguments to XH-UPDATE-TOC.

Macro: .XN-INIT

Macro: .XH-UPDATE-TOC depth heading-text

The XN-INIT hook macro does nothing by default. XH-UPDATE-TOC brackets heading-text with XS and XE calls, indenting it by 2 ens per level of depth beyond the first.

We could therefore produce a table of contents similar to that in the previous example with fewer macro calls. (The difference is that this input follows the “Approach” entries with leaders and page numbers.)

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

To get the section number of the numbered headings into the table of contents entries, we might define XN-REPLACEMENT as follows. (We obtain the heading depth from groff ms’s internal register nh*hl.)

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

You can change the style of the leader that bridges each table of contents entry with its page number; define the TC-LEADER special character by using the char request. A typical leader combines the dot glyph ‘.’ with a horizontal motion escape sequence to spread the dots. The width of the page number field is stored in the TC-MARGIN register.

4.6.7 Differences from AT&T ms

The groff ms macros are an independent reimplementation, using no AT&T code. Since they take advantage of the extended features of GNU troff, they cannot be used with AT&T troff. groff ms supports features described above as Berkeley and Research Tenth Edition Unix extensions, and adds several of its own.

• The internals of groff ms differ from those of AT&T ms. Documents that depend upon implementation details of AT&T ms may not format properly with groff ms. Such details include macros whose function was not documented in the AT&T ms manual.¹⁸
• The error-handling policy of groff ms is to detect and report errors, rather than to ignore them silently.
• Research Tenth Edition Unix supported P1/P2 macros to bracket code examples; groff ms does not.
• groff ms does not work in GNU troff’s AT&T compatibility mode. If loaded when that mode is enabled, it aborts processing with a diagnostic message.
• Multiple line spacing is not supported. Use a larger vertical spacing instead.
• groff ms uses the same header and footer defaults in both nroff and troff modes as AT&T ms does in troff mode; AT&T’s default in nroff mode is to put the date, in U.S. traditional format (e.g., “January 1, 2021”), in the center footer (the CF string).
• Many groff ms macros, including those for paragraphs, headings, and displays, cause a reset of paragraph rendering parameters, and may change the indentation; they do so not by incrementing or decrementing it, but by setting it absolutely. This can cause problems for documents that define additional macros of their own that manipulate indentation. Use the ms RS and RE macros instead of the in request.
• AT&T ms interpreted the values of the registers PS and VS in points, and did not support the use of scaling units with them. groff ms interprets values of the registers PS, VS, FPS, and FVS equal to or larger than 1,000 (one thousand) as decimal fractions multiplied by 1,000.¹⁹ This threshold makes use of a scaling unit with these parameters practical for high-resolution devices while preserving backward compatibility. It also permits expression of non-integral type sizes. For example, ‘groff -rPS=10.5p’ at the shell prompt is equivalent to placing ‘.nr PS 10.5p’ at the beginning of the document.
• AT&T ms’s AU macro supported arguments whose values were used with some non-RP document types; that of groff ms does not.
• Right-aligned displays are available. The AT&T ms manual observes that “it is tempting to assume that ‘.DS R’ will right adjust lines, but it doesn’t work”. In groff ms, it does.
• To make groff ms use the default page offset (which also specifies the left margin), the PO register must stay undefined until the first ms macro is called.

  This implies that ‘\n[PO]’ should not be used early in the document, unless it is changed also: accessing an undefined register automatically defines it.

• groff ms supports the PN register, but it is not necessary; you can access the page number via the usual % register and invoke the af request to assign a different format to it if desired.²⁰
• The AT&T ms manual documents registers CW and GW as setting the default column width and “intercolumn gap”, respectively, and which applied when MC was called with fewer than two arguments. groff ms instead treats MC without arguments as synonymous with 2C; there is thus no occasion for a default column width register. Further, the MINGW register and the second argument to MC specify a minimum space between columns, not the fixed gutter width of AT&T ms.
• The AT&T ms manual did not document the QI register; Berkeley and groff ms do.

Register: \n[GS]

groff ms sets the register GS to 1; AT&T ms does not use it. A document can test its value to determine whether it is being formatted with groff ms or another implementation.

4.6.7.1 Unix Version 7 ms macros unimplemented by groff ms

Several macros described in the Unix Version 7 ms documentation are unimplemented by groff ms because they are specific to the requirements of documents produced internally by Bell Laboratories, some of which also require a glyph for the Bell System logo that groff does not support. These macros implemented several document type formats (EG, IM, MF, MR, TM, TR), were meaningful only in conjunction with the use of certain document types (AT, CS, CT, OK, SG), stored the postal addresses of Bell Labs sites (HO, IH, MH, PY, WH), or lacked a stable definition over time (UX). To compatibly render historical ms documents using these macros, we advise your documents to invoke the rm request to remove any such macros it uses and then define replacements with an authentically typeset original at hand.²¹ For informal purposes, a simple definition of UX should maintain the readability of the document’s substance.

.rm UX
.ds UX Unix\"

4.6.8 Legacy Features

groff ms retains some legacy features solely to support formatting of historical documents; contemporary ones should not use them because they can render poorly. See the groff_char(7) man page.

AT&T accent mark strings

AT&T ms defined accent mark strings as follows.

String: \*[']

Apply acute accent to subsequent glyph.

String: \*[`]

Apply grave accent to subsequent glyph.

String: \*[:]

Apply dieresis (umlaut) to subsequent glyph.

String: \*[^]

Apply circumflex accent to subsequent glyph.

String: \*[~]

Apply tilde accent to subsequent glyph.

String: \*[C]

Apply caron to subsequent glyph.

String: \*[,]

Apply cedilla to subsequent glyph.

Berkeley accent mark and glyph strings

Berkeley ms offered an AM macro; calling it redefined the AT&T accent mark strings (except for ‘\*C’), applied them to the preceding glyph, and defined additional strings, some for spacing glyphs.

Macro: .AM

Enable alternative accent mark and glyph-producing strings.

String: \*[']

Apply acute accent to preceding glyph.

String: \*[`]

Apply grave accent to preceding glyph.

String: \*[:]

Apply dieresis (umlaut) to preceding glyph.

String: \*[^]

Apply circumflex accent to preceding glyph.

String: \*[~]

Apply tilde accent to preceding glyph.

String: \*[,]

Apply cedilla to preceding glyph.

String: \*[/]

Apply stroke (slash) to preceding glyph.

String: \*[v]

Apply caron to preceding glyph.

String: \*[_]

Apply macron to preceding glyph.

String: \*[.]

Apply underdot to preceding glyph.

String: \*[o]

Apply ring accent to preceding glyph.

String: \*[?]

Interpolate inverted question mark.

String: \*[!]

Interpolate inverted exclamation mark.

String: \*[8]

Interpolate small letter sharp s.

String: \*[q]

Interpolate small letter o with hook accent (ogonek).

String: \*[3]

Interpolate small letter yogh.

String: \*[d-]

Interpolate small letter eth.

String: \*[D-]

Interpolate capital letter eth.

String: \*[th]

Interpolate small letter thorn.

String: \*[Th]

Interpolate capital letter thorn.

String: \*[ae]

Interpolate small æ ligature.

String: \*[Ae]

Interpolate capital Æ ligature.

String: \*[oe]

Interpolate small oe ligature.

String: \*[OE]

Interpolate capital OE ligature.

4.6.9 Naming Conventions

groff ms uses the following conventions for names of macros, strings, and registers. External names available to documents that use the macros contain only uppercase letters and digits. The package reserves the following identifiers for internal use.

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

When selecting a name for your document’s own macros, registers, macros, and strings, avoid those reserved by groff ms and those defined by GNU troff. See Register Index, Macro Index, and String Index, or groff(7) for complete lists thereof.

groff ms organizes most of its internal names into modules. The naming convenion is as follows.

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

5 GNU troff Reference

This chapter covers all of the facilities of the GNU troff formatting program. Users of macro packages may skip it if not interested in details.

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 maintenance, hyphenation breaking, and consistent paragraph indentation. Early in its development, the program gained the ability to prepare output for a phototypesetter; a document could then be prepared for output to 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 upon a variety of output formats or devices, including PDF, HTML, laser printers, and terminal displays.

roff input contains 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.

5.1.1 Filling

When GNU troff starts up, it obtains information about the device for which it is preparing output.²² An essential property is the length of the output line, such as “6.5 inches”.

GNU troff interprets plain text files employing the Unix line-ending convention. It reads input a character at a time, collecting words as it goes, and fits as many words together on an output line as it can—this is known as filling. To GNU troff, a word is any sequence of one or more characters that aren’t spaces or newlines. The exceptions separate words.²³ To disable filling, see Manipulating Filling and Adjustment.

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.

5.1.2 Sentences

A passionate debate has raged for decades among writers of the English language over whether more space should appear between adjacent sentences than between words within a sentence, and if so, how much, and what other circumstances should influence this spacing.²⁴ GNU troff follows the example of AT&T troff; it attempts to detect the boundaries between sentences, and supplements them with inter-sentence space.

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

GNU troff flags certain characters (normally ‘!’, ‘?’, and ‘.’) as potentially ending a sentence. When GNU troff encounters one of these end-of-sentence characters at the end of an input line, or one of them is followed by two (unescaped) spaces on the same input line, it appends an inter-word space followed by an inter-sentence space in the output.

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

In the above example, inter-sentence space is not added after ‘P.’ or ‘T.’ because the periods do not occur at the end of an input line, nor are they followed by two or more spaces. Let’s imagine that we’ve heard something about defamation from Mr. Harper’s attorney, recast the sentence, and reflowed it in our text editor.

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.

“Barnum” doesn’t begin a sentence! What to do? Let us meet our first escape sequence, a series of input characters that give instructions to GNU troff instead of being used to construct output device glyphs.²⁵ An escape sequence begins with the backslash character \ by default, an uncommon character in natural language text, and is always followed by at least one other character, hence the term “sequence”.

The dummy character escape sequence \& can be used after an end-of-sentence character to defeat end-of-sentence detection on a per-instance basis. We can therefore rewrite our input more defensively.

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.

Adding text caused our input to wrap; now, we don’t need \& after ‘T.’ but we do after ‘P.’. Consistent use of the escape sequence ensures that potential sentence boundaries are robust to editing activities. Further advice along these lines follows in Input Conventions.

Normally, the occurrence of a visible non-end-of-sentence character (as opposed to a space or tab) immediately after an end-of-sentence character cancels detection of the end of a sentence. For example, it would be incorrect for the formatter to infer the end of a sentence after the dot in ‘3.14159’. However, it treats several characters transparently after the occurrence of an end-of-sentence character—it does not cancel end-of-sentence status upon encountering them. Such characters are often used as footnote marks or to close quotations and parentheticals. The default set is ‘"’, ‘'’, ‘)’, ‘]’, ‘*’, \[dg], \[dd], \[rq], and \[cq]. The last four are examples of special characters, escape sequences whose purpose is to obtain glyphs that are not easily typed at the keyboard, or which have special meaning to the formatter (like \ itself).²⁶

\[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)

Configure the sets of characters that potentially end sentences or are transparent to sentence endings with the cflags request (see Characters and Glyphs). Use the ss request to change—or eliminate—supplemental inter-sentence space (see Manipulating Filling and Adjustment).

5.1.3 Hyphenation

When an output line is nearly full, it is uncommon for the next word collected from the input to exactly fill it—often, there is room left over for only part of the next word. Hyphenation is the process of splitting a word so that it appears partially on one line, followed by a hyphen to indicate to the reader that the word has been broken, and that its remainder lies on the next. Hyphenation break points can be manually specified; GNU troff also uses a hyphenation algorithm and language-specific pattern files (based on TeX’s) to decide which words can be hyphenated and where.

Hyphenation does not always occur even when the hyphenation rules for a word allow it; it can be disabled, and when not disabled there are several parameters that can prevent it in certain circumstances. See Manipulating Hyphenation.

5.1.4 Breaking

Once an output line is full, the formatter places the next word (or remainder of a hyphenated one) on a different output line; this is called a break. In this manual and in roff discussions generally, a “break” if not further qualified always refers to the termination of an output line. When the formatter is filling text, it introduces breaks automatically to keep output lines from exceeding the configured line length. After an automatic break, the formatter adjusts the line if applicable (see below), and then resumes collecting and filling text on the next output line.

Sometimes, a line cannot be broken automatically. This usually does not happen with natural language text unless the output line length has been manipulated to be extremely short, but it can with specialized text like program source code. We can use perl at the shell prompt to contrive an example of failure to break the line. We also employ the -z option to suppress normal output.

$ perl -e 'print "#" x 80, "\n";' | gnroff -z
    error→ cannot adjust line; overset by 15n

The remedy for these cases is to tell GNU troff where the line may be broken without hyphens. This is done with the non-printing break point escape sequence ‘\:’; see Manipulating Hyphenation.

What if the document author wants to stop filling lines temporarily, for instance to start a new paragraph? There are several solutions. A blank input line not only causes a break, but by default it also outputs a one-line vertical space (effectively a blank output line). This behavior can be modified; see Blank Line Traps. Macro packages may discourage or disable the blank line method of paragraphing in favor of their own macros.

A line that begins with one or more spaces causes a break. The spaces are output at the beginning of the next line without being adjusted (see below); however, this behavior can be modified (see Leading Space Traps). Again, macro packages may provide other methods of producing indented paragraphs. Trailing spaces on text lines are discarded.²⁷

What if the file ends before enough words have been collected to fill an output line? Or the output line is exactly full but not yet broken, and there is no more input? The formatter breaks the pending output line without adjustment upon encountering the end of input. Certain requests also cause breaks, implicitly or explicitly. This is discussed in Manipulating Filling and Adjustment.

5.1.5 Adjustment

After performing an automatic break, the formatter may then adjust the line, widening inter-word spaces until the text reaches the right margin. Extra spaces between words are preserved. Leading and trailing spaces are handled as noted above. You can align text to the left or right margin only, or center it; see Manipulating Filling and Adjustment.

5.1.6 Tabs and Leaders

The formatter translates input horizontal tab characters (“tabs”) and Control+A characters (“leaders”) into movements to the next tab stop. Tabs simply move to the next tab stop; leaders place enough periods to fill the space. Tab stops are by default located every half inch measured from the drawing position corresponding to the beginning of the input line; see Page Geometry. Tabs and leaders do not cause breaks and therefore do not interrupt filling. Below, we use arrows → and bullets • to indicate input tabs and leaders, respectively.

A→B→C•D→•E
.br
1
→2→3•4
→•5
    ⇒ A       B       C.......D       ........E
    ⇒ 1         2       3.......4         ........5

Tabs and leaders lend themselves to table construction.²⁸ The tab and leader fill characters can be configured, and further facilities for sophisticated table composition are available; see Tabs and Fields. There are many details to track when using such low-level features, so most users turn to the tbl(1) preprocessor to lay out tables.

5.1.7 Requests and Macros

We have now encountered almost all of the syntax there is in the roff language, with an exception already noted in passing.²⁹ A request is an instruction to the formatter that occurs after a control character, which is recognized at the beginning of an input line. The regular control character is a dot (.). Its counterpart, the no-break control character, a neutral apostrophe ('), suppresses the break that is implied by some requests. These characters were chosen because it is uncommon for lines of text in natural languages to begin with them. If you require a formatted period or apostrophe (closing single quotation mark) where the formatter expects a control character, prefix the dot or neutral apostrophe with the dummy character escape sequence, ‘\&’.

An input line beginning with a control character is called a control line. Every line of input that is not a control line is a text line.³⁰

Requests often take arguments, words (separated from the request name and each other by spaces) that specify details of the action you expect the formatter to perform. If a request is meaningless without arguments, it is typically ignored.

Requests and escape sequences comprise the control language of the formatter. Of key importance are the requests that define macros. Macros are invoked like requests, enabling the request repertoire to be extended or overridden.³¹

A macro can be thought of as an abbreviation you can define for a collection of control and text lines. When a document calls a macro by placing its name after a control character, the formatter replaces the control line with the macro’s definition. The process of textual replacement is known as interpolation.³² Interpolations are handled as soon as they are recognized, and once performed, the formatter scans the replacement for further requests, macro calls, and escape sequences.

In roff systems, the de request defines a macro.³³

.de DATE
2020-11-14
..

The foregoing input produces no output by itself; all we have done is store information in a macro named ‘DATE’. Observe the pair of dots that ends the macro definition. This is a default; you can specify your own terminator for the macro definition as the second argument to the de request.

.de NAME ENDNAME
Heywood Jabuzzoff
.ENDNAME

In fact, the ending mark is itself the name of a macro to be called, or a request to be invoked, if it is defined at the time its control line is read.

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

In the foregoing example, “Big Rip” printed before “Big Bang” because its macro was called first. Consider what would happen if we dropped END from the ‘.de START’ line and added .. after .END. Would the order change?

Let us consider a more elaborate example.

.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

The above document started with a series of control lines. Three macros were defined, with a de request declaring each macro’s name, and the “body” of the macro starting on the next line and continuing until a line with two dots ‘..’ marked its end. The text proper began only after the macros were defined; this is a common pattern. Only the NOTICE macro was called “directly” by the document; DATE and BOSS were called only by NOTICE itself. Escape sequences were used in BOSS, two levels of macro interpolation deep.

The advantage in typing and maintenance economy may not be obvious from such a short example, but imagine a much longer document with dozens of such paragraphs, each requiring a notice of managerial approval. Consider what must happen if you are in charge of generating a new version of such a document with a different date, for a different boss. With well-chosen macros, you only have to change each datum in one place.

In practice, we would probably use strings (see Strings) instead of macros for such simple interpolations; what is important here is to glimpse the potential of macros and the power of recursive interpolation.

We could have defined our DATE and BOSS macros in the opposite order; perhaps less obviously, we could also have defined them after NOTICE. Such “forward references” are well-defined because the body of a macro definition is, for the most part, stored rather than interpreted (see Copy Mode). While a macro is being defined (or appended to), requests are not interpreted and macros not interpolated; some commonly used escape sequences are however interpreted. roff systems also support recursive macro calls, as long as you have a way to break the recursion (see Conditionals and Loops). Maintainable roff documents tend to arrange macro definitions to minimize forward references.

5.1.8 Macro Packages

Macro definitions can be collected into macro files, roff input files designed to produce no output themselves but instead ease the preparation of other roff documents. There is no syntactical difference between a macro file and any other roff document; only its purpose distinguishes it. When a macro file is installed at a standard location and suitable for use by a general audience, it is often termed a macro package.³⁴ Macro packages can be loaded by supplying the -m option to GNU troff or a groff front end. Alternatively, a document requiring a macro package can load it with the mso (“macro source”) request.

5.1.9 Input Format

Organize input to GNU troff into lines separated by the Unix newline character (U+000A), using the character encoding it recognizes: ISO Latin-1 (8859-1). A document encoded in ISO 646:1991 IRV (US-ASCII), or, equivalently, uses only code points from the “C0 Controls” and “Basic Latin” parts of the Unicode character set is also a valid ISO Latin-1 document; the standards are interchangeable in their first 128 code points.³⁵

Some control characters (from the sets “C0 Controls” and “C1 Controls” as Unicode describes them) are invalid as input characters. GNU troff discards them upon reading.³⁶ It processes a character sequence “foo”, followed by an invalid character and then “bar”, as “foobar”.

Invalid input characters comprise 0x00, 0x0B, 0x0D–0x1F, and 0x80–0x9F.³⁷ GNU troff uses some of these code points for internal purposes, making non-trivial the extension of the program to accept UTF-8 or other encodings that use characters from these ranges.

5.1.10 Input Encodings

Recall from Groff Options, that the groff command’s -k option runs the preconv preprocessor to perform input character encoding conversions to satisfy GNU troff’s requirement of a single-byte encoding compatible with ISO 646:1991 IRV (US-ASCII).

Localization influences automatic hyphenation in two distinct but related respects. A macro file specific to a character coding identifies which character codes correspond to letters expected in the language’s hyphenation pattern files and sets up case equivalences for those letters. A language’s macro file determines which of these letters are equivalent to other letters for hyphenation purposes.

For example, in English, the letter ‘ñ’ occurs in loan words. The latin1.tmac and latin9.tmac macro files define a hyphenation code for ‘ñ’ and make ‘Ñ’ equivalent to it. The English localization file en.tmac furthermore makes ‘ñ’ equivalent to ‘n’. In Spanish (es.tmac), however, ‘ñ’ and ‘n’ are not equivalent. The language localization file (see Manipulating Hyphenation) loads an appropriate encoding localization file; a document need not do so directly.

koi8-r

To use KOI8-R, an encoding for the Russian language, either place ‘.mso koi8-r.tmac’ at the very beginning of your document or supply ‘-m koi8-r’ as a command-line argument to groff. The ru.tmac localization file loads koi8-r.tmac automatically.³⁸

latin1

ISO Latin-1 is an encoding for Western European languages. The de.tmac, en.tmac, it.tmac, and sv.tmac localization files load latin1.tmac automatically.

latin2

To use ISO Latin-2, an encoding for Central and Eastern European languages, invoke ‘.mso latin2.tmac’ at the beginning of your document or supply ‘-m latin2’ as a command-line argument to groff. The cs.tmac localization file loads latin2.tmac automatically.

latin5

To use ISO Latin-5, an encoding for the Turkish language, invoke ‘.mso latin5.tmac’ at the beginning of your document or supply ‘-m latin5’ as a command-line argument to groff.

latin9

ISO Latin-9 succeeds Latin-1; it includes a Euro sign and better coverage for French. To use this encoding, invoke ‘.mso latin9.tmac’ at the beginning of your document or supply ‘-m latin9’ as a command-line argument to groff. The es.tmac and fr.tmac localization files load latin9.tmac automatically.

Some characters from an input encoding may not be available with a particular output driver, or their glyphs may not have representation in the font used. For terminal devices, fallbacks are defined, like ‘EUR’ for the Euro sign and ‘(C)’ for the copyright sign. For typesetter devices, you may need to “mount” fonts that support glyphs required by the document. See Font Positions.

Because a Euro glyph was not historically defined in PostScript fonts, groff comes with a font called freeeuro.pfa that provides the Euro in several styles. Standard PostScript fonts contain the glyphs from Latin-5 and Latin-9 that Latin-1 lacks, so these encodings are supported for the ps and pdf output devices as groff ships, while Latin-2 is not.

Unicode supports characters from all other input encodings; the utf8 output driver for terminals therefore does as well. The DVI output driver supports the Latin-2 and Latin-9 encodings if the command-line option ‘-m ec’ is used as well. ³⁹

5.1.11 Input Conventions

Since a roff formatter fills text automatically, its experienced users tend to avoid visual composition of text in input files: the esthetic appeal of the formatted output is what matters. Therefore, roff input should be arranged such that it is easy for authors and maintainers to compose and develop the document, understand the syntax of roff requests, macro calls, and preprocessor languages used, and predict the behavior of the formatter. Several traditions have accrued in service of these goals.

• Follow sentence endings in the input with newlines to ease their recognition (see Sentences). It is frequently convenient to end text lines after colons and semicolons as well, as these typically precede independent clauses. Consider doing so after commas; they often occur in lists that become easy to scan when itemized by line, or constitute supplements to the sentence that are added, deleted, or updated to clarify it. Parenthetical and quoted phrases are also good candidates for placement on text lines by themselves.
• Set your text editor’s line length to 72 characters or fewer.⁴⁰ This limit, combined with the previous item of advice, makes it less common that an input line will wrap in your text editor, and thus will help you perceive excessively long constructions in your text. Recall that natural languages originate in speech, not writing, and that punctuation is correlated with pauses for breathing and changes in prosody.
• Use \& after ‘!’, ‘?’, and ‘.’ if they are followed by space or newline characters and don’t end a sentence.
• In filled text lines, use \& before ‘.’ and ‘'’ if they are preceded by space, so that revisions to the input don’t turn them into control lines.
• Do not use spaces to perform indentation or align columns of a table. Leading spaces are reliable when text is not being filled. (Exception: when laying out a table with GNU tbl, specifying the nospaces region option causes the program to ignore spaces at the boundaries of table cells.)
• Comment your document. It is never too soon to apply comments to record information of use to future document maintainers (including your future self). We thus introduce another escape sequence, \", which causes the formatter to ignore the remainder of the input line.
• Use the empty request—a control character followed immediately by a newline—to visually manage separation of material in input files. Many of the groff project’s own documents use an empty request between sentences, after macro definitions, and where a break is expected, and two empty requests between paragraphs or other requests or macro calls that will introduce vertical space into the document.

  You can combine the empty request with the comment escape sequence to include whole-line comments in your document, and even “comment out” sections of it.

We conclude this section with an example sufficiently long to illustrate most of the above suggestions in practice. For the purpose of fitting the example between the margins of this manual with the font used for its typeset version, we have shortened the input line length to 56 columns. As before, an arrow → indicates a tab character.

.\"   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 origin near the upper left corner. Coordinate values are in basic units and increase down and to the right. Useful ones are typically positive and within numeric ranges corresponding to the page boundaries.

Text is arranged on a one-dimensional lattice of text baselines from the top to the bottom of the page. A text baseline is a (usually invisible) line upon which the glyphs of a typeface are aligned. Vertical spacing is the distance between adjacent text baselines. Typographic tradition sets this quantity to 120% of the type size. Typographers term this unit a vee.

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.⁴¹ A glyph therefore “starts” at its bottom-left corner. The formatter’s origin is one vee below the page top to prevent a glyph from lying partially or wholly off the page.

Further, it is conventional not to write or draw at the extreme edges of the page. Typesetters configure a page offset, a rightward shift from the left edge that defines the zero point from which the formatter reckons the line indentation and length.⁴²

Combining the foregoing facts results in an origin that lies at the page offset in the horizontal dimension and at the text baseline (using the default vertical spacing) in the vertical dimension. A document can change these prior to its first written or drawn output; see Line Layout and Manipulating Type Size and Vertical Spacing.

Vertical spacing has an impact on page-breaking decisions. Generally, when a break occurs, the formatter automatically moves the drawing position to the next text baseline. If the formatter were already writing to the last line that fits on the page, advancing by one vee would place the next text baseline off the page. To avoid that, roff formatters instruct the output driver to eject the page, start a new one, and again place the drawing position at the page offset 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 also breaks 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 of at least one vee.

5.3 Measurements

A roff document sometimes requires the input of numeric parameters to specify measurements. Express them as integers or decimal fractions with an optional scaling unit suffixed. A scaling unit is a letter that immediately follows the magnitude of a measurement. Digits after the decimal point are optional. Examples of measurements include ‘10.5p’, ‘11i’, ‘.5f’, and ‘3.c’.

The formatter scales measurements by the specified scaling unit, storing them 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, then reading the register.

u

Basic unit; it is at least as small as any other 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

Scaled point; see Using Fractional Type Sizes.

z

Typographical point; like p, but used only with type sizes, to overcome a limitation of AT&T troff; see Using Fractional Type Sizes.

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; on typesetters, an en is one-half em, but on terminals an en equals an em, because they align all text to a grid of character cells.

v

Vee; recall Page Geometry.

M

Hundredth of an em.

5.3.1 Motion Quanta

The basic unit u is not necessarily an output device’s smallest addressable length; u can be smaller to avoid integer rounding errors. The minimum distances that a device can work with in the horizontal and vertical directions are termed its motion quanta. The formatter rounds measurements to applicable motion quanta. Half-quantum fractions round toward zero.

Register: \n[.H]

Register: \n[.V]

These read-only registers interpolate the horizontal and vertical motion quantum, respectively, of the output device in basic units.

For example, we might draw short baseline rules on a terminal device as follows. See Drawing Geometric Objects.

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

5.3.2 Default Units

A general-purpose register (one created or updated with the nr request⁴³) is implicitly dimensionless, or reckoned in basic units if interpreted in a measurement context. But it is convenient for many requests and escape sequences to infer a scaling unit for an argument if none is specified. An explicit scaling unit (not after a closing parenthesis) can override an undesirable default. Effectively, the default unit is suffixed to the expression if a scaling unit is not already present. GNU troff’s use of integer arithmetic should also be kept in mind.⁴⁴

The ll request interprets its argument in ems by default. Consider several attempts to set a line length of 3.5 inches when the type size is 10 points on a terminal device with a resolution of 240 basic units and horizontal motion quantum of 24. Some expressions become zero; the request clamps them to that quantum.

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

The safest way to specify measurements is to attach a scaling unit. To multiply or divide by a dimensionless quantity, use ‘u’ as its scaling unit.

5.4 Numeric Expressions

When evaluated, a numeric expression interpolates 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 depends on the host machine but is at least a 32-bit signed integer, which suffices to represent magnitudes within a range of ±2 billion.⁴⁶ Arithmetic saturates.⁴⁷

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. Division and 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, with synonym ==). When evaluating a comparison, the formatter replaces it 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, the formatter recognizes ! only at the beginning of a numeric expression not contained by another numeric expression. In other words, ! must be the “outermost” operator. Its presence elsewhere causes the expression to evaluate false.⁴⁸ This unfortunate limitation maintains compatibility with AT&T troff. Test a numeric expression for falsity within a complex expression 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 in these contexts, subtract it from zero or include the unary minus in parentheses with its argument. See Setting Registers, for examples.

A leading | operator indicates a measurement relative not to the drawing position but to a boundary. For horizontal motions, the boundary is the 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.⁵¹

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'input'

Interpolate 1 if input 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)
.  el          .tm \\$0: invalid number '\\$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 parentheses surround the (sub)expression containing them. 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 elicited an error diagnostic.

5.5 Identifiers

An identifier labels a GNU troff datum such as a register, name (macro, string, or diversion), typeface (font, family, or style), color, special character or character class, hyphenation language code, environment, or stream. Valid identifiers consist of one or more ordinary characters.⁵² An ordinary character is any Unicode Basic Latin character that is not a space and not the escape character; recall Input Format. 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.

Beginning a macro, string, or diversion name with the character ‘[’ or ‘]’ forecloses use of the grefer preprocessor, which recognizes input lines starting with ‘.[’ and ‘.]’ as bibliographic reference delimiters.

Escape sequence: \A'input'

Interpolate 1 if input is a valid identifier, and 0 otherwise. The delimiter need not be a neutral apostrophe; see Delimiters. Because GNU troff ignores any input character with an invalid code when reading it, invalid identifiers are empty or contain spaces, tabs, newlines, or escape sequences that interpolate something other than a sequence of ordinary characters.

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
.init-coordinate-pair "poi→nt" trash garbage \" ignored
.init-coordinate-pair point waste rubbish \" ignored
The center is at (\n[center!x], \n[center!y]).
    ⇒ 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.

The formatter’s handling of undefined identifiers is context-dependent. 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 name, the formatter defines it as empty and interpolates nothing.⁵³ Similarly, if the identifier is interpreted as a register name, the formatter initializes it to zero and interpolates that value.⁵⁴ Attempting to use an undefined typeface, special character or character class, color, environment, hyphenation language code, 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.

5.6.1 Control Characters

The mechanism of using roff’s control characters to invoke requests and call macros was introduced in Requests and Macros. The formatter recognizes a control character only at the beginning of an input line, or at the beginning of a branch of a control structure request; see Conditionals and Loops.

A few requests cause a break implicitly; use the no-break control character to prevent the break. Break suppression is its sole behavioral distinction. Employing the no-break control character to invoke requests that don’t cause breaks is harmless but poor style. See Manipulating Filling and Adjustment.

The control ‘.’ and no-break control ‘'’ characters can each be changed to any ordinary character⁵⁵ with the cc and c2 requests, respectively.

Request: .cc [o]

Recognize the ordinary character o as the control character. If o is absent or invalid, the default control character ‘.’ is selected. If o (or ‘.’ if o is invalid) is already the escape or no-break control character, an error is diagnosed and the request ignored. The identity of the control character is associated with the environment (see Environments).

Request: .c2 [o]

Recognize the ordinary character o as the no-break control character. If o is absent or invalid, the default no-break control character ‘'’ is selected. If o (or ‘'’ if o is invalid) is already the escape or control character, an error is diagnosed and the request ignored. The identity of the no-break control character is associated with the environment (see Environments).

When writing a macro, you might wish to know which control character was used to call it.

Register: \n[.br]

This read-only register interpolates 1 if the currently executing macro was called using the normal control character and 0 otherwise. If a macro is interpolated as a string, the .br register’s value is inherited from the context of the string interpolation. See Strings.

Use this register to reliably intercept requests that imply breaks.

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

Testing the .br register outside of a macro definition makes no sense.

5.6.2 Invoking Requests

A control character is optionally followed by tabs and/or spaces and then an identifier naming a request or macro. The invocation of an unrecognized request is interpreted as a macro call. Defining a macro with the same name as a request replaces the request. Deleting a request name with the rm request makes it unavailable. The als request can alias requests, permitting them to be wrapped or non-destructively replaced. See Strings.

There is no inherent limit on argument length or quantity. Most requests take one or more arguments, and ignore any they do not expect. A request may be separated from its arguments by tabs or spaces, but only spaces can separate an argument from its successor. Only one between arguments is necessary; any excess is ignored.⁵⁶ GNU troff does not interpret tabs as argument separators.⁵⁷

Generally, a space within a request argument is not relevant, not meaningful, or is supported by bespoke provisions, as with the tl request’s delimiters (see Page Layout). Some requests, like ds, interpret the remainder of the control line as a single argument. See Strings.

Spaces and tabs immediately after a control character are ignored. Commonly, authors use them to indent the source of documents or macro files.

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

If you assign an empty blank line trap, you can separate macro definitions (or any input lines) with blank lines.

.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

See Blank Line Traps.

5.6.3 Calling Macros

If a macro of the desired name does not exist when called, the formatter creates it and assigns it an empty definition.⁵⁸ Calling an undefined macro does end a macro definition naming it as its end macro (see Writing Macros).

To embed spaces within a macro argument, enclose the argument in neutral double quotes ". Horizontal motion escape sequences are sometimes a better choice for arguments to be formatted as text.

Consider calls to a hypothetical section heading macro ‘uh’.

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

The first line calls uh with three arguments: ‘The’, ‘Mouse’, and ‘Problem’. The remainder call the uh macro with one argument, ‘The Mouse Problem’. The last solution, using escaped spaces, can be found in documents prepared for AT&T troff. It can cause surprise when text is adjusted, because \SPC inserts a fixed-width, non-breaking space. GNU troff’s \~ escape sequence inserts an adjustable, non-breaking space.⁵⁹

The foregoing raises the question of how to embed neutral double quotes or backslashes in macro arguments when those characters are desired as literals. In GNU troff, the special character escape sequence \[rs] produces a backslash and \[dq] a neutral double quote.

In GNU troff’s AT&T compatibility mode, these characters remain available as \(rs and \(dq, respectively. AT&T troff did not consistently define these special characters, but its descendants can be made to support them. See Device and Font Description Files.

If even that is not feasible, options remain. To obtain a literal escape character in a macro argument, you can simply type it if you change or disable the escape character first. See Using Escape Sequences. Otherwise, you must escape the escape character repeatedly to a context-dependent extent. See Copy Mode.

For the (neutral) double quote, you have recourse to an obscure syntactical feature of AT&T troff. Because a double quote can begin a macro argument, the formatter keeps track of whether the current argument was started thus, and doesn’t require a space after the double quote that ends it.⁶⁰ In the argument list to a macro, a double quote that isn’t preceded by a space doesn’t start a macro argument. If not preceded by a double quote that began an argument, this double quote becomes part of the argument. Furthermore, within a quoted argument, a pair of adjacent double quotes becomes a literal double quote.

.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

Apart from the complexity of the rules, this traditional solution has the disadvantage that double quotes don’t survive repeated argument expansion in AT&T troff or GNU troff’s compatibility mode. This can frustrate efforts to pass such arguments intact through multiple macro calls.

.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

Outside of compatibility mode, GNU troff doesn’t exhibit this problem because it tracks the nesting depth of interpolations. See Implementation Differences.

5.6.4 Using Escape Sequences

Whereas requests must occur on control lines, escape sequences can occur intermixed with text and may appear in arguments to requests, macros, and other escape sequences. An escape sequence is introduced by the escape character, a backslash \ (but see the ec request below). The next character selects the escape’s function.

Escape sequences vary in length. Some take an argument, and of those, some have different syntactical forms for a one-character, two-character, or arbitrary-length argument. Others accept only an arbitrary-length argument. In the former scheme, a one-character argument follows the function character immediately, an opening parenthesis ‘(’ introduces a two-character argument (no closing parenthesis is used), and an argument of arbitrary length is enclosed in brackets ‘[]’. In the latter scheme, the user selects a delimiter character. A few escape sequences are idiosyncratic, and support both of the foregoing conventions (\s), designate their own termination sequence (\?), consume input until the next newline (\!, \", \#), or support an additional modifier character (\s again, and \n). In no case can an escape sequence parameter contain an unescaped newline. As with requests, use of some escape sequences in source documents may interact poorly with a macro package you use; consult its documentation to learn of “safe” sequences or alternative facilities it provides to achieve the desired result.

If the character that follows the escape character does not identify a valid operation, the formatter ignores the escape character.⁶¹

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

Escape sequence interpolation is of higher precedence than escape sequence argument interpretation. This rule affords flexibility in using escape sequences to construct parameters to other escape sequences.

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

In the above, the syntax form ‘\f(’ accepts only two characters for an argument; the example works because the subsequent escape sequences are interpolated before the selection escape sequence argument is processed, and strings family and style interpolate one character each.⁶²

The escape character is nearly always interpreted when encountered; it is therefore desirable to have a way to interpolate it, disable it, or change it.

Escape sequence: \e

Interpolate the escape character. \e is interpreted even in copy mode (see Copy Mode).

The \[rs] special character escape sequence formats a backslash glyph. In macro and string definitions, the input sequences \\ and \E defer interpretation of escape sequences. See Copy Mode.

Request: .eo

Disable the escape mechanism except in copy mode. Once this request is invoked, no input character is recognized as starting an escape sequence in interpretation mode.

Request: .ec [o]

Recognize the ordinary character o as the escape character. If o is absent or invalid, the default escape character ‘\’ is selected. If o (or ‘\’ if o is invalid) is already the control or no-break control character, an error is diagnosed and the request ignored.

Switching escape sequence interpretation off to define a macro and back on afterward can obviate the need to double the escape character within the definition. See Writing Macros. This technique is not available if your macro needs to interpolate values at the time it is defined—but many do not.

.\" simplified `BR` macro from the man(7) macro package
.eo
.de BR
.  ds result \&
.  while (\n[.$] >= 2) \{\
.    as result \fB\$1\fR\$2\"
.    shift 2
.  \}
.  if \n[.$] .as result \fB\$1\"
\*[result]
.  rm result
.  ft R
..
.ec

Request: .ecs

Request: .ecr

The ecs request stores the escape character for recall with ecr. ecr sets the escape character to ‘\’ if none has been saved.

Use these requests together to temporarily change the escape character.

Using a different escape character, or disabling it, when calling macros not under your control will likely cause errors, since GNU troff has no mechanism to “intern” macros—that is, to convert a macro definition into a form independent of its representation.⁶³ When a macro is called, its contents are interpreted literally.

5.6.5 Delimiters

Some escape sequences that require parameters delimit them. The neutral apostrophe ' is a popular delimiter choice and shown in this document. The neutral double quote " is also commonly seen. Punctuation characters are the best choice (and most portable to other troffs), except for those meaningful in numeric expressions; see below.

\l'1.5i\[bu]' \" draw 1.5 inches of bullet glyphs

The following escape sequences are not themselves delimited, and thus are allowed as delimiters: \SPC, \%, \|, \^, \{, \}, \', \`, \-, \_, \!, \?, \), \/, \,, \&, \:, \~, \0, \a, \c, \d, \e, \E, \p, \r, \t, and \u. However, we discourage using them this way; they can make the input confusing to read.⁶⁴ An invalid escape sequence is valid as a delimiter if the character after the escape character would be valid.