UNIX_System_V_ors_Workbench_Users_Guide_1989 UNIX System V Ors Workbench Users Guide 1989

User Manual: UNIX_System_V_ors_Workbench_Users_Guide_1989

Open the PDF directly: View PDF .
Page Count: 402

Download
Open PDF In Browser	View PDF

c:=:
Z

AT.T

><•

£2
Cf)

co
:3

-vstem

UNIX® System V
DOCUMENTOR'S WORKBENCHTM
User's Guide

UNIX® System V
DOCUMENTOR'S WORKBENCH™
User's Guide

•

Prentice Hall, Englewood Cliffs, New Jersey 07632

All rights reserved. No part of this book may be
reproduced in any form or by any means
without permission in writing from the publisher.
9

Printed in the United States of America

10 9 8 7 6 5 4 3 2 I

ISBN

0-13-943598-0

Prentice-Hall International (UK) Limited London
Prentice-Hall of Australia Pty. Limited 9 Sydney
Prentice-Hall Canada Inc., Toronto
Prentice-Hall Hispanoamericana, S.A q Mexico
Prentice-Hall of India Private Limited, New Delhi
Prentice-Hall of Japan, Inc., Tokyo
Simon & Schuster Asia Pte. Ltd. 9 Singapore
Editora Prentice-Hall do Brasil, Ltda., Rio de Janeiro
9

Table of Contents

Product Overview
User's Guide
Handbook for New Users

~AT.T

310-006
Issue 1

UNIX™ System V

DOCUMENTER'S WORKBENCH™
Software Release 2.0
Product Overview

©1986 AT&T
All Rights Reserved
Printed'in USA
NOTICE
The information in this document is subject to change without notice. AT&T
assumes no responsibility for any errors that may appear in this document.
9700 is a trademark of Xerox.
APS·5 is a trademark of Autologic.
DEC is a trademark of Digital Equipment.
DOCUMENTER'S WORKBENCH is a trademark of AT&T:
IMPRINT is a trademark of IMAGEN.
PDP is a trademark of Digital Equipment.
TEKTRONIX is a trademark of Tektronix.
Teletype is a registered trademark of AT&T:
UNIX is a trademark of AT&T:
VAX is a trademark of Digital Equipment.

L·24366Q-17

Table of Contents
Introduction

Description

Progra~s

Obsolete

Progra~s

Docu~entation

Overview of Technical

Infor~ation

Supported Hardware
Specifications for the 3B2 Computer
Terminal Dependencies
Software Dependencies

9
10
10
10

TABLE OF CONTENTS

iii

Introduction
The DOCUMENTER'S WORKBENCH Software is a set of computer programs developed at AT&T Bell Laboratories to run under the UNIX operating
system. These programs help you format any type of document. The
DOCUMENTER'S WORKBENCH Software supports a range of output devices
from typewriter-like printers to phototypesetting equipment.

PRODUCT OVERVIEW

Description
The DOCUMENTER'S WORKBENCH Software is a powerful and sophisticated set of text formatting tools that helps you produce a wide variety of
documents, including letters, research papers, memoranda, reports, and
books. You can use the DOCUMENTER'S WORKBENCH Software to create
documents that contain tables, mathematical equations, line drawings, and
plots of data.
With the DOCUMENTER'S WORKBENCH Software you can dramatically
diminish the time you need to plan and prepare the following features of
your document.
• margins
• titles
• lists and displays
• footnotes
• page headers and footers
• page numbering
• table of contents
• glossary
• index
Anyone can run the DOCUMENTER'S WORKBENCH programs-a clerk, a
secretary, the writer or editor-you need only a basic familiarity with the
UNIX operating system. Using any UNIX system text editor, you type in
your text and intersperse formatting instructions (such as .P for paragraph),
that state precisely how you want your document to look when it is printed.
Then you choose the appropriate preprocessors and formatter to process
your file for printing.

PRODUCT OVERVIEW

Programs
The DOCUMENTER'S WORKBENCH programs can be grouped into the
following general categories:
Formatters

nroff and troff are text-formatting programming
languages for typewriter-like printers and phototypesetters, respectively. These "super word processors are at the heart of the DOCUMENTER'S WORKBENCH Software. The macro packages and preprocessors (see below) create instructions that the formatters use to produce a formatted document.
lt

Macro

There are four macro packages available with the
OOCUMENTER'S WORKBENCH Software: mm, mv,
man, and mptx. The mm, or Memorandum Macros,
package allows you to produce memoranda and
letters easily. The mv package allows you to make
high quality typeset transparencies in a variety of
sizes. The man macro package allows you to format
UNIX system manual pages, and mptx allows you to
format a permuted index.

Preprocessors

Four preprocessors are included with the
DOCUMENTER'S WORKBENCH Software: tbl, eqn,
pic, and grap. tbl helps you make tables: large or
small, simple or complex. eqn enables you to
present mathematical notation easily. pic enables
you to draw a wide variety of forms and line pictures, and grap, a "language" for describing plots of
data, automatically scales and labels axes. Preprocessors are used in conjunction with the text formatters
nroff or troff to produce your final formatted file.

Programs to Create an Index
subj scans your document to collect a list of keywords. ndx creates an index from the keyword list
subj makes.
Programs for Comparing and Checking Documents
checkmm checks input files and tells you if you
have made any syntax errors in the DOCUMENTER'S
WORKBENCH formatting instructions. diffmk

PRODUCT OVERVIEW

Programs

compares two versions of a document and produces
a third version that highlights the differences
between the two original files. macref produces a
cross-reference of the requests, macros, number
registers, and strings that you use in a file. It is
helpful for those who want to develop new sets of
macros.
Postprocessors

daps translates troff output for an Autologic APS-5
phototypesetter. ditO translates output from troff
for an Imagen IMPRINT-I0 laser printer. tc turns
troff output into code that a TEKTRONIX 4015
typesetter can use.

PRODUCT OVERVIEW

Obsolete Programs
Several programs that ''Were included with Release 1.0 of the
DOCUMENTER'S WORKBENCH Software are not in Release 2.0.

checkcw

is used with ocw, the preprocessor for otroff. It checks
whether left and right deiimiters and ~cw l.eN pairs are
properly ba~anced. Because otroff is not distribt,lted with
DOCUMENTER'S WORKBENCH Software 2.0, there is no
longer a need for checkcw.

checkeq

is used with eqn; checkeq is not included in
DOCUMENTER'S WORKBENCH Release ,2.0 because the command checkinm provides more extensive checking of proper
equation formatting.

dx9700

prepar~s troff documents for the Xerox 9700 printer. The
Xerox 9700 is no longer a supported device, and so the command is not distributed with DOCUMENTER'S WORKBENCH
Release 2.0.

mmlint

is a sroff/mm-nroff/mm document compatibility checker.
Because sroff I mm is not distributed with DOCUMENTER'S
WORKBENCH Release 2.0, there is no longer a need for
mmlint.

non-btl.sh

reinstalls mm macros without AT&T Bell Laboratories
specific features. This command is not included with
DOCUMENTER'S WORKBENCH Release 2.0 because AT&T Bell
Laboratories specific strings have been moved to an external
file called I usr I pub I strings.mm. The system administrator
can edit this external file to meet local needs.

ocw

is a preprocessor for otroff. Because otroff is not distributed
with DOCUMENTER'S WORKBENCH Release 2.0, there is no
longer a need for ocw.

osdd

The osdd adapter macro package is a tool used with the mm
macro package to prepare Operations Systems Deliverable
Documentation. The command is not distributed with
DOCUMENTER'S WORKBENCH Release 2.0.

PRODUCT OVERVIEW

Obsolete Programs

otc

is a postprocessor for otroff. Because otroff is not distributed with DOCUMENTER'S WORKBENCH Release 2.0, there
is no longer a need for otc.

otroff

The otroff text formatter is an early version of troff that formats text for only one device, the Cf AfT phototypesetter.
otroff is not distributed with DOCUMENTER'S WORKBENCH
Release 2.0.

sroff

sroff formats text for printing on typewriter-like devices and
line printers, including the Xerox 9700 printer. The Xerox
9700 is no longer a supported device; therefore, sroff is not
distributed with DOCUMENTER'S WORKBENCH Release 2.0.

x9700

prepares nroff documents for the Xerox 9700 printer. The
Xerox 9700 is no longer a supported device; therefore, the
command x9700 is not distributed with DOCUMENTER'S
WORKBENCH Release 2.0.

PRODUCT OVERVIEW

Documentation
The following documents are available for Release 2.0 of the
DOCUMENTER'S WORKBENCH Software system:

•

UNIX System V DOCUMENTER'S WORKBENCH Software User's
Guide (Select Code 310-004): The User's Guide contains three

sections: 1) the "Sampler, which shows files before and after
formatting, 2) a preface, and 3) tutorials. The first two sections familiarize the novice with the software in general, and
the tutorials cover its use in detail.
II

•

UNIX System V DOCUMENTER'S WORKBENCH Software Technical
Discussion and Reference Manual (Select Code 310-005): Organ-

ized to suit the more experienced user,. this tech1.1ical explanation of the software is presented according to patterns of customary use. The components of the software are discussed in
detail, and manual pages are also provided.
•

UNIX System V DOCUMENTER'S WORKBENCH Software Handbook

(Select Code 310-008): The Handbook is a memory jogger for
accomplished users who want a more technical understanding
of the software.
•

UNIX System V DOCUMENTER'S WORKBENCH Software Handbook
for New Users (Select Code 310-009): This handbook is aimed

at new users. It is task-oriented, and it incorporates aspects of
the "Sampler" from the User's Guide.
•

UNIX System V DOCUMENTER'S WORKBENCH Software Product
Overview (Select Code 310-006): This document prOVides a

summary of the software and its features, a list of available
documents, and a brief technical description for those who
might be asked to evaluate the software.
•

UNIX System V DOCUMENTER'S WORKBENCH Software Release
Notes (Select Code 310-007): The Release Notes, written for

system administrators, includes the software installation procedures for all processors that support the DOCUMENTER'S
WORKBENCH Software. In addition, it gives transition information for owners of earlier product releases.

PRODUCT OVERVIEW

Documentation

You may get copies.of the documents in this list from AT&T. When
placing orderS, refer to the Select Code for the document that you want (for
example 310-004 for the User's Guide).
write to:

AT&T Customer Information Center
P.O.Box 19901
Indianapolis, Indiana 46219

or call:

1-800-432-6600 within the continental United States

To order the DOCUMENTER'S WORKBENCH Software Release 2.0 call
1-800-828-UNIX for the source product
1-800-247-1212 for the binary product

PRODUCT OVERVIEW

Overview of Technical Information

Supported Hardware
The following list identifies the hardware on which DOCUMENTER'S
WORKBENCH Release 2.0 is supported for UNIX System V Release 2.0 as of
April 1985:
• AT&T 3B2/300,400 Computers
• AT&T 3B5 Computer
• AT&T 3B2OS/A Computers
• VAX 750
The UNIX operating system and components of the DOCUMENTER'S
WORKBENCH Software have been run on various other computers, including DEC PDP-ll/45, PDP-ll/70, and VAX-ll/780 mini-computers.

Specifications for the 3820 Computer and the VAX
For the AT&T 3B20 Computer and the DEC VAX-1l/780 and VAX-ll/750
computers, the source code for the DOCUMENTER'S WORKBENCH Software
Release 2.0 is distributed on a single magnetic tape containing two files in
cpia format, written at 1600 bpi. Only a system administrator with root
privileges may access this tape. Installing the object code of DOCUMENTER'S
WORKBENCH Software Release 2.0 also requires root userid privileges. The
Release Notes (310-007) presents complete installation instructions.

Specifications for the 385 Computer
For the 3B5 Computer, source code is distributed on either a Lark II disk
cartridge or a nine-track magnetic tape, and contains two files in cpia format. (The binary version of the DOCUMENTER'S WORKBENCH is only available on nine-track magnetic tape.) Again, it is written at 1600 bpi, and root
userid privileges are required. The Release Notes (310-007) presents complete installation instructions.

PRODUCT OVERVIEW

Overview of Technical Information

Specifications for the 3B2 Computer
Installing the DOCUMENTER'S WORKBENCH Software on the 3B2 Computer requires four floppy disks. Each floppy disk contains "install" and
"uninstall" scripts for the installation and removal of the files contained on
it. The required disk space for this product is 5500 blocks in the lusr file
system.
The first floppy disk contains all files that you need to use troff, grap,
mmt, mvt, pic, eqn and tc plus a driver (for the Autologic APS-5 typesetter)
and the font tables for this driver. The files on this first disk require 1100
blocks (512 bytes/block) of free space in the lusr file system.
The second floppy disk contains all the files you need to use nroff,
neqn, mm, and man. The files on this disk require 750 blocks of free space
in the I usr file system.
The third floppy disk contains files used by both nroff and troff. This
disk requires 1300 blocks of free space in the lusr file system.
The fourth floppy disk contains the driver, font tables and raster tables
for the Imagen IMPRINT-tO laser printer. The files on this disk require
2350 blocks of free space in the lusr file system.
You can find a detailed list of the files on each floppy together with
complete instructions for installation in the Release Notes.

Terminal Dependencies
You can display text processed by nroff, tbl, neqn and mm on a
typewriter-like printer or on a terminal without graphics capabilities. Text
processed by troff, the mv macro package, eqn, pic, and grap must be sent
to a terminal or a printer that supports typesetting (for example, a Teletype
5620 terminal).

Software Dependencies
AT&T supports the DOCUMENTER'S WORKBENCH Software Release 2.0
only on UNIX System V Release 2.0 and subsequent releases. AT&T does
not support DOCUMENTER'S WORKBENCH Software Release 2.0 on any other

PRODUCT OVERVIEW

Overview of Technical Information

version of the UNIX system. All the software that the DOCUMENTER'S
WORKBENCH Software needs for installation and execution is part of UNIX
System V Release 2.0 and subsequent releases.
On AT&T 3B2 Computers, the following utilities packages must be
installed before the DOCUMENTER'S WORKBENCH Software can be installed:
Directory and File Management Utilities Package
Terminal Filter Utilities Package (must be purchased separately)
The installation script checks that these packages are installed on your
3B2 Computer and will prevent you from installing the DOCUMENTER'S
WORKBENCH Software if they are not installed.

PRODUCT OVERVIEW

.~ AT.T

310-004
Issue 1

UNIXTM System V
.
DOCUMENTER'S WORKBENCHTM
Software Release 2.0

User's Guide

NOTICE
The information in this document is subject to change without notice. AT&T
assumes no responsibility for any errors that may appear in this document.
APS-5 is a trademark of Autologic.
DOCUMENTER'S WORKBENCH is a trademark of AT&l:
PU1 is a trademark of Digital Research.
TEKTRONIX is a trademark of Tektronix.
Teletype is a registered trademark of AT&T:
UNIX is a trademark of AT&T.
VAX is a trademark of Digital Equipment.
VERSATEC is a registered trademark of Versatec.
Excerpts from Virgil's Aeneid were borrowed from The Aeneid of Thomas Phae,
and Thomas Twyne: A Critical Edition Introducing Metrica/TYpography. ed.
Steven Lally, New York and London: Garland Publishing (1986).

L-244067-23

Table of Contents

Part 1
Preface
mm: Technical Discussion
tbl: Technical Discussion

nroffltroff: Technical Discussion

Part 2
checkmm(l)
co1(l)
daps(l)
dil0(1)
diffmk(l)
eqn(1)
eqnchar(S)
font(S)
grap(l)
hyphen(l)
macref(l)
man(5)
mm(l)
mm(S)
mmt(l)
mptx(S)
mv(S)

TABLE OF CONTENTS

III

Table of Contents

ndx(l)
neqn(l)
nroff(l)

nterin(S)
pic(!)
ptx(l)
8ubj(1)
tbl(l)
tc(t)
troff(l)
troff(S)

TECHNICAL DISCUSSION AND REFERENCE MANUAL

Introduction
The DOCUMENTER'S WORKBENCH Software provides a family of programs for typesetting materials containirig equations, tables, and diagrams,
as well as standard text. The base upon which these interrelated programs
rest is a text formatter called trofl, a generic term for nroff/troff, developed
by Joseph P. Ossanna around 1973. By itself, trofl, with its many requests
and escape sequences, provides a highly detailed level of text processing,
performing few high-level formatting operations beyond line filling and
justification. It accepts input from other, more specialized programs. In
particular, page layout is controlled by the mm macro package, so-called
because troff is a macro processor.
Several DOCUMENTER'S WORKBENCH Software programs deal with
specific areas of document preparation. eqn, for example, is a language for
typesetting mathematical expressions. It acts as a preprocessor for troff.
That is, the high-level instructions you give eqn are compiled into the
lower-level troff code that will actually plot the desired mathematical notation. The other DOCUMENTER'S WORKBENCH Software preprocessors are
eqn, tbl, pic, and grap.
grap, actually, is a "pre-preprocessor." This language, which you use to
make graphs of numerical data, accepts English-oriented input and directs
its output to pic, which in turn feeds troff.
Finally, troff's output, however produced, can be directed to any of a
large number of devices, ranging from conventional typesetters to laser
printers and bitmap terminals.
The figure shown below gives an overview of this input-output activity:

grap

tbl
pic ~ t ff ~ output
~ r
devices
eqn

----:.
t

r----'
macro I

package JI

In addition, the figure suggests the characteristic usage of DOCUMENTER'S
WORKBENCH tools. Rather than one program doing all of the work, several
specialized programs accomplish a wide variety of diverse functions. This

PREFACE

Introduction

approach enables each component to use an individually tailored language
particularly suited to its own purposes. That is, DOCUMENTER'S WORKBENCH Software is not top-heavy with a single, lowest-commondenominator language that must address a multitude of different demands.
Rather, each program's "dialect" is dedicated, relatively stream-lined, and
easy to use.

TECHNICAL DISCUSSION

troff
troff traces its origins back to a group of formatters that developed from
J. E. Saltzer at MIT during the 1960s. (The name roff actually
derives from a primitive formatter that Brian Kernighan wrote for his own
use as a graduate student.) troff's name was coined to express typesetter
run-off. It uses formatting commands, called requests, that are interspersed
through the text to govern processing. A report title, for example, might be
formed with the folloWing two lines of requests:

RUNOFF by

.ce 1
.ft B
which would place the next line of text in a centered position and change
the font to bold. troff provides eighty-five such requests, which are in turn
effectively multiplied by their respective numerical and alphabetical arguments.
In addition, troff uses about forty in-line commands for changing character size and typeface, placing special characters, invoking previously
defined characters or words, and dictating a variety of movements about the
page, to name a random assortment. For example, \£1 changes all succeeding text to italic, \(co gives the encircled copyright symbol, and \h'numeric
argument' moves text a distance indicated by a simple numeric argument,
arithmetic expression, register evaluation, or a combination of these. Arguments concerning physical dimensions may specify inches, centimeters,
picas, ems, ens, points, and machine units.
troff, unlike most of its its related components, does not have individual requests or escape sequences for automatically providing running titles
at the top of the page, setting up a table of contents, or making concordances. In contrast to say, the mm macro package, it is intended to permit
the user a detailed access to the inner workings of DOCUMENTER'S WORKBENCH Software.
troff is programmable; it has variables, arithmetic arguments, and conditional tests of many things, including the dimensions of processed text. It
allows you to define macros that encapsulate a sequence of operations or
that receive and store processed text. It also permits you to set traps
(marked page positions) that pass control to macros you have set up for this
purpose.

PREFACE

vII

troff

While this advanced level of detailed access can be indispensable, it is
not always desirable. Higher-level components, such as mm macros, should
be used for most text formatting. troff should be thought of as the instrument for fine-tuning that enables you to accomplish the non-standard processing that more generalized components do not offer. Furthermore, troff
should be understood as a language especially designed for text programming. It is capable of sophisticated manipulation of typography, evaluation
of accumulated text (or "diversions"), placement of graphical elements contingent upon diversion evaluation, and detailed page control.

viII

TECHNICAL DISCUSSION

Macro Packages
DOCUMENTER'S WORKBENCH Software uses a number of macro packages that enable the user to think in terms of text-title, page headings,
footnotes-rather than in terms of typography. Each of these packages is
designed to accomplish specialized tasks ranging from memorandum and
report preparation to compiling indexes.

The mm macro package is by far the most powerful and varied of these.
Formed as a library of Iroff request and string combinations, these macros
also allow for limited programmable features. mm prOVides the tools you
would need for most text processing: static or floating displays, seven levels
of numbered page headings, one- or two-column formatting, table-ofcontents formatter (collected automatically from numbered headings), to
name a few features. Many of these standard features can be altered to suit
individual tastes.
DOCUMENTER'S WORKBENCH Software also includes the mptx macro
package, used to make permuted indices and the mv 'macro package for
making view graphs and proj~ction slides. DOCUMENTER'S WORKBENCH
Software's indexing tools are mptx, ndx, pIx, and 8ubj.

PREFACE

Preprocessors
eqn defines a simple language for representing mathematical expressions. People trained in mathematics can usually learn it in a few minutes;
people without such training can normally use the language effectively in
an hour or so. For example:
a+b over c+d+e

= -b sup 2 over pi

generates this:

a+b
c+d+e

-b
---

Because eqn runs as a preprocessor, the entire document that contains
the equation is passed through it before reaching troff, which accepts eqn's
output as input. eqn does not, however, influence non-mathematical parts
of the text. It looks for language native to eqn (usually placed between the
macros .EQ al1d .EN) and ignores the rest.
tbl is trqff's preprocessor for making tables. It uses a language altogether different from the other preprocessors, which are more oriented
toward spoken English. It is, nonetheless, a simple language to learn and
can usually be mastered after one session. The following input lines are an
example:

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - Preprocessors

•'1'S

center t doublebox;
cfB s s
ccc

.. c c
Ip8 n n.
PEogram Sizes
NlIme
5aJrce

Lines

\f3troff\fP
\f3eqn\fP
\f3tb1\fP
\f3pi.c\fP
\f3grap\fP

Cbject bytes
(text-tdata)

8681
1821
2581
3760
2791

73136
34164
39936
83968
58368

•'l'E

(The columns of listed data items are separated by tabs.)
The output looks like this:

Name
troff

eqn
tbl
pic
grap

Program Sizes
Source Object bytes
(text+data)
Lines

8681
1821
2581
3760
2791

73136
34164
39936
83968
58368

pic is the facility for drawing figures and diagrams. It places forms
(boxes, circles, lines, and splines) at absolute positions (using Cartesian coordinates) or at specified positions relative to already placed objects. The following is an example of pic input:

PREFACE

Preprocessors

.PS

anow "i:nplt" above
box "process"
anow "out:p.lt" abaYe
.PE

and it will produce the following illustration:
input

---~~_~

process

outpu!

You may follow each object with attributes that control its size and position
and associated text strings. You may, in addition, plot forms other than the
ones that pic already supplies. A macro facility allows common operations
to be encapsulated, and these macros will accept arguments, enabling you to
build a library of pic drawings which, furthermore, can be modified at each
usage.
grap prOVides a language for describing graphs. Its output is pic input.
pic in turn feeds requests and strings to troff. By default grap plots input
numbers as a scatter plot, with automatically computed tick marks. Other
commands prOVide control over labels, scaling, logarithmic coordinates, and
the like. The following is a grap graph:

xii

TECHNICAL DISCUSSION

Preprocessors

UChariots of Fire"

Time
(in seconds)

1900
1920
1940
1960
1980
Olympic 400 Meter Run: Winning Times
which was produced by the following input:

.G1

frame top invi.s right invi.s
label left "Time" "(in seocnds)"
label bot "Olympic 400 Meter Run: Wi.:rmi.D] Times"
draw solid
1896 54.2
1900 49.4
1904 49.2
1908 50.0
1980 44.60
flX1tl 1924,51 to 1924,49
" "Olari.ots of Fire"" ljust at 1924,51

arrc:M

.G2

grap, like its near-relative pic, has a macro facility and control-flow features.

PREFACE

xIII

Table of Contents
1. Introduction

1.1. How this Technical Discussion is Organized
1.2. Definitions
1.3. Conventions
1.4. Formatting Concepts
1.4.1. Basic Terms
1.4.2. Arguments and Double Quotes
1.4.3. Unpaddable Spaces
1.4.4. Hyphenation
1.4.5. Tabs
1.4.6. Bullets
1.4.7. Dashes, Minus Signs, and Hyphens
1.4.8. Trademark String
1.4.9. BEL Character
1.4.10. Use of Formatter Requests

1
2
3
4
4
4

5
6

6
7

8
8
8

2. The Structure of a Document

3. Formatting the Body of a Document

13
13
13
14
14
15
15
17
18
18
20
21

3.1. Formatting Paragraphs (.P)
3.1.1. Paragraph Type (Pt)
3.1.2. Numbered Paragraphs (Np)
3.1.3. Spacing Between Paragraphs (Ps)
3.2. Formatting Lists
3.2.1. General Characteristics of Lists
3.2.2. Automatically Incremented Lists (.AL)
3.2.3. Marked Lists (.ML)
3.2.4. Variable-Item Lists (.VL)
3.2.5. Bullet, Dash, and Reference Lists (.BL, .DL, .RL)
3.2.6. Nested Lists

TABLE OF CONTENTS

Table of Contents

3.2.7. List-Begin Macro and Customized Lists
3.2.8. Defining List Structures
3.3. Footnotes (.FS, .FE)
3.3.1. Changing the Format of Footnote Text (.FO)
3.3.2. Spacing Between Footnote Entries (Fs)
3.4. Page Headers and Footers
3.4.1. Page Headers (.PH)
3.4.2. Even-Page Header and Odd-Page Header (.EH, .OH)
3.4.3. Page Footer (.PF)
3.4.4. Even-Page Footer, Odd-Page Footer, and First-Page
Footer (.EF, .OF)
3.4.5. Headers and Footers for the Memorandum and Released
Paper Style
3.4.6. Strings and Registers in Header and Footer Macros
3.4.7. Top and Bottom (Vertical) Margins (.VM)
3.4.8. Private Documents (Pv)
3.4.9. Generalized Top-of-Page Processing
3.5. Section Headings (.H)
3.5.1. Unnumbered Section Headings (.HU)
3.5.2. Altering the Appearance of Section Headings
3.5.3. Headings and Table of Contents (CI)
3.5.4. Section Headings and User Exit Macros
3.6. Displays
3.6.1. Static Displays (.OS, .OE)
3.6.2. Floating Displays (.OF, .OE)
3.7. Tables (using lbl)
3.8. Equations (using eqn)
3.9. Figure, Table, Equation, and Exhibit Titles (.FG, .TO, .Ee, .EX)

22
25
28
29
31
31
32
32
32
33
33
33
34
34
35
36
38
39
44
44
47
47
49
51
53
53

4. Formatting the Beginning of a Document

4.1. Formal Memorandum Style
4.1.1. Choosing a Formal Memorandum Type (.MT)
4.1.2. TM Numbers

56
56
58

mm: TECHNICAL DISCUSSION

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

4.1.3. Changing the Date (.ND)
4.1.4. Giving the Memorandum a Title (.TL)
4.1.5. Specifying the Author (.AU)
4.1.6. Specifying the Author's Title (.AT)
4.1.7. Specifying the Author's Firm (.AF)
4.1.8. Calling Beginning Formal Memorandum Macros in the
Correct Order
4.2. Other Beginning Macros
4.2.1. Abstract (.AS, .AE)
4.2.2. Other Keywords (.OK)
4.2.3. Bottom Block (.8S, .8E)
4.3. Proprietary Marking Macro (.PM)
4.4. Define File Information
4.5. Business Letter Style
4.5.1. Letter-Type Macro (.LT)
4.5.2. Writer's Address Macros (.WA, .WE)
4.5.3. Inside Address Macros (.IA, .IE)
4.5.4. Letter-Options Macro (.LO)
4.5.5. Multi-page Letters
4.5.6. Sequence of Beginning Letter Macros

5. Formatting the End of a Document
5.1.
5.2.
5.3.
5.4.
5.5.
5.6.
5.7.

Formal Closing and Signature Line (.FC, .SG)
Approval Line (.AV)
"Copy to" and Other Notations (.NS, .NE)
Table of Contents (.TC)
Changing the Table of Contents (.TX, .TY)
Cover Sheet (.CS)
References (.RS, .RF, .RP)

TABLE OF CONTENTS

59
59
60
61
62
63
63
63
64
64
65
67
67
67
71
72
73
76
76
78
78
79
80
82
83
85
85

III

Table of Contents

6. Miscellaneous Macros
6.1. Bold, Italic, and Roman Fonts (.B, .1, .R)
6.2. Justification of Right Margin (.SA)
6.3. Skipping Pages (.SK)
6.4. Forcing an Odd Page (.OP)
6.5. Setting Point Size and Vertical Spacing (.S)
6.6. Producing Accents
6.7. Two-Column Output (.2C, .IC)
6.8. Inserting Text Interactively (.RD)
6.9. SCCS Release Identification (RE)
6.10. Extending and Changing the Macros
6.10.1. Naming Conventions
6.10.2. Sample Extensions
6.11. Vertical Spacing (.SP)

7. Troubleshooting and Error Messages
7.1. Error Terminations
7.2. Disappearance of Output
7.3. Error Messages

8. Using the mm Command Line
8.1.
8.2.
8.3.
8.4.

Typical mm Command Lines and Options
Co·mmand Line Options for Specifying a Printer
Giving nroff or troff the mm Flag
Setting Number Registers from the Command Line

9. Appendices
9.1.
9.2.
9.3.
9.4.
9.5.

Appendix
Appendix
Appendix
Appendix
Appendix

A: mm Macro Name Summary
B: mm String Name Summary
C: mm Number Register Summary
D: ERROR MESSAGES
E: The Define File-/usr/lib/macros/strings.mm

mm: TECHNICAL DISCUSSION

88
88
89
90
90
91
93
93
95
96
96
96
97
100
101
101
101
102
103
103
105
106
106
110
110
116
117
121
126

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

9.6. Appendix F: Sample Footnotes
9.1. Appendix G: Formal Memorandum
9.8. Appendix H: Business Letter

128
131
134

TABLE OF CONTENTS

List of Figures
Figure 1: Arguments to the .AL Macro

Figure 2: Type and Mark for .LB

Figure 3: Appearance for Values of .LB Type

Figure 4: Arguments to the .FD Macro

Figure 5: Values for the Pv Number Register

Figure 6: The HF String

Figure 7: Arguments to the .DS Macro

Figure 8: Arguments to the .MT Macro

Figure 9: Arguments to .PM (Proprietary Markings)

Figure 10: Arguments to the .LT Macro and their Functions

Figure 11: Types Given to .LO and their Functions

Figure 12: Arguments to the .NS Macro

Figure 13: Arguments to the .SA Macro

Figure 14: Arguments to the.S Macro

Figure 15: Effects of the n Register on Page Numbering Style

LIST OF FIGURES

108

vII

1. Introduction
This is a technical discussion of the mm (Memorandum Macro) package,
a collection of macros that you use to format documents such as letters,
reports, memoranda, papers, manuals, and books. Macros are formatting
commands that combine the functions of one or more nroff or troff
requests.
Read this technical discussion if you have experience using the mm
package. If you have never used mm before, you first might want to read
"The Macro Package mm: a Tutorial" in the User's Guide. Once you decide
what macros you want to use, refer to this discussion for details about how
to use them.

1. 1. How this Technical Discussion is Organized
This first chapter offers definitions of terms that are basic to text processing, specifies conventions that this technical discussion uses, and
describes formatting concepts relevant to your use of Mm. It is provided to
enrich and clarify the discussion of each facility of mm that follows.
Assume that a document that you format with mm consists of four segments: a parameter setting segment, a beginning, a body, and an end.
"Chapter 2" discusses these segments, which provide the organizing principle for the rest of this technical discussion. "Chapter 3" presents macros
relevant to formatting the body of a document. In "Chapter 4," macros for
formatting the beginning of a document are described. "Chapter 5" explains
end macros. Finally, "Chapter 6" covers miscellaneous macros. In each of
these chapters, a macro's default formatting action is described followed by
ways to change this default behavior. For the most part, macros are
described starting with the simplest usage and progressing to more
advanced cases. It might be best to read a section in detail only to the point
where you have enough information to obtain the result that you want and
then to skim the rest.
After covering all mm macros, this technical discussion tells you about
troubleshooting and error messages in "Chapter 7." "Chapter 8" gives a full
account of using the mm command line to process the files you create.
Appendices are presented in "Chapter 9."

mm: TECHNICAL DISCUSSION

Introduction

1.2. Definitions
"Formatter" refers to either the nroff or the troff text-formatting program. These programs have their own tutorials in the User's Guide and their
own technical discussion in this book. Unless a functional distinction
requires otherwise, "the formatter" refers to both nroff and troff.
Requests are built-in commands recognized by the formatter. Although
you seldom need to use these requests directly when you use mm, this section contains references to some requests. For example, the request .sp
inserts a blank line in the output at the place that the request occurs in the
input file. Request names consist of two lower-case letters. For an introduction to nroff I troff, see "The Formatter nroff," or "The Formatter troff" in
the User's Guide. For details, refer to the "nroff/troff Technical Discussion"
in this book.
Macros are named collections of requests. That is, each macro is an
abbreviation for a collection of requests that are used repeatedly in the same
combination. Rather than typing them each time they are needed, you simply type the macro that calls them. Sometimes, macros are composed of
strings and number registers, which are described below.
The mm package supplies many macros, and you can define additional
ones. The names of mm macros consist of one or two upper-case letters, so
if you create your own formatting macros, name them with a lower-case and
upper-case letter, for example, .pD, to prevent usurping the function of an
mm macro. Appendix A, the "mm Macro Name Summary," gives a complete listing of mm macros.
Strings are character variables, each of which names a string of alphanumeric characters. Page headers, page footers, and lists often contain
strings. You give a string a value with the .ds (define string) request, and
you obtain its value by typing its name, preceded by "V"" (for I-character
names) or "Iff' (for 2-character names). For instance, the string DT in mm
normally contains the current date, thus the input line
Today is '*(D1'.

results in output such as this:
Today is Februa%y 24, 1986.

TECHNICAL DISCUSSION

Introduction
You can replace the current date by redefining the contents of this
string, for example,
.ds I11' 06/04185

or by invoking a macro designed for that purpose {4.1.3}. Appendix B provides the "mm String Name Summary."
Number registers, which are similar to integer variables, store the value
of various text parameters, such as the number of spaces between paragraphs (register Ps). The formatter program uses these registers for flags,
for arithmetic, and for automatic numbering. You can give certain registers
a value using the .nr request, and you can reference them by preceding
their names by \n (for I-character names) or \n( (for 2-character names, for
example, \n(Ps).
The following line creates a new number register d, and sets its value to
one more than that of another new register dd: .nr d 1+\n(dd. Some
number registers are read-only. That is, you can reference them, but you
cannot change their value. An "mm Number Register Summary" appears as
Appendix C to this technical discussion.

1.3. Conventions
Numbers enclosed in curly braces ({ }) refer to section numbers. For
example, this is section h.3}.
In the synopses of macro calls, square brackets «(]) surrounding an
argument show that it is optional. An argument in italics means that you
are to substitute a legal value for that argument. Ellipses (00.) show that the
preceding argument may appear more than once.
In cases where the behavior of the two formatters nroff and troff is
obviously different, the nroff formatter output is described first with the
troff formatter output following in parentheses. For instance,
The title is underlined (italic).
means that the title is underlined by the nroff formatter and italicized by
the troff formatter.

mm: TECHNICAL DISCUSSION

Introduction

1.4. Formatting Concepts
1.4. 1. Basic Terms
A formatter normally fills output lines from one or more input lines.
You may justify output lines so that both the left and right margins are
aligned. As you fill lines, you may also hyphenate words as necessary
(1.4.4}. It is possible to turn any of these modes on and off (use .SA {6.2},
Hy h.4.4}, and the .nf and .ft formatter requests). Turning off line filling
also. turns off justification and hyphenation.
Certain requests and macros cease line filling, print the input line (of
whatever length), and begin a new output line after the printed text. This
printing of a partially filled output line is known as a line break. A few
formatter requests and most of the mm macros cause a line break.
You can use formatter requests h.4.10} with mm, but there are consequences and side effects that each such request might have. Generally, you
should use mm macros alone because
• They are much easier to use, to control, and later to change the
overall style of the document.
• You obtain complex features (such as footnotes or tables of contents) with ease.
• You are freed from having to define many page control func~
tions in the nroff or troff languages.

1.4.2. Arguments and Double Quotes
For any macro call, a null argument is an argument whose width is
zero. The preferred form for a null argument, which often has a special
meaning, is "". Omitting an argument is not the same as supplying a null
argument (for example, see the .MT macro (4.1.1)). You can omit arguments
only at the end of an macro argument list, but you can place null arguments
anywhere in the list.

TECHNICAL DISCUSSION

IntroducUon

Enclose any macro argument containing ordinary (paddable) spaces in
double quotes, or mm will interpret the spaces as argument delimiters. A
double quote (") is a single character that must not be confused with two
apostrophes ('I), two acute accents ("), or two grave accents C').
You may not use double quotes as part of the value of a macro argument
or of a string that you use as a macro argument. If you must have double
quotes in a macro argument value, use two grave accents C') or two acute
accents (•• ) instead. This restriction is necessary because many macro arguments are processed a variable number of times.

1.4.3. Unpaddable Spaces
When the formatter justifies output lines to give an even right margin,
it may append additional spaces to existing spaces in a line. This may distort the desired alignment of text. To avoid this distortion, you must
specify a space that cannot be expandecl. during justification. There are two
ways to accomplish this:
• You may type a backslash followed by a space (\). These
characters directly generate an unpaddable space.
• You may use some seldom-used character to be translated into
a space on output.
Because this translation occurs after justification, you may use the
chosen character anywhere an unpaddable space is desired. The tilde C) is
often used with the translation request for this purpose. To use the tilde in
this way, put the follOWing request at the beginning of your document:
.tr -, where the tilde is followed by a space. If you must put a tilde in the
output, you can temporarily "recover" it by inserting .tr -- before the place
where you need it. Repeating the .tr· restores its usage as a space after a
line break or after the line containing the tilde has been flushed from the
line buffer.
You should not translate the tilde character into a space when you use it
within the .EQ and .EN macros or assigned eqn delimiters.

mm: TECHNICAL DISCUSSION

Introduction

1.4.4. Hyphenation
Formatters do not hyphenate unless you request it. You can turn on
hyphenation in the body of the text by typing the following request at the
beginning of the input file: .nr Hy 1-. Section 3.3.1 describes hyphenation
used within footnotes and across page boundaries.
If you request hyphenation, the formatters will automatically hyphenate
words as necesSary. However, you may specify hyphenation points for a
specific occurrence of any word with a special character known as a hyphenation indicator, or you may specify hyphenation points for a small list of
words (about 128 characters). If the hyphenation indicator (initially, the 2character sequence "\%") appears at the beginning of a word, the word is
not hyphenated. Alternatively, you can use the indicator to show legal
hyphenation points inside a word. All occurrences of the hyphenation
indicator disappear on output.

You may specify a different hyphenation indicator. The circumflex ("')
is often used for this purpose by inserting the following macro at the beginning of a document input text file: .HC ". Any word containing hyphens or
dashes (also known as em dashes) is hyphenated immediately after a
hyphen or dash if hyphenation is necessary, even if the hyphenation function is turned off.
You may supply (via the exception word .hw request) a small list of
words with the proper hyphenation points shown. For example, to show
the proper hyphenation of the word "printout," you may specify .hw printout.

1.4.5. Tabs
The macros .MT {4.1.1}, .TC {S.4}, and .CS {S.6} use the formatter tabs
.ta request to set tab stops. The default values of tab settings are every eight
characters in the nroff formatter, and every lh inch in the troff formatter.
You may set tabs to other values.
For the nroff formatter, default tab setting values are 8, 16, 24, 32, 40, ...,
160 characters for a total of 20 tab stops. That is, the default tab settings
correspond to the follOWing example:
.ta 8 16 24 32 40 48 56 64 72 • . . 160

TECHMCALD~CUSmON

Introduction

You may separate tab settings with commas, spaces, or any other nonnumeric character. You may set tab stops in any horizontally oriented scale.
The formatter interprets a tab character with respect to its position on
the input line rather than its position on the output line. In general, you
should only put tab characters on lines after you turn off line filling (.nf)
h.4.10l. The tbl program {3.7} changes tab stops but does not restore
default tab settings.

1.4.6. Bullets
The troff formatter provides the bullet character (.). For compatibility
with troff, mm also provides a bullet string: \ ·(BU. The bullet list (.BL)
macro (3.2.5) uses this string to generate automatically the bullets for bullet
listed items.

1.4.7. Dashes, Minus Signs, and Hyphens
The troff formatter distinguishes among the dash, the minus sign, and
the hyphen, but the nroff formatter does not.
•

If you intend to use nroff, you may only use the minus sign
(-) for the minus, hyphen, and dash.

• If you plan to use troff primarily, you should follow troff

escape conventions.
•

If you plan to use both formatters, take care during input text
file preparation. Unfortunately, these graphic characters cannot be represented in a way that is both compatible and convenient for both formatters.

The following approach is suggested:
Dash

Type "\ "(EM" for each text dash for both nroff and troff formatters. This string generates an em dash in the troff formatter and two dashes (--) in the nroff formatter. Dash list
(.DL) macros {3.2.S} automatically generate the em dash for
each list item.

Hyphen

Type" - and use as is for both formatters. The nroff formatter will print it as is. The troff formatter will print - (a
true hyphen).
II

mm: TECHNICAL DISCUSSION

Introduction

Minus

Type "\-" for a true minus sign regardless of formatter. The
nroff formatter will ignore the \. The troff formatter will
print - (a true minus sign).

1.4.8. Trademark String
A trademark string \ It(Tm is available with Mm. This places the letters
"TM" one-half line above the text that it follows. For example,
The

.I
UNIX\f 1\* (1m
System V User's Guide

.R
is available fran the library.

yields
The
UNIX™

Systt'''' V User's Guide
is available from the library.

1.4.9. BEL Character
Many macros use the non-printing character BEL as a delimiter to compute the width of an argument or to delimit arbitrary text in page headers
and footers {3.4}, headings {3.5}, and lists {3.2}. This is to decrease the possibility that an argument might contain a character identical to one delimiting it, which would produce undesirable results.

1.4.10. Use of Formatter Requests
You need not use most formatter requests with mm since it provides the
corresponding formatting functions in a more straightforward fashion. The
following requests can be useful with mm:

TECHNICAL DISCUSSION

Introduction

.af

Assign format

.br

Break

.ce

Center

.de

Define macro

.ds

Define string

.li

Fill output lines

.ft

Change font

.hw

Exception word

.Is

Line spacing

.nf

No filling of output lines

.nr

Define and set number register

.nx

Go to next file (does not return)

.rm

Remove macro or string

.rr

Remove register

.rs

Restore horizontal spacing

.so

Switch to source file and return

.sp

Space

.ta

Tab stop settings

.ti

Temporary indent

.tl

Title

.tr

Translate

.sy

Issue command(s) to UNIX system

The .fp, .lg, and .55 requests are sometimes useful for the troff formatter. In general, it is best not to use too many troff requests in conjunction with mm.

mm:

TECHNICAL DISCUSSION

2. The Structure of a Document
A document that you format with mm consists of four segments, any of
which you may omit. If you include any of these segments, you must put
them in the following order:
. • The parameter setting segment sets the general style and
appearance of a document. Here, you control page length and
width, margin justification, numbering styles for heading and
lists, page headers and footers, proprietary markings, among
other properties of the document. Also, you can add macros or
redefine existing ones. You can omit this segment entirely if
you are satisfied with mm's default values; the segment produces no output but performs only the formatter setup for the
rest of the document. Here is an example of a parameter setting
segment:

.or Ls 0

specifies that no spacing occurs between any list
items

.or Cl 4

saves up to 4th level section headings for table of
contents

.or Pi ,

sets paragraph indentation to 7 spaces

.or Hs 4

specifies a line of space between text and section
headings up to 4th level

• The beginning consists of those items that occur only once at
the start of a document: a memorandum title, names, the date,
and so on. Here is the beginning of a formal memorandum:

.PM PM3

specifies a proprietary marking of
"SEE PROPRIETARY NOTICE ON COVER PAGE"

.Tt

specifies that line following the macros, "Work
Report," is the title

.AU "J. Smith" JS
formats information about the author, "J. Smith"

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - The Structure of a Document

.MT

sets the formal memorandum type

Here is the beginning of a business letter:
.WA

signals the beginning of the writer's address

.WE

signals the end of the writer's address

.fA

signals the beginning of the addressee's address

.IE

signals the end of the addressee's address

.LO SA "Dear Jane,"
sets the letter's salutation to "Dear Jane,"
.LT BL

specifies a Blocked type business letter

• The body of a document is the text itself. It may be as little
text as a single paragraph or as much as hundreds of pages.
It may have a hierarchy of section headings up to seven levels deep {3.S}, and you may automatically number section
headings and save them to generate the table of contents.
mm provides five additional levels of subordination by a set
of list macros for automatic numbering, alphabetic sequencing, and "marking" of list items {3.2.1}. You can put various
types of displays {3.6}, tables {3.7}, figures {3.9}, equations
{3.8}, references {S.7}, and footnotes {3.3} in the body.
• The end contains items that usually occur at the close of a
document. Included are signature(s), and lists of notations
(for example, 'Copy to' lists) {S.3}, which may occur at the
beginning of the document (4.2.1}.) You may call certain
macros at the end to print information that is wholly or partially derived from the rest of the document such as the table
of contents or the cover sheet {S.6}.
For example,
.FC

prints the formal closing, "Yours very truly,"

.SG

prints the name(s) specified with .AU

.NS

begins a "Copy totl list

mm: TECHNICAL DISCUSSION

The Structure of a Document

.NE

signals the end of the "Copy to" list

.TC

generates a table of contents

The existence and size of these four segments varies widely among
different document styles. Although a specific item of a segment (such as
date, title, author names, and so on) may differ depending on the document,
there is a uniform way of typing it into an input text file. To make it easy
to edit or revise input file text at a later time:
• Keep input lines short.
• Break lines at the end of clauses.
• Begin each new sentence on a new line.

TECHNICAL DISCUSSION
\

3. Formatting the Body of a Document
3.1. Formatting Paragraphs (.P)
To use oP, which stands for paragraph, your input would look like this:
oP [type]
Text

oP without an argument forces left justification (the first line begins at
the left margin), as does oP O. oP 1 indents the first line five spaces unless
you specify another amount of indentation by changing the value contained
in the number register Pi. For example, to indent particular paragraphs ten
spaces, type the following line once at the top of your file: onr Pi 10 and
then use oP 1 before every paragraph that you want indented.

3. 1.1. Paragraph Type (Pt)
Suppose that you want all paragraphs indented. Rather than type oP 1 ,
you can set the Pt number register, which controls the paragraph type. The
initial value of Pt is 0, which provides left-justified paragraphs. Force every
paragraph in your output to be indented by inserting the follOWing line at
the beginning of the document input file: onr Pt 1. You may specify the
amount of indentation by setting Pi as before if you do not want to use the
default.
Indent all paragraphs except after headings, lists, and displays (discussed below) by entering the follOWing at the beginning of your document
input file: onr Pt 2.
Both the Pi and Pt register values must be greater than zero to indent
paragraphs. Values that you use to specify indentation must be unsealed
and are treated as character positions (ens). nroff understands an en to be'
equal to the width of a character. troff understands an en to be the number
of points (1 point - 1/72 of an inch) equal to half the current point size.
Regardless of the value of Pt, .P 1 causes indentation by the amount
specified by the register Pi. If oP occurs inside a list, the indent (if any) of
the paragraph is added to the current list indent {3.2.1}.

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

3.1.2. Numbered Paragraphs (Np)
Produce numbered paragraphs by setting the Np register to 1, which
numbers paragraphs within first level headings. Use the .nP macro rather
than the .P macro to produces paragraphs that are numbered within second
level headings.
•H 1 "FIRST HEADDG"

•H 2 "5ec:x:I1d Head:in]"
.nP
'!hese numbered paragraphs cxmtain a "double-line i.rxient,"
in which tile text of the seoond line aligns with tile text
of the first line, so that the number stands cut.
'!he th.i%d and followiD] lines of a numbered paragralil retuxn
to the left margin.

produces
-

1 -

1. 01 These numbered paragraphs contain a "double-l ine
indent."
in which the text of the second line aligns with the text of
the first line. so t~at the number stands out. The third and
follo~ing lines of a numbered paragraph return to the left
margin.

3. 1.3. Spacing Between Paragraphs (Ps)
The Ps number register controls the amount of spacing between paragraphs. By default, the formatter sets Ps to 1, yielding one blank space
(one-half vertical space). Giving Ps a value of 0 yields no space between
paragraphs.

TECHNICAL DISCUSSION

Formatting the Body of a Document

3.2. Formatting Lists
3.2. 1. General Characteristics of Lists
mm provides a convenient way to create lists automatically. All lists are
composed of three basic parts:
• A list-initialization macro determines the line spacing, indentation, marking with special symbols, and numbering or
alphabetizing of list items. Available list-initialization macros
are
.AL

Automatically Incremented List

.ML

Marked List

•VL

Variable-Item List

.BL

Bullet List

.DL

Dash List

.RL

Reference List

If you do not provide arguments to the list-initialization macro, text
will be indented by a default number of spaces from the indent
currently in force. This default varies as a function of what type of
list you call. Change the indentation value by placing the desired
indentation into the number register Li.

• One or more list-item macros (.LI) identifies each item in
your list. List-item macros are followed by the text of the
corresponding list item:
.LI [mark [1] ]

Text

Use the .LI macro with all list types and for each list item.•LI normaily
causes output of a single blank line before its list item although you may
suppress this feature by setting the Ls (list space) register. Ls is set to the
innermost list level in nested lists for which spacing is done. For example,
.nr Ls 0 specifies that no spacing will occur around any list items. The
default value for Ls is 6 (which is the maximum list nesting level).

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

You may supply arguments to .lI.
•

If you give .lI no arguments, it labels the item with the mark
specified by the most recent list-initialization macro (for example, .Bl sets the mark to be a bullet).

• If you give .lI a single argument, that argument is output

instead of the current mark.
• If you give .lI two arguments, the first argument becomes a

prefix to the current mark, allowing you to emphasize one or
more items in a list.
For example,
.BL

.LI
This is a bullet item.
.LI +

This replaces the bullet with a "plus."
.LI + 1

This uses a "plus" as prefix to the bu1let .
•LE

when formatted yields
-

1 -

This is a bullet item.

+ This replaces the bullet with a "plus."
+ ~ This uses a "plus" as prefix to the bullet.

Do not put ordinary (paddable) spaces into the mark because the alignment of items is lost if you justify the right margin {1.4.3}.
If the current mark in the current list is a null string, and the first argument of .lI is omitted or null, the resulting effect is that of a hanging
indent. That is, the first line of the following text is "outdented, starting at
the same place where the mark would have started {3.2.4}. The list-end
macro (.lE) ends the list: .LE [1]. If you specify an argument to .LE, it outputs a blank line.
II

TECHNICAL DISCUSSION

Formatting the Body of a Document

The list-initialization macro saves the previous list status (indentation
marking style, and so on), and changes the status to that of the new initialization macro. The list-end macro restores the status of the previous list
unless there is no previous list. In that case, the list-end macro restores the
status to that existing before the list-initialization macro call. This information about list status is important to remember when you format nested"
lists, which are described below.

3.2.2. Automatically Incremented Lists (.AL)
.AL stands for automatically incremented list. The general syntax of the
macro is as follows: .AL [type [text-indent [1] ] ].
If you do not specify arguments, the list is numbered, and text is
indented the value of Li, initially six (five) spaces from the indent in force
when the .AL is called, leaving room for a space, two digits, a period, and
two spaces before the text.
Do not scale values that specify indentation. These values are scaled in
terms of "character positions" (ens).

Specifying a type produces a different type of sequencing. The value of
type in the table below shows the first element in the sequence desired.
Argument
1
A
a
I
i

Interpretation
Arabic (default for all levels)
Upper-case alphabetic
Lower-case alphabetic
Upper-case roman
Lower-case roman

Figure 1: Arguments to the .AL Macro

If you specify a text-indent argument, the formatter uses it as the number
of spaces from the current indent to the text of the list items. This value
overrides that in Li for the list where you use the argument.

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

If you give a third argument, a blank line will not separate items in the
list. However, a blank line will occur before the first item.

3.2.3. Marked Lists (.ML)
The .ML macro expects you to specify an arbitrary mark that may consist
of one or more characters: .ML mark [text-indent [1]]. Text is indented textindent spaces if the second argument is not null; otherwise, the text is
indented one more space than the width of mark. If the third argument is
specified, no blank lines will separate items in the list.
Do not put ordinary (paddable) spaces into the mark because the alignment of items is lost if you justify the right margin. Here's a file containing
a marked list before formatting:
.ML $
.LI

sales are up•
•LI

Profits are up•
•LE

Here's that same list after formatting:
- 1 -

Sales are up.

Profits are up.

3.2.4. Variable-Item Lists (.VL)
Another version of the marked list is the "variable-item" list that you
call with the .VL macro: .VL text-indent [mark-indent [1]]. When you begin
a list with a .VL macro, there is effectively no current mark; you provide
each .LI its own mark. This form is typically used to display definitions of
terms or phrases.

TECHNICAL DISCUSSION

Formatting the Body of a Document

.tr ..
•VL 1.0
.LI requests

are the nost elementa%y text-fcmnatting ocamand available with
IXXXJMENI'm'S ~ Software •
.LI macros
are collections of simple fcmnatting c:x:moams called by a
sin]le name •
•LI denonstratian_of_a_long}llark:
This item sOOws the effect of a long mark; one space
separates the mark fran the beginn:in; of the text.
. LI ..

This item effectively has no mark because the tilde
is translated into a space .
•LE

when formatted yields
- 1 -

No hyphenation. Automatic hyphenation is turned off. Words
containing hyphens (for example, mother-in-law) may still
be split across lines.
Hyphenate.

Automatic hyphenation is turned on.

Hyphenation indicator character is set to "c" or removed.
During text processing, the indicator is suppressed and
will not appear in the output. Prepending the indicator to
a word has the effect of preventing hyphenation of that
word.

As with the other list types, text-indent provides the distance from
current indent to beginning of the text. Mark indent produces the number
of spaces from current indent to beginning of the mark, and it defaults to 0
if omitted or null. If you specify a third argument, no blank lines will
separate items in the list. Again, do not put ordinary (paddable) spaces into
the mark because the alignment of items is lost if you justify the right margin.

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

3.2.5. Bullet, Dash, and Reference Lists (.DL, .DL, .RL)
To initialize any of these

lists~

type: .BL or .DL or .RL [text-indent [1] ]

A bullet (e) followed by one space marks each list item. As always, if
you specify a text-indent argument, it overrides the default indentation. In
the default case, the text of a bullet list lines up with the first line of
indented paragraphs (set with the number register Pi {3.1}).
With each of these list types, no blank lines will separate items in the
list if you specify a second argument. A dash ( - ) followed by one space
marks each list item of a dash-list. Here's an example of input:

.DL
.LI
Prepare documents am tables
.LI

Develop new macro cxmoands
.LE
- 1 -

- Prepare documents and tables
- Develop new macro commands

An .RL macro call begins an automatically numbered list that encloses
the numbers in square brackets ([]).
Here's the input:
.RL 8 1
.LI
~'s ~

USer's Guide

.LI
~'S ~

Technical Discussicm

and Reference Manual
.LI
~'S ~

.LE

The output is as follows:

TECHNICAL DISCUSSION

Handbook

FormaUlng the Body of a Document

- 1 -

[ 1]
[2]

DOCUMENTER' S WORKBENCH User' s Guide
DOCUMENTER' S WORKBENCH Technical Discussion and
Ref erence Manual
[ 3 ] DOCUMENTER • S WORKBENCH Handbook

3.2.6. Nested Lists
Lists may be nested up to six levels. Here is an example of nested lists:
.AL
.LI

Develop metmds for produciD]

cJoomentatian
.LI

Perfcmn duties resultiDJ fJ:aD the developnent of tl1ese methods.
Far example,
.BL
.LI

Use text processiD] to:
.DL
.LI

Prepare documents

tables

.LI

Develop new macro
.LE

c:::cmnams

.LI

serve

as a point of cxmtact with printers

distributors .
•LE
.LI
If tl1e jd) b>lder's interests am writing skills match tl1e
needs of the Technical Writing Staff t

write documents •
•LE

Here's how that same list looks after it has been formatted.

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

1.
2.

1 -

Develop methods for producing documentation
Perform duties resulting from the development of these
methods. For example:
~

Use text processing to:
- Prepare documents and tables
- Develop new macro commands

Serve as a point of contact with printers and
distributors.

If the job holder's interests and writing skills
matched the needs of the Technical Writing Staff,
there might be an opportuni ty to wri te documents.

In this example, the first list-initialization macro that occurs is .At. Since
you specify no argument f9r .AL, the formatter numbers list items in
sequence with Arabic numerals. Before the list-end macro associated with
.AL occurs, another list-initialization macro appears, .Bt. Now, a bullet
marks each list item. Finally, .DL marks list items with dashes. When the
.LE associated with .DL occurs, a bullet marks list items again, since .BL was
the list-initialization macro active before the dash list. When.LE ends the
bullet list, list items are numbered until .LE occurs again.
Every time a new list-initialization macro occurs, the list status (indentation, marking style, and so on) changes..LE restores the status generated
by the immediately preceding list-initialization macro.

3.2.7. List-Begin Macro and Customized Lists
List-initialization macros described above suffice for almost all cases.
However, you may obtain more control over the layout of lists by using the
basic list-begin macro (.LB). The syntax is as follows:
.LB text-indent lJIark-indent pad type [mark [LI-space [LB-space ] ]

The other list-initialization macros use .LB. Its arguments are as follows:

TECHNICAL DISCUSSION

FormaUlng the Body of a Document

• The text-indent argument that provides the number of spaces
that text indents from the current indent. Normally, this value
is taken from the Li register (for automatic lists) or from the Pi
register (for bullet and dash lists).
• The combination of mark-indent and pad arguments determines
the placement of the mark. The mark is placed within an area
(called mark area) that starts mark-indent spaces to the right of the
current indent and ends where the text begins (that is, ends
text-indent spaces to the right of the current indent). The markindent argument is typically O.
• Within the mark area, the mark is left justified if the pad argument is O. If pad is a number n (greater than 0), then n blanks
append to the mark; the mark-indent value is ignored. The
resulting string immediately precedes the text. The mark is
effectively right justified pad spaces immediately to the left of
text.
• The arguments type and mark interact to control the type of
marking used. If type is 0, simple marking is performed using
the mark character(s) found in the mark argument. If type is
greater than 0, automatic numbering or alphabetizing is done;
and mark is then interpreted as the first item in the sequence to
be used for numbering or alphabetizing. That is, it is chosen
from the set (1, A, a, I, i) {3.5.2.6}. This is summarized below:
Type

Mark

omitted
string
omitted

1, A, a, I, i

0
0

Result
hanging indent
string is the mark
Arabic numbering
automatic numbering or
alphabetic sequencing

Figure 2: Type and Mark for .LD

Each non-zero value of type from one to six selects a different way
of displaying the marks. The following table shows the output
appearance for each value of type, where x is the generated number

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

or letter:
Value

Appearance

1
2
3

x.
x)
(x)

[xl

5
6

(xl

Figure 3: Appearance for Values of oLD Type

• Do not put ordinary (paddable) spaces in the mark.
• The LI-space argument gives the number of blank lines (each
one-half of the current vertical spacing) that should be output
by each .LI macro in the list. If omitted, LI-space defaults to 1;
use the value 0 to obtain compact lists. If LI-space is greater than
0, the .LI macro issues a one request for two lines just before
printing the mark.
• The LB-space argument is the number of blank lines (each onehalf the vertical spacing) to be output by .LB itself. If omitted
LB-space defaults to O.
There are three combinations of LI-space and LB-space:
• The normal case is to set LI-space to 1 and LB-space to 0 yielding
one blank line before each item in the list; such a list is usually
ended with a oLE 1 macro to end the list with a blank line.
• For a more compact list, Ll-space is set to 0, LB-space is set to 1,
and the . LE macro is used at the end of the list. The result is a
list with one blank line before and after it.
• If both LI-space and LB-space are set to 0 and the .LE macro is

used to end the list, a list without any blank lines will result.

TECHNICAL DISCUSSION

Formatting the Body of a Document

3.2.8. Defining List Structures
This section is intended only for people who write formatter macros. If
you have not written macros, or if you are content with the lists that mm
provides by default, you may skip this section. To learn about writing macros, check the "User's Guide" for "The Formatter nroff," "The Formatter
troff," and check this book for the "nroff/troff Technical Discussion."

If a large document requires complex list structures, it is useful to be
able to define the appearance for each list level only once instead of having
to define it at the beginning of each list. For example, you might define a
generalized list-initialization macro in such a way that causes each listnesting level to behave differently from its predecessor or successor. Suppose you want levels 1 through 5 of lists to have the following appearance:
-

1 -

[1]

a)
+

The following code defines a macro (.aL) that always begins a new list
and determines the type of list according to the current list level. As the
example demonstrates, the mm list macros use the number register :g to
determine the current list level; it is 0 if there is no currently active list.
Each call to a list-initialization macro increments :g, and each .LE call decrements it.

mm: TECHNICAL DISCUSSION

FormaUlng the Body of a Document

.de aL
.\"
.\"

.nr 9 \nC:9
.if
.i f
.if
.if
.if

\\ng=O .AL
\\ng=1 .LB
\ \ng=2.BL
\ \ng=3 .LB
\\ng=4 .M[,

A \" give me an A•

\nCLi. 0 1
\ It give
\nCLi. 0 2
+ V' give

4
me a bullet

2 a

me a +

Now, you can use this macro (with .LI and .LE) instead of .AL, .RL, .BL,
.LD, and .ML. For example, the following input:
.aL
.LI

first line .
•aL
.LI

second line •
•LE
.LI

third line •
•LE

will yield
-

1 -

first line.
[ 1] second line.

third line.

You could take another approach to lists that is similar to the .H
mechanism. The list-initialization as well as the .LI and the .LE macros are
all included in a single macro. That macro (called .bL below) requires an
argument to tell it what level of item is required; it adjusts the list level by
either beginning a new list or setting the list level back to a previous value,
and then it issues a .LI macro call to produce the item:

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - Formatting the Body of a Document
.de bL

· \"
.ie
· \"
.el
.if
· \"
· \"
· \"
.if

if argument, that is the level
\\n(.$ .nr 9 \\$1
if no argument, use current level
.nr 9 \ \n( :g
(\\ng-\\n( :g»1 .)D "
SKIPPnG OF LEVEL "
increasing level by uore than 1
if 9 > :9, begin new list
and reset 9 to current level (.aL chaD]es 9)

··ILLmAL

\\ng>\\n(:g \{.aL \\nq-1
nr 9 \ \n( :g\}
· \" if :g > 9, prune back to oorrect level
.if \\n( :g>\\nq .I.C \\ng
· \"
if :9 = 9, stay wi.thin current list

.LI

\" always, get out an item

Calling .bL without arguments causes it to stay at the current list level.
The .LC macro (List Clear) removes list descriptions until the level is less
than or equal to that of its argument. For example, the .H macro includes
the ".LC 0" call. If you want to resume text at the end of a list, insert the
call ".LC 0" to clear out the lists completely. The example below illustrates
the small amount of input needed by this approach. The input text
The quick brown fax jumped over the lazy dog's back .
•bL 1
first line .
•bL 2

secxmd line .
•bL 1

third line .
•bL

fourth line .
.Il: 0
fifth line.

yields

mm: TECHNICAL DISCUSSION

FormaUlng the Body of a Document

- 1 -

The quick brown fox jumped over the lazy doC}' s back.
A.

first line.
[ 1] second line.

third line.

c. fourth line.
fifth line.

3.3. Footnotes (.FS, .FE)
There are two macros that delimit the text of a footnote. The .FS (footnote start) macro marks the beginning of the text of a footnote, and the .FE
(footnote e~d) macro marks the end:
.FS [label]

Footnote text
.FE

These macros form a macro pair; you cannot use one macro without the
other. Mark the footnoted line of your paper or memo with '·F" or with
the optional label. If you mark your footnoted line with '·F," do not supply
a label with .FS; footnotes wil~ be numbered automatically. If you use a
footnote label, follow .FS with the label you have chosen (.FS label).
The footnote text (enclosed within the macro pair) should immediately
follow the word that you footnote in the input text, so that "'·F or label
occurs at the end of a line of input and the next line is the .FS macro call.
Consider the following examples. The first is input for a numbered footnote:
It

'!his is the line oantai.n:iDI the word\*F
.FS

'!his is the text of the footnote .
•FE
to be footnoted.

TECHNICAL DISCUSSION

Formatting the Body of a Document

Next is a labeled footnote:
1hi.s is a labeled.FS *
The footnote is labeled with an asterisk.
•FE

footnote.
Appendix F shows "Sample Footnotes."
Your memo or paper may contain both user-labeled and automatically
numbered footnotes. Another .FS, a .DS (static display (3.6.1}), or a .DF (a
floating display (3.6.2}) are not permitted between .FS and .FE macros. If
you do not end the text of a footnote with .FE, you will probably cause a
formatter error. If you require footnotes in the title, the abstract or in a
table, note that only labeled footnotes appear properly. Everywhere else,
automatically numbered footnotes work fine.

3.3.1. Changing the Format of Footnote Text (.FD)
Use .FD to control the hyphenation, right margin justification, and
indentation of footnote text, and to control left or right justification of the
footnote label when you indent footnote text: .FD [arg [1] ].
The leftmost column of the following table shows the legal arguments
to .FD [arg]. The rema.ining four columns show the hyphenation,
justification and indentation that you obtain with each value of [arg]. For
additional information concerning the .ad, .na, .hy, and .nh requests (which
stand for adjust, no adjust, hyphenation, and no hyphenation, respectively),
see the "nroff/troff Technical Discussion" in this book.

mm: TECHNICAL DISCUSSION

Forma"lng the Body of a Document

Hyphenation

Adjust

Text
Indent

Label
Justification

O·

.nh

.ad

yes

left

.hy

.ad

yes

left

.nh

.na

yes

left

.hy

.na

yes

left

.nh

.ad

left

.hy

.ad

left

.nh

.na

left

.hy

.na

left

.nh

.ad

yes

right

.hy

.ad

yes

right

10··

.nh

.na

yes

right

.hy

.na

yes

right

Argument

• default for the mmt command line
.. default for mm command line

Figure 4: Arguments to the .FD Macro

TECHNICAL DISCUSSION

Formatting the Body of a Document

An argument of 11 or greater is equivalent to .FD O. The effect of a null
or omitted argument varies according to the command line you use to process your file. If you use the mm command, a null or omitted argument is
equivalent to .FD 10; if you use the mmt command, a null or omitted argument is equivalent to .FD O.
If you specify the second argument, automatically numbered footnotes
begin again with 1 when a first-level heading is encountered. This is most
useful with the "section-page" page numbering scheme. As an example, the
input line .FD "" 1 maintains the default formatting style and causes footnotes to be numbered afresh after each first-level heading in a document.

Hyphenation across pages is inhibited by mm except for long footnotes
that continue to the following page. If you permit hyphenation, it is possible for the last word on the last line on the current page footnote to be
hyphenated. To avoid this, you may specify an even .FD argument.
Footnotes are separated from the body of the text by a short line rule.
Those that continue to the next page are separated from the body of the text
by a full-width rule. In the troff formatter, footnotes are set in type two
points smaller than the point size used in the body of text.

3.3.2. Spacing Between Footnote Entries (Fs)
Normally, one blank line (a 3-point vertical space) separates footnotes
when more than one occurs on a page. To change this spacing, set the Fs
number register to the desired value. For example, .nr Fs 2 will cause two
blank lines (a 6-point vertical space) to occur between footnotes.

3.4. Page Headers and Footers
A page header (or header) is text that occurs at the top of pages, while a
page footer (or footer) occurs at the bottom of pages. By default, the mm
macro package centers the page number surrounded by dashes at the top of
every page (except the first page of a formal memorandum) and does not
print a page footer.
Change this default by using a mm page header macro or a page footer
macro. Usually, you change a header or footer once at the beginning of the
document, but you may change the header or footer as many times as you
wish. You may specify a line on every page, a line on the even page only,
and a line on the odd page only; thus, the header and footer may contain as

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

many as two lines of text: the line printed at the top of every page and the
line for the even- or odd-numbered page.

3.4. 1. Page Headers (.PH)
Use the .PH macro to specify a header for the top of every page: .PH
[arg]. The initial value of [arg] for .PH is the centered page number sur-

rounded by dashes.
For all header and footer macros (.PH, .EH, .OH, .PF, .EF, and .OF) the
argument [arg] is of the form:
II '

left-part' center-part' right-part'

The formatter left justifies the left-part, centers the center-part, and
right justifies the right-part of the header or footer argument that you provide. For example,
.PH

John smith' , Teclmical Writing Staff'

produces
John Smith

Technical Writinq Staff

at the top of every page of the document (after you call .PH). In the example above, the center part of the header is left unspecified. If it is inconvenient to use apostrophe ('~) as the delimiter because an apostrophe occurs
within one part, you may uniformly replace the apostrophe with any other
character. For example,
If

-Let's put this left-This center-Let's put this riqht- II

3.4.2. Even-Page Header and Odd-Page Header (.EH, .OH)
The .EH macro supplies a line to be printed at the top of each evennumbered page immediately following the page header: .EH [arg]
The .OH macro is the same as the .EH except that it applies to oddnumbered pages: .OH [arg). The initial value of [arg] for both .EH and .OH
is a blank line.

3.4.3. Page Footer (.PF)
The .PF macro specifies the line that is to appear at the bottom of every
page: .PF [arg]. The initial value of the page footer is a blank line.

TECHNICAL DISCUSSION

Formatting the Body of a Document

3.4.4. Even-Page Footer, Odd-Page Footer, and First-Page Footer
(.EF, .OF)
The .EF macro supplies a line to be printed at the bottom of each evennumbered page immediately preceding the page footer: .EF [arg]. The .OF
macro supplies a line to be printed at the bottom of each odd-numbered
page immediately preceding the footer: .OF [arg]. The initial value of these
footers is a blank line.

3.4.5. Headers and Footers for the Memorandum and Released
Paper Style
In a memorandum or a released-paper style document, the page header
on the first page is automatically suppressed provided a break does not
occur before the .MT macro is called. Macros and text in the following
categories do not cause a break and are permitted before the memorandum
types (.MT) macro:
• Memorandum and released-paper style document macros
(.TL, .AU, .AT, .TM, .AS, .AE, .OK, .ND, .AF, .NS, and .NE)
• Page headers and footers macros (.PH, .EH, .OH, .PF, .EF, and
.OF)
• The .nr and .ds requests.

3.4.6. Strings and Registers in Header and Footer Macros
String and register names may be placed in arguments to header and
footer macros. If the value of the string or register is to be computed when
the respective header or footer is printed, invocation must be escaped by
four backslashes. This is because string or register invocation is processed
three times:
1. As the argument to the header or footer macro
2. In a formatting request within the header or footer macro
3. In a

.n request during header or footer processing.

In paragraphs, you only need one backslash (for example, \nP). In a page
header, you need four; in a static display, you need two, and so on.

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

For example, the mm page number register P must be escaped with four
backslashes to specify a header in which the page number is to be printed at
the right margin, for example: .PH"" 'Page \\\\nP'" creates a right-justified
header containing the word "Page" followed by the page number. Similarly, to specify a footer with the "section-page" style, you specify .PF ""'\\\\n(Hl-\\\\nP -'"
If you make the string a] contain the current section heading that is to

be printed at the bottom of each page, the .PF macro call is .PF "''\\\\·(aT'''.
If you use only one or two backslashes, the footer would print a constant value for al namely, its value when .PF appeared in the input text.

3.4.7. Top and Bottom (Vertical) Margins (.VM)
The .VM (vertical margin) macro allows you to specify additional space
at the top and bottom of the page: .VM [top] [bottom]. This space precedes
the page header and follows the page footer. A null top or bottom argument
or an argument of 0 puts no additional space before the header or after the
footer.
top and bottom are two unsealed arguments that are treated as v's
(default vertical line spaces: see the "nroff/troff Technical Discussion"). For
example, .VM 10 15 adds 10 blank lines to the default top of page margin
and 15 blank lines to the default bottom of page margin. Both arguments
must be positive (you may decrease default spacing at the top of the page by
redefining .TP (3.4.9}).

3.4.8. Private Documents (Pv)
The word "PRIVATE" may be printed, centered, and underlined on the
second line of a document (preceding the page header). This is done by setting the Pv register value: .nr Pv value. Possible values are as follows:
Value

o
1

Meaning
do not print PRIVATE (default)
PRIVATE on first page only
PRIVATE on all pages

Figure 5: Values for the Pv Number Register

TECHNICAL DISCUSSION

Formatting the Body of a Document

If value is 2, the user definable .TP macro may not be used because mm
uses the .TP macro to print "PRIVATE" on all pages except the first page of a
memorandum on which .TP is not invoked.

3.4.9. Generalized Top-at-Page Processing
This section is intended only for people who write formatter macros. If
you have not written macros, or if you are content the way that mm handles top-of-page processing by default, you may skip this section.

During header processing, mm invokes two user-definable macros:
• The .TP (top of page) macro is invoked in the environment
(refer to .ev request) of the header.
• The .PX is a page header user-exit macro that is invoked
(without arguments) when the normal environment has been
restored and with the "no-space" mode already in effect.
The effective initial definition of .TP (after the first page of a document)
is
.de TP
.sp 3
.tl \\*( }t
.i£ e 'tl \\*( }e
.if 0 'tl \\*( }o
.sp 2

The string It contains the header, the string }e contains the even-page
header, and the string }o contains the odd-page header as you define them
with the .PH, .EH, and .OH macros, respectively. To obtain more specialized page titles, you may redefine the .TP macro {3.5}. Formatting done
within the .TP macro is processed in an environment different from that of
the body. For example, to obtain a page header that includes three centered
lines of data (document number, issue date, and revision date) you could
define the .TP as follows:

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

.de TP

.sp

.ce 3
777-888-999
Iss. 2, AUG 1985
Rev. 7, 5EP 1985
.sp

Use .PX as a user-defined macro to specify text that you want to appear
at the top of each page after the normal header.
.de PX

.ce
RES'mIcrED

INroRMATI~:

RJR YCXlR EnS cm.,y

3.5. Section Headings (.H)
mm provides two types of section headings: numbered and unnumbered. To create a numbered section heading, type
.H level [heading-text [heading-suffix] ]
Text

The level argument provides the numbered heading level. There are
seven heading levels; level 1 is the highest, level 7 is the lowest. The
heading-text argument is the text of the heading. For example,
.H 1 IlFIRST-LEoVEL HEADIM;II
•H 2 "5eoand-level headi.rq"
.H 3 "'lbi.m-level head:iDi'
.H 1 "AtClHER FIRST-LEVEL HEADIM;"
.H 2 "Another second-level headingll
.H 3 IIAnother third-level headi.rq"
.H 4 "Fourth-level headi.rqll
.H 3 "Still anotlier third-level headingll
.H 5 IlFifth-level headi.rq"

TECHNICAL DISCUSSION

FormaUlng the Body of a Document

produces output like this:
1.
1.1

FIRST-LEVEL HEADING
Second-level heading

1.1.1

2.
2.1

Third-level heading

ANOTHER FIRST-LEVEL HEADING
Another second-level heading

2.1.1

Another third-level heading

2.1.1.1
2.1.2

Fourth-level heading

Still another third-level heading

2.1.2.0.1

Fifth-level heading

Enclose the argument in double quotes if the heading contains more
than one word or contains spaces. One word of heading-text does not
require quotes.
In the example above, using a fifth-level heading immediately after a
third-level heading makes the value of level 4 become zero. Unless you
conform to the hierarchy of headings (using a second-level heading after a
first-level heading, and so on), you might obtain results that you do not
want.
The heading-suffix argument may be used for footnote marks that should
not appear with heading text in the table of contents {5.4}. For example,
•H 1 "'DIE UNIX OPmATIN:; SYSTEM" *
.FS *
Trademark of A$.T Bell LalxJratories .
•FE

Do not use \ ItF as the heading suffix. If you do, a number does not appear
in the heading as you expect (the string \ ItF will) and the footnote numbering goes awry.

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

There is no need for a .P macro (3.t) immediately after .H (or .HU, see
below) because the .H macro performs the spacing and indentation functions of the .P macro. If you do use .P after .H, mm ignores it. However, it
is good practice to start every paragraph of a document with a .P macro.
Later, if you take headings out of your file, paragraphs remain intact.
The effect of .H on line spacing and the font of the heading-text varies
according to the level argument. Here is the default effect of each level.
.H 1 heading-text

Produces an underlined (italicized) font heading followed by a single blank line. The text after the
heading-text begins on a new line and indents according to the current paragraph type.
.H n heading-text

Produces an underlined (italicized) heading followed
by two spaces (3 ~ n ~ 7). The following text
begins on the same line, that is, these are run-in
headings.
Appropriate numbering and spacing occur even if you omit the heading-text
argument from a .H macro call.

3.5. 1. Unnumbered Section Headings (.HU)
To produce an unnumbered heading, type .HU heading-text. The .HU
macro is a special case of .H; it acts the same way as .H except that no heading mark is printed. To preserve the hierarchical structure of headings
when you intermix .H and .HU calls, .HU produces headings at level 2 by
default. You may change this default value by changing the value of a the
number register Hu. Whatever value you give Hu becomes the heading
level for .HU. Thus, in the normal case, the only difference between
.HU "An unnumbered heading"

.H 2

A second-level heading"

is that the latter prints the heading mark:

TECHNICAL DISCUSSION

Formatting the Body of a Document

An unnumbered heading

2.2 A seoand-level heading

By default, both macros have the effect of incrementing the numbering
counter for level 2 and resetting to zero the counters for levels 3 through 7.
For example,
1.

This is a first-level heading

1. 1 A seoand-level heading
1. 1. 1 A third-level heading
An unnumbered

1.2.1

headiDl

A third-level heading (rx>te that level 2 has :incremented)

3.5.2. Altering the Appearance of Section Headings
You can change the appearance of headings easily by setting certain
registers and strings at the beginning of the document input text file. This
permits quick alteration of a document's style because this style-control
information is concentrated in a few lines rather than being distributed
throughout the document.
3.5.2.1. Prespacing and Page Ejection

A first-level heading, produced by .H 1, normally has two blank lines
(one vertical space) preceding it. One blank line (one-half vertical space)
precedes all other headings. You may force every first-level heading to the
top of a new page by inserting .nr Ej 1 at the beginning of the document
. input text file. Make long documents more manageable by starting each
section on a new page. Setting the Ej register to a higher value causes the
same effect for headings up to that level, that is, a page eject occurs if the
heading level is less than or equal to the Ej value.

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document
3.5.2.2. Spacing after Section Headings

Three registers control the appearance of text immediately following a
.H call. The registers are Hb (heading break level), Hs (heading space
level), and Hi (post-heading indent).
• If the heading level is less than or equal to Hb, a line break

{I.4.I} occurs after the heading.
• If the heading level is less than or equal to Hs, mm inserts a

blank line (one-half vertical space) after the heading.
• If a heading level is greater than Hb and also greater than Hs,
then the heading (if any) is immediately followed by text on the

same line.
These registers permit you to separate headings from the text in a consistent way throughout a document and allow you to alter easily white
space and heading emphasis. The default value for Hb and Hs is 2.
For any stand-alone heading (a heading on a line by itself) the Hi
number register controls alignment of the next line of output.
• If Hi is 0, text is left-justified.
• If Hi is 1 (the default value), mm indents text according to the
paragraph type as specified by the Pt register {3.l.1}.
• If Hi is 2, mm indents text to line up with the first word of the

heading itself so that the heading number stands out more
clearly.
To cause a blank line (one-half vertical space) to appear after the first
three heading levels, to have no run-in headings, and to force the text following all headings to be left-justified (regardless of the value of Pt), you
should put the follOWing line in the parameter setting segment:
.nr lis 3
.nr Hb 7
.nr Hi 0

TECHNICAL DISCUSSION

Formatting the Body of a Document
3.5.2.3. Centered Section Headings (He)

Use the Hc register to obtain centered headings. A heading is centered
if its level argument is less than or equal to Hc and if it is also a stand-alone
heading {3.5.2.2}. For example,

.nr He 1
.H 1 UNIX

.H 2 "Application Packages"
.H 2 Languages

produces

1. UNIX
1.1 Application Packages
1.2 Languages
The Hc register is initially set to 0 (no centered headings).
3.5.2.4. Bold, Italic, and Underlined Headings
3.5.2.4.1. Control by Level.

Any heading that is underlined by the nroff formatter is italicized by
the troff formatter. The string HF (heading font) contains seven codes that
specify fonts for heading levels 1 through 7. Legal codes, code interpretations, and defaults for HF codes are shown below:

HF
1

Default
HF

no underline
roman

underline
italic

bold
bold

2222222
2222222

Formatter

nroff
troff

Figure 6: The HF String

Thus, all levels are underlined by the nroff formatter and italicized by
the troff formatter. You may reset HF as desired. Any value omitted from
the right end of the list is assumed to be a 1. The following request would
result in five bold levels and two underlined (italic) levels:

mm:TECHNICALD~cusmON

Formatting the Body of a Document

.ds IfF 3 3 3 3 3 2 2

3.5.2.4.2. nraft Underlining Style.

The nroff formatter underlines in either of two styles:
• The normal style (.ul request) is to underline only letters and
digits.
• The continuous style (.cu request) underlines all characters
including spaces.
By default, mm attempts to use the continuous style on any heading
that is to be underlined and is short enough to fit on a single line. If a
heading is to be underlined but is longer than a single line, the heading is
underlined in the normal style.
All underlining of headings can be forced to the normal style by using
the -rUt flag when invoking the nroff formatter {8.4}.
3.5.2.5. Section Heading Point Sizes (HP)

You may specify the desired point size for each heading level with the
HP string (for use with the troff formatter only).
•ds HP [psl) [ps21 [ps31 [ps41 [psSl [ps61 [ps71

By default, mm prints the text of headings (.H and .HU) in the same
point size as the body except that bold stand-alone headings are printed in a
size one point smaller than the body. You can specify the string HP, which
is similar to the string HF, to contain up to seven values, corresponding to
the seven levels of headings. For example,
.ds HP 12 12 10 10 10 10 10

specifies that the first and second level headings are to be printed in 12point type with the remainder printed in IO-point. Specified values may
also be relative point-size changes, for example,
.ds HP +2 +2 -1 -1

TECHNICAL DISCUSSION

Formatting the Body of a Document

If you specify absolute point sizes, then absolute sizes are used regardless of the point size of the body of the document. If relative point sizes
are specified, then point sizes for headings are relative to the point size of
the body even if the latter is changed.

Null or zero values imply that the default size is used for the
corresponding heading level. Only the point size of the headings is
affected. Specifying a large point size without providing increased vertical
spacing (via .HX and/or .HZ (3.5.4}) may cause overprinting.
3.5.2.6. Marking Styles Numerals and Concatenation (.HM)

The registers named HI through H7 are used as counters for the seven
levels of headings. Register values are normally printed using Arabic
numerals. The .HM macro (heading mark style) allows this choice to be
overridden thus providing "outline" and other document styles:
.HM [argl] ... [arg7]

This macro can have up to seven arguments; each argument is a string indicating the type of marking to be used. Legal arguments and their meanings
are

Argument

Meaning

Arabic (default for all levels)
Arabic with enough leading zeroes
to get the specified number of digits
Upper-case alphabetic
Lower-case alphabetic
Upper-case roman
Lower-case roman
Interpreted as 1 (Arabic)
No effect

0001
A
a

I
i

omitted
illegal

By default, the complete heading mark for a given level is built by concatenating the mark for that level to the right of all marks for all levels of
higher value. To inhibit the concatenation of heading level marks, that is,
to obtain just the current level mark followed by a period, the heading mark
type register (Ht) is set to 1. For example, a commonly used "outline" style
is obtained by:

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

.HM I A 1 a i
.nr Ht 1

3.5.3. Headings and Table of Contents (CI)
Automatically collect the text of headings and their corresponding page
numbers for a table of contents by doing the following:
• Specify in the contents level register, Cl, what level headings
you want to save
• Call the .TC macro (S.4) at the end of the document.

mm saves any heading whose level is less than or equal to the value of
the Cl register and later displays it in the table of contents. The first two
levels of headings are saved if you use .TC without putting a value in Cl
(that is, Cl by default contains the value 2).
Because of the way headings are saved, it is possible to exceed the
formatter's storage capacity, particularly when saving many levels of many
headings, while also processing displays {3.6} and footnotes {3.3}. if this
happens, the "Out of temp file space" formatter error message appears (see
Appendix D); the only remedy is to save fewer levels and/or to have fewer
words in the heading text.

3.5.4. Section Headings and User Exit Macros
The .HX, .HY, and .HZ macros are the means by which you obtain a
final level of control over the section heading mechanism:
.HX dlevel rlevel heading-text
.MY

dlevel rlevel heading-text

.HZ dievel rlevel heading-text

These macros are not defined by mm; they are intended to be defined by
you. The.H macro call invokes .HX shortly before it prints the heading
text; it calls .HZ as its last action. After .HX is invoked, the size of the
heading is calculated. This processing causes certain features that may have
been included in .HX, such as .li for temporary indent, to be lost. After the
size calculation, .HY is called so that you may redefine these features. All
default actions occur if these macros are not defined. If .HX, .HY, or .HZ
are defined by you, user-supplied definition is interpreted at the appropriate

TECHMCALD~CUSmON

Formatting the Body of a Document

point. These macros can therefore influence handling of all headings
because the .HU macro is actually a special case of the .H macro.
If you originally invoked the .H macro, then the derived level argument
(dlevel) and the real level argument (rlevel) are both equal to the level given
in the .H invocation. If you originally invoked the .HU macro {3.5.1}, dlevel
is equal to the contents of register Hu, and rlevel is O. In both cases,
heading-text is the text of the original invocation.

By the time .H calls .HX, it has already incremented the heading
counter of the specified level {3.5.2.6}, produced blank lines (vertical spaces)
to precede the heading {3.5.2.1}, and accumulated the "heading mark," that
is, the string of digits, letters, and periods needed for a numbered heading.
When .H calls .HX, you may reference all mm registers and strings, as
well as the following:
string }O

If you make rlevel non-zero, this string contains the "head-

ing mark." Two unpaddable spaces (to separate the mark
from the heading) have been appended to this string.
If rlevel is 0, this string is null. If string }O is null, you

omit the heading mark in the table of contents produced
with the.TC macro.
register;O

This register shows the type of spacing that is to follow
the heading {3.5.2.2}.
A value of 0 means that the heading is run-in. A value of
1 means a break (but no blank line) is to follow the heading. A value of 2 means that a blank line (one-half vertical
space) is to follow the heading.

string }2

If "register ;0" is 0, this string contains two unpa4dable

spaces that will be used to separate the (run-in) heading
from the following text.
If "register ;0" is non-zero, this string is null.

This register contains an adjustment factor for a .ne request
issued before the heading is actually printed. On entry to
.HX, it has the value 3 if dlevel equals 1, and 1 otherwise.
The .ne request is for the following number of lines: the
contents of the "register ;0" taken as blank lines (halves of
vertical space) plus the contents of "register ;3" as blank
mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

lines (halves of vertical space) plus the number of lines of
the heading.
You may alter the values of )0, )2, and ;3 within .HX. The following are
examples of actions that might be performed by defining .HX to include the
lines shown:
• Change first-level heading mark from format n. to n.O:
.if \\$1=1 .ds }O \\n(H1.0\<~\<~
(where stands for a space)
• Separate run-in heading from the text with a period and two
unpaddable spaces:
.if \\n( ;0=0 .ds }2 .\<~\<~
• Ensure that at least 15 lines are left on the page before printing
a first-level heading:
.if \\$1=1 .nr ;3 (1S-\\n(;0
• Add three additional blank lines before each first-level heading:
.if \\$1=1 .~ 3
• Indent level 3 run-in headings by five spaces:
.if \\$1=3 .ti Sn If temporary strings or macros are used within .HX, their
names should be chosen with care (6.10.1).

When .H calls the .HY macro after the .ne is issued, certain features
requested in .HX must be repeated. For example,
.de HY

.if \\$1=3 .ti 5n
The .HZ macro is called at the end of .H to control actions after the
heading is produced. In a large document, sections may correspond to
chapters of a book, and you may want to change a page header or footer, for
example:

.de HZ
.if \\$1=1 .PF "Section \\$3"

TECHNICAL DISCUSSION

Formatting the Body of a Document

3.6. Displays
Displays are blocks of text that you want kept together, not split across
pages. mm provides two styles of displays: static and floating.
A static display appears in the same relative position in the output text
as it does in the input text. This may result in extra white space at the bottom of the page if the display is too big to fit there.
A floating display "floats" through the input text to the top of the next
page if there is not enough room for it on the current page. Input text that
follows a floating display may precede it in the output text.
By default, a display is processed with line-filling turned off, with
single-spacing, and not indented from the exiting margins. Do not nest
displays and footnotes, in any combination. Do not put headings within
displays or footnotes.

3.6.1. Static Displays (.DS, .DE)
A static display is delimited by the .DS and .DE macro pair.
•DS

[format [fill [rindent] ]

Text
.DE
With no arguments, .DS accepts lines of text exactly as typed (line-filling
off) and will not indent lines from the prevailing left margin or from the
right margin.
The format argument is an integer or letter you use to control the indentation and centering of displays. The fill argument is an integer or letter.
These arguments can have the following meanings:

mm: TECHNICAL DISCUSSION

Formatting the Body of a Document

Format

o or L
1 or I
2 or C
3 or CB
none

Fill
""

o or N
1 or F
none

Meaning
no indent
no indent
indent by standard amount
center each line
center as a block
no indent
Meaning
line-filling
line-filling
line-filling
line-filling

off
off
on
off

Figure 7: Arguments to the .DS Macro

The rindent argument is the number of characters that the line length
should be decreased, that is, an indentation from the right margin.

The default static display indentation wth .DS 1 or .DS I is five spaces,
but you can change it by changing the value in the number register Si. By
default, then, text of an indented display aligns with the first line of
indented paragraphs, unless you also change the value contained in Pi {3.l}.
These two number registers are independent of one another.
The display format argument value 3 (or CD) centers (horizontally) the
entire display as a block (as opposed to .DS 2 and .DF 2 that center each
line individually). All collected lines are left justified, and the display is
centered based on width of the longest line. By default, a blank line is
placed before and after static and floating displays. You can prevent this by
setting the number register Os to o.

,):

The following example shows usage of all three arguments for static
displays. The input

:.~

.. -,

TECHNICAL DISCUSSION

Formatting the Body of a Document

.DS I F 5
We the people of the United States,
in order to form a Dm'e perfect union,
establish justice, ensure danestic traIXlUillity,
provide for the carm:m defense,
and secure the blessings of liberty to
ourselves am our posterity,
do ordain and establish this Constitution to the
United States of America .

.DE
produces
We the peopl e of the Uni ted States. in order to form a
more perfect union. establish justice. ensure domestic tranquillity. provide for the common defense. and secure the blessings of
liberty to ourselves and our posterity. do ordain and establish
this Constitution to the United States of America.

This block of text is indented five ems from the current left margin, filled,
and indented five spaces from the right margin.

3.6.2. Floating Displays (.DF, .DE)
Delimit a floating display with the macro pair .DF and .DE.
•DF

[format [fill [rindent] ]

Text
.DE
Arguments to .DF have the same meanings as they do to .DS except when
they concern format. With floating displays, the formatter calculates indentation and centering with respect to the initial left margin because the prevailing indent may change between the time when the formatter first reads
the floating display and when the display is printed. One blank line occurs
before and after a floating display.
When the formatter encounters a floating display, it processes and
places the display onto a queue waiting to be output. The formatter
removes displays from the queue and prints them in the order entered,
which is tr.,~ order they appeared in the input file. If a new floating display
is encountered and the queue of displays is empty, the new display is a candidate for immediate output on the current page.

mm:

TECHNICAL DISCUSSION

Formatting the Body of a Document

As long as the display queue contains one or more displays, the formatter automatically enters new displays there, rather than putting them
out. When the formatter puts out a display, it also removes it from the
queue.
When the formatter reaches the end of a section (using section-page
numbering) or the end of a document, it automatically removes all displays
from the queue, putting them out. This occurs before the formatter
processes an .SG macro (S.l).
A display will fit on the current page if there is enough room to contain
the entire display or if the display is longer than one page in length and
less than half of the current page has been used.
You may exercise precise control over the positioning of floating
displays on output with two number registers, De and Df (see below).
Immediate output of the display queue is governed by size of display and
the setting of the Df register code. The De register code controls whether
text will appear on the current page after a floating display has been produced.
The De and Df number register code settings and actions are as follows:
De register:
Code Action

No special action occurs (also the default condition).

A page eject always follows the output of each floating display, so
only one floating display appears on a page and no text follows it.

For any other code, the action performed is the same as for code 1.
Df register:
Code Action

Floating displays are not output until end of section (when
section-page numbering) or end of document.

Output new floating display on current page if there is space; otherwise, hold it until end of section or document.

TECHNICAL DISCUSSION

Formatting the Body of a Document

Output exactly one floating display from queue to the top of a new
page or column (when in 2-column mode).

Output one floating display on current page if there is space; otherwise, output to the top of a new page or column.

Output as many displays as will fit (at least one) starting at the top
of a new page or column. If De is set to 1, each display is followed by a page eject, causing a new top of page to be reached
where at least one more display is output.

Output a new floating display on the current page if there is room
(default condition). Output as many displays (but at least one) as
will fit on the page starting at the top of a new page or column. If
De is set to 1, each display is followed by a page eject causing a
new top of page to be reached where at least one more display is
output.

For any code greater than 5, the action performed is the same as for code 5.
You may also use the .we macro {6.7} to control handling of displays in
double-column mode and to control the break in text before floating
displays.

3.7. Tables (using tbl)
.TS [H]
global options;
format section.
title lines
[.'lH [N]]

Data
.TE

The macro pair .TS (table start) and .TE (table end) delimits text to be
examined by tbl and sets proper spacing around the table. The display
function (.DS and .DE) and the tbl delimiting function are independent.
To keep together blocks that contain any mixture of tables, equations, filled
text, unfilled text, and caption lines, enclose the .TS/.TE block within a
display (.DS/.DE) if the table is less than a page long. You may enclose
floating tables inside floating displays (.DF /.DE).

mm:TECHN'CALD~cusmON

Formatting the Body of a Document

mm formats headings for tables that extend over several pages. If a
table heading is needed for each page of a multi-page table, the H argument
should be specified to the .TS macro as above. Following the options and
format information, table title is typed on as many lines as required and is
followed by the .TH macro. The .TH macro must occur when .TS H is used
for a multi-page table. This is not a feature of tbl but of the definitions provided by the mm macro package.
The .TH (table header) macro may take as an argument the letter N.
This argument causes the table header to be printed only if it is the first
table header on the page. Use this option when it is necessary to build long
tables from smaller .TS H/.TE segments. For example,
.TS H

Global options;
Format section.
Title lines
.TH

Data
.TE
.TS H

Global options;
Format section.
Title lines
.TH N

Data
.TE

causes the table heading to appear at the top of the first table segment and
no heading to appear at the top of the second segment when both appear
on the same page. However, the heading still appears at the top of each
page that the table continues onto. Use this feature when a single table
must be broken into segments because of table complexity (for example, too
many blocks of filled text). If each segment had its own .TS R/.TH
sequence, it would have its own header. However, if each table segment
after the first uses .TS H/.TH N, the table header will appear only at the
beginning of the table and the top of each new page or column that the
table continues onto.

TECHNICAL DISCUSSION

Formatting the Body of a Document

For the nroff formatter, you may use the -e option [-E for mm (B.ll]
for terminals that are capable of finer printing resolution. This causes better
alignment of features such as the lines forming the corner of a box. The-e
option is not effective with col.

3.8. Equations (using eqn)

.m
.m

[label]

Equation(s) input
.EN
.DE

The programs neqn and eqn expect to use the .EQ (equation start) and
.EN (equation end) macros as delimiters in the same way that tbl uses .TS
and .TE; however, .EQ and .EN must occur inside a .DS/.DE pair. There is
an exception to this rule - if .EQ and .EN are used to specify only the delimiters for in-line equations or to specify eqn/neqn defines, the .DS and
.DE macros must not be used; otherwise, extra blank lines will appear in the
output.
The .EQ macro takes an argument that will be used as a label for the
equation. By default, the label will appear at the right margin in the "vertical center" of the general equation. The Eq register may be set to 1 to
change labeling to the left margin.
The equation will be centered for centered displays; otherwise, the
equation will be adjusted to the opposite margin from the label.

3.9. Figure, Table, Equation, and Exhibit Titles (.FG,
•TB, .Ee, .EX)
You may use the .FG (figure title), .TB (table title), .Ee (equation caption), and .EX (exhibit caption) macros inside .DS/.DE pairs to number
figures, tables, and equations automatically, and give them titles.

mm: TECHNICAL DISCUSSION

FormaUlng the Body of a Document

[title [override [flag] ] ]

.TB [title [override [flag] ] ]
.EX: [title [override [flag] ] ]
.:EX [title [override [flag] ] ]

These macros use registers Fg, Tb, Ee, and Ex, respectively (see section 8.4
on -rNS to reset counters in sections). For example,

.m "This is a Figure Title

yields
Figure 1. This is a Figure Title
The .TB macro replaces "Figure" with "TABLE," the .EC macro replaces
"Figure" with "Equation," and the .EX macro replaces "Figure" with "Exhibit."
The output title is centered if it can fit on a single line; otherwise, all lines
but th~ first are indented to line up with the first character of the title.
Change the format of the numbers using the .af request of the formatter.
By setting the Of register to 1, you may change the format of the caption
from"
Figure 1. Title
to
Figure 1- Title
Use the override argument to change normal numbering. If you omit the
flag argument or use an argument of 0, override is used as a prefix to the
number; if the flag argument is 1, override becomes a suffix; and if the flag
argument is 2, override replaces the number. If -rNS {8.4} is given,
"section-figure" numbering is set automatically and user-specified override
argument is ignored.
As a matter of formatting style, you might want to place table headings
above the text of tables, and put figure, equation, and exhibit titles below
.
corresponding figures and equations.

You obtain a List of Figures, List of Tables, List of Exhibits, and List of
Equations after mm prints the Table of Contents if the number registers Lf,
Lt, Lx and Le (respectively) are set to 1. By default, all but Le are set to 1 by
default. You can ch~nge the titles of these lists by redefining the follOWing
strings, which are presente~ here with their default values:

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - Formatting the Body of a Document

.ds
.ds
.ds
•ds

Lf LIsr
Lt LIsr
Lx. LIST
Le LIsr

OF
OF
OF
OF

FIGURES

TABLEs
EXHIBITS
mIATICES

mm: TECHNICAL DISCUSSION

4. Formatting the Beginning of a Document
Two specific styles of documents are available with mm: formal
memorandum style, which includes formats for memoranda, released papers
and external letters, and business letter style.

4. 1. Formal Memorandum Style
The mm formal memorandum style allows three document types: the
memorandum, the released paper and the external letter. Commonly, people who write formal memoranda put certain information at the beginning
of the document (the date, title, case numbers, authors, and so on) or at the
end of the document (the signature line and a list of the document's recipients), and put it nowhere else. You specify these beginning and end
items the same way for each formal memorandum type. Their formatted
appearance depends on which type you choose with the .MT macro. (See
"Appendix G" for an example of a formal memorandum.)

4.1.1. Choosing a Formal Memorandum Type (.MT)
This is how you use .MT:
.MI'

[argument [addressee] ]

An argument specifies a particular formal memorandum type. Legal values
for the argument are as follows:

TECHNICAL DISCUSSION

Formatting the Beginning of a Document

Argument

o
none
1
2
3

4
5

"string"

Type
memorandum
memorandum
memorandum
memorandum
memorandum
memorandum
released-paper
external-letter
memorandum

Value
no memorandum type printed
no memorandum type printed
MEMORANDUM FOR FILE
MEMORANDUM FOR FILE
PROGRAMMER'S NOTES
ENGINEER'S NOTES

released-paper style
external-letter style
string (enclosed in quotes)

Figure 8: Arguments to the .MT Macro

The formal memorandum style produces a standard mast at the top of
the first page of your document. The following input lines produce the
next mast (and those that follow it). Put these lines immediately after the
parameter setting segment of your document:
.NO "september 28, 1984"
.TL
Document Production Cooniinator
.M) "Jalm Smith" JS XF 5414 6398 7-123
.AF "Business Canplter Systems, Inc."
.M!' n (where n is a legal argument to .MT)

First, consider the memorandum type (here, .MT).
Business Computer Systems, Inc.
subject: Document Production
Coordinator

date:

September 28, 1984

from:

John Smith
XF 5414
x6398 7-123

If you give .MT any argument other than 4 or 5, you obtain, a few lines
after the last line of author information, the value of value in the preceding
table.

mm: TECHNICAL DISCUSSION

FormaUlng the Beginning of a Document

There are two alternatives to the memorandum type. To obtain the
released-paper style, use .MT 4, which produces a different mast:
Document Production Coordinator
John Smith
Business Computer Systems, Inc.

With the external-letter style (.MT 5), mm prints only the title (without the
word "subject:") and the date in the opposite left and right corners, respectively, of the top of the first page.
Document Production
Coordinator

September 28, 1984

Specify the addressee of a memo, released paper or letter with the
second argument to .MT. This argument may be any words you choose.
Providing the addressee causes the name you've specified and the page
number to replace the normal page header (page headers will be discussed
below) on the second and succeeding pages of a memo.
•M!' 1 "Michael Snith"

You may not use the addressee argument when the .MT type equals 4.
If you try, output will cease after the first page.

4. 1.2. TM Numbers
If the memorandum is an AT&T technical memorandum, TM numbers
are supplied via the .TM macro.
•'IN [number] ...

Up to nine numbers may be specified. For example,
•'IN 7654321 77777777

mm ignores this macro call in the released-paper and external-letter styles
{4.4.1l.

TECHNICAL DISCUSSION

Formatting the Beginning of a Document

4. 1.3. Changing the Date (.ND)
By default, the current date appears in the "date" part of a memorandum
or in the right corner of an external letter. You may override the current
date using the .ND macro.
•ND new date

4. 1.4. Giving the Memorandum a Title (.TL)
The .TL macro gives your formatted document a title. To use .TL, type:
•TL

[charging-case number(s) [filing-case number(s)] ]

Text
.AU (or another macro)

AT&T Bell Laboratories uses arguments to the .TL macro to specify the
charging-case number(s) and filing-case number(s).
• The charging-case number stands for an account to which a
person's time is charged. Enter multiple charging-case numbers
as "subarguments" by separating each from the previous with
a comma and a space, and enclosing the entire argument
within double quotes (see example below).
• The filing-case number describes where the memorandum is to
be filed. Enter multiple filing-case numbers the same way you
enter charging-case numbers (see example below).
Here is an example of specifying more than one charging-case number and
filing-case number:
.TL "12345, 67890" "987654321, 987654322"
D:>cument Production Coordinator

Those numbers will appear after the title like this (except for released paper
style, when they do not appear at all):
D:>cument Production
Coordinator
Charge Case 12345, 67890

File case 987654321, 987654322

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

The title of the memorandum follows the .TL macro. You may use the
.br request to break the title into several lines
.TL 12345
Ibcument Production
.bI'
Coordinator for the
.bI'
Technical writiD] staff

4. 1.5. Specifying the Author (.AU)
Use .AU to specify the author of your memo or paper:
.MJ name [initials [loc [dept [ext [room [arg [arg [arg ] ] ] ] ] ] ] ]

.TL 12345
Ibcument Production
.bI'

Coordinator for the
.bI'
Technical writiD] Staff

In the "from:" portion of a formatted memorandum, location and department number follows the author's name on one line and room number and
extension number follow it on the next line. The "x for the extension is
added automatically:
lt

fran: Jolm Srnith
XF

5414

7-123 x6398machine_5ljjs
For the memorandum type, you type information that describes an
author after the .AU macro as arguments. This information includes:
• name (for example, John Smith)
• initials (for example, JIS)
• location (XF)

TECHNICAL DISCUSSION

Formatting the Beginning of a Document

• department (5414)
• telephone extension (6398)
• room (7-123)
• one, two or three additional arguments (for example,
machine_5!jjs)
The first six arguments must appear in the order given, that is, the author's
name must be typed before the initials, which must be typed before the
location, and so on. By default, these arguments are ignored for the
released paper style and the external letter style. If you want to leave any
of these arguments blank, put a null argument at the appropriate place.
If you want to suppress printing the location, department number,
extension number, room number and later arguments, set the number register Au to 0; the default value is 1.
If a memorandum has more than one author, use a separate .AU macro
for each author, for example,
.NJ "Jolm SDith" JJS XF 5414 6398 7-123 machine_5ljjs
.NJ "Jolm Foley" JJF XF 5415 6666 7-321 machine_6Ij£

produces
from: John Smith
XF 5414
7-123 x6398
machine_5ljjs
John Foley
XF 5415
7-321 x6666
machine_61jf

4. 1.6. Specifying the Author' 8 Title (.AT)
Specify the author's title with the .AT macro.
•AT title ...

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

.AT must immediately follow .AU for the given author. For example,
.AU "Jolm Snith" JJS XF 5414 6398 7-123
.AT SUpervisor "Teclmica1 Writing Staff"

produces the following output at the signature block:
Jolm smith
SUpervisor
Teclmica1 WritiJx.J Staff

You may give.AT up to nine arguments. Each argument will appear in
the signature block (at the end of the memorandum, which is discussed
below) on a separate line following the signer's name. If you need a long
title, surround phrases in double quotes, turning several words into single
arguments.
4.1.7. Specifying the Author's Firm (.AF)
Supply the name of your firm with .AF.
•AF

"name of the firm"

Use .AF before .AU to avoid a formatting error. If you use .MT 4, your firm
name appears after the author's name. For example,
.AF "Business Catplter Systems, Inc."

puts "Business Computer Systems, Inc." in bold letters in the upper right
hand corner of the first page of your memo. If you specify .MT 4, "Business
Computer Systems, Inc." appears centered and double spaced from the
author's name.
If you do not supply a name with .AF, "AT&T Bell Laboratories" appears as
the name of your firm unless your system administrator edits strings.mm

(5.5).

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - Formatting the Beginning of a Document

4.1.8. Calling Beginning Formal Memorandum Macros In the Correct
Order
If you use the macros described thus far, you must call them in the following order to avoid a formatting error:
.NO new date
•TL [charging-case number( s) [filing-case number(s)]
Text
.AF "name of the firm ll
.AU Name [initials [lac [dept [ext [room [arg [arg [arg]]]]]]]]
.M!' [type [addressee] ]

.AF "aIsiness Corplter Systems, Inc. 1I

The only required macros for a memorandum, released paper or external
letter are .TL, .AU, and .MT.

4.2. Other Beginning Macros
4.2.1. Abstract (.AS, .AE)
If a formal memorandum has an abstract, delimit the text of the abstract
with the .AS (abstract start) and .AE (abstract end) macro pair.
•AS [arg [indent]
Text of abstract
.AE

Abstracts are printed on page one of a document and/or on its cover sheet.
There are three types of cover sheets:
• Released paper
• Memorandum
• Memorandum for file (also used for engineer's notes,
memoranda for record, and so on)
Cover sheets for released papers and memoranda are obtained by invoking the .CS macro.

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

With the released-paper type (argument to the .MT macro is 4) and with
the memorandum type, if the first argument of .AS is

Abstract prints on page 1 and on the cover sheet (if any).

Abstract appears only on the cover sheet (if any).

With the memorandum for file type and in all other documents (other
than external letters) if the first argument of .AS is:

Abstract appears on page 1 and no cover sheet prints.

Abstract appears only on the cover sheet that will be produced
automatically (that is, without invoking the .CS macro).

It is not possible to get either an abstract or a cover sheet with an external letter (first argument of the .MT macro is 5).

Notations such as a "Copy to" list are allowed on memorandum for file
cover sheets; the .NS and .NE macros must appear after the .AS 2 and .AE
macros. Headings and displays are not permitted within an abstract.
The abstract is printed with ordinary text margins; an indentation to be
used for both margins can be specified as the second argument of .AS.
Values that specify indentation must be unsealed and are treated as "character positions," that is, as the number of ens.

4.2.2. Other Keywords (.OK)
.OK keyword [m]

Topical keywords should be specified on a technical memorandum cover
sheet. You may specify up to nine such keywords or keyword phrases as
arguments to the .OK macro; if any keyword contains spaces, you must
enclose them in double quotes.

4.2.3. Bottom Block (.BS, .BE)
Specify lines of text to be printed at the bottom of each page after the
footnotes (if any) but before the page footer with the bottom block macro
pair .DS/.DE.

TECHNICAL DISCUSSION

Formatting the Beginning of a Document

.85

Text
.BE

The bottom block should occur before the use of any footnotes (3.3) or macros that define the memorandum style (4.1.4). Otherwise, an interaction
between this macro pair and another macro that redefines the appearance of
the bottom of the page may cause you problems.
Remove the bottom block by specifying an empty block, as shown
below:
.BS
.BE

The bottom block appears on the table of contents, text pages, and the cover
sheet for memorandum for file, but it does not appear on the technical
memorandum or released-paper cover sheets.

4.3. Proprietary Marking Macro (.PM)
The .PM (proprietary marking) macro appends to the page footer a
proprietary disclaimer.
•PM [code]

The argument is selected from among the following (note that arguments formerly used with DOCUMENTER'S WORKBENCH Software 1.0 are
included):

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

Current
Arg

Former
Arg

PMl

BP,N,P,
BPN

Disclaimer
Message

AT&T BELL LABORATORIES· PROPRIETARY
Use pursuant to G.E.I. 2.2

PM2

IlLme

THIS DOCUMENT CONTAINS PROPRIETARY INFORMATION OF
AT&T AND IS NOT TO BE DISCLOSED OR USED EXCEPT IN
ACCORDANCE WITH APPLICABLE CONTRACTS OR AGREEMENTS.

PM3

Ilolle

SEE PROPRIETARY NOTICE ON COVER PAGE

PM4

BPP,BR

AT&T BELL LABORATORIES - PROPRIETARY (RESTRICTED)

Solely for authorized persons having a need to know
pursuant to G.E.I. 2.2

PMS

ILL

THIS DOCUMENT CONTAINS PROPRIETARY INFORMATION OF
AT&T BELL LABORATORIES AND IS NOT TO BE DISCLOSED.
REPRODUCED, OR PUBLISHED WITHOUT WRITTEN CONSENT.
THIS DOCUMENT MUST BE RENDERED ILLEGIBLE WHEN BEING DISCARDED.

PM6

CI-II

Not for disclosure to AT&T Information Systems.
Subject to FCC separation requirements under Computer Inquiry II

Figure 9: Arguments to .PM (Proprietary Markings)

Use .PM at the beginning of your document, before you use footnotes {3.3}
or macros that define the memorandum style {4.1.4}. Otherwise, an interaction between this macro and another that redefines the appearance of the
bottom of the page may cause you problems.

TECHNICAL DISCUSSION

Formatllng the Beginning of a Document

These disclaimers are in a form approved for use by the AT&T. Mark:ings are underlined. (They are italic in troff.) You may use the CI-II marking with any other message by two separate .PM requests. For example,

.PM CI-II
.PM N

produces a CI-II and NOTICE mark.
These proprietary markings are specified in the define file. System
administrators can change the contents of this define file, strings.inm, to
match your needs. This file is described in the next section. In cases where
the disclaimer message for a code argument has been removed the argument
issues a currently approved disclaimer message. Since the code argument
may produce a different disclaimer message (a shorter or longer message),
the page formatting of the document may be affected.

4.4. Define File Information
The define file contains pre-defined strings for the .MT and .PM macros. Appendix E presents the contents of the file. The file
lusr/lib/macros/strings.mm contains the define file. Only system administrators may change specific string and font information, since only they
have write permissions for the define file.

4.5. Business Letter Style
An alternative to the formal memorandum style is the business letter
style, which produces four types of business letters: blocked, semiblocked,
full-blocked, and simplified. (See Appendix H for an example of an mm
business letter.)

4.5. 1. Letter-Type Macro (. LT)
The letter-type macro .LT formats a letter in one of four business styles:
.LT [arg]

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

.LT accepts one (optional) argument. Arguments and corresponding
format are as follows:

Argument

none
BL
SB
FB
SP

Format
blocked
blocked
semiblocked
full-blocked
simplified

.LT controls the placement on the page of the output of the subordinate
macro .LO and the subordinate macro pairs (.IA and .IE, •WA and.WE)
which differs according to each of the four business letter formats.
Business letter and formal memorandum macros (.LT and .MT) are
mutually exclusive. If you specify both .LT and .MT specific macros in a
single document, nroff I ttoff attempts to process the file according to the
first formatting specific macro it encounters. mm ignores .MT-specific macros (.2C, .AF, .AS, .AT, .AU, .AV, .CS, .OK, .TC, .TL, .TM) and .MT-specific
command line parameters (-rAn, -rEn, -rN4) if you use them with .LT;
conversely, if you use .LT-specific macros (.WA, .WE, .IA, .IE, .LO) with
.MT, mm ignores them.
If you use these business letter macros, the macro pairs, .WA-.WEand

.IA-.IE, and the page formatting macro .LT are required, all other business
letter macros are optional.
The .LT macro arguments control paragraph indentation for each of the
four letter types. If you redefine the Pt and Pi registers, the user specified
indentations will override. Specification of the Pt and Pi registers must
occur after specification of the.LT macro.
• In the blocked format all lines of text begin at the left margin
except the date line, return address, closing, and writer's
identification. These begin at the center of the line. (The center
of the line is not a fixed point, it is calculated for the current
line length.)

TECHmCALD~CUSmON

- - - - - - - - - - - - - - - Formatting the Beginning of a Document

• The semiblocked format is the same as the blocked format;
except, the first line of each paragraph is indented five spaces.
• In full-blocked format all lines begin at the left margin. There
are no exceptions.
• The simplified format is the same as the full-blocked format;
except, the salutation is replaced by an all-capital subject line
and is followed by an additional blank line, the closing is omitted, and the writer's identification is in all-capital letters on one
line.
Table 1 presents a synopsis of the placement of business letter components for the four .LT letter formats and lists the macros (which are
explained in detail below) that you use to format those components.

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

Macro & Function

Placement on Page By .LT Argument·
BL
SB

.WA/.WE
Writer's Address

Center

Left

.LO eN [arg]
Confidential Notation

Left

.LO RN(arg]
Reference Notation

Center

Left

.IA/.IE
Inside Address

Left

.LO AT [arg]
Attention

Left

.LO SA [arg]
Salutation

Left

Non e

.LO SJ [arg]
SUbject Line

Left

Indented

Left

.P Paragraphs

Left

Indented

Left

.FC Closing

Center

Left

.SG Signature

Center

Left

.NS/.NE
Copy Notation

Left

Figure 10: Arguments to the .LT Macro and their Functions

There are two possible error conditions for the .LT macro:
• If you omit the .LT macro, file processing aborts and an
appropriate error message prints.

TECHNICAL DISCUSSION

Formatting the Beginning of a Document

• If mm does not recognize an argument to .tT, the file process-

ing aborts and an appropriate error message prints.

4.5.2. Writer's Address Macros (.WA, .WE)
Use this macro pair to specify the writer (author) of the letter and the
writer's return address.
•WA writer-name [title]
Return address

.WE

Fbr example,
.WA IIJames Iorrin, Ph.D. II Director
SUnmit Research CarqJan;y
38 River Road
SUlIIni.t, New Jersey 07901
.WE

If a complete return address is not necessary for the letter (for example,
if you use printed letterhead stationary) you can specify the writer information alone:
.WA IIJames IDrrin, Ph.D. II Director
.WE

The return address cannot exceed 14 lines. Lines in the return address
that follow line 14 do not appear on the letter.
The two arguments specified for the .WA and .WE macro pair, the
writer-name and the title, prOVide information used by the .SG macro {S.l}.
If you do not specify the .SG macro, the writer's name does not appear on
the letter.
For the case of multiple writers on a single letter, you may specify only
one writer return address. The specified writer return address must appear
with the first writer-name as the first invocation of the .WAf.WE macro
pair. Later return address specifications do not appear on the letter,
although any number of additional writer names may be specified. For
example,

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

.WA "James Larrin, Ph.D. tr Director
SUnmit Research Catpany
38 River Road
SUnmit, New Jersey 07901
.WE
•WA lIJalm Snith" SUpervisor
.WE
•WA "Diane Karle ll "Technical SUpport"
.WE

For blocked and semiblocked letter styles the writer return address
begins on line 12 from the top of the first page and each line begins at the
center of the line. For the full-blocked and simplified letter styles the
writer return address begins on line 12 from the top of the page and each
line begins at the left margin.
Top of page processing can be controlled directly through nroff. The
beginning of the printed page is user-defined. See the requests .wh and .ch
in the "nroff/troff Technical Discussion."

If you omit either or both of the •WA and •WE macros, the file processing aborts and an appropriate error message prints.

4.5.3. Inside Address Macros (.IA, .IE)
.IA and .IE are a macro pair you use to specify the addressee and the
addressee's address. There are two different ways that you can use this
macro pair:
.IA

Text
.IE

or
.IA

[addressee-name [title] ]

Text
.IE
For example,

TECHNICAL DISCUSSION

Formatting the Beginning of a Document

.IA

Fred smith, Ph.D.

Columbia University
116th Street
New York, New York 10019
.IE

or
.IA "Fred smith, Ph.D. II
.IE

For all four letter styles of .LT, the inside address prints on the fifth line
below the date (if a reference notation or confidential notation appear after
the date, the inside address prints three lines below the notation) and each
line begins at the left margin.
If you omit either or both of the .IA and .IE macros, the file processing
aborts and an appropriate error message prints.

4.5.4. Letter-Options Macro (.LO)
The letter-options macro provides the capability for specifying five common business letter components:
.LD

type [arg]

The .LO macro takes care of placement and spacing of these letter components for each .LT letter format. .LO requires one argument to specify a
letter component type, and accepts one optional string argument to refine
its action.

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

Type

Corresponding Component

confidential notation
reference notation
attention
salutation
subject line

RN
AT
SA
S}

Figure 11: Types Given to .LO and their Functions

4.5.4.1. Confidential Notation (eN)

The confidential notation shows that a business letter should be read
only by the person to whom it is addressed. The confidential notation
appears on the second line below the date line of the letter and begins at
the left margin for all letter formats.
If the optional string argument is present the specified string replaces
the default. For example,
.ID Ql IlRESTRICTED"

The default of eN prints CONFIDENTIAL in upper-case.
4.5.4.2. Reference NotaUon (RN)

The reference notation supplies specific information to be used by the
addressee. For example,
.ID RN "Meeting of 1/25 11

The reference note appears two lines below the date line of the letter (or on
the second line below any notation that follows the date) left aligned with
the date line for all four letter formats.
RN provides a common format for including a reference note by printing the string In reference to: preceding the optional string argument to
.LO. The format string In reference to: cannot be redefined. There is not a
default value for the optional argument.

TECHMCALD~CUSmON

Formatting the Beginning of a Document

4.5.4.3. Attention (AT)

The attention line directs the letter to the attention of a specific person
or department. For example,
.
•lD AT "Dr. Smith"

The attention information appears on the second line below the inside
address of the letter and begins at the left margin.
AT provides a common format for directing a letter to the attention of a
specific person by printing the string "ATTENTION: preceding the
optional string argument to .LO. The format string "ATTENTION:" cannot
be redefined. There is not a default value for the optional argument.
lI

4.5.4.4. Salutation. (SA)

The salutation specifies the letter's opening greeting. For the blocked,
semiblocked, and full-blocked formats the salutation appears on the second
line below the inside address (or on the second line below the attention
line, if used). In the simplified letter format, the salutation is ignored.
The default of SA prints "To Whom It May Concern:" for the salutation.
If the optional string argument is present the specified string will replace
the default. For example,
.lD SA "Dear Dr. smith"
4.5.4.5. Subject Line (SJ)

The subject line shows what the letter is about. In the blocked and
full-blocked letter formats the subject line information appears on the
second line below the salutation and begin at the left margin. For the semiblocked format the subject line appears on the second line below the salutation and is indented five spaces. In the simplified letter format the subject
line information appears in place of the salutation three lines below the
inside address of the attention line; the salutation, if yOll use it, is ignored.
For the blocked, semiblocked, and full-blocked formats, SJ provides a
common format for indicating what the letter is about by printing the string
"SUBJECT: preceding the optional string argument to .LO.
•lD SJ "Staff Meeting:"

The format string "SUBJECT: cannot be redefined. There is not a default
val ue for the optional argumen t.

mm: TECHNICAL DISCUSSION

Formatting the Beginning of a Document

For the simplified letter, the subject line string argument prints on the
third line below the inside address or the attention line (a salutation is
ignored if used).
If you specify the .LO macro without an argument or the argument you
specify is unrecognized, the file processing aborts and an appropriate error
message prints.

4.5.5. Multi-page Letters
The .LT macro controls the format for the first page of the letter. The
letter macros will not alter the default nroff Itroff page processing following the first page of the letter.

4.5.6. Sequence of Beginning Letter Macros
Macros .WA, .WE, .IA, .IE, and .LT must be given in the order listed in
the following table. .LO can be specified multiple times with different
argument types. The .LO argument types do not have to be in any specific
order. All .LO requests must be specified before .LT.

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - Formatting the Beginning of a Document

.ND new date
.WA writer's name [title]

Return address
Street
City, State Zip Code
Text
.WE
.IA

Addressee name
Title
Company
Street
City, State Zip Code
Text
.IE
.00 type [arg]
.LT [arg]

.P
Text
.Fe
.$

•NS

[arg [1] ]
[arg [1] ]

Text
.NE

If you put nroff/troff requests and lines of text before .LT, you change
how .LT works. For example, if the first line of a file is a line of text, mm
processes the file as if you had not specified .LT.

mm: TECHNICAL DISCUSSION

5. Formatting the End of a Document

5.1. Formal Closing and Signature Line (.Fe, .SG)
If you like, you may make your formal memorandum more formal with
the .FC macro, which prints "Yours very truly," as a formal closing. You
may specify an argument to .FC. to present a different closing.

The .SG (for "signature line") macro prints the author's name(s) after the
formal closing, otherwise the author's name appears after the last line of the
body of the memo. Each printed name begins at the center of the page.
Three blank lines are left above each name for an author's signature. Use
.FC before .SG or the formal closing w'ill appear after the signature line.
Here's how you use .FC and .SG together. You may use
itself.

eit~er

macro by

.Fe ["closing argument"]
. $ [arg [1] ]

You append a line of reference data including location code (for example, XF), department number (5414) and author's initials OJ5) by typing .5G
"" instead of .5G. These data appear after the author's name and before the
"Copy to" list (which is described below) and look like this:

XF-5414-JJS
If you type any other argument after .SG (not ""), that argument is treated as
the typi~t's initials and is appended to the reference data. For example, if
you specify:
.$

abc

the following line appears after the author's signature and before the "Copy
to" list:

XF-5414-JJS-abc
If there are several authors and the second argument is given, reference
data is placed on the signature line of the first author. This reference data
contains only the location and department number of the first author, even
though the other authors' initials are printed. Therefore, if there are
authors from different departments and/or from different locations, the

TECHNICAL DISCUSSION

Formatting the End of a Document

reference data should be supplied manually after calling .SG without arguments, like this:
.$

XF-5414-JJS
XF-5415-SJF
This manually supplied information appears on the signature line of the
second author.
For business letter style documents, the .SG macro prints the writer's
name(s) after the formal closing, if any. Placement of the writer's names(s)
for the signature block is controlled by the .LT macro specification (for
example at the left margin or at the center of the page). The optional arguments accepted by .SG will not alter the. processing of the macro when used
in conjunction with .LT.

5.2. Approval Line (.AV)
Use the .AV macro after the last notation block to generate automatically a line for the approver's signature and the date.
•AV approver's-name [1]

For example,
.AV "Todd Doe"

produces
APPROVED:

Todd Doe

Date

Use the optional second argument to prevent the mark "APPROVED:" from
appearing above the approval line.
The .SG and .NS macros format signatures of authors and a list of notations, respectively. These macros do not work with released-paper style
(.MT 4, 4.1.1).

mm: TECHNICAL DISCUSSION

Formatting the End of a Document

5.3. "Copy to" and Other Notations (.NS, .NE)
Many types of notations (such as a list of attachments or "Copy toll lists)
may follow signature and reference data. Various notations are obtained
through the .NS macro, which provides for proper spacing and for breaking
notations across pages if necessary. You use .NS like this:
.NS [argument [1] ]
Names or other notation

.NE

If you use the optional second argum~nt, the first argument will be used
as the entire notation string. Codes for argument and the corresponding
notations are

Argument
none

o
1
2

3
4
5
6

8
9
10
11
12
13

"string"
"string", with 2nd arg

Notations
Copy to
Copy to
Copy to
Copy (with atl.) to
Copy (without atl.) to
Att.
Atts.
Ene.
Encs.
Under Separate Cover
Letter to
Memorandum to
Copy (with atts.) to
Copy (without atts.) to
Abstract Only to
Complete Memorandum to
Copy (string) to
string

Figure 12: Arguments to the .NS Macro

TECHNICAL DISCUSSION

Formatting the End of a Document

The string, which you mayor may not enclose in double quotation
marks, is placed within parentheses between the words "Copy" and "to" if it
consists of more than two characters; otherwise, it is ignored. For example,
.NS "with

att. 1 only"

generates
Copy (with att. 1 only) to

as the notation.
You may specify more than one notation before the .NE macro because
a .NS macro stops the preceding notation, if any. For example,
.NS 4

Attacbnent 1-List of branch offices and managers
Attachment 2-List of regional offices and managers
.NS 1

Bill Taylor
.NS 2
J. Craven
A. Greenland
.NE

produces
Atts.
Attachment 1-List of branch offices and managers
Attachment 2-List of regional offices and managers
Copy (wi th at t .) to
Bill Taylor
Copy (without att.) to
J. Craven
A. Greenland

If you use a second argument, the first argument becomes the entire
notation. For example,
.NS "Table of Contents to" 1

produces
Table of Contents to

as the notation.

mm: TECHNICAL DISCUSSION

Formatting the End of a Document

You may also use .NS and .NE at the beginning of a document following .AS 2 and .AE to place the notation list on the Memorandum for File
cover sheet {S.6}. If you give notations at the beginning without .AS 2,
they will be saved and printed at the end of the document.

5.4. Table of Contents (.TC)
For most documents, the table of contents appears at the beginning, but
because you have to call .TC at the end of your unformatted file, this
Technical Discussion treats it as a macro for the end of the document. mm
produces the table of contents at the end because the entire document must
be processed before the table of contents can be generated from gathered
section headings.
This macro normally appears once at the end of the document, after the
Signature Block {S.l} and Notations {S.3} macros.
The .TC macro generates a table of contents containing heading levels
that were saved for the table of contents as determined by the value of the
CI register {3.5.3} .
•'It: [sieve/] [spacing] [tlevel] [tab] [hl] [h2] [h3] [h4] [h5]

Arguments to .TC control spacing before each entry, placement of associated
page number, and additional text on the first page of the table of contents
before the word "CONTENTS."
Spacing before each entry is controlled by the first and second arguments (slevel and spacing). Headings whose levels are less than or equal to
slevel will have spacing blank lines (halves of a vertical space) before them.
Both slevel and spacing default to 1. This means that first-level headings are
preceded by one blank line (one-half a vertical space). The slevel argument
does not control what levels of heading have been saved; saving of headings is the function of the CI register.
The third and fourth arguments (tlevel and tab) control placement of the
associated page number for each heading. Page numbers can be justified at
the right margin with either blanks or dots (called leaders) separating the
heading text from the page number, or the page numbers can follow the
heading text.

TECHNICAL DISCUSSION

Formatting the End of a Document

• For headings whose level is less than or equal to tlevel (default
2), page numbers are justified at the right margin. Here, the
value of tab determines the character used to separate heading
text from page number. If tab is 0 (default value), dots (that is,
leaders) are used. If tab is greater than 0, spaces are used.
• For headings whose level is greater than t1evel, page numbers
are separated from heading text by two spaces (that is, page
numbers are "ragged right," not right justified).
Additional arguments (hI ... hS) are horizontally centered on the page
and precede the table of contents.

5.5. Changing the Table of Contents (.TX, .TY)
If you call the .TC macro with at most four arguments, mm calls the
user-exit macro .TX (without arguments) before the word "CONTENTS" is
printed, qr calls the user-exit macro .TY, and does not print the word "CONTENTS. By defining .TX or .TY and calling .TC with at most four arguments, you can specify what needs to be done at the top of the first page of
the table of contents. For example,
II

.de TX
.ce 2

Special Application
Message Transmission
.sp 2
.in +Sn
Approved: \l' 2. Si '

.in
.sp
.TC

yields the following output when you format the file that contains them:

mm: TECHNICAL DISCUSSION

Formatting the End of a Document

Special Application
Message Transmission
Approved:

If you define the .TX macro as .TY, the word "CONTENTS II would be
suppressed. Defining .TY as an empty macro suppresses "CONTENTS" with
no replacement:

.de 'n'

By default, the first level headings appear in the table of contents left
justified. Later levels align with the text of headings at the preceding level.
You may change these indentations by defining the Ci string that takes a
maximum of seven arguments corresponding to the heading levels. You
must give at least as many arguments as are set by the Cl register. With
these registers, arguments must be scaled. For example, with IICI =: 5":
.ds Ci .25i .5i .75i 1i 1i

\" troff

or
.ds Ci 0 2n 4n 6n

an \"

nroff

Two other registers are available to change the format of the table of
contents:
• By default, table of contents pages will have lower-case roman
numeral page numbering. If the Oc register is set to 1, the .TC
macro' wil~ not print any page number but will instead reset the
P register to 1. It is your responsibility to give an appropriate
page footer to specify the placement of the page number. Ordinarily, the same .PF macro (page footer) used in the body of the
document is adequate.
• Front matter pages, such as those listing figures and tables, will
be produced separately unless Cp is set to 1, which causes these
lists to appear on the same page as the table of contents.

TECHMCALD~CUSmON

Formatting the End of a Document

5.6. Cover Sheet (.CS)
Like the table of contents macro, you call the cover sheet macro (.CS) at
the end of the document, even though you usually put a cover sheet at the
beginning. .CS generates a cover sheet in either the released paper or
memorandum type of the formal memorandum style.

.cs [pages [other [total [Jigs [tbls [refs] ] ] ] ] ]
All other information for the cover sheet is obtained from data given before
the .MT macro call {4.1.1}. If you use the memorandum type, the .CS macro
generates the "Cover Sheet for Technical Memorandum". The data that
appear in the lower left corner of the memorandum cover sheet (counts of:
pages of text, other pages, total pages, figures, tables, and references) are
generated 'automatically (0 is used for "other pages"). You may change these
values by supplying the corresponding arguments to the .CS macro. If you
use the released-paper style, all arguments to .CS are ignored.

5.7. References (.RS, .RF, .RP)
Obtain automatically numbered references by typing \ ·(Rf (invoking
the string Rf) immediately after the text you want to reference. This places
the next sequential reference number (in a smaller point size) enclosed in
brackets one-half line above the text you reference. mm keeps reference
count in the Rf number register. mm uses the number register :R to print
the reference number for each reference call in the text (V"(Rf). You may
change the format or value of the :R register to effect the reference marks,
without affecting the total count of references.
Use the .RS and .RF macros to delimit text of each reference.

Text to be referenced.\*(Rf
.RS

Reference
.RE'

mm: TECHNICAL DISCUSSION

Formatting the End of a Document

The .RS macro takes an optional argument, a string-name. For example,
.RS aA

Reference
.RF

The string aA is assigned the current reference number. You may use
this string later in the document as the string call, \ ·(aA, to reference text
that must be labeled with a prior reference number. The reference is
enclosed in brackets one-half line above the text to be referenced. You do
not need a .RS/.RF pair f~r subsequent references.
You may use the .RP (reference page) macro to produce reference pages
anywhere else within a document (that is, after each major section). It is
not needed to' produce 'a separate reference page with default spacings at
the end of the docum~nt.
.
The .RP macro produces the reference page.
•RP

[argl [arg2] ]

Two arguments may be used with .RP. Possibilities for the first argument
are as follows:
'

Argument 1

o
1

Function
Reset reference counter (default).
Do not set reference counter.

Possibilities for the second argument are as follows:
Argument 2

o
1
2
3

Function
Put on separate page (default).
Do not cause a following .SK.
Do not cause a prece"din'g .SK.
Do not cause a preceding or following .SK.

This page contains the reference items (that is, reference text enclosed
within .RS/.RF pairs). Reference items are separated by a space (one-half a
vertical space) unless you set the Ls register.to 0 to suppress this spacing.
You may change the reference page title by defining the Rp string:

TECHNICAL DISCUSSION

Formatting the End of a Document

.ds Rp "New Title"

If no .SK macro is issued by the .RP macro, a single blank line separates
the references from the following/preceding text. You may wish to adjust
spacing. For example, to produce references at the end of each major section:
.sp 3
.RP 1 2
.H 1 "Next 5ectianll

mm: TECHNICAL DISCUSSION

6. Miscellaneous Macros

6. 1. Bold, Italic, and Roman Fonts (.B, .1, .R)
mm provides three macros for changing the prevailing font of a document.
.B [bold-arg [previous-!ont-arg] ] •••
. I [ita/ic-arg [prelJ;ous-!ont-arg] ] ...

When you invoke it without arguments, .8 changes the font to bold,
and .1 changes to underlining (italic). mm uses these fonts until you invoke
another font macro, such as the .R macro, which restores roman font. Thus,

.I
here is sane text .
.R
yields underlined text via the nroff and italic text via the troff formatter.
If you invoke the .8 or .1 macro with one argument, that argument
appears in the appropriate font (underlined in the nroff formatter for .1).
Then mm restores the previous font (underlining is turned off in the nroff
formatter). If you give two or more arguments (maximum six) with a .8 or
.1 macro call, the second argument is concatenated to the first with no intervening space (1/12 space if the first font is italic), but it is printed in the
previous font. Remaining pairs of arguments are similarly alternated. For
example,
.I italic "

~rds

of text " right-justified

produces
it,lIic words of text rigllt-justified

The .8 and .1 macros alternate with the prevailing font at the time the
macros are invoked. To alternate specific pairs of fonts, the following macros are available:
.IB

.BI

.IR

.R!

TECHNICAL DISCUSSION

.RB

.BR

Miscellaneous Macros

Each macro takes a maximum of six arguments and alternates arguments
between specified fonts.
When you use a terminal that cannot underline, you can insert the following line in the parameter setting segment to eliminate all underlining:
.rIn

.rm cu

mm handles font changes in headings separately {3.5.2.4}.

6.2. Justification of Right Margin (.SA)
Use the .SA macro to set right-margin justification for the main body of
text.
.SA [arg]

Choose from two justification flags: current and default. Initially, mm sets
both flags for no justification in the nroff formatter and for justification in
the troff formatter. An argument to .SA causes the following action:
Argument

Omitted

Meaning
Sets both flags to no justification.
It acts like the .na request.

Sets both flags to cause both
right and left justification,
the same as the .ad request.

Causes the current flag to be copied
from the default flag, thus
performing either a .na or .ad
depending on the default condition.

Figure 13: Arguments to the .SA Macro

mm: TECHNICAL DISCUSSION

Miscellaneous Macros

In general, you can use the no adjust request (.na) to ensure that
justification is turned off. Use .SA to restore justification, rather than the .ad
request. Specify justification or no justification for the remainder of the text
by inserting .SA 1 or .SA 0 one time at the parameter setting segment.

6.3. Skipping Pages (.SK)
The .SK macro skips pages but retains the usual header and footer processing.
•SK [pages]

If you omit the pages argument, or make it null or 0, .SK skips to the top of
the next page unless it is currently at the top of a page (then it does nothing). .SK n skips n pages. .SK positions text that follows it at the top of a
page, while .SK 1 leaves one page blank except for the header and footer.

6.4. Forcing an Odd Page (.OP)
Use the .OP macro to ensure that formatted output text following the
macro begins at the top of an odd-numbered page.

•op
• If currently at the top of an odd-numbered page, text output
begins on that page (no motion takes place).

• If currently on an even page, text resumes printing at the top of
the next page.
• If currently on an odd page (but not at the top of the page), one
blank page is produced, and printing resumes on the next oddnumbered page after that.

TECHNICAL DISCUSSION

Miscellaneous Macros

6.5. Setting Point Size and Vertical Spacing (.5)
Change the prevailing point size and vertical spacing by invoking the .S
macro.

.s [point size [vertical_spacing] ]
In the troff formatter, the default point size (obtained from the mm register
5 (8.4}) is 10 points, and the vertical spacing is 12 points (six lines per inch).
You may use the mnemonics 0 (default value), C (current value), and P
(previous value) for both arguments.
• If an argument is negative, current value is decremented by
the specified amount.
•

If an argument is positive, current value is incremented by the
specified amount.

• If an argument is unsigned, it becomes the new value.
•

If there are no arguments, the .S macro defaults to P.

• If you specify the first argument but not the second, then
(default) 0 is used for the vertical spacing.

Default value for vertical spacing is always two points greater than the
current point size. Footnotes {3.3} are two points smaller than the body
with an additional 3-point space between footnotes. A null ("") value for
either argument defaults to C (current value). Thus, if n is a numeric value:

mm: TECHNICAL DISCUSSION

Miscellaneous Macros

Macro and
Argument

.s n
.s n
.s
.s
.s n n

Result
.S p p
.S en
.S 0 e
.So D
.SeD
.S e e
.S 00

Figure 14: Arguments to the .S Macro

P means previous value, D means default value (usually 10 point), and
means current value

If you make the first argument greater than 99, the default point size (10
points) is restored. If the second argument is greater than 99, mm uses the
default vertical spacing (current point size plus two points). For example,

.S 100
.S 14 111

.S 10 12
.S 14 16

The .SM macro allows you to reduce by one point the size of a string.
•SM strinq1 [strinq2] [strilx]3l

If you omit the third argument (string3), the first argument (string1) is
made smaller and is concatenated with the second argument (string2), if
specified. If all three arguments are present (even if any are null), the
second argument is made smaller and all three arguments are concatenated.
For example,

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - Miscellaneous Macros

Input
.SMX
.SM XY
.SM Y X Y
.SM YXYX
.SM YXYX)
.SM (YXYX)
.SM Y XYX ""

Output

x
xY
YXY
YXYX
YXYX)
(YXYX)
YXYX

6.6. Producing Accents
The following example shows that you may use strings to produce
accents for letters:

Input

Output

Grave accent

c\·

Acute accent

e\·'

Circumflex

0\-"

Tilde

n\·-

Cedilla

c\.,

Lower-case umlaut

u\·:

Upper-case umlaut

U\·;

Name

6.7. Two-Column Output (.2C, .tC)
The mm text formatting macro package can format two-columns on a
page. The .2C macro begins 2-column processing that continues until a .tC
macro (I-column processing) is encountered.

mm: TECHNICAL DISCUSSION

Miscellaneous Macros

.2C
text and fomatting requests (except another . 2C)
.1C

In 2-column processing, each physical page is thought of as containing 2columnar "pages" of equal (but smaller) "page" width. Page headers and
footers are not affected by 2-column processing. The .2C macro does not
balance 2-column output.
It is possible to have full-page width footnotes and displays when in 2column mode though footnotes and displays are by default narrow in 2column mode and wide in I-column mode..WC controls footnote and
display width, which is specified in arguments. .WC WD FF, for instance,
causes all displays to be wide and all footnotes to be the same width.
.WC N reinstates the defaults. If you give conflicting settings to .WC, mm
selects the last one: a .WC WF -WF command has the effect of a .WC -WF.
Arguments to .WC are as follows:

Argument:

Meaning:

Default mode (-WF, -FF, -WD, FB).

Wide footnotes (even in 2-column mode).

-WF

DEFAULT: Turn off WF. Footnotes follow column mode;

wide in I-column mode (.lC), narrow in 2-column
mode (.2C), unless FF is set.
FF

First footnote. All footnotes have same width as first
footnote encountered for that page.

-FF

DEFAULT: Turn off FF. Footnote style follows settings

of WF or -WF.
WD

Wide displays (even in 2-column mode).

-WD

DEFAULT: Displays follow the column mode in effect

when display is encountered.
FB

DEFAULT: Floating displays cause a break when output

on the current page.

-FB

Floating displays on current page do not cause a break.

TECHNICAL DISCUSSION

Miscellaneous Macros

6.8. Inserting Text Interactively (.RD)
The .RO (read insertion) macro allows you to stop the standard output
of a document and to read text from the standard input until two consecutive newline characters are found .
•RO [prompt [diversion [string] ] ]

When newline characters are encountered, normal output is resumed.
• The prompt argument prints at the terminal. If not given,
.RO signals you with a BEL on terminal output.
• The diversion argument allows you to save all text typed in
after the prompt in a macro whose name is that of the diversion.
• The string argument allows you to save for later reference the
first line following the prompt in the named string.
The .RO macro follows the formatting conventions in effect. Thus, the
following examples assume that the .RD is invoked with line-filling off
(.nf):
.RO Name aA bB

produces
Name: J. Jones

(you type name)

16 Elm Rd.,

Piscataway

The diverted macro .aA will contain
J. Jones
16ElmRd.,

Piscataway

The string bB (V·(bB) contains "J. Jones."
A newline character followed by an EOF (user specifiable CONTROL-d)
also allows you to resume normal output.

mm: TECHNICAL DISCUSSION

Miscellaneous Macros

6.9. SCCS Release Identification (RE)
The RE string contains the sees release and the mm text formatting
macro package current version level. For example,
'Ihis is version \*(RE of the macros.

produces
- 1 -

This is version 10.129 of the

maCIOS.

This information is useful in analyzing suspected bugs in mm. The
easiest way to have the release identification number appear in the output is
to specify -rDt {8.4} on the command line. This causes the RE string to be
output as part of the page header {3.4.1}.

6.10. Extending and Changing the Macros
6. 1O. 1. Naming Conventions

In this part, the following conventions are used to describe names:
n

Digit

Lower-case letter

Upper-case letter

Any alphanumeric character (n, a, or A, that is, letter or digit)

Any nonalphanumeric character (special character)

Request, macro, and string names are kept by the formatters in a single
internal table; therefore, there must be no duplication among such names.
Number register names are kept in a separate table.

TECHMCALD~CUSmON

Miscellaneous Macros
6.10.1.1. Components Used by Formatters

Requests:

aa (most common)
an (only one, currently: c2)

Registers:

aa (normal)
.x (normal)
.5 (only one, currently: .$)
a. (only one, currently: c.)

6.10.1.2. Components Used by mm

Macros and Strings:

A, AA, Aa (accessible to you; for example, macros
.P and .HU, strings F, BU, and Lt)
nA (accessible to you; only two, currently: IC and
2C)

aA (accessible to you; only one, currently: nP)
5 (accessible to you; only the seven accents,
currently (6.6})

registers:

An, Aa (accessible to you; for example, HI, Fg)
A (accessible to you; meant to be set on the command line; for example, C)

6.10.2. Sample Extensions
6.10.2.1. Appendix Headings

The follOWing is a way of generating and numbering appendix headings:

mm: TECHNICAL DISCUSSION

Miscellaneous Macros

.nr Hu 1
.nr a 0
.de aH
.nr a +1

.nr P 0
•PH 'I' , 'Appendix \ \na-\\ \ \nP' 'I
.SK

.HU "\\$1"

After the above initialization and definition, each call of the form
.aH "Title"

begins a new page (with the page header changed to "Appendix a-n") and
generates an unnumbered heading of title, which, if desired, can be saved
for the table of contents. To center appendix titles the Hc register must be
set to 1 {3.5.2.3}.
6.10.2.2. Hanging Indent with Tabs.

The following example uses the hanging indent feature of variable-item
lists {3.2.4}. A user-defined macro is defined to accept four arguments that
make up the mark. In the output, each argument is to be separated from the
previous one by a tab; tab settings are defined later. Since the first argument may begin with a period or apostrophe, the \& is used so that the formatter does not interpret such a line as a formatter request or macro call.
The 2-character sequence \& is understood by formatters to be a zero-width
space. It causes no output characters to appear, but it removes the special
meaning of a leading period or apostrophe. The \t is translated by the formatter into a tab. The \c is used to concatenate the input text that follows
the macro call to the line built by the macro.

TECHNICAL DISCUSSION

Miscellaneous Macros

.de

.LI

\&\\$1\t\\$2\t\\$3\t\\$4\t\c

.ta 8 14 20 24
.VL 1.0i
.ax .nh off \- no
No hyphenation.
Autanatic h¥Phenation is turned off.
WXds cantai.nin] h;yphens
(far ~le, l1Other-in-Iaw) may still be split across lines .
.ax .h;y on \- no
Hjphenate.
Autanatic h;yphenation is turned on .

.aX .he\ c none none no
Hyphenation indicator character is set to "C " or renoved.
During text processin], the iDiicator is suppressed
and will not appear in the output.
PrependinJ the indicator to a word has the effect
of preventing h;yphenation of that word •
•LE

The resulting output is:
-

1 -

No hyphenation. Automatic hyphenation is turned off. Words
containing hyphens (for example, mother-in-law) may still
be split'across lines.
Hyphenate.

Automatic hyphenation is turned on.

mm: TECHNICAL DISCUSSION

Miscellaneous Macros

6.11. Vertical Spacing (.SP)
There exists several ways of obtaining vertical spacing, all with different
effects. The .sp request spaces the number of lines you specify unless you
turn off spacing with .ns, then mm ignores the .sp request. You can restore
spacing with the .rs request.
Spacing is turned off automatically at the end of a page header to eliminate spacing by a .sp or .bp request that happens to occur at the top of a
page.
Use the .SP macro to avoid the accumulation of vertical space by successive macro calls.

.sP (lines]
Several .SP calls in a row will not produce the sum of the arguments but
only the maximum argument. For example, the following produces only
three blank lines:

.sP 2
.sP 3
.sP
Many mm macros use .SP for spacing. For example, if you immediately
follow .LE 1 {3.2.t} with .P {3.t}, mm produces only a single blank line
(one-half vertical space) between the end of the list and the following paragraph. An omitted argument to .SP defaults to one blank line (one vertical
space). Negative arguments are not permitted. The argument must be unsealed, but fractional amounts are permitted. The .DS request also inhibits
the .SP macro (as well as the .sp request).

100

nCHMCALD~CUSmON

7. Troubleshooting and Error Messages

7. 1. Error Terminations
When an mm macro detects an error, it performs the following actions:
• It performs a line break.

• It prints the formatter output buffer (which may contain some
text) to avoid confusion regarding location of the error.
• It prints a short message giving the name of the macro that

detected the error, type of error, and approximate line
number in the current input file of the last processed input
line. The last section of this chapter explains error messages.
• It stops processing unless register 0 (8.4) has a positive value.
In the latter case, it continues processing even though the

output is guaranteed to be garbled from that point on.
The error message outputs directly to your terminal. If you are using an
output filter, such as 300, 450, or hp to postprocess the nroff formatter output, this message may be garbled by being intermixed with text that is held
in that filter's output buffer. If you are using any eqn/neqn or tbl material,
and if the -olist option of the formatter causes the last page of the document not to be printed, a harmless "broken pipe" message may result.

7.2. Disappearance of Output
Disappearance of output usually occurs because of an unclosed diversion
(for example, a missing .OE or .FE macro). Fortunately, macros that use
diversions are careful about it, and these macros check to make sure that
illegal nestings do not occur. If any error message is issued about a missing
.OE or .FE, search backwards from the termination point and look for the
corresponding .OF, .05, or .FS (since you must use these macros in pairs).

mm: TECHNICAL DISCUSSION

101

Troubleshooting and Error Messages

The command grep -n '''\~EDFRT][EFNQSrfiles ... prints all the .DF,
.DS, .DE, .EQ, .EN, .FS, .FE, .RS, .RF, .TS, and .TE macros found in files ...,
each preceded by its file name and the line number in that file. Use this
listing to check for illegal nesting and/or omission of these macros. Also,
the checkmm programs finds mismatched macro pairs.

7.3. Error Messages
An mm error message has a standard part followed by a variable part.
The standard part has the form:
mRCR :

(file)input line n:

Variable parts consist of a descriptive message usually beginning with a
macro name. Appendix 0 lists them in alphabetical order by macro name,
each with a more complete explanation.

102

TECHNICAL DISCUSSION

8. Using the mm Command Line
Use the mm command line to print documents using nroff and the mm
macros. Use mmt to format documents with troff and the macros.

8. 1. Typical mm Command Lines and Options
These are the typical command lines for mm (options are described
below). Pipe results to a printer or phototypesetter as appropriate, or
redirect output to a file.
• Text without tables or equations:
mm [options] file ...
mmt options file ...
• Text with tables:
mm -t options file ...
mmt -t options file ...
• Text with equations:
mm -e options file ...
mmt -e options file ...
• Text with line pictures:
mmt -p options file ...
• Text with graphs:
mmt -g options file ...

mm: TECHNICAL DISCUSSION

103

Using the mm Command Line

• Text with both tables and equations:
mm -t -e options file ...
mmt -t -e options file ...
• Text with tables, equations, pictures and graphs:
mmt -t -e -p -g options file ...

You can put options in any order you wish, but you must put them before
the file name(s).
-e calls neqn (mm) or eqn (mmt) and causes it to read
lusr/pub/eqnchar
-c calls col(l)
-t

calls tbl

-p calls pic (use this with mmt only)
-g calls grap (use this with mmt only)
-E calls the -e option of nroff
-12 specifies that 12 characters per inch, or 78 characters per normal output line (6 1/2 inches) are output. This specification is called "12pitch mode." The pitch switch on your printer should be set to 12.
By default, 10 characters per inch are output.

-Ttty_type
specifies to which output device you are sending your output.
When you format a document, prepare the output for a particular type of
terminal, because the output may require features that are specific to that
tprminal. For example, some terminals produce reverse paper motion or
half-line paper motion in both directions. A list of the supported terminals
you may use with mm appears in the following section. (Check with your
system administrator for a list of locally supported devices.)

104

TECHNICAL DISCUSSION

Using the mm Command Line

If you use two-column processing {6.7}, you must specify either the -c
option to mm [mm uses col(1) automatically for many terminal types] or
you must postprocess nroff formatter output with col(1). In the latter case,
you must specify the -T37 terminal type to the nroff formatter, take care
not to specify the -h option, and process the output of col(1) by the
appropriate terminal filter (for example, 450); mm with the -c option handles all this automatically.

8.2. Command Line Options for Specifying a Printer
Use one of the following arguments to the mm command line option
-T to specify an output device to the formatter. To specify a program that
drives the printer, use the -T option. It is a way of telling the formatter to
carry out certain operations that your particular printer program can execute. Ask your system administrator what argument to -T is appropriate
for your text formatting set-up. A list of all supported arguments (values for
tty_type) and the devices they signify are as follows:

Hewlett-Packard 2631 printer in regular mode
Hewlett-Packard 2631 printer in compressed
mode
2631-e Hewlett-Packard 2631 printer in expanded mode
DASI·300 printer
300
300-12 DASI-300 terminal set to 12-pitch (12 characters
per inch)
DASI-300s printer (3005 is a synonym)
3005
3005-12 DASI·300s printer set to 12-pitch (12 characters
per inch) (3005-12 is a synonym)
Teletype Model 37 terminal
37
DTC-382
382
Trendata 4000a terminal (4000A is a synonym)
4000a
DASI·450 (Diablo Hyterm) printer
450
450-12 DASI·450 terminal set to 12-pitch (12 characters
per inch)
Anderson Jacobson 832 terminal
832
C.ITOH printer
8510
generic name for printers that can underline
Ip

2631
2631-c

mm: TECHNICAL DISCUSSION

105

Using the mm Command Line

tn300
X

and tab. (All text using reverse linefeeds, such
as those having tables, that is sent to Ip must be
processed with col.) Ip is the default device for
mm.
GE Terminet 300 terminal
printers equipped with TX print train

8.3. Giving nroff or troff the -mm Flag
You may also use the mm package by including the -mm flag as an
argument to nroff or troff. The -mm flag causes the file
lusr/lib/tmac/tmac.m to be read and processed before any other files. This
action:
• defines the Memorandum Macros
• sets default values for various parameters
• initializes the formatter to be ready to process input text files

8.4. SeUing Number Registers from the Command
Line
With mm, you commonly use number registers to hold parameter values
that control various aspects of output style. You can change many of these
values within the text files with .nr requests. In addition, you can set some
of these registers from the command line. This is useful when parameters
should not be embedded within the input text. The number register meanings are

106

-rAn

n = 1 has effect of invoking the .AF macro without an
argument (4.1.7).

-ren

Sets type of copy (for example, DRAFT) to be printed at
bottom of each page {3.4.3}.
n = 1 for OFFICIAL FILE COPY.
n = 2 for DATE FILE COPY.
n = 3 for DRAFT with single spacing and default paragraph style.

TECHNICAL DISCUSSION

Using the mm Command Line

n = 4 for DRAFT with double spacing and IO-space
paragraph indent.
-rDl

Sets debug mode.
This flag requests formatter to continue processing even
if mm detects errors that would otherwise cause termination. It also includes some debugging information in
the default page header {3.4.I}.

-rEn

Controls fo~t of Subject/Date/From fields.
n = 0, fields are bold (default for the troff formatter).
n = 1, fields are roman font (regular text-default for the
nroff formatter).

-rLk

Sets length of physical page to k lines.
For the nroff formatter, k is an unscaled number
representing lines.
For the troff formatter, k must be scaled.
Default value is 66 lines per page.
This flag is used, for example, when directing output to
a Versatec printer.

-rNn

Specifies page numbering style (See Figure 8-1).
n = 0 (default), all pages get the prevailing header
{3.4.1}.
n ;: 1, page header replaces footer on page 1 only.
n = 2, page header is omitted from page 1.
n = 3, "section-page" numbering {3.5.3} occurs (.FD
{3.3.I} and .RP {5.7} defines footnote and reference
numbering in sections).
n = 4, default page header is suppressed; however, a
user-specified header is not affected.
n = 5, "section-page n and "section-figure" numbering
occurs.

mm: TECHNICAL DISCUSSION

107

Using the mm Command Line

Page 1

Pages 2-end

header
header replace s footer
no header
"sectio n-page " as footer
no header
"sectio n-page " as footer
and "section-figure"

header
header
header
same as page 1
no header unless .PH define d
same as page 1

1
2

3
4

Figure 15: Effects of the n Registe r on Page Numbe ring Style

Conten ts of the prevail ing header and footer do not depen d
on numbe r registe r N value; N contro ls wheth er the header
(N=3) or the footer (N-5) is printed , as well as the page
numbe ring style. If header and footer are null {3.4}, the
value of N is irrelev ant.
-rOk

-rPn

Offsets output k spaces to the right.
For the nroff format ter, k is an unseal ed numbe r represe nting lines or charac ter positio ns.
For the troff format ter, k must be scaled.
This flag is helpfu l for adjusti ng output positio ning on some
termin als. The default offset if this registe r is not set on the
comma nd line is 0.75 inch (nroff) and 0.5 inch (troff) .
Specifi es that pages of the docum ent are to be numbe red
startin g with n.
This registe r may also be set via a .nr reques t in the input
text.

-rSn

Sets point size and vertica l spacin g for the docum ent.
The defaul t n is 10, that is, 10-poi nt type on 12-poi nt vertica l
spacin g, giving six lines per inch {6.5}.
This flag applies to the troff format ter only.

-rTn

Provid es registe r setting s for certain devices .
If n is 1, line length and page offset are set to 80 and 3,
respect ively.
Setting n to 2 change s the page length to 84 lines per page

108

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - Using the mm Command Line

and inhibits underlining; it is meant for output sent to the
Versatec printer.
This flag applies to the nroff formatter only.
-rUt

Controls underlining of section headings. This flag causes
only letters and digits to be underlined. Otherwise, all characters (including spaces) are underlined {3.5.2.4.2}. This flag
applies to the nroff formatter only.

-rWk

Sets page width (line length and title length) to k.
For the nroff formatter, k is an unsealed number representing character positions.
For the troff formatter, k must be scaled.
This flag can be used to change page width from the default
value of 6 inches (60 characters in 10 pitch or 72 characters
in 12 pitch).

mm: TECHNICAL DISCUSSION

109

9. Appendices

9. 1. Appendix A: mm Macro Name Summary
The following listing shows all the mm macros and their usage. Each
item in the list gives a definition of the macro followed by its normal format and arguments. The numbers enclosed in braces {} show the section in
this technical discussion where a complete explanation of each macro may
be found. You do not call macros marked with an asterisk directly. They
are "user exits" that you define, and they are called by the mm macros from
inside header, footer, or other macros.
.

.tC

I-column processing {6.7}

.tC

110

.2C

2-column processing {6.7}
.2C

.AE

Abstract end {4.2.I}
.AE

.AF

Alternate format of "subject:/date:/from: block {4.1.7}
.AF ["name of firm"]

.AL

Automatically incremented list start {3.2.2}
.AL [type [text-indent [1] ] ]

.AS

Abstract start {4.2.I}
.AS [arg [indent] ]

.AT

Author's title {4.1.6}
.AT [title] ...

•AU

Author information {4.1.S}
.AU name [initials [/oe [dept [ext [room [arg [arg [arg] ] ] ] ] ] ] ]

.AV

Approval signature {S.2}
.AV [name [1] ]

bold {6.I}
.B [bold-arg [previous-font-arg] ] •••

TECHNICAL DISCUSSION

Appendices

.BE

Bottom block end {4.2.3}
.DE

.BI

bold/italic {6.1}
.BI [bold-arg [italic-arg [bold [italic [bold [italic] ] ] ] ] ]

.BL

Bullet list start {3.2.5}
.BL [text-indent [I] ]

.DR

bold/roman {6.I}
.BR [bold-arg [roman-arg [bold [roman [bold [roman] ] 1] ] ]

.BS

Bottom block start {4.2.3}
.BS

.CS

Cover sheet {5.6}
.CS [pages [other [total [figs [tbls [refs] ] ] ] ] ]

.DE

Display end {3.6.1}
.DE

.DF

Display floating start {3.6.2}
.DF [format [fill [rindent]] ]

.DL

Dash list start {3.2.5}
.DL [text-indent [1] ]

.DS

Display static start {3.6.1}
.DS [format [fill [rindent] ] ]

.EC

Equation caption {3.9}
.EC [title [override [flag] ] ]

.EF

Even-page footer {3.4.4}
.EF [arg]

.EH

Even-page header {3.4.2}
.EH [arg]

.EN

End equation display {3.8}
.EN

.EQ

Equation display start {3.8}
.EQ [label]

.EX

Exhibit caption {3.9}
.EX [title [override [flag] ] ]

mm: TECHNICAL DISCUSSION

111

Appendices

.FC
.FD

Formal closing {S.I}
.FC [closing]
Footnote default format {3.3.I}
.FD [arg [1] ]

112

.FE

Footnote end {3.3}
.FE

.FG

Figure title {3.9}
.FG [title [override [flag] ] ]

.FS

Footnote start {3.3}
.FS [label]

Heading-numbered {3.5}
.H level [heading-text [head'ing-sujfix] ]

.HC

Hyphenation character h.4.4}
.HC [hyphenation-indicator]

.HM

Heading mark style (Arabic or roman numerals, or letters)
{3.5.2.6}
.HM [argl] ... [arg7]

.HU

Heading-unnumbered {3.S.I}
.HU heading~text

.HX·

Heading user exit X (before printing heading) {3.5.4}
.HX dlevel rlevel heading-text

.HY·

Heading user exit Y (before printing heading) {3.5.4}
.HY dlevel rlevel heading-text

.HZ·

Heading user exit Z (after printing heading) {3.5.4}
.HZ dlevel rlevel heading-text

italic (underline in the nroff formatter) {6.1}
.I [italic-arg [previous-!ont-arg] ] •••

.IA

Inside address start {4.5.3}
.IA [addressee-name [title] ]

.ID

italic/bold {6.1}
.ID [italic-arg [bold-arg [italic [bold [italic [bold] ] ] ] ] ]

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - Appendice8

.IE

Inside address end {4.S.3}
.IE

.IR

italic/roman {6.1}
.IR [italic-arg [roman-arg [italic [roman [italic [roman] ] ] ] ] ]

.lD

List begin {3.2.7}
.lD text-indent mark-indent pad type [mark [Ll-space] ]
[LB-space]

.lC

List-status clear {3.2.S}
.lC [list-level]

.IT

Letter Type {4.S.I}
.IT [arg]

.lE

List end {3.2.1}
.lE [I]

.ll

List item {3.2.1l
.ll [mark [I] ]

.lO

Letter Options {4.S.4}
.lO type [arg]

.Ml

Marked list start {3.2.3}
.Ml mark [text-indent [I] ]

.MT

Memorandum type {4.1.1}
.MT [type [addressee] ] or .MT [4] [I]

.ND

New date {4.1.3}
.ND new-date

.NE

Notation end {5.3}
.NE

.NS

Notation start {S.3}
.NS [arg [I] ] nP" Double-line indented paragraphs {3.1.2}
.nP

.OF

Odd-page footer {3.4.4}
.OF [arg]

.OU

Odd-page header {3.4.2}
.OU [arg]

mm: TECHNICAL DISCUSSION

113

Appendices

.OK

Other keywords for the Technical Memorandum cover sheet
{4.2.2}
.OK [keyword] ...

•OP

Odd page {6.4}
.OP

Paragraph {3.t}
.P [type]

.PF

Page footer {3.4.3}
.PF [arg]

.PH

Page header {3.4.1}
.PH [arg]

.PM

Proprietary marking {4.3}
.PM [code]

.PX Ifo

Page-header user exit {3.4.9}
.PX

Return to regular (roman) font {6.1}

.R
.RB

114

roman/bold {6.1}
.RB [roman-arg [bold-arg [roman [italic [roman [italic] ] ] ] ]

.RD

Read insertion from terminal {6.8}
.RD [prompt [diversion [string] ] ]

.RF

Reference end {5.7}
.RF

.RI

roman/italic {6.1}
.RI [roman-arg [italic-arg [roman [italic [roman [italic] ] ] ] ] ]

.RL

Reference list start {3.2.5}
.RL [text-indent [I] ]

.RP

Produce reference page {5.7}
.RP [arg [arg]

.RS

Reference start {5.7}
.RS [string-name]

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - Appendices

Set troff formatter point size and vertical spacing {6.S}
.S [size [spacing] ]

.SA

Set adjustment (right-margin justification) default {6.2}
.SA [arg]

.SG

Signature line {S.I}
.SG [arg [1] ]

.SK

Skip pages {6.3}
.SK [pages]

.SM

Make a string smaller {6.S}
.SM stringl [string2 [string3] ]

.SP

Space vertically {6.II}
.SP [lines]

.TB

Table title {3.9}
.TB [title [override [flag] ] ]

.TC

Table of contents {S.4}
.TC [slevel [spacing [tlevel [tab [hl [h2 [h3 [h4 [h5] ] ] ] ] ] ] ] ]

.TE

Table end {3.7}
.TE

.TH

Table header {3.7}
.TH [N]

.TL

Title of memorandum {4.1.4}
.TL [charging-case [filing-c~se~ ]

.TM

Technical Memorandum number(s) {4.1.2}
.TM [number] ...

.Tp lfo

Top-of-page macro {3.4.9}
.TP

.TS

Table start {3.7}
.TS [H]

.TX Ifo

Table of contents user exit {S.S}
.TX

.TY Ifo

Table of contents user exit (suppresses "CONTENTS") {S.4.1}
.TY

mm: TECHNICAL DISCUSSION

115

Appendices

.VL

Variable-item list start {3.2.4}
.VL text-indent [mark-indent [1]]

•VM

Vertical margins {3.4.7}
.VM [top [bottom] ]

.WA

Writer's address start {4.5.2}
.WA writer-name [title]

.WC

Footnote and display width control {6.7}
.WC [format]

.WE

Writer's address end {4.5.2}
.WE

9.2. Appendix B: mm String Name Summary
The following list shows the predefined string names used by the mm
macro package. The numbers in braces {} show the section in this technical
discussion where more information about the string can be found.

116

Bullet {1.4.6}
nroff: e
troff:-

Table of contents indent list {S.4.1}
Up to seven scaled arguments for heading levels

Date h.2}
Current date, unless overridden
Month, day, year (for example, May 31, 1979)

Em dash string h .4.7}
Produces an em dash in the troff formatter and a double
hyphen in nroff F Footnote number generator {3.3}
nroff: \u\\n+(:p\d
troff: \v'-.4m'\s-3\\n+(:p\sO\v'.4m'

Heading font list {3.S.2.4.1}
Up to seven codes for heading levels 1 through 7
2 2 2 2 2 2 2 (all levels given emphasis)

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - - Appendices

Heading point size list {3.5.2.5}
Up to seven codes for heading levels 1 through 7

Title for LIST OF EQUATIONS {3.9}

Title for LIST OF FIGURES {3.9}

Title for LIST OF TABLES (3.9)

Title for LIST OF EXHIBITS (3.9)

sees Release and Level of mm

(6.9)

Release.Level (for example, 15.129)
Rf

Reference number generator {5.8}

Title for References {5.8}

Trademark string h.4.8}
Places the letters "TM" one-half line above the text that it follows Seven accent strings are also available. (See section 6.6.)

9.3. Appendix C: mm Number Register Summary
The list that follows contains a description of all the predefined number
registers used by mm. Numbers enclosed in braces {} show the section in
this technical discussion where more information about the register can be
found. After each description is the normal value of the register followed
by the range of allowable values, enclosed in brackets []. The lower and
upper limit of values are separated by a colon (:). An asterisk attached to a
register name means that this register can be set only from the command
line or before the mm macro definitions are read by the formatter. Section 1.2 has notes on setting and referencing registers. Any register haVing
a single-character name can be set from the command line {8.4}. These are
marked with a dagger (t) in the follOWing list.
A •t

Handles preprinted forms and logo
{8.4} 0, [0:2]

Inhibits printing of author information
(4.1.5) 1, [0:1)

mm: TECHNICAL DISCUSSION

117

Appendlcea

118

C •t

Copy type (original, DRAFf, and so on)
(8.4) 0 (Original), [0:4]

Level of headings saved for table of contents
(3.5.3) 2, [0:7]

Placement of list of figures, and so on
(3.9) 1 (on separate pages), [0:1]

D •t

Debug flag
(8.4) 0, [0:1]

Display eject register for floating dislays
(3.6.2) 0, [0:1]

Display format register for floating displays
(3.6.2)5, [0:5]

Static display pre- and post-space
(3.6.1) 1, [0:1]

E •t

Controls font of the subject: I date: I from: fields
(8.4) 1 (nroff) 0 (troff), [0:1]

Equation counter, used by .EC macro
(3.9) 0, [o:?]
Incremented by one for each .EC call.

Page-ejection flag for headings
(3.5.2.1} 0 (no eject), [0:7]

Equation label placement
{3.8} 0 (right-adjusted), [0:1]

Exhibit counter, used by .EX macro
(3.~) 0, [o:?] .
Incremented by one for each .EX call.

Figure counter, used by .FG macro
{3~9} 0, [o:?]
Incremente.d by one for each .FG call.

Footnote space (that is, spacing between footnotes)
{3.3.2} t [o:?]

TECHNICAL DISCUSSION

Appendices

HI-H7

Heading counters for levels 1 through 7
{3.5.2.6} 0, (O:?]
Incremented by the .H macro of corresponding. level or the
.HU macro if at level given by the Hu register. The H2
through H7 registers are reset to by any .H (.HU) macro at a
lower-numbered level.

Heading break level (after .H and .HU)
{3.5.2.2} 2, [0:7]

Heading centering level for .H and .HU
{3.5.2.3} 0 (no centered headings), [0:7]

Heading temporary indent (after .H and .HU)
{3.5.2.2} 1 (indent as paragraph), [0:2]

Heading space level (after .H and .HU)
{3.5.2.2} 2 (space only after .H 1 and .H 2), [0:7]

Heading type (for .H: single or concatenated numbers)
{3.5.2.6} 0 (concatenated numbers: 1.1.1, and so on), [0:1]

Heading level for unnumbered heading (.HU)
{3.5. I} 2 (.HU at the same level as .H 2), [0:7]

Hyphenation control for body of document
{I.4.4} 0 (automatic hyphenation off), [0:1]

Length of page
{S.4} 66, [20:?]
(IIi, [2i:?] in troff formatter)

List of equations
{3.9} 0 (list not produced) [0:1]

List of figures
{3.9} 1 (list produced) [0:1]

List indent
{3.2.1} 6 (nroff) 5 (troff), [O:?]

List spacing between items by level
{3.2.1} 6 (spacing between all levels) [0:6]

List of tables
{3.9} 1 (list produced) [0:1]

mm: TECHNICAL DISCUSSION

119

Appendices

List of exhibits
{3.9} 1 (list produced) [0:1]

Numbering style
{S.4} 0, [0:5]
Numbering style for paragraphs
{3.1.2} 0 (unnumbered) [0:1]

o t

Offset of page
{S.4} .75i, [O:?]
(0.5i, [Oi:?] in troff formatter)
For nroff formatter, these values are unsealed numbers
representing lines or character positions. For troff formatter,
these values must be scaled.

Table of contents page numbering style
{5.4.1} 0 (lower-case roman), [0:1]

Figure caption style
{3.9} 0 (period separator), [0:1] Pt Page number managed by
mm
{S.4} 0, [O:?]

Paragraph indent
{3.1.3} 5 (nroff) 3 (troff), [O:?]

Paragraph spacing
{3.1.1} 1 (one blank space between paragraphs), [O:?]

Paragraph type
{3.1.I} 0 (paragraphs always left justified), [0:2]

··PRIVATE" header

{3.4.9} 0 (not printed), [0:2]
Rf

S
Si

120

Reference counter, used by .RS macro
{5.S} 0, [O:?]
Incremented by one for each .RS call.
It

The troff formatter default point size
{S.4} 10, [6:36]
Standard indent for displays
{3.6. I} 5 (nroff) 3 (troff), [O:?]

TECHNICAL DISCUSSION

Appendices

T •t

Type of nroff output device
{8.4} 0, [0:2]

Table counter, used by .TB macro
{3.9} 0, [o:?]
Incremented by one for each .TB call.

U •t

Underlining style (nroff) for .H and .HU
{8.4} 0 (continuous underline when possible), [0:1]

W •t

Width of page (line and title length)
{8.4} 6i, [10:1365]
(6i, [2i:7.54i] in the troff formatter)

9.4. Appendix D: ERROR MESSAGES
When processing text using the mm macro package, mm will
report any errors it can detect. Since the macros are written in the
basic formatter primitives, other errors may be found and reported
by the formatter.
An mm error message has a standard part followed by a variable
part. The standard part has the form:
ERROR:(filename) input line n:
The variable part consists of a descriptive message, usually beginning with a macro name. The variable parts are listed alphabetically
by macro name below:
CS:cover sheet too long
Text of the cover sheet is too long to fit on one page. The abstract
should be reduced or the indent of the abstract should be decreased.
DE:no DS or OF active
A .DE macro has been encountered, but there has not been a previous .DS or .DF macro to match it.
DF:illegal inside TL or AS
Displays are not allowed in the title or abstract.

mm: TECHNICAL DISCUSSION

121

AppendlcGs

DF:missing DE
A .DF macro occurs within a display, that is, a .DE macro has been
omitted or mistyped.
DF:missing FE
A display starts inside a footnote. The likely cause is the omission
(or misspelling) of a .FE macro to end a previous footnote.
DF:too many displays
More than 26 floating displays are active at once, that is, have been
accumulated but not yet output.
DS:illegal inside TL or AS
Displays are not allowed in the title or abstract.
DS:missing DE
A .DS macro occurs within a display, that is, a .DE has been omitted
or mistyped.
DS:missing FE
A display starts inside a footnote. The likely cause is the omission
(or misspelling) of a .FE to end a previous footnote.
FE:no FS active
A .FE macro has been encountered with no previous .FS to match it.
FS:missing DE
A footnote starts inside a display, that is, a .DS or .DF occurs
without a matching .DE.
FS:missing FE
A previous .FS macro was not matched by a closing .FE, that is, an
attempt is being made to begin a footnote inside another one.

122

TECHNICAL DISCUSSION

Appendices

H:bad arg:value
The first argument to the .H macro must be a single digit from one
to seven, but value has been supplied instead.
H:missing arg
The .H macro needs at least one argument.
H:missing DE
A heading macro (.H or .HU) occurs inside a display.
H:missing FE
A heading macro (.H or .HU) occurs inside a footnote.
HU:missing arg
The .HU macro needs one argument.
lD:missing arg(s)
The .lD macro requires at least four arguments.
lD:too many nested lists
Another list was started when there were already six active lists.
lE:mismatched
The .lE macro h~s occurred without a previous .lD or other list- initialization macro {3.2}. This is not a fatal error. The message is
issued because there exists some problem in the preceding text.
ll:no lists active
The .ll macro occurred without a preceding list-initialization macro.
The latter probably has been omitted or entered incorrectly.
lO: Required argument missing
The .lO macro requires an argument.

mm: TECHNICAL DISCUSSION

123

Appendices

LO: LO argument not recognized
You have provided an argument to .LO that it does not recognize.
LT: LT argument not recognized
You have provided an argument to .LT that it does not recognize.
ML:missing arg
The .ML macro requires at least one argument.
ND:missing arg
The .ND macro requires one argument.
RF:no RS active
The .RF macro has been encountered with no previous .RS to match
it.
RP:missing RF
A previous .RS macro was not matched by a closing .RF.
RS:missing RF
A previous .RS macro was not matched by a closing .RF.
S:bad arg:value
The incorrect argument value has been given for the .S macro {6.S}.
SA:bad arg:value
The argument to the .SA macro (if any) must be either 0 or 1. The
incorrect argument is shown as value.
SG:missing DE
The .SG macro occurred inside a display.
SG:missing FE
The .SG macro occurred inside a footnote.

124

TECHNICAL DISCUSSION

Appendices

SG:no authors
The .SG macro occurred without any previous .AU macro(s).
Check TL, AU, AS, AE, MT sequence
The correct order of macros at the start of a memorandum is shown
in section 4.1.8. Something has disturbed this order.
Check TL, AU, AS, AE, NS, NE, MT sequence
The correct order of macros at the start of a memorandum is shown
in section 4.1.8. Something has disturbed this order. (Occurs if the
.AS 2 (4.1.9) macro was used.)
VL:missing arg
The .VL macro requires at least one argument.
Check WA, WE, lA, IE, LT sequence
The correct order of these macros is shown in section 4.2.6. Something has disturbed this order.
)W: WA macro missing
If you use .LT, you must specify at least one .WA-.WE pair.

)W: WA or WE macro missing
If you use .WA or .WE, you must specify the other member of the
macro pair.

)W: WA, WE, or IE macro missing
You have omitted either or both of the .IA and .IE macros.
WC:unknown option
An incorrect argument has been given to the. we macro.

mm: TECHNICAL DISCUSSION

125

AppendlcG8

9.5. Appendix E: The Define FUe-

I usr I lib I macros I strings.mm
0\"
• \ It
• \ It

0\"
•\ n

•\ n
• \"

•\"
0\"

Copyright (c) 1984 AT&.T
All Rights Reserved
'mI5 IS UNPUBLIsHm PR:>PRlE1'ARl SXJRCE CODE OF ~T
'D1e copyright notice alxwe does not evidence art:! actual
or intended publication of such source code.
@( # )macroS: St:riDJs oDlD
105
• \ II tab
begins cxmnentso
No oc:mnerits shoold appear on the same line as the string
definiticmo

.\n

•\"

The followiD1 striD] is used by the macro MI'

•\"
.ds ]5

]5 defined as logo character

•\ "
}z ecinpany Name
.ds }Z N1&T Bell Laboratories
.\"
•\ "
The followiD1 St:riDJs are used by the macro fM
.\"
0\".
Proprietary mark:in] "fM1" (BP, Nt P and BPN) lines 1-4
ods ]M N1&T BELL ~ - ~
.ds ]0 Use plrsuaI1t to G.E.I. 2.2
.ds ]Q
.ds ]R
•\"
Proprie1".a%y mark:in] "PM2" (CA) lines 1-4
.ds ]A THIS I:XXDIENl' CCNrAINS ~ INFtlRMATIOO OF
.ds ]F A'1&T AND IS NJl' 'ro BE DISCLPRIETARr !C1'ICE ~ 0JIJm P/GE
.ds ]J
.ds ]K
.ds ]L
0\ n
Proprietary markiD] "PM4" (BPP am BR) lines 1-4
ods ]U A'1&T BELL ~ - ~ (~C'I'ED)
126

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - - Appendices

·ds
.ds
.ds
·V·
.ds
.ds
.ds
•ds

]V Solely for authorized persons haviDj a need to know
]W plrsuaJ1t to G.E.I. 2.2

]X
Proprietary mark:iD:J lIFMSlI
]i
]j
]k
]1

(IIL) lines 1-4

'mIS ~ CXNrAINS PROPRIErARY INRRofATICN OF

A'mLT BELL ~ AND IS tel'1':) BE DIscw;m,
REPRD.m>, CR PUBLISHm WI'11D11' WRrrIm (XN;mI' •
'mIS ~ MOST BE RE:m!mD II.I.mIBLE WHEN m::m; DISCARDED.
•\11
Proprietary markinq 1IFM611 (CI-II) lines 1-4
.ds ]m CI-II
.ds ]0 Not for disclosure to A'mLT Infamatians Systems •
.ds ]p SUbject to Fa:: separaticn requirements under CaIplter IIqui.ry II
.ds ]q

mm: TECHNICAL DISCUSSION

127

Appendices

9.6. Appendix F: Sample Footnotes
Input:
.FD 10

.P
This example illustrates several footnote styles
for roth labeled am autallatically numbered foob1otes.
First inplt, then altplt is shown.
With the foob1ote style set to the
default style,
the first footnote is processeq\*F
.FS
This is the first foob1ote text example.
This is the default style (.FD 10).
The right margin is not justified,
hyphenation is rot pexmi.tted,
text is indented, and the autanatically generated label is
right justified in the text-indent space .
•FE
and followed by a secx:md footnote. *****

.FS *****
This is the seoand footnote text exanple.
This is also the default style (.FD 10)
rot wi. th a lang footnote label (*****) provided by the user .
•FE

.FD 1
Footnote style is cl1aD]ed by using the . FD macro to
specify hyphenation, right margin justification,
indentation, am left justification of the label.
This produces the third footnote, \*F
.FS
This is the third footnote exanple (. FD 1).
The right margin is justified, the footrote text is indented,
and the label is left justified in the text-iJXlent space.
Although not necessarily illustrated by this example,
hyphenation is permi.tted .
•FE

and then the fourth footnote."

128

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - Appendices

.FS

This is the fourth footIx>te example (. Ft> 1).
The style is the same as the third footnote .
•FE
.Ft> 6

Footnote style is set again via the .Ft> macro for no hyphenation,

no right margin justification,
no indentation, am with the label left justified.
This prcx1uces the fifth footnote.\*F
.FS

This is the fifth footnote example (.Ft> 6).
The right margin is not justified, hyphenation is not pexmitted,
footnote text is not in1ented,
am the label is placed at the begi.nnin:J of the first line .
•FE

mm: TECHNICAL DISCUSSION

129

Appendices

Output:
-

1 -

This example illustrates several footnote styles for both
labeled and automatically numbered footnotes. First input,
then output is shown. With the footnote style set to the
default style, the first footnote is processed1 and followed
by a second footnote .••••• Footnote style is changed by
using the .FD macro to specify hyphenation, right margin
justification, indentation, and left justification of the
label. This produces the third footnote, 2 and then the
fourth footnote. ~ Footnote style is set again via the . FD
macro for no hyphenation, no right margin justification, no
indentation, and with the label left justified. This
produces the fifth footnote. 3
1. This is the first footnote text example. This is the
defaul t style (. FD 10). The right margin is not
justified, hyphenation is not permitted, text is
indented, and the automatically generated label is right
justified in the text-indent space .
••••• This is the second footnote text example. This is
also the default style (.FD 10) but with a long footnote
label ( ••••• ) provided by the user.
2. This is the third footnote example (. FD 1). The right
margin is justified, the footnote text is indented, and
the label is left justified in the text-indent space.
Although not necessarily illustrated by this example,
hyphenation is permitted.
:This is the fourth footnote example (. FD 1). The style
is the same as the third footnote.
3. This is the fifth footnote example (. FD 6). The right
margin is not justified, hyphenation is not permitted,
footnote text is not indented, and the label is placed at
the beginning of the first line.

130

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - Appendices

9.7. Appendix G: Formal Memorandum
Input:
.ND "September 28, 1984"
.TL
Ik>cument Production Coordinator
.AU "Jolm smith" JJ5 XF 5414 6398 7-123 machine_Sljjs
.AF "Business Carplter Systems, Inc."
.M!' 0

.P
Business Ca't1:Uter Systems, Inc. (ICS) has job

open.inJs for people that
can do the following tasks:
.AL

.LI
Develop metlxXls far producing

documentation
.LI
Perfonn duties resulting fnn the developnent of these methods.

For example,
.BL
.LI
Use text processinJ with UNIX* 1XX!lMENlER'5 w:>RI Use text processinq wi th UNIX. DOCUMENTER' S

WORKBENCH. (mm, nroff, tbl) to:
- Prepare documents and tables
- Develop new macro commands
«> Serve

as a point of contact for BCS with printers
and distributors.

If the job holder's interests and writinq skills match
the needs of the Technical Writing Staff, write
documents.

John Smith
Copy to
BCS Technical Wri ting Staf f

• Trademark of AT&T

mm: TECHNICAL DISCUSSION

133

Appendices

9.8. Appendix H: Business Letter
Input:

.00 AT "Persamel"
•WA "Bill Taylor" "Director of Placement 5ervi.ces ll

Columbia mrlversity
116th street
New York, NY 10019
.WE
.00 SA "Dear Dr. smith: II
.00 RN "Career Day l1
•IA I1Rebeoca smithII
Business Coup1ter Systems, Inc.
190 River Boulevard

Durham, N.C. 27707

.IE
.LT BL

\01ld be happy to include a representative of your oanpany in our
"Career Day" program this spriD;J.
I am forwarding your request to James Blinn, who is orqaniziD;J the event

this year .
•P
'lbank you for ywr interest in our placement programs.
•Fe "Sincerely, II
.$
.NS 5

.NE
.NS

J. Blinn
.NE

134

TECHNICAL DISCUSSION

Appendices

Output:
-

1 -

Columbia University
116th Street
New York, NY 10019
December 15, 1985
In reference to:

Career Day

Rebecca Smith
Business Computer Systems, Inc.
190 River Boulevard
Durham, N.C. 27707
ATTENTION:

Personnel

Dear Dr. Smi th:
We would be happy to include a representative of your
company in our nCareer Dayn proqram this sprinq. I am
forwardinq your request to James Blinn, who is orqanizinq
the event this year.
Thank you for your interest in our placement proqrams.

Sincerely,

Bill Taylor
Director of Placement Services
JL-der
Ene.
Copy to
J. Blinn

mm: TECHNICAL DISCUSSION

135

Table of Contents
1. Introduction

2. Table Delimiters (.TS and .TE)

3. Global Options

4. Format Section

4.1. Key Letters
4.2. Additional Features

5
7

5. Data

6. Additional Command Lines

7. Using the tb} Command

15
16
16

7.1. Equations in Tables
7.2. Using Number Registers

8. tb} Sampler

TABLE OF CONTENTS

1. Introdliction
This is a t,echnical discussion of tbl, a program that you use to' produce
simple and complex tables. Read this if you have had some experience with
tbl; if you have never used tbl before, you should read the tutorial "The
Preprocessor tbl" in the User's Guide.
Tables that you format with tbl consist of columns that you may center,
right-adjust, left-adjust, or align according to digit and decimal point. You
may place labels over single columns or groups of columns. A table entry
may contain equations or consist of several rows of text. You may draw
horizontal or vertical lines in the table, and you may enclose any table or
element in a box.

fbi: TECHNICAL DISCUSSION

2. Table Delimiters (.TS and .TE)
Delimit tables with the macro pair .TS (table start) and .TE (table end).
tbl processes certain commands (options, key letters, and commands specifying such details as point size and font control) that it finds between this
macro pair, and it generates formatting requests, escape sequences, defined
strings, and number registers. The .TS and .TE lines are copied so that
nraff/traff formatter layout macros (such as mm formatting macros) can use
these lines as delimiters. The general format of a file that you would submit to tbl is

text
.TS

table
.TE

text
.TS

table
.TE

text

The format of each table is

.TS

global options;
format section.
daia
.TE

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - Table Delimiters

Each table is independent and contains
• Global options that affect the layout of the whole table
• A format section that describes individual columns and rows
of the table
• Data that you want printed
Unlike the options section, the format section and data are always required.

fbI: TECHNICAL DISCUSSION

3. Global Options
You may specify a single line of options to affect the layout of the
whole table. These must be placed immediately after the .TS line. On this
line, you must separate options with spaces, tabs, or commas. You must end
the options line with a semicolon. Allowable options are

center

centers the table (default is left-adjusted)

expand

makes the table as wide as current line length

box

encloses the table in a box

allbox

encloses each data entry of the table in a box

doublebox

encloses the table in two boxes

tab (x)

separates data entries by using x instead of tab

linesize (n)

sets lines or rules (for example, from box) in n-point type

delim (xx)

recognizes x and x as eqn delimiters.

TECHNICAL DISCUSSION

4. Format Section
The format section of the table specifies the layout of the columns. Each
line in the format section corresponds to one line of table data except the
last format line, which corresponds to all following data lines up to any
additional .T& command line. (.T& is described below.) Each format line
contains a key letter for each column of the table.

4. 1. Key Letters
In the format section, you may separate key letters with spaces or tabs to
improve readability, but spaces or tabs are not necessary. A dot (.) indicates
the end of key letters and should follow the last key letter before data is
entered in the lines below. Key letters are
L or 1 specifies a left-adjusted column entry
R or r specifies a right-adjusted column entry
C or c specifies a centered column entry
N or n specifies a numerical column entry. Numerical entries are
aligned according to digit and decimal point.
A or a specifies an alphabetic subcolumn. All entries in an alphabetic
subcolumn are aligned on the left and positioned so that the
widest entry is centered within the column.
S or s specifies a spanned heading. The entry from the previous
column continues across this column. You may not use this key
letter for the first column of a table.
specifies a vertically spanned heading. The entry from the previous row continues down through this row You may not use this
key letter for the first row of a table.
The layout of key letters in the format section resembles the layout of
the data in the table. Thus, a simple 3-column format might appear as
css
lnn.

fbI: TECHNICAL DISCUSSION

Format Section

The first line of the table contains a heading centered across all three
columns. Each remaining line of the table contains a left-adjusted item in
the first column followed by two columns of numerical data. A sample
table in this format is

CENTERED HEADING
9.1
Item-a
34.22
Item-b
12.65
.02
23
5.8
Item-c
Total
69.87
14.92
Instead of listing the format of successive lines of a table on consecutive
lines of the format section, you may give successive line formats on the
same line, separated by commas. That is, you can specify the format for the
above exampIe like this:

s, 1 n n.

Again, signal the end of the key letter section with a dot (. ).
When you specify numerical column alignment (n), tbl seeks a location
for the decimal point. The rightmost dot (. ) adjacent to a digit is used as a
decimal point. If there is no dot adjoining a digit, the rightmost digit is
used as a units digit. If you do not specify alignment, the item is centered
in the column. However, you may use the escape sequence \& (a zerowidth character) to override dots and digits or to align alphabetic data. This
aligns the dots, and the \& disappears from the final output. In the following example, the output column shows how items in the input column are
aligned in a numerical column.

TECHNICAL DISCUSSION

Format Section

Input:

output:

.TS

center;

n.
13

4.2
26.4.12

abodefq
abod\&efq
abodefq\&
43\&.3.22
749.12

4.2
26.4.12

abodefq
abcrlefq
abcdefq
433.22
749.12

.TE

If you use numerical data in the same column with wider L or r type
table entries, tbl centers the widest number relative to the wider L or r
items and preserves alignment within the numerical items. This is similar
to the behavior of a type data. Alphabetic subcolumns (requested by the a
key letter) are always slightly indented relative to L items. If necessary, the
column width is increased to force this. This is not true for n type entries.
You should not use n and a items in the same column.

4.2. Additional Features
Additional features of the key letter system are
Horizontal lines
You may replace a key letter by an underscore (_) to
specify a horizontal line in place of the column entry, or
an equal sign (==) to specify a double horizontal line. If
an adjacent column contains a horizontal line or if there
are vertical lines adjoining this column, the horizontal
line extends to meet nearby lines. If you provide any
data entry for a column containing an underscore or an
equals sign, tbl ignores the entry and prints a warning
message.

fbi: TECHNICAL DISCUSSION

Format Section

Vertical lines
If you place a vertical bar (I) between column key letters,
a vertical line appears between the corresponding
columns of the table. A vertical bar to the left of the first
key letter or to the right of the last one produces a line at
the edge of the table. If two vertical bars appear between
. key letters, tbl draws a double vertical line.

Space between columns
You may follow a key letter with a number to show the
amount of separation between this column and the next.
The number specifies the separation in ens. One en is a
relative measure about the width of the letter "nil in the
current point size. More precisely, an en is the number
of points (1 point =z 1/72 inch) equal to half the current
type size. If you use the expand global option, these
numbers are multiplied by a constant so that the table is
as wide as the current line length. The default column
separation number is 3. If you change the separation
number, the largest space requested prevails.
Vertical spanning
Vertically spanned entries extending over several rows of
the table are centered in their vertical range. If you folIowa key letter with tor T, any corresponding vertically
spanned item begins at the top line of its range.
Font changes
You may specify that the corresponding column should
be in a different font from the default font (usually
roman) by following a key letter with the letter f or F
and a character naming the desired font. You should put
a space or a tab between a I-letter font name and whatever follows. The single letters B, b, I, and i are shorter
synonyms for fD and fl. Font-change requests given
with the data override these specifications.
Point size changes
You may specify the point size of the corresponding table
entries by following a key letter with p or P and a
number. If p or P is followed by an arithmetic expression, such as +2, the formatter interprets it as an increment (or decrement in the case of -2) from the current

TECHNICAL DISCUSSION

Format Section

point size. If you give both a point size and a column
separation value, you must separate them with one or
more blanks.
Vertical spacing changes
You may specify the vertical line spacing used ~ithin a
multi-line data entry by following a key letter with v or
V and a number. The formatter interprets an arithmetic
expression (+2 or -2, for example) as an increment or
decrement from the current vertical spacing. You mus.t
separate a column separation value by blanks or some
other specification from a vertical spacing request. This
request has no effect unless the corresponding data entry
is a text block.
Column width indication
You may specify minimum column width by following a
key letter with w or Wand a width value in parentheses
(for example, cw(S)). If the largest element in the column
is not as wide as this specified width value, the formatter
uses the width value to determine column size. If the
largest element in the column is wider than the value
you specify, the width of the largest element determines
column width.
The formatter also uses the width value as a default line
length for included text blocks. You can use normal
oroff I troff formatter dimensions, such as i, m, 0, v, or u
to scale the width value. (See the "nroff/troff Technical
Discussion".) If you do not specify a scale, the formatter
uses ens. If the width value is an unsealed integer, you
may omit the parentheses. If you give another width
value in a column, the last one you specify controls the
width.
Equal-width columns
If you follow a key letter by e or E, you specify equalwidth columns. The formatter makes all columns whose
key letters are followed by e or E the same width.
Staggered columns
You may specify that the corresponding entry is to be
moved up one-half line by following a key letter with u

fbi: TECHNICAL DISCUSSION

Format Section

or U. This ma~es it easy to have a column of differences
between numbers in an adjoining column. The allbox
option does not work with staggered columns.
Zero-width item
A key letter followed by z or Z specifies that the
corresponding data item is to be ignored in calculating
column widths. This may be useful in alloWing headings
to run across adjacent columns where spanned headings
would be inappropriate.
Default
Column descriptors missing from the end of a format line
are assumed to be L. That is, if you have more columns
of data than descriptors to specify them, the data in the
unspecified columns are left-justified. The longest line in
the format section defines the number of columns in the
table. tbl ignores columns in the data if there are not
corresponding key letters in the format section.
As some examples in the "tbl Sampler," the features need not be
separated by spaces except to avoid ambiguities involving point size and
font changes. Thus, a numerical column entry in italic font and 12-point
type with a minimum width of 2.5 inches and separated by 6 ens from the
next column could be specified as

np12w(2.5i)fI 6

TECHNICAL DISCUSSION

5. Data
Put table data after the format section, typing each line of the table as
one line of data. You may break a long input line into smaller lines by
ending each short line, except the last, with a backslash. The resulting output line is as long as the combined parts.
Data to be placed in different columns (data entries) should be separated
with tabs or with whatever character you specify in the tab global option.
There are a few special cases of data entries:
nroff I troff commands within tables
tbl assumes that an input line beginning with a dot is a
request to the formatter and interprets it accordingly,
retaining its position in the table. For example, a space
within a table may be produced with the .sp request in
the data.
Full width horizontal lines
tbl interprets a data line containing only the _ (underscore) character or c::a (equal sign) to be a single or double
line, respectively, extending the full width of the table.
Single column horizontal lines
tbl interprets a data entry containing only the _ character
or the .... to be a single or double line extending the full
width of the column. Such lines extend to meet horizontal or vertical lines adjoining this column. To obtain
these characters explicitly in a column, precede them
with the escape sequence \&, or follow them with a space
before the usual tab or newline character.
Short horizontal lines
A data entry containing only the string _ is assumed to
be a single line as wide as the contents of the column. It
does not extend to meet adjoining lines.
Repeated characters
A data entry containing only a string of the form \Rx,
where x is any character, is replaced by repetitions of the
character x as wide as data in the column. The sequence
does not extend to meet adjoining columns.

fbi: TECHNICAL DISCUSSION

Data

Vertically spanned entries
A data entry containing only the escape sequence '"
specifies that the data e'ntry immediately above it spans
downward over the corresponding row. It is equivalent
to a table format key letter of ".
Text blocks
To include a block of text as a data entry, precede it by T(
and follow it by T}. Thus, the sequence
• • • T{

block of
text
T} • • •

is a convenient method for inserting data not easily
placed between tabs. You may put T( (the beginning
delimiter) anywhere in the data section. Do not put any
character to the immediate right of this delimiter. You
must put T} (the end delimiter)a't the beginning of a
line, a~d you may follow T) with a tab or tab character.
You may follow the tab with additional columns of data
on the same line. Table 4 in the "tbl Sampler" shows
how to Use text blocks.
.
Text blocks are pulled out from the table, processed
separately by the formatter, and replaced in the table as a
solid biock. Various limi~s in the nroff I troff program are
likely to be exceeded if 30 or more text blocks are used in
a table. This produces diagnostic messages such as Too
many

text block diversicms;

tbl quits, Too many

striDJ/macro names, or 'Too many number registers.
If no lin~ length is specified in the block of text or in the
table format,· the default is to use
.
Lx C I (N

+ 1)

where L is the current line length, C is the number of
table columns spanned by the text, and N is the total
columns in the table.

TECHNICAL DISCUSSION

Data

Other parameters (point size, font, and so on) that you
may use in typesetting the text block are
• those in effect at the beginning of the table (including the effect of the •TS macro)
• any table format specifications of size, spacing, and
font using the p, v, and f modifiers to the column
key letters

• nroff I troff requests within the text block itself
(requests within the data but not within the text
block itself do not affect that block).
Although you may put many lines in a table, tbl uses only the first 200
lines to create the table. Similarly, column adjustment is determined for the
first 200 lines only. You may arrange a multi-page table as several singlepage tables if these limits prove to be a problem.
When calculating column widths, tbl assumes that all data entries are in
the font and size being used when the formatter encounters .TS. This is
true except for font and size changes specified in the table format section
(see Table 7 in the "tbl Sampler" or within the table data (as mentioned in
the section "Data"). You may sprinkle nroff/troff requests throughout a
table, but take care not to confuse tbl's width calculations.

fbi: TECHNICAL DISCUSSION

6. Additional Command Lines
To change the format of a single table, use the .T& (table continue)
command. Such a table would look like this:

.'1'5

global options ;
format s£'ction •
data
.T6.

IItU' format stction •
data
.T6.

ntwtr format section •
data
.TE

Using this procedure, each table line can be close to its corresponding
format line. It is not possible to change the number of columns, the space
between columns, the global options such as box, or the selection of
columns to be made equal in width in additional command lines. tbl does
not recognize this command after the first 200 lines of a table.

TECHNICAL DISCUSSION

7. Using the tbI Command
As the term "preprocessor" implies, you process a file with tbl before
you run nroff or troff. On the UNIX system, the tbl program can process a
simple table with the nroff commands
tbl -TX file

I nroff

[option (5)]

or
mm -t (option(s») file
For troff output you can use
tb] file

I troff

(option(s)]

or
mmt -t (option(s)] file
When there are several input files containing tables, equations, pictures, and
mm macro requests, type
tbl -TX filel file 1. .. I neqn

I nroff

-mm

For troff output type
tbl -TX filel file2...

eqn

troff -mm

The next section explains the rationale for placing tbl before eqn).
Notice that you may specify options usually used with the nroff formatter. Using nroff/troff is similar to using nroff. If you specify "-" as
the file name, tbl reads the standard input at that point.
The special -TX command-line option to tbl produces output without
fractional line motions to accommodate line printers without adequate driving tables or postprocessors. That is, this option tells tbl to process data in
terms of full line motions.

fbi: TECHNICAL DISCUSSION

Using the tbl Command

7.1. Equations in Tables
When both tbl and eqn programs operate on the same file, you should
call tbl first. If there are no equations within tables, either sequence works.
It is usually faster to execute tbl first because eqn normally produces a
larger expansion of the input. However, if you have equations within
tables (using eqn's delim statement, see Table 5 in the "tbl Sampler"), you
must execute tbl first, or the output will be scrambled. You should avoid
use of eqn's equations in n-style (numeric) columns since tbl attempts to
split numerical format items into two parts, and the delim (xx) statement
prevents splitting numerical columns within delimiters. For example, if the
eqn delimiters are $$, a delim ($$) statement causes a numerical column
entry such as
1245 $\(+- 16$
to be divided after 1245, not after 16.

7.2. Using Number Registers
The tbl program accepts up to 35 columns of data; this figure may be
compromised depending on the availability of nroff/troff formatter number
registers. tbl itself must define several macros and number registers. As a
result, you must not use the following names for macros that you create:
#f, #0, #+, #%, #&, and #. You must also avoid using number registers
named by tbl. These include 2-digit numbers from 31 to 99 and strings of
the form 4x,5x, #x, x+, xl, "'x, and x-, where x is any lower-case letter. The
register names ##, #-, #"', #T, and T# are also used by tbl in certain circumstances. To conserve register names, the n and a key letters share a
register; hence the restriction that you may not use them in the same
column of the format section.
As an aid in writing layout macros, tbl defines the number register TW,
which is the table width, by the time that the .TE macro is invoked. You
may use the register in the expansion of .TE. More important, to assist in
laying out mUlti-page boxed tables, the macro T# is defined to produce the
bottom lines and side lines of a boxed table and then to be invoked at its
end.

TECHNICAL DISCUSSION

Using the tbl Command

You can print a multi-page boxed table with a repeated heading by giving the argument H to the.TS macro. If the table start macro is written
•'l'S H

then, a line of the form
.TH

must be given in the table after any table heading (or at the start if none).
Material up to the .TH is placed at the top of each page of the table. The
remaining lines in the table are placed on several pages as required. This is
a feature of the mm macros, not of tbl.

fbi: TECHNICAL DISCUSSION

8. tbl Sampler
The following tables illustrate basic concepts of the tbl program. The
symbol in the input data represents a tab character produced by

typing \t or by pressing the tab key. Although each table shows particular
options or features, you may glean other information about usage from
them.
The following pages contain successive examples of matching input and
output to provide models for making a variety of tables. The general format
of the ntbl Sampler" is to show the contents of an input file, as read at a terminal, on the left page:

Input:

.TS

option option option option
key letter descriptor key letter descriptor
key letter descriptor key letter descriptor
key letter descriptor key letter descriptor
key letter descriptor key letter descriptor.
table heading data
optional double or single horizontal line
data entry data entry data entry
optional double or single horizontal line
data entry data entry <'WI> data entry
optional double or single horizontal line
data entry <'WI> data entry <'WI> data entry
.TE

TECHNICAL DISCUSSION

tbl Sampler

On the opposite right page, a corresponding example of output appears.

Output:
table headinK data
data entry data entry data entry
data entry data entry data entry
data entry data entry data entry
The command line used for most of the examples below is as follows:

tbl file

I troff I phototypesetter

Table 5 required

tbl file

I eqn I troff I phototypesetter

in order to process the equations made with eqn.

fbi: TECHNICAL DISCUSSION

tbl Sampler

Table 1: Using Horizontal Lines in Place of Key Letters

Input:

.1'5
box;

LLL

LL
L L

T LB

LL
L L L.
jamJazy <'DB> februaxy <'DB> mrcb
april <'IU> may
june <'IU> july <'1M> Ib'lths
august <'IU> septeab!r

octcber
.'l'E

<'DB>

DCMlIIber

<'IU>

deceatler

TECHNICAL DISCUSSION

tbl Sampler
Output:

january
april
june
august
october

february
may
july
september
november

march

Months
december

tbl: TECHNICAL DISCUSSION

tbl Sampler

Table 2: Changing Point Size of One Column
Input:

.TS

c c
np-2 : n : •
Stack

2 23

6.5

2.1

.TE

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - tbl Sampler

Output:

Stack
2
3
4

46
23
15
6.5
2.1

fbi: TECHNICAL DISCUSSION

tbl Sampler

Table 3: Using Additional Command Lines
Input:

.1'5
box, center;
cf3 s s s.

Carp:>sitim of Foods

-.'I'6.
c I c s s
clcss
c : c I c : c.
Fcxxl Percent by weight
\'"
\ '"

Protein

Fat

\ '" \'" \ '"

Carbohydrate

.'I'6.

1 : n In: n.
Apples .4 .5 13.0
Halibut 18.4 502
Lima beans 7.5 .8 22.0
Milk 303 400 5.0
MJshroans 305 04 600
Rye bread 900 06 5207
oTE

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - tbl Sample,

Output:

Composition of Foods
Percent by Weight
Food
CarboProtein Fat
hydrate
13.0
.4
.5
Apples
Halibut
18.4
5.2
...
Lima beans
7.5
.8
22.0
Milk
3.3
4.0
5.0
3.5
Mushrooms
.4
6.0
Rye bread
9.0
52.7
.6

fbI: TECHNICAL DISCUSSION

tbl Sample r

Table 4: Using Text Blocks and Contro lling Colum n Width
Input:

.1'5
alll:xJx;
cf2 s s

cw(1i) cw(1.5i) ew(1.5i)
1 1 1.
New York Area Rocks

.sp
Era Formatio n /Iqe (years)
Precanb rian Readin:] ProD} > 1 billion
Paleozo ic Manhatt an ProD} 400 million
Mesozoi c T{
Newark Basin. inc1.
Stockton . I.ockatal g' •
and Brunswi ck
fOXJl8tio ns
T} 200 million
cenozoi c Coastal Plain T{
en 1£0} Islard
30,000 years;
Cretaceo us sedimen ts
redeJX)Si ted
by recent
glaciati on

T}
.TE

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - tbl Sampler

Output:

New York Area Rocks
Era
Precambrian
Paleozoic
Mesozoic

Formation
Reading Prong
Manhattan Prong
Newark Basin, incl.,
Stockton, Lockatong,
and Brunswick formations

Cenozoic

Coastal Plain

Age (years)

> 1 billion
400 million
200 million

On Long Island 30,000
years; Cretaceous sediments redeposited by
recent glaciation

fbI: TECHNICAL DISCUSSION

tbl Sampler

Table 5: Includ ing Equations

Input:

.m
delim SS
.EN
.TS

doublebo x;

c c
1 1.
Name <'JM> Definiti on

.sp
.VB +2p

Gaztm!l <'JM> SGtV"'IA (z) = int sub 0 sup inf t sup {z-1}
e sup -t dtS
Sine <'JM> Ssin (x) = 1 over 2i ( e sup ix - e sup -ix )S
Error <'JM> S EaDan erf (z)= 2 over sqrt pi int sub 0 sup
z e sup {-t sup 2} dtS
Bessel <'1M'> SJ sub 0 (z)= 1 over pi int sub 0 sup pi cos
(z sin theta )d theta $
zeta <'1M'> S zeta (9) = sum fJ:Clll k=1 to inf k sup -s --( Re-s > 1)S
.VB -2p
.sp 2p
•'l'E

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - tbl Sampler

Output:

Name

Definition

fooo tz-Ie- dt

Gamma

r(z)=

Sine

sin(x)= 2; (e IX -e- IX )

Error

2
erf(z)= ~

1·

Bessel

1
Jo(z )=1r

e- t 2dt

cos(zsin8)d8

Zeta

r(s)=

~k-s

(Re s>l)

k-I

fbi: TECHNICAL DISCUSSION

tbl Sampler

Table 6: Using Additi onal Comm and Lines and Defini ng Tab Charac
ter

Input:

.TS
tab(
C

<'tAB>

);

ci s
I n

an.
5ate London Transpo rt Statisti cs
(Year 1964)

Railway route miles

244

'I\We <'tAB> 66
SUlrsurf ace 22
SUrface 156

.sp .5
.'1'&.
I r

a r.
Passen; er traffic \- railway
Journey s 674 million
Average length 4.55 miles
Passen; er miles <'tAB> 3,066 million
.'1'&.
I r

a r.
Passen; er traffic \- road
Journey s 2,252 million
Average length 2.26 miles
Passen; er miles 5,094 million
.'1'&.
In

an.
. sp .5
Vehicle s 12,521
Railway m:>tor cars 2,905
Railway trailer cars 1,269
Total railway 4, 174
Qanibus es 8,347

TECHNICAL DISCUSSION

tbl Sampler

Output:

Some London Transport Statistics
(Year 1964)

Railway route miles
Tube
Sub-surface
Surface
Passenger traffic - railway
Journeys
Average length
Passenger miles
Passenger traffic - road
Journeys
Average length
Passenger miles
Vehicles
Railway motor cars
Railway trailer cars
Total railway
Omnibuses

244
66
22
156
674 million
4.55 miles
3,066 million
2,252 million
2.26 miles
5,094 million
12,521
2,905
1,269
4,174
8,347

fbi: TECHNICAL DISCUSSION

tbl Sampler

Table 7: Using Differe nt Point Sizes and Colum n Widths

Input:

•'l'S
box tab( );
cbsss

clclcs
ltiw(1i) lltw(1.5 i)p8llp8 llw(1.5 i)p8.
5aDe Interest inq Places

Nane Descrip tien

<'1'AB>

Practica 1 Infanta tien

T{
American ftlseum
of Nilblral Hi.staIy
T} <'1'AB> T{

'lhe collecti cns fill 11.5 acres
(Micheli n) or 25 acres (MrA)
of exhibiti en halls en

four floors. '1bere is a full-siz ed
replica of a blue whale and the

1IlOrld's largest star saRiUre
(stolen in 1964).
T} Hours <'fM> 10-5, ex. SUn 11-5, wed. to 9
\ " <'1'AB> \ " <'1'AB> IDcatim <'1'AB> T{
central Park west & 79th St.

T}
\'"

<'1'AB> \"

\" \"
\" <'1'AB> \" <'fM>

Itdmissio n Dcmati.on: $1.00 asked
SUbway AA to 81st st.
Telephon e 212-873- 4225

Bra1x ZOO T{
About a mile looq and .6 mile
wide, this is the largest zoo in

America .

A lim eats 18

pounds of meat a day while a
sea lien eats 15 pounds of fish.
T} <'fM> Hours <'1'AB> T{

TECHNICAL DISCUSSION

tbl Sampler

Input Cont'd:

10-4: 30 winter, to 5: 00

suamer

T}
~ \'" <'lAB> IQcation T{
185th St. & SOUthem Blvd, the Broox.

\'"

T}
Itdmissicm $1.00, bIt 'l\1,we,'lb free
&lbway <'lAB> 2, 5 to Fast '1'rEm:nt Ave.
~ Telephone 212-933-1759

\'"

<'lAB> \ "

\ " <'rAB> \ "

~yn M.1s~ <'fA&> T{
Five floors "of galleries contain
American and ancient art.
'1bere are American period
roaDS and architectural ca:naDents

saved fran wreckers,
such as a classical figure fran
Pennsylvania

Station.
T} <'lAB> 1bJrs <'lAB>

wed-sat, 10-5, SUn 12-5

V' \" <'lAB> IQcatim T{
Eastem Pkway &. WashiD;Jta\ 1Ne.

Brooklyn.
T}
\ " <'rAB> \ " <'fA&>

Itdmissim Free
2,3 to Fastem Parkway.
'1'el~ <'lAB> 212-638-5000

\" <'Wi> \" <'lAB> SUbway
\" <'fA&> \" <'lAB>

T{
New York

Historical Society
T} <'fA&> T{

All the oriqinal p:rinti.ngs for
Audubon's
.1
Birds of ADerica
.R

fbi: TECHNICAL DISCUSSION

tbl Sampler

Input Cont'd:

are here. as are exhibits of American
deoorat ive arts. New York
histozy . Hudson River seoool
painting s. carriage s. am glass
papexwe ights •
T} <'UoB> Hours T{

TUes-Fri & SUn. 1-5;
T}
\" \"

sat 10-5

Location

Central Park west & 77th St.
T}
\" \,.
\ " \ "

&\"

\ "

Admission

Free
SUbey AA to e1st St.

Telepxme

.TE

TECHNICAL DISCUSSION

212-873-3400

tbl Sampler
Output:
Some Interesting Places
Name

American Museum
of Natural History

Bronx Zoo

Brooklyn Museum

Ntw York Historical
Society

Description
The collections fill 11.5 acres
(Michelin) or 25 acres (MTA)
of exhibition halls on four
floors. There is a full-sized
replica of a blue whale and
the world's largest star sapphire (stolen in 1964).
About a mile long and .6
mile wide, this is the largest
zoo in America. A lion eats
18 pounds of meat a day
while a sea lion eats 15
pounds of fish.

Five floors of galleries contain American and ancient
art. There are American
period rooms and architectural ornaments saved from
wreckers, such as a classical
figure from Pennsylvania
Station.
All the original paintings for
Audubon's Birds Of America
are here, as are exhibits of
American decorative arts,
New York history, Hudson
River school paintings, carriages, and glass paperweights.

Practical Information
Hours
Location

10-5, ex. Sun 11-5, Wed. to 9
Central Park West &: 79th St.

Admission
Subway
Telephone

Donation: $1.00 asked
AA to 81st St.
212-873-4225

Hours

10-4:30 winter, to 5:00 summer

Location

185th St. &: Southern Blvd,
the Bronx.

Admission
Subway
Telephone

$1.00. but Tu,We,Th free
2,5 to East Tremont Ave.
212-933-1759

Hours
Location

Wed-Sat. 10-5, Sun 12-5
Eastern Pkway &: Washington Ave. Brooklyn.

Admission
Subway
Telephone

Free
2,3 to Eastern Parkway.
212-638-5000

Hours

Tues-Fri &: Sun. 1-5; Sat 10-5

Location

Central Park West & 77th St.

Admission
Subway
Telephone

Free
AA to 81st St.
212-873-3400

tbl: TECHNICAL DISCUSSION

Table of Contents
Introduction

~mm~

1. General Explanation
2. Font and Character Size Control
3. Page Control
4. Text Filling, Adjusting, and Centering
5. Vertical Spacing
6. Line Length and Indenting
7. Macros, Strings, Diversion, and Position Traps
8. Number Registers
9. Tabs, Leaders, and Fields
10. Input and Output Conventions and Character Translations
11. Local Horizontal and Vertical Motions, and the Width Function
12. Overstrike, Bracket, Line-drawing, and Zero-width Functions
13. Hyphenation
14. Three Part Titles
15. Output Line Numbering
16. Conditional Acceptance of Input
17. Environment Switching
18. Insertions from the Standard Input
19. Input/Output File SWitching
20. Miscellaneous
21. Output and Error Messages
22. Request and Section Number Cross Reference
23. Escape Sequences for Characters, Indicators, and Functions
24. Predefined General Number Registers
25. Predefined Read-only Number Registers
26. Predefined Strings

TABLE OF CONTENTS

6
6
7
7
8
8
8
9
9
10
10
11
11
11
12
12
13
13
13
13
14
14
15
17
17
18

Table of Contents

A Technical Description of nroff/troff
1. General Explanation
1.1. Form of Input
1.2. Formatter and Device Resolution
1.3. Numerical Parameter Input
1.4. Numerical Expressions
1.5. Notation
2. Font and Character Size Control
2.1. Character Set
2.2. Fonts
2.3. Character Size
3. Page control
4. Text Filling, Adjusting, and Centering
4.1. Filling and Adjusting
4.2. Interrupted Text
5. Vertical Spacing
5.1. Base-line Spacing
5.2. Extra Line-space
5.3. Blocks of Vertical Space
6. Line Length and Indenting
7. Macros, Strings, Diversions, and Position Traps
7.1. Macros and Strings
7.2. Copy Mode Input Interpretation
7.3. Arguments
7.4. Diversions
7.5. Traps
8. Number Registers
9. Tabs, Leaders, and Fields
9.1. Tabs and Leaders
9.2. Fields
10. Input and Output Conventions and Character Translations
10.1. Input Character Translations
10.2. Ligatures

nroff/troff: TECHNICAL DISCUSSION

19
19
19
19
20
21
22
22
22
23
24
27
29
29
30
32
32
32
32
34
35
35
36
36
37
38
41
43
43
43
45
45
45

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

10.3. Backspacing, Underlining, and Overstriking
10.4. Control Characters
10.5. Output Translation
10.6. Transparent Throughput
10.7. COQlments and Concealed New-lines
11. Local Horizontal and Vertical Motions, and the Width Function
11.1. Local Motions
11.2. Width Function
11.3. Mark Horizontal Place
12. Overstrike, Bracket, Line-drawing, and Zero-width Functions
12.1. Overstriking
12.2. Zero-width Characters
12.3. Large Brackets
12.4. Line Drawing
13. Hyphenation
14. Three Part Titles
15. Output Line Numbering
16. Conditional Acceptance of Input
17. Environment Switching
18. Insertions from the Standard Input
19. Input/Output File Switching
20. Miscellaneous
21. Output and Error Messages

Special Characters
1. Input Names for " " and - for Non-ASCII Special Characters
2. Non-ASCII Characters and Minus on the Standard Fonts

TABLE OF CONTENTS

46
47
47
48
48
49
49
49
50
50
50
50
50
51
53
54
56
57
59
60
61
62
64

65
65
66

III

Introduction
nroff and troff are text processors provided with the UNIX System V
DOCUMENTER'S WORKBENCH Software. They accept lines of text interspersed with lines of format control information and process the text into a
printable, paginated document having a user-designed style. nroff and
troff offer unusual freedom in document styling, including the following:
arbitrary style headers and footers; arbitrary style footnotes; multiple
automatic sequence numbering for paragraphs, sections, and other userdefined blocks of text; multiple column output; dynamic font and point-size
control; arbitrary horizontal and vertical local motions; and a group of
automatic overstriking, bracket construction, and line drawing functions.
nroff and troff are highly compatible with each other, and it is almost
always possible to prepare input acceptable to both. Conditional input is
provided that enables the user to embed input expressly destined for either
program. troff formats text suitable for phototypesetters and printers capable of producing digital-typographical output.
The general form of invoking nroff or troff at the UNIX system command level is
nroff option(s) fi'e(s) I printer
or
troff option(s) fi'e(s) I typesetter
where option(s) represents any of a number of options and option arguments, and fi'e(s) represents the file containing the document to be formatted. °An argument consisting of a single minus (-) is taken to be a file name
corresponding to the standard input. If no file is given, input is taken from
the standard input. The options, which may appear in any order so long as
they appear before the file name(s), are

Option

ERect

-e

(nroff only.) Produce equally-spaced words in adjusted
lines, using full terminal resolution.

-h

(nroff only.) Use output tabs during horizontal spacing
to speed up output as well as to reduce output byte
count. Device tab settings are assumed to be every 8

nroff/troff: TECHNICAL DISCUSSION

Introduction

nominal character widths, as are the settings of input
(logical) tabs.

-i

Read standard input after the input files are exhausted.

-mname

Prepend the macro file /usr/lib/tmac.name to the input
files. nroff and troff can accept several -m options on
the command line causing all macro packages thus
named to be read in turn. The possible macro packages
(the memorandum macros, the man macros, the viewgraph macros, and the permuted index macros) would be
called, with the following options, respectively: -mm,
-man, -my, and -mptx.

-nN

Number first generated page N.

-olist

Print only pages whose page numbers appear in list. list
consists of comma-separated numbers and number
ranges. A number range has the form N-M and means
pages N through M; an initial -N means from the beginning to page N; and a final N- means from N to the end.

-q

Invoke the simultaneous input-output mode of the .rd
request.

-raN

Set the number register whose (one-character) name is a
to N.

-sN

Stop every N pages. nroff will halt prior to every N
pages (default N=l) to allow paper loading or changing,
and will resume upon receipt of a new-line. troff will
stop the phototypesetter every N pages, produce a trailer
to allow for changing of paper, and will resume after the
phototypesetter START button is pressed. In oroff the
ASCII BEL character will sound when stopping between
pages.

TECHMCALD~CUSmON

Introduction

-Ttty_type

Specifies the name of nroff terminal type, tty_type.
Currently defined names are
Hewlett-Packard 2631 printer in regular mode
Hewlett-Packard 2631 printer in compressed
mode
2631-e Hewlett-Packard 2631 printer in expanded mode
DASI-300 printer
300
300-12 DASI-300 terminal set to 12-pitch (12 characters
per inch)
DASI-300s printer (3005 is a synonym)
3005
3005-12 DASI-300s printer set to 12-pitch (12 characters
per inch) (3005-12 is a synonym)
Teletype Model 37 terminal (default)
37
DTC-382
382
Trendata 4000a terminal (4000A is a synonym)
4000a
DASI-450 (Diablo Hyterm) printer
450
450-12 DASI-450 terminal set to 12-pitch (12 characters
per inch)
Anderson Jacobson 832 terminal
832
C.ITOH printer
8510
generic name for printers that can underline
Ip
and tab. (All text using reverse linefeeds, such
as those having tables, that is sent to Ip must be
processed with col.)
GE Terminet 300 terminal
tn300
printers equipped with TX print train
X

2631
2631-c

(Check with your system administrator for a list of
locally supported devices.)
In troff, the - T option may be used to slJecify the output
device. In addition, it is possible to set the environment
variable "TYPESETTER." The output devic~s presently supported for troff are the Autologic APS-5 (-Taps) and the
Imagen Imprint-10 (-TilO)
-uN

(nroff only.) Set the emboldening strike-count (number
of character overstrikes) for the bold font (normally

nroff/troff: TECHNICAL DISCUSSION

Introduction

mounted at the third font position) to be N. If option is
used without N, the number of overstrikes is assumed to
be zero. Note that it is not possible to turn off the
emboldening in nroff if the overstriking is controlled
locally by the printing device (e. g., DASI 300s). See the
.bd request in Section 2.3 and the .b number register in
Section 4 for a fuller treatment of emboldening.

-z

Suppress formatted output. Only diagnostics and messages from .tm requests will occur.

-a

Send a printable ASCII approximation of results to the
standard output.

Each option is invoked as a separate argument; for example,
nroff -04,8-10 -T300-12 -mabc filel file2
requests formatting of pages 4, 8, 9, and 10 of the document contained in
files named filel and file2, specifies the output terminal as a DASI 300 in
12-pitch, and invokes the macro p~ckage abc.
Various pre- and postprocessors are available for use with nroff and
troff. These include the preprocessors for writing equations, neqn and
eqn (for nroft and troff respectively); the preprocessor for making
tables, tbl; the prep(ocessor for drawing pictures, pic, and the grap
preprocessor for presenting statistics in a graph. A reverse-line postprocessor, col, is available for multiple-column nroff output on terminals
without reverse-line ability; col expects the Teletype Model 37 escape
sequences that nro'ff produces by default. troff output can be viewed on
the Teletype Model 5620. No special filter is required to postprocess
troff's output for the 5620. The finished version of a document typeset
with troff is most frequently sent to a phototypesetter:
gr~p

filers)

I pic I tbl I eqn I troff

opti01l(s)

I typesetter

The first pipe (I) indicates the redirecting of grap's output to pic's input;
the second pipe shows pic's output being redirected to tbl's input; the
third pipe shows tbl's output flowing into eqn's input; the fourth indicates the piping of eqn's output to troff's input. Finally, the accumulated o~tput from these processes is piped to a postprocessor that interprets troff's output graphics language for the output device.

TECHNICAL DISCUSSION

Introduction

te is a phototypesetter-simulator postprocessor, which enables you to
view troff output on a Tektronix 4014 terminal. The syntax for its usage
is as follows:
grap file (5)

I pic I tbl I eqn I troff

option(5)

I te

The remainder of this manual consists of a "Summary" followed by
"A Technical Description of nroff/troff." The numbered sections of the
"Summary" correspond to numbered sections of the "Technical Description," in which the individual nroff/troff subcomponents are covered in
detail.

nro"/tro": TECHNICAL DISCUSSION

Summary
This summary presents abstracts of requests, escape sequences, number
registers, and predefined strings. It gives essential information about these
subcomponents such as syntax usage, value of arguments, and default scaling of parameters. The following is a key to some of the notation:

Notes:
B
D

o
P

T
v,p,m,u

t
+

Request normally causes a break.
Mode or relevant parameters associated with current diversion
level.
Relevant parameters are a part of the current environment.
Must stay in effect until logical output.
Mode must be still or again in effect at the time of physical output.
Parameters are typesetter- or printer-dependent.
Default scale indicator; if not specified, scale indicators are
ignored.
Values separated by n;" are for nroff and troff respectively.
Requests marked with "t" h!.ve no effect in nroff.
Requests marked with "t" cause a line break, like that caused by
.br. Invoking them with the control character II'" (instead of ".")
will suppress that break function.

1. General Explanation
(This topic is covered in section 1 of the "Technical Description" below.)

2. Font and Character Size Control
Request
Form

Initial
Value

Notes Explanation
Ii No
Argument

.ps±N
.ss N

IOpoint
12/36 em

previous
ignored

.csFNM

off

TECHNICAL DISCUSSION

E,t
E,t
P,t

Point size; also \s±N.
Space-character size set to
N/36 em.
Constant character space (width)
mode (font F).

Summary

.bd F N
.bd S F N

off
off

.ft F

Roman

.fp N F

P
P
previous

E,T

ignored

Embolden font F by N-I units.
Embolden Special Font when
current font is F.
Change to font F = x, xx, or I-N.
Also \fx, \f(xx, \fN.
Font named F mounted on physical position I <:N.

3. Page Control
Request
Form

Initial
Value

Ii No
Notes Explanation
Argument

.pl±N
.bp ±N

11in

I1in

N=l
N=l

ignored
previous

.pn ±N
.po ±N
.neN

0;26/27 in

.mk R

none

internal

.rt ±N

none

internal

N=IV

v
Page length.
B,t,v Eject current page; next page
number N.
Next page number N.
v
Page offset.
D,v Need N vertical space (V -= vertical spacing).
Mark current vertical place in
D
register R.
D,v Return (upward only) to marked
vertical place.

4. Text Filling, Adjusting, and Centering
Request
Form

Initial
Value

.br
.fi
.nf

fill
fill

.ad c
.na
.ce N

adj,both
adjust
off

II No
Notes Explanation
Argument

adjust
N=l

Break.
B,*
B,*,E Fill output lines.
B,t,E No filling or adjusting of output
lines.
E
Adjust output lines with mode c.
E
No output line adjusting.
B,*,E Center following N input text
lines.

nroff/troff: TECHNICAL DISCUSSION

Summary

5. Vertical Spacing
Request
Form

Initial
Value

.vs N
.Is N

1/6in;12pts previous
N=l
previous

II No
Notes Explanation
Algument

.sp N

N=lV

.sv N
•os
.ns
.rs

N=lV

space

E,p
E

Vertical base line spacing (V).
Output N-l Vs after each text
output line.
B,t,v Space vertical distance N in
either direction.
v
Save vertical distance N.
Output saved vertical distance.
Turn no-space mode on.
D
D
Restore spacing; turn no-space
mode off.

6. Line Length and Indenting
Request
Form

Initial
Value

II No
Notes Explanation
Algument

.11 ±N
.in ±N
.li ±N

6.5in
N=O

previous
previous
ignored

E,m Line length.
B,t,E,m Indent.
B,t,E,m Temporary indent.

7. Macros, Strings, Diversion, and Position Traps
Request
Form

Initial
Value

II No
Notes Explanation
Algument

.de xx yy

.yy=•.

.am xx yy
•dsxx string -

.yy=••
ignored

.as xx string .rm xx

ignored
ignored

TECHNICAL DISCUSSION

Define or redefine macro xx; end
at call of yy.
Append to a macro.
Define a string xx containing
string.
Append string to string xx.
Remove request, macro, or
string.

Summary

.rn xx yy

ignored

.di xx
.da xx
.wh N xx

end
end

.ch xx N
.dt N xx
.it N xx
.em xx

none

off
off
none

D
D
v
v
D,v
E

Rename request, macro, or string
xx to yy.
Divert output to macro xx.
Divert and append to xx.
Set location trap; negative is
with respect to page bottom.
Change trap location.
Set a diversion trap~
Set an input-line count trap.
End macro is xx.

8. Number Registers
Request
Form

Initial
Value

.nr R ±N M.af R c

If No
Notes Explanation
Argument
Define and set number register
R; auto-increment by M.
Assign format to register R (c==l,
i, I, a, A).
Remove register R.

Arabic

.rr R

9. Tabs, Leaders, and Fields
Request
Form
.ta Nt ...

Initial
Value
O.8;O.5in

.tc c
.Ic c
.fe a b

none
off

If No
Notes Explanation
Argument
E,m Tab settings; left type, unless
none
t=R (right) or t=C (centered).
none
E
Tab repetition character.
none
Leader repetition character.
E
Set field delimiter a and pad
off
character b.

nroff/troff: TECHNICAL DISCUSSION

Summary

10. Input and Output Conventions and Character
Translations
Request
Form

Initial
Value

II No
Notes Explanation
Argument

.ec c
.eo

.lg N
.ul N

-;on
off

N=l

.cu N

off

N=l

.uf F

Italic

on
on

.cc c
.c2 c

E
E

.tr abcd....

none

Set escape character.
Turn off escape character
mechanism.
Ligature mode on if N> O.
Underline (italicize in troff) N
input lines.
Continuous underline in nroff;
like .ul in troff.
Underline font set to F (to be
switched to by .ul).
Set control character to c.
Set no-break control character to
c.
Translate a to b, etc., on output.

11. Local Horizontal and Vertical Motions, and the
Width Function
Vertical
Motion

troff

Effect in
nroff

\v'N' Move distance N
lh line up

lh em up

lh em down lh line down

1 em up

1 line up

Horizontal
Motion

TECHNICAL DISCUSSION

nroff

\h'N' Move distance N
\(space) Unpaddable space-size space
Digit-size space
\0

Effect in
troff

1/6 em space
1/12 em space

ignored
ignored

Summary

12. Overstrike, Bracket, Line-drawing, and Zerowidth Functions
Function

Escape
Sequence
\o'string'

Automatically centered overstriking of characters named
in string.
Zero-width spacing following character c to produce
overstruck characters.
Vertically pile characters named in string.
Horizontal line drawing function. Optional character c
may be named to travel to the right a distance N. Travel
to the left may be specified with a negative N.
Vertical line drawing function. Optional character c
may be specified to travel downward a distance N. Upward
distance may be specified with a negative N.

\zc
\b'string'
\1'Nc'

\L'Nc'

13. Hyphenation
Request

Initial
Value

Form

.nh
•hy N
.he c

If No
Notes Explanation
Argument

no hyphen E
no hyphen hyphenate E

.hw wordl ..,

ignored

No hyphenation .
Hyphenate; N = mode.
Hyphenation indicator character
c.
Exception words.

14. Three Part Titles
Request

Initial

Form

Value

.t1 'left'center'right'
.pe c
%
.It ±N
6.5in

If No
Notes Explanation
Argument
off

E,m

Three part title.
Page number character.
Length of title.

nro"/tro": TECHNICAL DISCUSSION

Summary

15. Output Line Numbering
Request
Form

Initial
Value

liND

Notes Explanation

Algument

.nm ±N M 5 I

off

.nn N

N-l

Number mode on or off, set
parameters.
Do not number next N lines.

16. Conditional Acceptance of Input
Request
Form

Initial
Value

liND

Notes Explanation

Algument

.if c anything-

If condition c true, accept anything as
input, for multi-line use \{any-

.if Ie anything

If condition c false, accept any-

thing\}.
thing.
•if N anything

•if !N anything

.if 'stringl 'string2' anything
•if !'stringl'string2' anything

.ie c anything
.el anything

TECHNICAL DISCUSSION

> 0, accept anything.
If expression N ~ 0, accept anything
If stringl identical to string2,
accept anything.
If stringl not identical to string2,
accept anything.
If portion of if-else; all above
forms (like if).
Else portion of if-else.

If expression N

- - - - - - - - - - - - - - - - - - - - - - - - - Summary

17. Environment Switching
Request
Form

Initial
Value

Ii No
Notes Explanation
Argument

.ev N

N=O

Environment switched (push
down).

18. Insertions from the Standard Input
Request
Form

Initial
Value

.rd prompt

Ii No
Notes Explanation
Argument
Read insertion.
Exit from nroff/troff.

prompt=BEL -

•ex

19. Input/Output File Switching
Request
Form

Initial
Value

.so file
.nx file
.cf file
.If N file

If No
Notes Explanation
Argument
Switch source file (push down).
Next file.
Copy file .
change line number and file
name.
Pipe output to program.

end-of-file -

.pi program

20. Miscellaneous
Request
Form

Initial
Value

Notes Explanation
Ii No
Argument

.mccN

off

.tm string

new-line

.ig yy

•.11.11=••

E,m

Set margin character c and
separation N.
Print string on terminal (UNIX
standard message output).
Ignore till call of .11.11•

nro"/tro": TECHNICAL DISCUSSION

Summary

.pm t

all

Print macro names and sizes;
if t present, print only total of

•£1
.ab text

B,*
user abort

.sy cmd args -

sizes.
Flush output buffer.
Terminates processing immediately.
cmd executed but output not
captured.

21. Output and Error Messages
(This topic is covered in section 21 of the "Technical Description," which follows.)

22. Request and Section Number Cross Reference
.ab 20
.ad 4
.af 8
.am 7
.as 7
.bd 2
.bp 3
.br 4

.e2 10
.ee 10
.ee 4
.cf 19
.eh 7
.es 2
.eu 10
.da 7

.de 7
.di 7
.ds 7
.dt 7
.ee 10
.el 16
.em 7
.eo 10

.ev 17
.ex 18
.fe 9
.6 4
.f1 20
.fp 2
.ft 2
.he 13

.hwl3
.hy 13
.ie 16
.if 16
.ig 20
.in 6
.it 7
.Ie 9

TECHNICAL DISCUSSION

.If 19

.Ig 10
.Il 6
.Is 5
.It 14
.me20
.mk 3
.na 4

.ne 3
.nf 4
.nh 13
.nml5
.nn 15
.nr 8
.ns 5
.nx 19

.05 5
.pe 14
.pi 19
.pl 3
.pm20
.pn 3
.po 3
.ps 2

.rd 18
.rm 7
.rn 7
.rr 8
.rs 5
.rt 3
.so 19
.sp 5

.ss 2
.sv 5
.sy 20
.ta 9
.te 9
.ti 6
.t1 14
.tm20

.tr 10
.uf 10
.ul 10
.vs 5
.wh 7

- - - - - - - - - - - - - - - - - - - - - - - - - Summary

23. Escape Sequences for Characters, Indicators,
and Functions
Section
Escape
Reference Sequence
10.1
10.1
2.1
2.1

Meaning
\ (to prevent or delay the interpretation of \)
Printable version of the current escape character.
, (acute accent; typographically equivalent to \(aa)
, (grave accent; typographically equivalent to

\e
\'

\(ga)

\\.

2.1
7.2
11.1
11.1
11.1

\(space)

11.1

4.1
10.6
10.7
7.3
13
2.1
7.1
9.1
12.3
4.2
11.1

\&
\!
.\"

- (minus sign in the current font)
• (period or dot; see .de)
Unpaddable space-size space character
Digit width space
1/6 em narrow space character (zero width in

nroff)

\$N

\%
\(xx
\-x, \-(xx

\a
\b'abc...

\c
\d

12.4
2.2
8

\fx,\f(xx,\fN
\gx, \g(xx

11.1

\h'N'

2.3

\H'N'

1/12em half-narrow space character (zero width
in nroff)
Non-printing, zero width character
Transparent line indicator
Beginning of comment
Interpret argument 1 ~N~9
Default optional hyphenation character
Character named xx
Interpret string x or xx
Non-interpreted leader character
Bracket building function
Interrupt text processing
Forward (down) 1/2em vertical motion (1/2 line
in nroff)
Line-drawing functions
Change to font named x or xx, or position N
Return the format of values stored in general
number registers x and xx.
Local horizontal motion; move right N (negative
left)
Height control of characters (does not affect
width).

nroff/troff: TECHNICAL DISCUSSION

Summary

11.3

\kx

12.4

\l'Nc'

12.4

\L'Nc'
\nx,\n (-) are often extra wide.
The scaling for horizontally-oriented control characters, verticallyoriented control characters, and the requests .nr, .if, and .ie are as follows:
Orientation

Measure by Default

Horizontal

Em (m)

Vertical

Vertical line space (v)

Basic unit (u)
Point (p)

Request or Function
.11, .in, .ti, .ta, .It, .po,
.me, \h, \1.
.pl, .wh, .ch, .dt, .sp, .sv,
.ne, .rt, \v, \x, \l

.nr, .if, .ie.
.ps, .vs, \H, \s.

All other requests ignore any scale indicators. When a number register containing an already appropriately scaled number is interpreted to provide
numerical input, the unit scale indicator u may need to be appended to

TECHNICAL DISCUSSION

Description

prevent an additional inappropriate default scaling. The number, N, may
be specified in decimal-fraction form but the parameter finally stored is
rounded to an integer number of basic units.
The absolute position indicator I may be prepended to a number N to
generate the distance to the vertical or horizontal place N. For verticallyoriented requests and functions, IN becomes the distance in basic units from
the current vertical place on the page or in a diversion to the the vertical
place N. (See section 7.4, "Diversions.") For all other requests and functions, IN becomes the distance from the current horizontal place on the
input line to the horizontal place N. For example,
.sp 13.2c
will space in the required direction to 3.2centimeters from the top of the
page.

1.4. Numerical Expressions
Wherever numerical input is expected an expression involving
parentheses, the arithmetic operators +, -, I, ., % (mod), and the logical
operators <, >, <-, > -, - (or --), 8t (and), and: (or) may be used.
Except where controlled by parentheses, evaluation of expressions is left-toright. In the case of certain requests, an initial + or - is stripped and interpreted as an increment or decrement indicator respectively. In the presence
of default scaling, the desired scale indicator must be attached to every
number in an expression for which the desired and default scaling differ.
For example, if the number register x contains 2 and the current point size
is 10, then

.11 (4.25i+\nxP+3)/2u
will set the line length to 1/2 the sum of 4.25 inches

+ 2 picas + 3 ems.

The use of white space in arithmetic expressions is not permitted. There is
no precedence among arithmetic and logical operators. nroff/troff expressions do not recognize decimal multipliers or divisors; a high level of precision may be achieved by mixing scales within expressions.

nroff/troff: TECHNICAL DISCUSSION

Description

1.5. Notation
Numerical parameters are indicated in this manual in two ways. ±N
means that the argument may take the form N, +N, or -N and that the
corresponding result is to set the affected parameter to N, to increment it by
N, or to decrement it by N respectively. Plain N means that an initial algebraic sign is not an increment indicator, but merely the sign of N. Generally, unreasonable numerical input is either ignored or truncated to a reasonable value. For example, most requests expect to set parameters to nonnegative values: exceptions are .sp, .wh, .ch, .nr, and .if. The requests .ps,
.ft, .po, .vs, .Is, .11, .in, and .It restore the previous parameter value in the
absence of an argument.
Single character arguments are indicated by single lower-case letters
and one or two character arguments are indicated by a pair of lower-case
letters. Character string arguments are indicated by multi-character
mnemonics.

2. Font and Character Size Control
2. 1. Character Set
The troff character set consists of the so-called Commercial II character
set plus a Special Mathematical Font character set. With three exceptions,
these ASCII characters are input as themselves, and non-ASCII characters are
input in the form \(xx where xx is a two-character name. The three ASCII
exceptions are mapped as follows:

TECHNICAL DISCUSSION

Description

ASCII Input
Character
Name
acute accent
grave accent
minus

Printed by troff
Character
Name
close quote
open quote
hyphen

The characters " " and - may be input by \', \', and \- respectively or by
their names. (See the Table of Special Characters.) ASCII control characters
are discussed in the section, "Input Character Translation."
nroff understands the entire troff character set, but can in general print
only ASCII characters, additional characters as may be available on the output device, such characters as may be able to be constructed by overstriking
or other combination, and those that can reasonably be mapped into other
printable characters. The exact behavior is determined by a driving table
prepared for each device. The characters " " and _ print as themselves.

2.2. Fonts
Default fonts may differ from device to device. Typically, the fonts will
include the following: Times Roman (R), Times Italic (I), Times Bold (B),
and the Special Mathematical Font (5). The current font may be changed by
use of the .ft request, or by embedding at any desired point either \fx, \f(xx,
or \fN where x and xx are the name of a mounted font and N is a numerical
font position. It is not necessary to change to the Special Font; characters
on that font are handled automatically.
A request for a named but not mounted font is translated into a request
to mount the font at position O. This position is reserved for such dynamic
requests and is otherwise inaccessible. troff can be informed that any particular font is mounted by use of the .fp request. The list of known fonts is
device-dependent. In the subsequent discussion of font-related requests, F
represents either a one or a two-character font name. The current font is
available (as a numerical position) in the read-only number register .f.
nroff understands font control and normally underlines italic characters.
(See section 10.3, "Backspacing, Underlining, and Overstriking.")

nroff/troff: TECHNICAL DISCUSSION

Description

2.3. Character Size
The available character point sizes depend on the individual printing
device. The .ps request is used to change or restore the point size. Alternatively, the point size can be changed between any two characters by embedding a \sN at the desired point. (N may represent the desired available size
or \s±N may be used to increment or decrement the size by N; double-digit
increments or decrements are expressed as \s±NN.) \sO restores the previous size. Requested point size values that are between two legal sizes will
yield the closer legal size. The current size is available in the .s register.
In troff the escape sequence \H'N' sets the height of a character without
affecting its width. N can be expressed in absolute values or in relative
values of the form ±N.

Request
Form
.ps ±N

Initial
Value

.ssN

12/36 em

.csFNM

off

IOpoint

Notes Explanation
II No
AJYument
previous
E
Point size set to ±N. Alternatively, embed \sN or \s±N.
Any positive size value may be
requested; if invalid, the nearest
valid size will result, with a
maximum size to be determined
by the individual printing device. A paired sequence +N,-N
will work because the previous
requested value is also remembered. Ignored in nroff.
ignored

TECHNICAL DISCUSSION

Space-character size is set to
N/36 ems. This size is the
minimum word spacing in
adjusted text. Ignored in nroff.

Constant character space (width)
mode is set on for font F (if
mounted); the width of every
character will be taken to be
N/36 ems. If M is absent, the

Description

em is that of the character's
point size; if M is given, the em
is M-points. All affected characters are centered in this space,
including those with an actual
width larger than this space.
Special Font characters occurring
while the current font is Fare
also so treated. If N is absent,
the mode is turned off. The
mode must be still or again in
effect when the characters are
physically printed. Ignored in
nroff.
.bd F N

off

The characters in font F will be
artificially emboldened by printing each one three times,
separated by N -1 basic units. If
N is missing the embolden
mode is turned off. In nroff the
default setting is .bd 3 3, specifying that characters on the font
mounted at position 3 (normally
bold) are to be overstruck 3
times (i. e., printed in place a
total of 4 times).
The column heads above were
printed with .bd 2 3. That is,
the font stored at font position 2
was emboldened by an offset of
3. The font name itself may be
substituted for the font position
(e. g..bd I 3). The -u command
line option may be used to
change the number of overstrikes using an argument that is
functionally identical to .bd's
second argument. (See section
2.3, "Character Size. The mode
lt

)

nroff/troff: TECHNICAL DISCUSSION

Description

must be still or again in effect
when the characters are physically printed. This request may
affect the contents of the general
number register .b.
Note that it is not possible to
turn off the emboldening in
nroff if it is being controlled
locally by the printing device (e.
g., DASI 300s).
.bd 5 F N

off

.ft F

Roman

.fpN F file

ignored

The characters in the Special
Font will be emboldened whenever the current font is F. The
mode must be still or again in
effect when the characters are
physically printed .

Font changed to F. Alternatively, embed \fF. The font
name P is reserved to mean the
previous font.
Font position. This is a statement that a font named F is
mounted on position N. It is a
fatal error if F is not known.
Fonts and the possible range of
their numerical positions is
device-dependent. .fp accepts a
third optional argument, file,
which is an alternate version of
the font F.

.bd can be used to embolden characters, effectively increasing the
number of available fonts. This capability of modifying existing fonts to
make new ones is enhanced with the troff escape sequence, \5, used to slant
output characters by a number of specified degrees. This escape sequence is
stated as \5'N' where N may be any integer, negative or positive. 0 turns
slanting off.

TECHNICAL DISCUSSION

Description

3. Page control
Top and bottom margins are not automatically provided; it is conventional to define two macros and to set traps for them at vertical positions 0
(top) and -N (N from the bottom). A pseudo-page transition onto the first
page occurs either when the first break occurs or when the first nondiverted text processing occurs. Arrangements for a trap to occur at the top
of the first page must be completed before this transition. In the following,
references to the current diversion mean that the mechanism being
described works during both ordinary and diverted output (the former
being considered as the top diversion level). (See section 7.4, "Diversions.")
The physical limitations on nroff and troff output are output-device
dependent.
Form

Initial
Value

II No
Notes Explanation
Argument

.pl ±N

11 in

.bp ±N

N-l

Request

.pn ±N

ignored

Page length set to ± N. The
internal limitation is about
75 inches in troff and about
136 inches in nroff. The current
page length is available in the .p
register.

B,t,y

Break page. The current page is
ejected and a new page is
begun. If ±N is given, the new
page number will be ±N. Also
see request .ns.
Page number. The next page
(when it occurs) will have the
page number ±N. A .pn must
occur before the initial pseudopage transition to affect the page
number of the first page. The
current page number is in the %
register.

nroff/troff: TECHNICAL DISCUSSION

Description
.po ±N

0; 1 int

.ne N

Page offset. The current left
margi n is set to ± N. The troff
initial value provides 1 inch of
paper margin. (See section 6,
"Line Length and Indenting.")
The current page offset is available in the .0 register.

N-IV

D,v

Need N vertical space. If the
p'age space needed (N) is greater
than the distance to the next
trap (D), then a forward vertical
space of size D occurs, which
will spring the trap. If there are
no remaining traps on the page,
D is the distance to the bottom
of the page. If the distance to
the next trap (D) is less than one
vertical line space (v), then
another line could still be output before the trap is sprung. In
a diversion, D is the distance to
the diversion trap, if any, or is
very large.

•mkR

none

internal

Mark the current vertical place
in an internal register (both
associated with the current
diversion level), or in register R,
if given. See .rt request.

.rt ±N

none

internal

D,v

Return upward only to a marked
vertical place in the current
diversion. If ±N (relative to the
current place) is given, the place
is ± N from the top of the page
or diversion or, if N is absent,
the place is that marked by a
previous .mk. Note that the .sp
request may be used in all cases
instead of .rt by spacing to the

TECHNICAL DISCUSSION

Description

absolute place stored in a explicit register; e.g., using the
sequence .mk R ....sp I\nRu.
(See section 5.3, "Blocks of Vertical Space.")

4. Text Filling, Adjusting, and Centering
4. 1. Filling and Adjusting
During fill mode, words normally are collected from input text lines
and assembled into an output text line until some word doesn't fit. An
attempt is then made to hyphenate the word in an effort to assemble a part
of it into the output line. In adjust mode the spaces between the words on
the output line are then increased to spread out the line to the current line
length minus any current indent. A word is any string of characters delimited by the space character, the beginning or end of the input line, or by a
combination of these. Any adjacent pair of words that must be kept
together (neither split across output lines nor spread apart in the adjustment
process) can be tied together by separating them with the unpaddable space
character"\ "(backslash-space). The adjusted word spacings are uniform in
troff and the minimum interword spacing can be controlled with the .ss
request. (See section 2, "Font and Character Size Control.") In nroff, they
are normally nonuniform because of quantization to character-size spaces;
however, the command-line option -e causes uniform spacing with full output device resolution. Filling, adjustment, and hyphenation can all be
prevented or controlled. (See section 13, "Hyphenation.") The text length
on the last line output is available in the .n register, and text base-line position on the page for this line is in the nl register. The text base-line highwater mark (lowest place) on the current page is in the .h register.
An input text line ending with ., 1, !, .), 1), or !) is taken to be the end
of a sentence, and an additional space character is automatically provided
during filling. Multiple inter-word space characters found in the input are
retained except for trailing spaces; initial spaces also cause a break.
When filling is in effect, a \p may be embedded or attached to a word to
cause a break at the end of the word and have the resulting output line
spread out to fill the current line length.

nrotf/trotf: TECHNICAL DISCUSSION

Description

A text input line that happens to begin with a control character can be
made to not look like a control line by prefacing it with the non-printing,
zero-width filler character \&t. Still another way is to specify output translation of a specific character into the control character using .tr. (See section
10.4, "Output Translation.") To suppress the break function of the control
character ".", replace it with the single quote, "'''.

4.2. Interrupted Text
The copying of an input line in no-fill (Le., no line filling) mode can be
interrupted by terminating the partial line with a \c. The next encountered
input text line will be considered to be a continuation of the same line of
input text. Similarly, a word within filled text may be interrupted by terminating the word (and line) with \c; the next encountered text will be
taken as a continuation of the interrupted word. If the intervening control
lines cause a break, any partial line will be forced out along with any partial
word.

Request
Form

Initial
Value

If No
Notes Explanation
Argument

.br

. .fi

.nf

Break. The filling of the line
currently being collected is
stopped and the line is output
without adjustment. Text lines
beginning with space characters
and empty text lines (blank
lines) also cause a break.

fill on

B,E

Fill subsequent output lines.
The register .u is 1 in fill mode
and 0 in no-fill mode.

fill on

B,E

No-fill. Subsequent output lines
are neither filled nor adjusted.
Input text lines are copied
directly to output lines without
regard for the current line
length.

TECHNICAL DISCUSSION

Description

.ad c

adj,both

adjust

Line adjustment is begun. If fill
mode is not on, adjustment will
be deferred until fill mode is
back on. If the type indicator c
is present, the adjustment type is
changed as shown in the following table.

Indicator
r
c

b or n
absent

Adjust Type
adjust left margin only
adjust right margin only
center
adjust both margins
unchanged

The adjustment type indicator c
may also be a number obtained
from the .j register. (See section
25 in the "Summary,"
"Predefined Read-Only Registers. ")

.na

adjust

.ce N

off

N-l

No-adjust. Adjustment is turned
off; the right margin will be
ragged. The adjustment type for
.ad is not changed. Output line
filling still occurs if fill mode is
on.

a,E

Center the next N input text
lines within the current (linelength minus indent). If N-O,
any residual count is cleared. A
break occurs after each of the N
input lines. If the input line is
too long, it will be left adjusted.

nroff/troff: TECHNICAL DISCUSSION

Description

5. Vertical Spacing
5. 1. Base-line Spacing
The vertical spacing (V) between the base-lines of successive output
lines can be set using the .vs request with a resolution that is devicedependent in both nroff and troff. V must be large enough to accommodate the character sizes on the affected output lines. For the common type
sizes (9-12 points), usual typesetting practice is to set V to 2 points greater
than the point size; troff default is IO-point type on a 12-point spacing (as
in this document). The current V is available in the .v register. Multiple-V
line separation (e. g., double spacing) may be requested with .Is.
5.2. Extra Line-space
If a word contains a vertically tall construct requiring the output line
containing it to have extra vertical space before and/or after it, the extraline-space function \x'N ' can be embedded in or attached to that word. In
this and other functions having a pair of delimiters around their parameter
(here '), the delimiter choice is arbitrary except that it can't look like the
continuation of a number expression for N. If N is negative, the output line
containing the word will be preceded by N extra vertical space; if N is positive, the output line containing the word will be followed by N extra vertical space. If successive requests for extra space apply to the same line, the
maximum values are used. The most recently utilized post-line extra linespace is available in the .a register.

5.3. Blocks of Vertical Space
A block of vertical space is ordinarily requested using .sp, which honors
the no-space mode and which does not space past a trap. A contiguous
block of vertical space may be reserved using .sv.

TECHNICAL DISCUSSION

Description

Request
Form

Initial
Value

II No
Notes Explanation
Argument

.vsN

1/6in;12pts

E,p

Set vertical base-line spacing
size V. Transient extra vertical
space available with \x'N ' (see
above).

.IsN

N-l

Line spacing set to ±N. N-l Vs
(blank lines) are appended to
each output text line.
Appended blank lines are omitted, if the text or previous
appended blank line reached a
trap position.

.sp N

N-IV

B,v

Space vertically in either direction. If N is negative, the
motion is backward (upward)
and is limited to the distance to
the top of the page. Forward
(downward) motion is truncated
to the distance to the nearest
trap. If the no-space mode is
on, no spacing occurs (see .DS
and .rs below).

.svN

N-IV

Save a contiguous vertical block
of size N. If the distance to the
next trap is greater than N, N
vertical space is output. Nospace mode has no effect. If this
distance is less than N, no vertical space is immediately output,
but N is remembered for later
output (see .os). Subsequent .sv
requests will overwrite any still
remembered N.

.os

Output saved vertical space.
No-space mode has no effect.

nroft/trotf: TECHNICAL DISCUSSION

Description

Used to finally output a block of
vertical space requested by an
earlier .sv request.
(

.ns

space

No-space mode turned on.
When on, the no-space mode
inhibits .sp requests and .bp
requests without a next page
number. The no-space mode is
turned off when a line of output
occurs, or with .rs.

.rs

space

Restore spacing. The no-space
mode is turned off.

Causes a break and outputs a
blank line exactly like .sp 1.

Blank text line

6. Line length and Indenting
The maximum line length for fill mode may be set with .11. The indent
may be set with .in; an indent applicable to only the next output line may
be set with .ti. The line length includes indent space but not page offset
space. The line-length minus the indent is the basis for centering with .ce.
The effect of .11, .in, or .ti is delayed, if a partially collected line exists, until
after that line is output. In fill mode the length of text on an output line is
less than or equal to' the line length minus the indent. The current line
length and indent are available in registers .I and .i, respectively. The
length of three-part titles produced by .tt is independently set by .It. (See
section 14, "Three Part Titles.")

Request
Form

Initial
Value

If No
Notes Explanation
Argument

.11 ±N

6.5in

E,m

Line length is set to ±N. In
troff the maximum (linelength)+(page-offset) is devicedependent.

B,E,m

Indent is set to ±N. The indent

•in ±N

TECHNICAL DISCUSSION

- - - - - - - - - - - - - - - - - - - - - - - - - - Description

is prepended to each output
line.
•ti ±N

ignored

B,E,m

Temporary indent. The next
output text line will be indented
a distance ± N with respect to
the current indent. The resulting total indent may be zero
(equal to current page offset) but
may not be less than the current
page offset. The temporary
indent applies only for the one
output line following the
request; the value of the current
indent (that value stored in the
.i register) is not changed.

7. Macros, Strings, Diversions, and Position Traps
7. 1. Macros and Strings
A macro is a named set of arbitrary lines that may be invoked by name
or with a trap. A string is a named string of characters, not including a
new-line character, that may be summoned by name at any point. Request,
macro, and string names share the same name list. Macro and string names
may be one or two characters long and may usurp previously defined
request, macro, or string names. Any of these entities may be renamed with
.m or removed with .rm.
Macros are created by .de and .di, and appended to by .am and .da; .di
and .da cause normal output to be stored in a macro. Strings are created by
.ds and appended to by .as. A macro is invoked in the same way as a
request; a control line beginning .xx will execute the contents of macro xx
(macro .xx may be followed by a maximum of nine argum'?nts): should the
macro-define contain requests or escape sequences, these will be executed
along with the rest of the defined contents of xx. If the macro is defined to
contain text, that text will print. The strings defined as x and xx are
and
respectively. String referinserted at any desired point with
ences and macro invocations may be nested.

,-x ,-(xx

nrolf/trolf: TECHNICAL DISCUSSION

D••crlpUon

7.2. Copy Mode Input Interpretation
During the definition and extension of strings and macros (not by diversion) the input is read in copy mode. The input is copied without interpretation except that
• The contents of number registers, indicated by \0, are substituted.
• Strings, indicated by \lt x and \It(xx, are read into the text.
• Arguments indicated by \$ are replaced by the appropriate
values at the current macro level.
• Concealed new-lines indicated by \(new-line) are eliminated.
• Comments indicated by \ It are eliminated.

• \t and \a are interpreted as ASCII horizontal tab and SOH

respec-

tively. (See section 9, "Tabs, Leaders, and Fields.")
• \\ is interpreted as \.
• \. is interpreted as ".".
These interpretations can be suppressed by prepending a \. For example,
since \\ maps into a \, \\n will copy as \0 which will be interpreted as a
number register indicator when the macro or string is reread.

7.3. Arguments
When a macro is invoked by name, the remainder of the line is taken to
contain up to nine arguments. The argument separator is the space character, and arguments may be surrounded by double-quotes to permit embedded space characters. Pairs of double-quotes may be embedded in doublequoted arguments to represent a single double-quote. If the desired arguments won't fit on a line, a concealed new-line may be used to continue on
the next line.
When a macro is invoked the input level is pushed down and any arguments available at the previo'us level become unavailable until the macro is
completely read and the previous level is restored. A macro's own arguments can come intQ play at any point within the macro with \$N, which
introduces the Nth argument (l ~N ~9) into the macro's processing activity.
If an invoked argument doesn't exist, a null string results. For example, the

TECHNICAL DISCUSSION

Description

macro xx may be defined by
.de xx
\"begin definition
Today is \\$1 the \\$2.
\ "end definition

and called by
.xx lvblday 14th

to produce the text
Today is Monday the 14th.
Notice that the \$ was concealed in the definition with a prepended \. This
leading backslash protected the argument ($) so that it would be replaced by
the argument of the macro when invoked, and not by the argument in
effect when this one was being defined. The number of currently available
arguments is in the .$ register.
No arguments are available at the top (non-macro) level in this implementation. Because string referencing is implemented as an input-level
push down, no arguments are available from within a string. No arguments
are available within a trap-invoked macro.
Arguments are copied in copy mode onto a stack where they are available for reference. The mechanism does not allow an argument to contain a
direct reference to a long string (evaluated at copy time), and it is advisable
to conceal string references (with an extra \) to delay interpretation until
argument reference time.

7.4. Diversions
Processed output may be diverted into a macro for purposes such as
footnote or sidenote processing or determining the horizontal and vertical
size of some text for conditional changing of pages or columns. A single
diversion trap may be set at a specified vertical position. The number registers dn and dl respectively contain the vertical and horizontal size of the
most recently ended diversion. Processed text that is diverted into a macro
retains the vertical size of each of its lines when reread in no-fill mode
regardless of the current V. Constant-spaced (.cs) or emboldened (.bd) text
that is diverted can be reread correctly only if these modes are again or still
in effect at reread time. One way to do this is to embed in the diversion
the appropriate .cs or .bd requests with the transparent mechanism
described in section 10.6, "Transparent Throughput."

nroff/troff: TECHNICAL DISCUSSION

Description

Diversions may be nested and certain parameters and registers are associated with the current diversion level (the top non-diversion level may be
thought of as the Oth diversion level). These are the diversion trap and
associated macro, no-space mode, the internally-saved marked place (see
.mk and .rt), the current vertical place (.d register), the current high-water
text base-line (.h register), and the current diversion name (.z register).

7.5. Traps
Three types of trap mechanisms are available-page traps, a diversion
trap, and an input-line-count trap. Macro-invocation traps may be planted
using .wh at any page position including the top. This trap position may be
changed using .ch. Trap positions at or below the bottom of the page have
no effect unless or until moved to within the page or rendered effective by
an increase in page length.
Two traps may be planted at the same position only by first planting
them at different positions and then moving one of the traps; the first
planted trap will conceal the second unless and until the first one is moved.
If the first one is moved back, it again conceals the second trap.
The macro associated with a page trap is automatically invoked when a
line of text is output whose vertical size reaches or sweeps past the trap
position. Should several traps be placed so close together that a single output line could spring all of them, all but the first will be ignored. Reaching
the bottom of a page springs the top-of-page trap, if any, provided there is a
next page. The distance to the next trap position is available in the .t register; if there are no traps between the current position and the bottom of the
page, the distance returned is the distance to the page bottom.
A macro-invocation trap effective in the current diversion may be
planted using .dt. The.t register works in a diversion; if there is no subsequent trap a large distance is returned.

Request
Form
.de xx yy

Initial
Value

If No
Notes Explanation
Argument
.yy-..

TECHNICAL DISCUSSION

Define or redefine the macro xx.
The contents of the macro begin
on the next input line. Input
lines are copied in copy mode
until the definition is

Description

terminated by a line beginning
with .yy, whereupon the macro
yy is called. In the absence of
yy, the definition is terminated
by a line beginning with "..". A
macro may contain .de requests
provided the terminating macros
differ or the contained
definition terminator is concealed; ".." can be concealed as
which will copy as "\.." and
be reread as
" \ \. . 11

II•• ".

.am xx yy

Append to macro (append version of .de).

.yy-..

.ds xx string ignored

Define a string xx containing
string. Any initial double-quote
in string is stripped off to permit
initial blanks.

.as xx string ignored

Append string to string xx
(append version of .ds).

.rm xx

ignored

Remove request, macro, or
string. The name xx is removed
from the name list and any
related storage space is freed.
Subsequent references will have
no effect.

.rn xx yy

ignored

Rename request, macro, or string
xx to yy. If yy exists, it is first
removed.

.di xx

end

Divert output to macro xx. Normal text processing occurs during diversion except that page
offsetting is not done. The
diversion ends when the request
.di or .da is encountered without

nroff/troff: TECHNICAL DISCUSSION

Descrip tion

an argum ent; extran eous
reques ts of this type should not
appear when nested diversi ons
are being used.
.da xx

end

Divert, append ing to xx (appen d
version of .di).

.wh N xx

Install a trap to invoke xx at
page positio n N; a negativ e N
will be interpr eted with respect
to the page bottom . Any macro
previo usly plante d at N is
replace d by xx. A zero N refers
to the top of a page. In the
absenc e of xx, the first found
trap at N, if any, is remov ed.

.ch xx N

Chang e the trap positio n for
macro xx to be N. In the
absenc e of N, the trap, if any, is
remov ed.

.dt N xx

off

D,V

Install a diversi on trap at position N in the curren t diversi on
to invoke macro xx. Anoth er .dt
will redefin e the diversi on trap.
If no argum ents are given, the
diversi on trap is remov ed.

.it N xx

off

Set an input-l ine-co unt trap to
invoke the macro xx after N
lines of text input have been
read (contro l or reques t lines
don't count). The text may be
in-line text or either in-line or
trap-in voked macros represe nting text. (See the discuss ion of
the input-l ine-co unt .it reques t
in section 7.5, "Traps.")

TECHNICAL DISCUSSION

Description

.em xx

none

The macro xx will be invoked
when all input has ended. The
effect is the same as if the contents of xx had been at the end
of the last file processed.

8. Number Registers
A variety of parameters are available to the user as predefined, named
number registers. The user may also define his own named registers.
Register names are one or two characters long and do not conflict with
request, macro, or string names. Except for certain predefined read-only
registers, a number register can be read, written, automatically incremented
or decremented, and inserted into the input using a variety of counting
methods. Automatically numbered sections and paragraphs are common
usages. A number register may be used any time numerical input is
expected or desired. (See section 1.4, "Numerical Expressions.")
Number registers are created and modified using .nr, which specifies the
name, numerical value, and the auto-increment size. Registers are also
modified, if accessed with an auto-incrementing sequence. If the registers x
and xx both contain N and have the auto-increment size M, the following
access sequences have the effect shown:

Sequence

\nx
\n(xx
\n+x
\n-x
\n+(xx
\n-(xx

Effect on
Register
none
none
x incremented by M
x decremen ted by M
xx incremen ted by M
xx decremented by M

Interpreted
Value
N
N

N+M
N-M
N+M
N-M

When evaluated, a number register is converted to decimal (default),
decimal with leading zeros, lower-case roman, upper-case roman, lower-case
alphabetic, or upper-case alphabetic according to the format specified by .af.
The escape sequence \gxx or \g( xx gives the format used by the registers x
or xx. This escape sequence will only return a value if the stated register
has been set or used; otherwise, it returns O. The value can also be saved
and used as the second argument to .af to restore a previous format.

nroff/troff: TECHNICAL DISCUSSION

Description

Request
Form

Initial
Value

If No
Notes Explanation
Argument

.nr R ±N M-

.af R c

The number register R is
assigned the value ±N with
respect to the previous value, if
any. The increment for autoincrementing is set to M .
Assign format c to register R.
The available formats are

Arabic

Format
1
001

I
a
A

Numbering
Sequence
0,1,2,3,4,5,...
000,001,002,003,004,005,...
o,i,ii,iii,iv,v, .
O,I,II,III,IV,V, .
O,a,b,c, ,z,aa,ab,...,zz,aaa,...
O,A,B,C, ,Z,AA,AB,...,ZZ,
AAA,...

An Arabic format having N
digits specifies a field width of
N digits. The read-only registers and the width function are
always Arabic. (See section 11.2,
"Width Function.")
.rr R

ignored

TECHNICAL DISCUSSION

Remove register R. If many
registers are being created
dynamically, it may become
necessary to remove unneeded
registers to recapture internal
storage space for new registers.

Description

9. Tabs, Leaders, and Fields
9.1. Tabs and Leaders
The ASCII horizontal tab character and the ASCII SOH (hereafter known
as the leader character) can both be used to generate either horizontal
motion or a string of repeated characters. The length of the generated
entity is governed by internal tab stops specifiable with .ta. The default
difference is that tabs generate motion and leaders generate a string of
periods; .tc and .Ie offer the choice of repeated character or motion. There
are three types of internal tab stops-left adjusting, right adjusting, and
centering. In the following table D is the distance from the current position
on the input line (where a tab or leader was found) to the next tab stop;
next-string consists of the input characters following the tab (or leader) up
to the next tab (or leader) or end of line; and W is the width of next-string.
Length of motion or
Location of
Tab
next-string
repeated characters
type
Left
D
Following D
D-W
Right adjusted within D
Right
D-W/2
Centered on right end of D
Centered
The length of generated motion is allowed to be negative, but that of a
repeated character string cannot be. Repeated character strings contain an
integer number of characters, and any residual distance is prepended as
motion. Tabs or leaders found after the last tab stop are ignored, but may
be used as next-string terminators.
Tabs and leaders are not interpreted in copy mode. \t and \a always
generate a non-interpreted tab and leader respectively, and are equivalent
to actual tabs and leaders in copy mode but are ignored during output
mode.

9.2. Fields
A field is contained between a pair of field delimiter characters, and
consists of sub-strings separated by padding indicator characters. The field
length is the distance on the input line from the position where the field

nroff/troff: TECHNICAL DISCUSSION

De8crlptlon

begins to the next tab stop. The difference between the total length of all
the sub-strings and the field length is incorporated as horizontal padding
space that is divided among the indicated padding places. The incorporated
padding is allowed to be negative. For example, if the field delimiter is #
and the padding indicator is "', #"'xxx"'right # specifies a right-adjusted string
with the string xxx centered in the remaining space.

Request
Form

Initial
Value

If No
Notes Explanation
Argument

.ta Nt ...

8n; O.5in

none

E,m

tz=R, right adjusting; t=C,
centering; t absent, left adjusting. tR tab stops are preset every
O.Sin.; nroff every 8 nominal
character widths. The stop
values are separated by spaces,
and a value preceded by + is
treated as an increment to the
previous stop value.

.te c

none

The tab repetition character
becomes c, or is removed specifying motion.

none

The leader repetition character
becomes c, or is removed specifying motion.

•le c

•Ie a b

off

TECHNICAL DISCUSSION

The field delimiter is set to a;
the padding indicator is set to
the space character or to b, if
given. In the absence of arguments the field mechanism is
turned off.

Description

10. Input and Output Conventions and Character
Translations
10.1. Input Character Translations
Ways of typing in the graphic character set are discussed in section 2.1
"Character Set." The ASCII control characters SOH and horizontal tab are
described in section 9.1, "Tabs and Leaders." The backspace is discussed in
section 10.3, "Backspacing, Underlining, and Overstriking." The new-line
delimits input lines. In addition, STX, £TX, ENQ, ACK, and BEL may be used
as delimiters or translated into a graphic with .tr. (See section 10.5, "Output
Translation.") troff normally passes none of these characters to its output;
nroff passes the BEL character. All others are ignored.
The escape character \ introduces escape sequences-causes the following character to mean another character, or to indicate some function. A
complete list of such sequences is given in the Summary and Index above. \
should not be confused with the ASCII control character ESC of the same
name. The escape character \ can be input with the sequence \\. The
escape character can be changed with .ec, and all that has been said about
the default \ becomes true for the new escape character. \e can be used to
print whatever the current escape character is. If necessary or convenient,
the escape mechanism may be turned off with .eo, and restored with .ec.

Request
Form

Initial
Value

If No
Notes Explanation
Argument

.ec c

•eo

Set escape character to \, or to c,
if given.
Turn escape mechanism off.

10.2. Ligatures
Five ligatures are available in the current troff character set fi, fI, If, !fi,
and /fl. They may be input (even in nroff) by \(fi, \(f1, \(ff, \(Fi, and \(Fl
respectively. The ligature mode is normally on in troff, and automatically
invokes ligatures during input.

nroft/troft: TECHNICAL DISCUSSION

Doscrlptlon

Request
Form

Initial
Value

II No
Notes Explanation
Argument

.lg N

off; on

Ligature mode is turned on if N
is absent or non-zero, and
turned off if N=O. If N=2, only
the two-character ligatures are
automatically invoked. Ligature
mode is inhibited for request,
macro, string, register, or file
names, and in copy mode. No
effect in nroff.

10.3. Backspacing, Underlining, and Overslrlking
Unless in copy mode, the ASCII backspace character is replaced by a
backward horizontal motion having the width of the space character.
Underlining as a form of line-drawing is discussed in section 12.4, "Line
Drawing." A generalized overstriking function is described in section 12.1,
"Overstriking."
nroff automatically underlines characters in the underline font
specifiable with .uf (normally Times Italic on font position 2.) See section
2.2, "Fonts." In addition to .ft and \fF, the underline font is selected by .ul
and .cu. Underlining is restricted to an output-device-dependent subset of
reasonable characters.

Request
Form

Initial
Value

.ul N

off

If No
Notes Explanation
Argument

TECHNICAL DISCUSSION

Underline in nroff (italicize in
troff) the next N input text
lines. Actually, switch to underline font, saving the current
font for later restoration; other
font changes within the span of
a .ul will take effect, but the restoration will undo the last
change. Output" generated by .tl
is affected by the font change,
but does not decrement N. (See
section 14, "Three Part Titles.")

Descrlpllon

If N> 1, there is the risk that a

trap-invoked macro may provide
text lines within the span;
environment switching can
prevent this.
.cu N

off

N-l

.uf F

Italic

A variant of .ul that causes
every character to be underlined
and causes no line breaks to
occur in the affected input lines.
That is, each output space following .cu is like an unpaddable
space. .cu is identical to .ul in
trof£.

Underline font set to F. In
nroff, F may not be on position
1 (initially Times Roman).

10.4. Control Characters
Both the control character "." and the no-break control character II'" may
be changed, if desired. Changes must be compatible with the design of
macros used in the span of the change, especially trap-invoked macros.

Request
Form

Initial
Value

If No
Notes Explanation
Argument

.cc c

The basic control character is set
to c, or reset to ".".

.c2 c

The no-break control character
is set to c, or reset to "'".

10.5. Output Translation
One character can be made a stand-in for another character using .tr.
All text processing (e.g., character comparisons) takes place with the input
(stand-in) character which appears to have the width of the final character.
The graphic translation occurs at the moment of output (including diversions).

nroff/troff: TECHNICAL DISCUSSION

Descrip tion

Reque st
Form

Initial
Value

.tr abed....

none

If No
Notes Explanation
Argum ent

Transl ate a into b, e into d, etc.
H an odd numbe r of charac ters
is given, the last one will be
mappe d into the space character.
To be consist ent, a particu lar
transla tion must stay in effect
from input to output time. To
reset .lr, follow reques t with
previo us argum ents given in
duplica te. The examp le given at
the start of this entry, for
instanc e, would be turned off as
follows: .tr aaee.

10.6. Trans paren t Throu ghput
An input line beginn ing with a \! is read in copy mode and transparen tly output (witho ut the initial \!); the text proces sor is otherw
ise
unawa re of the line's presen ce. This mecha nism may be used to
pass control inform ation to a post-processor or to embed contro l lines in a
macro
created by a diversi on.
10.7. Comm ents and Conce aled New-lines
An awkwa rdly long input line that must stay one line (e.g., a string
definit ion, or no-fille d text) can be split into many physic al lines
by ending
all but the last one with the escape \. The sequen ce \(new- line) is
always
ignore d-exce pt in a comme nt. Comm ents may be embed ded at
the end of
any line by prefaci ng them with \". The new-li ne at the end of a
comme nt
cannot be concea led. A line beginn ing with \" will appear as a blank
line
and behave like .sp 1; a comme nt can be on a line by itself by beginn
ing
the line with .\".

TECHNICAL DISCUSSION

DescrlpUon

11. Local Horizontal and Vertical Motions, and the
Width Function
11.1. Local Motio ns
horThe functio ns \v'N' and \h'N' can be used for local vertica l and
e
positiv
the
e;
izontal motion respec tively. The distanc e N may be negativ
ned
contai
directi ons are rightw ard and downw ard. A local motion is one
ary that
within a line. To avoid unexpe cted vertica l disloca tions, it is necess
ise
the net vertica l local motion within a word, in filled text, and otherw
within a line, balanc e to zero. The above and certain other escape
ing table.
sequen ces provid ing local motion are summa rized in the follow
Vertical
Motion

Effect in
nroff
R

\v'N' Move distanc e N

\u
\d
\r

'h line up
lh em up
Ih em down 'h line down
1 line up
1 em up

Horizon tal
Motion

Effect in
troff

nroff

\h'N' Move distanc e N
\(space) Un paddab le space-size space
Digit-size space
\0

1/6 em space
1/12 em space

ignored
ignored

As an examp le, E2 could be genera ted by the sequen ce
examp le that the
E\s-2\ v'-o.4m ' 2\v' O.4m' \s+2; it should be noted in this
0.4 em vertica l motion s are at the smalle r point size.

11.2. Width Funct ion
string (in
The width functio n \w'stri ng' genera tes the numer ical width of
and
string,
in
ded
embed
safely
basic units). Size and font change s may be
could
'u
-\w'1.
ti
.
le,
examp
will not affect the curren t enviro nment . For
of the
be used to tempor arily indent leftwa rd a distanc e equal to the size
string "1. ".
rs 5t
The width functio n also sets three numbe r registe rs. The registe
relativ e
and sb are set respec tively to the highes t and lowest extent of string
is
to the baselin e; then, for examp le, the total height of the string
betwee n
value
a
to
set
is
.ct
r
registe
r
numbe
the
\n(stu -\n(sb u. In troff
nroff/tr off: TECHNICAL DISCUSSION

Descrip tion

o and 3: 0 means that all of the characters in string were short lower case
charac ters withou t descen ders (like "en); 1 means that at least one
charac ter
has a descen der (like "y"); 2 means that at least one charac ter is tall
(like
"H"); and 3 means that both tall charac ters and charac ters with descen
ders
are presen t.
11.3. Mark Horizo ntal Place
The escape sequen ce \kx will cause the curren t horizo ntal positio
n in
the input line to be stored in registe r x. As an examp le, the constru
ction
\kxwor d\h'l\n xu+2u 'word will embold en word by backin g up to almost
its
beginn ing and overpr inting it, resulti ng in word.

12. Overstrike, Bracket, Line-drawing, and Zerowidth Functions
12. 1. Overs triking
Autom atically centere d overstr iking of up to nine charac ters is provid
ed
by the overstr ike functio n \o'string'. The charac ters in string are
overpr inted
with centers aligned ; the total width is that of the widest charac
ter. string
should not contain local vertical motion . As examp les, \0'e\" produc
es
e\o,\(m o\(sl' produc es ~.
12.2. Zero-w idth Chara cters
The functio n \zc will· output c withou t spacin g over it, and can be
used
to produc e left-ali gned overstr uck combin ations. As examp les, \z\(ci\(
pl
will produc e e, and \(br\z\ (rn\(ul \(br will produc e the smalle st
possibl e
constru cted box D.
12.3. Large Brack ets
The Special Mathem atical Font contain s a numbe r of bracke t constru
ction pieces ( ( l ) J { ~ I l J r 1) that can be combin ed into variou
s bracke t
styles. The functio n \b'strin g' may be used to pile up vertica lly
the characters in string (the first charac ter on top and the last at the bottom
); the characters are vertica lly separa ted by 1 em and the total pile is center
ed 1/2em
50

TECHNICAL DISCUSSION

Description

above the current baseline (lh line in nroff). For example,
\b' \(lc\(lf 'I' I \b' \(rc\(rf ' \x'

~.Sm'

\x'O.Sm'

produces [E ].

12.4. Line Drawing
The function \I'Nc' will draw a string of repeated c's towards the right
for a distance N. (\1 is \(lower-case L). If c looks like a continuation of an
expression for N, it may be insulated from N with a \&. If c is not specified,
the _ (baseline rule) is used (underline character in nroff). If N is negative,
a backward horizontal motion of size N is made before drawing the string.
Any space resulting from N /(size of c) having a remainder is put at the
beginning (left end) of the string. In the case of characters that are
designed to be connected such as baseline-rule _, underrule _, and rooten -, the remainder space is covered by overlapping. If N is less than the
width of c, a single c is centered on a distance N. As an example, a macro
to underscore a string can be written
.de us
\\$1\ 1 '

I O\(ul'

or one to draw a box around a string
.de bx
\(br\ : \\$1\

\(br\ 1 '

I O\(m'\ l '

O\(ul'

such that
•us "underlined \ 0, accept any-

thing.
.if !N anything

If expression N <; 0, accept any-

thing.
.if 'string1 'string2' anything

If string1 identical to string2,
accept anything.

.if rstringl 'string2' anything

If string1 not identical to string2,

accept anything.
.ie c anything
.el anything -

If portion of if-else; all above
forms (like .if).

Else portion of if-else.

nroff/troff: TECHNICAL DISCUSSION

Descrip tion

The built-in condit ion names are
Condit ion
Name

o
e
t
n

True If
Curren t page numbe r is odd
Curren t page numbe r is even
Forma tter is troff
Forma tter is nroff

If the condit ion c is true, or if the numbe r N is greater than zero,
or if the
strings compa re identic ally (includ ing motion s and charac ter size
and font),
anything is accepte d as input. If a ! preced es the condit ion, numbe
r, or
string compa rison, the sense of the acceptance is reverse d.

Any spaces betwee n the condit ion and the beginn ing of anything
are
skippe d over. The anything can be either a single input line (text,
macro, or
whatev er) or a numbe r of input lines. In the multi-l ine case, the
first line
must begin with a left delimi ter \( and the last line must end with
a right
delimi ter \J. The left delimi ter must be follow ed by either a comma
nd or
text:

.if 58>1 \{

O.5i

Follow ing this delimi ter with a backslash (, escapin g the newlin
e, yields
an equiva lent arrang ement.
The reques t .ie (if-else) is identic al to .if except that the accepta nce
state
is remem bered. A subseq uent and matchi ng .el (else) reques t then
uses the
reverse sense of that state. .ie - .el pairs may be nested .
Some examp les are

.if e . tl '

Even Page %'"
which output s a title if the page numbe r is even; and

.ie \n%>1 \{\
'~

O.5i

. tl ' Page %'"
'~

: 1.2i \}

.el .~. I 2.5i

which treats page 1 differe ntly from other pages.

TECHNICAL DISCUSSION

De8crlptlon

17. Environment Switching
A number of the parameters that control the text processing are gathered together into an environment, which can be switched by the user. The
environment parameters are those associated with requests noting E in their
Notes column; in addition, partially collected lines and words are in the
environment. Everything else is global; examples are page-oriented parameters, diversion-oriented parameters, number registers, and macro and string
definitions. All environments are initialized with default parameter values.

Request
Form

Initial
Value

If No
Notes Explanation
AJgument

.ev N

N-O

Environment switched to
environment O~N~2. Switching is done in push-down
fashion so that restoring a previous environment must be done
with .ev rather than specific
reference.

nrofl/trofl: TECHNICAL DISCUSSION

Description

1~.

Insertions from the Standard Input

The input can be temporarily switched to the system standard input
with .rd, which will switch back when two new-lines in a row are found
(the extra blank line is not used). This mechanism is intended for insertions in form-letter-like documentation. On the UNIX system, the standard
input can be the user's keyboard, a pipe, or a file.

Request
Form
.rd prompt

Initial
Value

If No

Notes Explanation

A~ument
prompt-BEL

Read insertion from the standard input until two new-lines
in a row are found. If the standard input is the user's keyboard, prompt (or a BEL) is written onto the user's terminal. .rd
behaves like a macro, and arguments may be placed after

prompt.
Exit from nroff/troff. Text processing is terminated exactly as
if all input had ended.

•ex

If insertions are to be taken from the terminal keyboard while output is
being printed on the terminal, the command-line option -q will turn off
the echoing of keyboard input and prompt only with BEL. The regular
input and insertion input cannot simultaneously come from the standard
input.
As an example, multiple copies of a form letter may be prepared by
entering the insertions for all the copies in one file to be used as the standard input, and causing the file containing the letter to reinvoke itself using
.nXi the process would ultimately be ended by an .ex in the insertion file.

TECHNICAL DISCUSSION

Description

19. Input/Output File Switching
Request
Form
.50

Initial
Value

file

.nx file

If No
Notes Explanation
Argument
Switch source file. The top
input (file reading) level is
switched to file. When the new
file ends, input is again taken
from the original file; .so's may
be nested. Note that file should
be preprocessed, if necessary,
before being called by .50. eqn,
tbl, pic, and grap will not reach
through .sos to process an object
file. Once a .50 is encountered,
the processing of file is immediate. Processing of the original
file (e. g., a macro that is still
active) is suspended.

end-of-file

Next file is file. The current file
is considered ended, and the
input is immediately switched to
file.

.cf file

Copy the contents of file, uninterpreted into troff output file at
this point. Havoc ensues unless
the motions in the file restore
the current horizontal and vertical position.

.If N file

Corrects troff's idea of the
current line number, N, and the
current file, file, for use in error
messages.

.pi program -

Pipe output to program. This

nrofl/trofl: TECHNICAL DISCUSSION

Description

request must occur before any
printing occurs. No arguments
are transmitted to program.

20. Miscellaneous
Request
Form

Initial
Value

If No
Notes Explanation
Argument

.mc eN

off

.tm string

new-line

After skipping initial blanks,
string (rest of the line) is read in
copy mode and written on the
user's terminal.

.ig yy

.yy-..

Ignore input lines. .ig behaves
exactly like .de except that the
input is discarded. (See section
7, "Macros, Strings, Diversions,
and Position Traps.") The input
is read in copy mode, and any
auto-incremented registers will
be affected.

TECHNICAL DISCUSSION

E,m

Specifies that a margin character
c appear a distance N to the
right of the right margin after
each non-empty text line (except
those produced by .tl). If the
output line is too long (as can
happen in no-fill mode) the
character will be appended to
the line. If N is not given, the
previous N is used; the initial N
is 0.2 inches in nroff and 1em
in troff. The margin character
used with this paragraph was a
12-point box-rule.

Description

.pm t

•El
.ab text

.sy cmd args -

Print macros. The names and
sizes of all of the defined macros
and strings are printed on the
user's terminal; if t is given,
only the total of the sizes is
printed. The size is given in
blocks of 128 characters.

all

Abort

Flush output buffer.
Prints text on the diagnostic output (normally the terminal) and
terminates without further processing. If text is missing, the
message "User Abort" is printed.
The output buffer is flushed.
Used in interactive debugging to
force output.
cmd is executed but its output is

not captured at this point. The
standard input for cmd is closed.
Output for processing must be
explicitly saved in an output
file.

nroff/troff: TECHNICAL DISCUSSION

Description

21. Output and Error Messages
The output from .tm, .pm, and the prompt from .rd, as well as various
error messages are written onto the UNIX system's standard error message
output. The latter is different from the standard output, where nroff formatted output goes. By default, both are written onto the user's terminal,
but they can be independently redirected.
Various error conditions may occur during the operation of nroff and
troff. Certain less serious errors having only local impact do not cause processing to terminate. Two examples are "word overflow," caused by a word
that is too large to fit into the word buffer (in fill mode), and "line overflow," caused by an output line that grew too large to fit in the line buffer;
in both cases, a message is printed, the offending excess is discarded, and
the affected word or line is marked at the point of truncation with a • in
nroff and a , . in troff. The philosophy is to continue processing, if possible, on the grounds that output useful for debugging may be produced. If a
serious error occurs, processing terminates, and an appropriate message is
printed. Examples are the inability to create, read, or write files, and the
exceeding of certain internal limits that make future output unlikely to be
useful.

TECHNICAL DISCUSSION

Special Characters
1. Input Names for ' , , , and - and for Non-ASCII
Special Characters
Char

Input Character
Name Name

\(fm
\(ct
\(em

\\(ru
\(hy
0

•
0

•

\(de
\(bu
\(sq
\(bx

close quote
open quote
foot mark
cent sign
3/4 em dash
current font minus
rule
hyphen
literal hyphen
degree
bullet
square
box

Char
fi
ff
ff
ffi
ffl
~

Ih
%

l!)

Input Character
Name Name
\(fi
\(ff
\(fl
\(Fi
\(FI
\(14
\(12
\(34
\(dg
\(dd
\(rg
\(co
\(tm

fi ligature
ff ligature
flligature
ffi ligature
ffl ligature
one-fourth
one half
three-fourths
dagger
double dagger
registered
copyright
trademark

nroff/troff: TECHNICAL DISCUSSION

Special Characters

2. Non-ASCII Characters and Mnus on the Standard
Fonts
The upper-case Greek letter names followed by t are mapped into
upper-case English letters in whatever font is mounted on font position one
(default Times Roman). The special math plus, minus, and equals are provided to insulate the appearance of equations from the choice of standard
fonts.

Char

Input Character
Name N
\(-A
\(-B
\(-G

\(-1

K
A

\(ltK
\(-L

Alphat
Betat
Gamma
Delta
Epsilont
Zetat
Etat
Theta
Iotat
Kappat
Lambda

\(·M

--0.

\(-N
\(ltC
\(-0
\(-P
\(-R
\(ltS
\(ltT
\(ltU

\(-0

E
Z
H

\(-E
\(-Z

P
~

T
y
4l
X
'1'

\(-y

\(-H

\(-F
\(-X

\(-Q
\(-W

Char

\(lt a
\(-b
\(-g
\(-d

\(-e

\(-z

p
'Y

\(-y

\(lth
\(-i
\(ltk

\(It}

MUt

IJ.

Nut
Xi
Omicront
Pi
Rhot
Sigma
Taut
Upsilon
Phi
Chit
Psi
Omega

\(-m
\(-n
\(-c

\(-0

\(-p
\(lt r
\(lt s
\(ts
\(ltt
\(-u
\(ltf
\(lt x
\(lt q
\(-w

p
(J

\"
T
lJ

><-

\(--

identically equal
approx approximates
not equal
right arrow
left arrow
up arrow
down arrow
multiply
divide
plus-minus
cup (union)
cap (intersection)
subset of
superset of
improper subset
improper superset

\«-

::::::::

\(}\(ap

x
+

::t
U

n
C

:::>
~
~

math plus
math minus
math equals
math star
acute accent
grave accent
underrule
slash
(matching backslash)
square root
root en extender

\(1-

\(->

\«\(ua
\(da
\(mu
\(di

\(+\(cu
\(ca
\(sb
\(sp
\(ib
\(ip

Char
00

Input Character
Name Name
\(if

\(pd
\(gr
\(no
\(pt
\(es
\(mo
\(or
\(br
\(rh
\(lh

\(d

V
~

ex:
(/J

E
I

I,..

r
l

\(It

\(lb
\(rt
\(rb
\(lk

\(rk

I
l

\(bv

J
r

\(rf
\(lc
\(rc
\cs
\vs
\(sc

)

1
"

\(If

infinity
partial derivative
gradient
not
proportional to
empty set
member of
or
box vertical rule
right hand
left hand
circle
left top of big curly
bracket
left bottom
right top
right bottom
left center of big
curly bracket
right center of big
curly bracket
bold vertical
left floor (left bottom
of big square bracket)
right floor (right bottom)
left ceiling (left top)
right ceiling (right top)
control-shift indicator
visible space indicator
section

nroff/troff: TECHNICAL DISCUSSION

CHECKMM(l)

NAME

checkmm - checks documents formatted with the mm macros
SYNOPSIS

checkmm [ file (s) ]
DESCRIPTION

checkmm stands for "check memorandum macros." Use checkmm to check
for syntax errors in files that have been prepared for the mm(l) or mmt(l)
command. For example, checkmm checks that you have a .DE (display end
macro) corresponding to every .DS (display start macro).
The output for checkmm is the number of lines checked, and a list of macros
that are unfinished because of missing macros. If you do not include a file
name on the command line, checkmm takes input from standard input.
SEE ALSO

eqn(l), mm(l), mmt(l), mvt(l), neqn(l), tbl(l), and mm(S).
DIAGNOSTICS

"checkmm Cannot open file(s) " if file(s) is unreadable. The remaining output
of the program is diagnostic of the source file.

REFERENCE MANUAL

COL(l)

NAME

col - filter reverse line-feeds
SYNOPSIS

col [ -bfpx ) [ - )
DESCRIPTION

col reads from the standard input and writes onto the standard output. It performs the line overlays implied by reverse line feeds (ASCII code ESC-7), and
by forward and reverse half-line-feeds (ESC-9 and ESC-8). col is particularly
useful for filtering multicolumn output made with the .rt command of nroff
and output resulting from use of the tbl(l) preprocessor.
If the -b option is given, col assumes that the output device in use is not
capable of backspacing. In this case, if two or more characters are to appear in
the same place, only the last one read will be output.
Although col accepts half-line motions in its input, it normally does not emit
them on output. Instead, text that would appear between lines is moved to
the next lower full-line boundary. This treatment can be suppressed by the
-f (fine) option; in this case, the output from col may contain forward halfline-feeds (ESC-9), but will still never contain either kind of reverse line
motion.
Unless the -x option is given, col will convert white space to tabs on output
wherever possible to shorten printing time.
The ASCII control characters SO (\017) and 51 (\016) are assumed by col to start
and end text in an alternate character set. The character set to which each
input character belongs is remembered, and on output 51 and SO characters are
generated as appropriate to ensure that each character is printed in the correct
character set.
On input, the only control characters accepted are space, backspace, tab,
return, new-line, 51, SO, VT (\013), and ESC followed by 7, 8, or 9. The VT
character is an alternate form of full reverse line-feed, included for compatibility with some earlier programs of this type. All other non-printing characters are ignored.
Normally, col will ignore any escape sequences unknown to it that are found
in its input; the -p option may be used to cause col to output these sequences
as regular characters, subject to overprinting from reverse line motions. The
use of this option is highly discouraged unless the user is fully aware of the
textual position of the escape sequences.
SEE ALSO

mm(l), nroff(l), tbl(l).

REFERENCE MANUAL

COL(l)

NOTES

The input format accepted by col matches the output produced by nrolf with
either the -T37 or -TIp options. Use -T37 (and the -f option of col) if the
ultimate disposition of the output of col will be a device that can interpret
half-line motions, and -TIp otherwise.
BUGS

Cannot back up more than 128 lines.
Allows at most 800 characters, including backspaces, on a line.
Local vertical motions that would result in backing up over the first line of
the document are ignored. As a result, the first line must not have any superscripts.

REFERENCE MANUAL

DAPS(I)

DAPS(l)

NAME

daps - postprocessor for the Autologic APS-S phototypesetter
SYNOPSIS

daps [ option(s)

1[ -- ] [ fi1e(s) ]

DESCRIPTION

daps prints fi1e(s) created by troff(l) on an Autologic APS-5 phototypesetter.
If you do not specify a fi1e(s), the standard input is printed. daps understands
the following options:
-b
reports whether the typesetter is busy; does not print output
-h string
prints string in this job's header. The header appears on a page
preceding the output.
list prints pages whose numbers are given in a list. containing single
numbers N, or ranges N1:-N 2, A missing N 1 means the lowestnumbered page, a missing N 2 means the highest.
-r
reports the number of ll-inch pages generated by this job. Use this
option only after you have checked with the typesetter operations
staff.
-5 n
stops after every n pages of output. daps continues when you push
the PROCEED button on the typesetter.
-t
directs output to the standard output instead of the typesetter.
-w
waits for typesetter to become free, then prints output.
The lile(s) that you submit to daps should be prepared under the -Taps
option of troff(1).
-0

FILES

I dev laps
lusr/liblfont/devaps/·

APS-S phototypesetter device
font description files for APS-5

SEE ALSO

ditO(l), te(l), troff(l), troff(S), mmt(l), mvt(l).
BUGS

Installations with an Autologic APS-5 phototypesetter should be aware that
getting a good match to their Autologic fonts will almost certainly require
hand-tuning of the font description files (see FILES above).

REFERENCE MANUAL

0110(1)

NAME

dilO - postprocessor for the Imagen Imprint-tO laser printer
SYNOPSIS

dil0 [ option(s) ] [ -- ] [ filers) ]
DESCRIPTION

ditO prints file(s) created by troff(l) on an Imagen Imprint-lO laser printer. It
is a phototypesetter simulator that can handle troft output prepared for any
supported typesetter. However, files sent to dilO look best when prepared
with the -Til0 option of troft.
If you do not specify a file, the standard input is printed. dilO understands
the following options:
-0 list prints pag~s whose numbers are given in a list containing single
numbers N, or ranges Ni:-N2' A missing N 1 means the lowestnumbered page, a missing N 2 means the highest.
-t
directs output to the standard output instead of the typesetter.
-r n resolution of printer is n dots per inch. dilO will adjust its choice of
raster files to produce properly scaled output. The default is 240.
FILES

/usr/lib/font/devilO/·
font description files for Imagen Imprint-lO
/usr/lib/font/devilO/rastilO/· raster files for Imprint-lO
/tmp/dimp·
output of dilO ready for Imagen
SEE ALSO

daps(l), tc(l), troff(1), troff(S), mmt(l), mvt(l).

REFERENCE MANUAL

DIFFMK(I)

DIFFMK(l)

NAME

diffmk - mark differences between files
SYNOPSIS

diffmk [--] fUel

fUe2 file3

DESCRIPTION

diffmk compares two versions of a file and creates a third file that includes
"change mark" requests (.mc) for nroff or troff(l). filel and file2 are the old
and new versions of the file. diffmk generates file3, which contains the lines
of file2 plus inserted formatter "change mark" requests. When file3 is formatted, changed or inserted text is shown by I at the right margin of each line.
The position of deleted text is shown by a single asterisk: •.
If anyone is so inclined, diffmk can be used to produce listings of C (or
other) programs with changes marked. A typical command line for such use
is
diffmk old.c new.c tmp; .nlOff maca tmp I pr
where the file macs contains
.pI 1
.II 77
.nf
.eo
.ec
The .11 request might specify a different line length, depending on the nature
of the program being printed. The .eo and .nc requests are probably needed
only for C programs.
SEE ALSO

nroff(l), and troff(l).
Where diffmk encounters - it uses the standard input.
BUGS

Aesthetic considerations may dictate manual adjustment of some output. File
differences involving only formatting requests may produce undesirable output, Le., replacing .sp by .sp 2 will produce a "change mark" on the preceding
or follOWing line of output.

REFERENCE MANUAL

EQN(l)

NAME

eqn - format mathematical text for troff
SYNOPSIS

eqn [-d xx] [-p n] [-5 n] [-f n] [-Ttty_type] [--] [fi'e(s)]
DESCRIPTION

eqn is a troff(l) preprocessor for typesetting mathematical text on a phototypesetter. Normal usage is:
eqn [option(s)] fi'e(s) I troff [option(s)] I [typesetter]
If you do not specify files (or if you specify - as the last argument), eqn reads
the standard input. eqn prepares output for the typesetter that you name in
the -T option. Currently supported devices are -Taps (Autologic APS-5),
and -TitO (Imagen Imprint-lO). The default is -Taps.
A line beginning with .EO marks the start of an equation; the end of an equation is marked by a line beginning with .EN. troff does not alter these lines,
so they may be defined in macro packages to get centering, numbering, etc.
Vou may also name two characters as delimiters; eqn treats subsequent text
between delimiters as input. Vou may set delimiters to characters x and x
with the command line argument -d xx or (more commonly) with delim xx
between .EO and .EN. The left and right delimiters may be the same character;
the dollar sign is often used as such a delimiter. Turn delimiters off with
delim off. eqn touches only text that is between delimiters or between .EO
and .EN.
Set apart keywords recognized by eqn with spaces, tabs, new-lines, braces,
double quotes, tildes, and circumflexes. Use braces, {}, for grouping; generally
speaking, anywhere you can use a single character such as x, you may use a
complicated construction enclosed in braces instead. Tilde (-) represents a
full space in the output, circumflex (") half as much.
Subscripts and superscripts are produced with the keywords sub and sup.
Fractions are made with over. sqrt makes square roots.
The keywords from and to introduce lower and upper limits. Left and right
brackets, braces, etc., of the right height are made with left and right. Legal
characters after left and right are braces, brackets, bars, c and f for ceiling and
floor, and" for nothing at all (useful for a right-side-only bracket). A left
thing need not have a matching right thing, but a right thing must have a
matching left thing.
Vertical piles of things are made with pile, Ipile, cpile, and rpile. Piles may
have arbitrary numbers of elements; Ipile left-justifies, pile and cpile center
(but with different vertical spacing), and rpile right justifies. Matrices are
made with matrix. In addition, there is rcol for a right-justified column.
Diacritical marks are made with dot, dotdot, hat, tilde, bar, vee, dyad, and
under.
You may change point sizes and fonts with size n or size ±n, roman, italic,
bold, and font n. Vou may change point sizes and fonts globally in a document by gsize nand gfont n, or by the command-line arguments -sn and
-fn.

REFERENCE MANUAL

EQN(l)

Normally, subscripts and superscripts are reduced by 3 points from the previous size; you may change this with the command-line argument -pn.
You can line up successive display arguments. Place mark before the desired
lineup point in the first equation; place lineup at the place that is to line up
vertically in subsequent equations.
You may define shorthands or redefine existing keywords with define:
define thing % replacement %
defines a new token called thing that is replaced by replacement whenever it
appears thereafter. The % may be any character that does not occur in replacement.
Keywords such as sum, int, inf, and shorthands such as >-, !-, and -> are
recognized. Greek letters are spelled out in the desired case, as in alpha or
GAMMA. Mathematical words such as sin, cos, and log are made Roman
automatically. troff(l) four-character escapes such as \(dd, which produces the
double dagger, may be used anywhere. Strings enclosed in double quotes
(-... -) are passed through untouched; this permits keywords to be entered as
text, and can be used to communicate with troff(l) when all else fails. Full
details are given in the REFERENCE cited below.
SEE ALSO

mmt(l), mvt(l), neqn(l), nroff(l), tbl(l), troff(l), eqnchar(5), mm(5), and
mv(5).
"The Preprocessor eqn- in the User's Guide.
BUGS

To embolden digits, parentheses, etc., it is necessary to quote them, as in bold
-12.3-. When you use eqn with the mm macro package, displayed equations
must appear only inside displays.
See also BUGS under troff(l).

REFERENCE MANUAL

EQNCHAR(5)

EQNCHAR(S)
NAME

eqncha r - special character definitions for eqn and neqn

SYNOPSIS

) ]
eqn lusr/pu b/eqnc har [ option(s) ] [ -- ] [ lile(s) ] I troff [ option(s
) ]
eqn lusr/pu b/cateq nchar [ option(s) ] [ -- ] [ Iile(s) ] I troff [ option(s
) ]
neqn lusr/pu b/eqnc har [ option(s) ] [ -- ] [ file(s) ] I nroff [ option(s
eqn -Taps lusr/pu b/apse qnchar [ option(s) ] [ -- ] [ fi1e(s) ] I
troff [ option(s) ]

DESCRIPTION

character
lusr/pu b/eqnc har contains the following troff(l) and nroff(l) printer.
or
r
pesette
phototy
a
on
le
definitions that are not ordinarily availab
neqn(l) .
These definitions are primarily intende d for use with eqn(l) and
rs:
characte
ng
eqncha r contains definitions for the followi

ciplus
citimes
wig
-wig
> wig

<->
1<
I>
ang
rang
3dot

thl
quarter
3quarter
degree

<
=

-->

("
)
Ii

.1.

L
L

square
circle
blot
bullet
prop
empty
member
nomem
cup
cap
incl
subset
supset
!subset
!supset
scrL

•

tlJ

E
~

n
l;
C

:::>

s:
:2
t

ic APS-5
lusr/pu b/apse qnchar is a version of eqncha r tailored for the Autolog
on other
l
optima
look
not
will
output
phototypesetter. If you use apseqnchar,
proshould
and
ndent,"
-indepe
"device
more
is
har
cateqnc
rs.
phototypesette
You
.
troff(l)
by
ted
suppor
device
duce output that looks reasonable on any
to
or
nchar
b/cateq
lusr/pu
to
har
b/eqnc
lusr/pu
link
may
to
linked
is
har
b/eqnc
By default, lusr/pu
lusr/pu b/apse qnchar .
I usr I pub I apseqnchar.

REFERENCE MANUAL

EQNCHAR(S)

SEE ALSO

eqn(l), neqn(l) , nroff(l) , troff(1), mm(l), mmt(l) , and mvt(l).
"The Preprocessor eqn in the User's Guide.
lt

FILES

lusr/pu b/eqnc har
lusr/pu b/apseq nchar
I usr I pub I cateqnchar

REFER ENCE MANUAL

FONT(S)

NAME

font - description files for troff
SYNOPSIS

troff -Ttty_type ...
DESCRIPTION

For each phototypesetter that troff(l) supports and that is available on your
system, there is a directory that contains files describing the phototypesetter
and its fonts. This directory is named lusr/lib/font/devtty_type, where
tty_type is the name of the phototypesetter. Currently, the supported devices
are aps for the Autologic APS-S and itO for the Imagen Imprint-tO laser
printer.
For a particular phototypesetter, tty_type, the ASCII file DESC in the directory
devtty_typewithin the trolf source directory describes its characteristics. A
binary version of this file (described below) is found
in
lusr/lib/font/devtty_typeIDESC.out. Each line of this ASCII file starts with a
word that identifies the characteristic, which is followed by appropriate
specifiers. Blank lines and lines beginning with the # character are ignored.
The legal lines for DESC are:
res num
resolution of device in basic increments per inch
hor num
smallest unit of horizontal motion
vert num
smallest unit of vertical motion
unitwidth num
pointsize in which widths are specified
sizescale num
scaling for fractional pointsizes
paperwidth num
width of paper in basic increments
paperlength num
length of paper in basic increments
biggestfont num

maximum size of a font
list of pointsizes available on typesetter, terminated by 0
number of initial fonts followed by the names of
fonts num name ...
the fonts. For example:
fonts 4 RIB 5
chanet
this always comes last in the file and is on a line
by itself. Following it is the list of special character names for this device. Names are separated
by a space or a newline. The list can be as long
as necessary. Names not in this list are not
allowed in the font description files.
res is the basic resolution of the device in increments per inch. hor and vert
describe the relationships between motions in the horizontal and vertical
directions. If the device is capable of moving in single basic increments in
both directions, both hor and vert would have values of 1. If the vertical
motions only take place in multiples of two basic units while the horizontal
motions take place in the basic increments, then hor would be 1, while vert
sizes num num ...

REFERENCE MANUAL

FONT(S)

would be 2. unitwidth is the pointsize in which all width tables in the font
description files are given. troff automatically scales the widths from the
unitwidth size to the pointsize it is working with. sizescale is not currently
used and is 1. paperwidth is the width of the paper in basic increments. The
APS-5 is 6120 increments wide. paperlength is the length of a sheet of paper
in the basic increments. biggestfont is the maximum number of characters on
a font.
For each font supported by the phototypesetter, there is also an ASCII file
with the same name as the font (e.g., R, I, CW). The format for a font
description file is:
name of the font, such as R or CW
name name
intemalname name
special
ligatures name ... 0

spacewidth num
chanet

internal name of font
sets flag indicating that the font is special
Sets flag indicating font has ligatures. The list of
ligatures follows and is terminated by a zero.
Accepted ligatures are: ff fi fI ffi ffl.
specifies width of space if something other than
default (1/3 of an em) is desired.
The character set must come at the end. Each
line follOWing the word charset describes one
character in the font. Each line has one of two
formats:
name width kerning code
name
where name is either a single ASCII character or
a special character name from the list found in
DESC. The width is in basic increments. The
kerning information is 1 if the character descends below the line, 2 if it rises above the letter
'a', and 3 if it both rises and descends. The kerning information for special characters is not used
and so may be O. The code is the number sent to
the typesetter to produce the character. The
second format is used to show that the character
has more than one name. The double quote
shows that this name has the same values as the
preceding line. The kerning and code fields are
not used if the width field is a double quote
character. The total number of different characters in this list should not be greater than the
value of biggestfont in the DESC file (see above).

In the source version of DOCUMENTER'S WORKBENCH Software, troff and its
postprocessors read this information from binary files produced from the
ASCII files by makedev, a program distributed with troff source. For those
having a source license and need to know, a description of the format of these
files follows:

REFERENCE MANUAL

FONT(5)

The file DESC.out starts with the dev structure, defined by dev.h:
1*

dev.h: characteristics of a typesetter

struct dev {
unsigned short filesize;
short
short
short
short
short
short
short
short
short
short
short
short
short
};

res;
hor;
vert;
unitwidth;
nfonts;
nsizes;
sizescale;
paperwidth;
paperlength;
nchtab;
lchname;
biggestfont;
spare;

I . number of bytes in file, .1
I . excluding dev part .1
I . basic resolution in goobies/inch .1
I . goobies horizontally .1

I . size at which widths are given.1
I . number fonts physically available .1
I . number of pointsizes .1

I. scaling for fractional pointsizes .1
I . max line length in units .1
I. max paper length in units .1
I . number of funny names in chtab .1

I. length of chname table .1
I . max # of chars in a font .1

I. in case of expansion .1

filesize is just the size of everything in DESC.out excluding the dev structure.
nfonts is the number of different font positions available. nsizes is the number
of different pointsizes supported by this typesetter. nchtab is the number of
special character names. lchname is the total number of characters, including
nulls, needed to list all the special character names. At the end of the structure is one spare for later expansions.
Immediately following the dev structure are a number of tables. First is the
sizes table, which contains nsizes + 1 shorts(a null at the end), describing the
pointsizes of text available on this device. The second table is the
funny_char_index_table. It contains indices into the table that follows it, the
funny_char_strings. The indices point to the beginning of each special character name that is stored in the funny-,har_strings table. The funny-,har_strings
table is lchname characters long, while the funny_charjndex_table is nchtab
shorts long.
Following the dev structure will occur nfonts {font} .out files, which are used to
initialize the font positions. These {fontl.out files, which also exist as separate
files, begin with a font structure and then are followed by four character
arrays:
struct Font {
I . characteristics of a font .1
char nwfont;
/. number of width entries .1
char specfont;
/. 1 == special font .1
char ligfont;
I . 1 == ligatures exist on this font .1
char namefont[10]; I . name of this font, e.g., R .1
char intname[10]; /. internal name of font, in ASCII ./
} ;

REFERENCE MANUAL

FONT(S)

The font structure tells how many defined characters there are in the font,
whether the font is a "special" font and if it contains ligatures. It also has the
ASCII name of the font, which should match the name of the file it appears
in, and the internal name of the font on the typesetting device (intname). The
internal name is independent of the font position and name that troff knows
about. For example, you might say mount R in position 4, but when asking
the typesetter to actually produce a character from the R font, the postprocessor which instructs the typesetter would use intname.
The first three character arrays are specific for the font and run in parallel.
The first array, widths, contains the width of each character relative to
unitwidth. unitwidth is defined in DESC. The second array, kerning, contains
kerning information. If a character rises above the letter 'a', 02 is set. If it
descends below the line, 01 is set. The third array, codes, contains the code
that is sent to the typesetter to produce the character.
The fourth array is defined by the device description in DESC. It is the
font jndex_table. This table contains indices into the width, kerning, and code
tables for each character. The order that characters appear in these three
tables is arbitrary and changes from one font to the next. In order for troff to
be able to translate from ASCII and the special character names to these arbitrary tables, the fontjndex_table is created with an order that is constant for
each device. The number of entries in this table is 96 plus the number of special character names for this device. The value 96 is 128 - 32, the number of
printable characters in the ASCII alphabet. To determine whether a normal
ASCII character exists, troff takes the ASCII value of the character, subtracts
32, and looks in the font jndex_table. If it finds a 0, the character is not
defined in this font. If it finds anything else, that is the index into widths,
kerning, and codes that describe that character.
To look up a special character name, for example \(pl, the mathematical plus
sign, and determine whether it appears in a particular font or not, the following procedure is followed. A counter is set to 0 and an index to a special character name is picked out of the counter'th position in the funn,l,-charjndex_table.
A string comparison is performed between funny_char_strings {
funny-,har jndex_table { counter J J and the special character name, in our example pI, and if it matches, then troff refers to this character as ( 96 + counter).
When it wants to determine whether a specific font supports this character, it
looks in fontjndex_table{(96+counter)), (see below), to see whether there is a 0,
meaning the character does not appear in this font, or a number, which is the
index into the widths, kerning, and codes tables.
Notice that since a value of 0 in the font_index_table shows that a character
does not exist, the Oth element of the width, kerning, and codes arrays are not
used. For this reason the Oth element of the width array can be used for a special purpose, defining the width of a space for a font. Normally a space is
defined by troff to be 1/3 of the width of the \(em character, but if the Oth
element of the width array is non-zero, then that value is used for the width
of a space.
SEE ALSO

troff(1), troff(5).

REFERENCE MANUAL

FONT(S)

FILES

lusr/lib/font/devtty_typeIDESC.out description file for phototypesetter tty_type
lusr/libl£ont/devtty_typelfont.out

font description files for phototypesetter tty_type

REFERENCE MANUAL

CRAP(1)

NAME

grap - pic preprocessor for drawing graphs
SYNOPSIS

grap [-Ttty_type) [-1) [ - -

[fi1e(s))

OPTIONS

-T
-1

Specifies tty_type as grap's output device. Currently supported
devices are aps (Autologic APS-S) and ditO (Imagen Imprint
10). -Taps is default.
Stops grap from looking for a library file of macro defines,
lusr/lib/dwb/grap.defines.

DESCRIPTION

grap is a language for typesetting graphs. It is also the name of a preprocessor that feeds input to pic(l). Thus, a typical command line would appear as
follows:
grap fi1e(s)

I pic I troff I typesetter

Graphs are surrounded by the troff "commands" .Gt and .G2. Data that is
enclosed is scaled and plotted, with tick marks supplied automatically. Commands exist to modify the frame, add labels, override the default ticks, change
the plotting style, define coordinate ranges and transformations, and include
data from files. In addition, grap provides the same loops, conditionals and
macro processing that pic does.
FILES

lusr/lib/dwb/grap.defines: definitions of standard plotting characters, e.g.,
bullet.
SEE ALSO

pic(l ).

REFERENCE MANUAL

HYPHEN(1)

NAME

hyphen - find hyphenated words
SYNOPSIS

hyphen [fi'e(s)]
DESCRIPTION

hyphen finds all the hyphenated words ending lines in fi1e(5) and prints them
on the standard output. If no arguments are given or if hyphen encounters
-, it uses the standard input. Thus, hyphen may be used as a filter.
EXAMPLE

You would use the following command-line to proofread nroff's hyphenation
in fi'e(s):
mm mm_option(s) file (5)

I hyphen

SEE ALSO

mm(l), troff(l).
BUGS

hyphen can't cope with hyphenated italic (or underlined words); it frequently
will either miss them altogether or mishandle them. hyphen occasionally
gets confused but with no ill effects other than spurious extra output.

REFERENCE MANUAL

MACREF(l)

NAME

macref - produces cross-reference listing of macro files
SYNOPSIS

macref [-t} [-5} [-n} [ - - } file(s)
DESCRIPTION

macref reads the named file(s) (which are assumed to be nroff(l) or troff(l)
input) and produces a cross-reference listing of the symbols in the input.
A -t on the command line causes a macro table of contents to be printed.
The option -5 causes symbol-use statistics to be printed. The option -n
causes one line to be printed for each reference to a symbol. The options may
be grouped behind one -. You may use ,,__" to delimit the end of options.
macref does not accept - as standard input.
The default output is a list of the symbols found in the input, each accompanied by a list of all references to that symbol. macref lists the symbols
alphabetically in the leftmost column, with the references folloWing to the
right. Each reference is given in the form:

[ [(NMnarne)} Mnarne-} type Inurn [#}
where the fields have the following meanings:

Mnarne

the name of the macro within which the reference occurs. This field
is missing if the reference occurs outside a macro. Any names listed
in the NMnarne part are macros within which Mname is defined.

type

the type associated, by context, with this occurrence of the symbol.
The types may be:
request
r
m
macro
d
diversion
s
string
n
number register
parameter (e.g., \$x is a parameter reference to x. Note that
p
parameters are never modified, and that the only valid parameter symbol names are 1, 2, ... 9).

Inurn

the line number on which the reference occurred.

this reference modifies the value of the symbol.

Generated names are listed under the artificial symbol name

sym".

SEE ALSO

nroff(l), troff(l), mm(!), mm(S), mv(S), mmt(l), mvt(l), and maneS).

REFERENCE MANUAL

MAN(S)

NAME

man - macros for formatting entries in this manual
SYNOPSIS

nroff -man file (5)
troff -man [ -rsl ] file(s)
DESCRIPTION

These nroff/troff macros are used to layout the format of the entries of this
manual. The default page size is 8.5"xll", with a 6.5"xlO" text area; the -rsl
option reduces these dimensions to 6"x9" and 4.75"x8.375", respectively; this
option also reduces the default type size from lO-point to 9-point, and the
vertical line spacing from l2-point to lO-point. The -rV2 option may be used
to set certain parameters to values appropriate for certain Versatec printers: it
sets the line length to 82 characters, the page length to 84 lines, and it inhibits underlining.
Any text argument below may be one to six "words." Double quotes (WW) may
be used to include blanks in a "word." If text is empty, the special treatment
is applied to the next line that contains text to be printed. For example, .1
may be used to italicize a whole line, or .SM followed by .B to make small
bold text. By default, hyphenation is turned off for nroff(l), but remains on
for troff(l).
Type font and size are reset to default values before each paragraph and after
processing font- and size-setting macros, for example, .I, .RB, .SM. Tab stops
are neither used nor set by any macro except .DT and .TH.
Default units for indents in are ens. When in is omitted, the previous indent
is used. This remembered indent is set to its default value (7.2 ens in troff(l),
5 ens in nroff(l» by .TH, .P, and .RS, and restored by.RE.
•TH t

sen Set the title and entry heading;

•SH text
•S5 text
•B

text

•1 text
.5M text

.RI a b

t is the title, s is the section
number, c is extra commentary, e.g., "local·, n is new manual
name. Invokes .DT (see below).
Place subhead text, for example, SYNOPSIS, here.
Place sub-subhead text, for example, Options, here.
Make text bold.
Make text italic.
Make text 1 point smaller than default point size.
Concatenate roman a with italic b, and alternate these two fonts
for up to six arguments. Similar macros alternate between any
two of roman, italic, and bold:

.IR .RB .BR .IB .BI

.P
.HP in
.TP in

.IP t in

Begin a paragraph with normal font, point size, and indent.. PP is
a synonym for the mm(5) macro .P.
Begin paragraph with hanging indent.
Begin indented paragraph with hanging tag. The next line that
contains text to be printed is taken as the tag. If the tag does not
fit, it is printed on a separate line.
Same as .TP in with tag t; often used to get an indented paragraph
without a tag.

REFERENCE MANUAL

MAN(S)

.RS in

Increase relative indent (initially zero). Indent all output an extra
in units from the current left margin.

.RE k

Return to the kth relative indent level (initially, k-l; k-O is
equivalent to k-l); if k is omitted, return to the most recent lower
indent level.
•PMm
Produces proprietary markings see REFERENCE to mm(l) below.
.OT
Restore default tab settings (every 7.2 ens in troff(l), 5 ens in
nroff(l».
.PO v
Set the interparagraph distance to v vertical spaces. If v is omitted, set the interparagraph distance to the default value (O.4v in
troff(l), Iv in nroff(l».
The following strings are defined:
\-R
G!) in troff(l), (Reg.) in nroff.
\-S
Change to default type size.
\-(Tm
Trademark indicator.
The following number registers are given default values by .TH:
IN
Left margin indent relative to subheads (default is 7.2 ens in
troff(1),5 ens in nroff(l»).
LL
Line length including IN.
PO
Current interparagraph distance.

EXAMPLES

The man macros are provided to process manual pages already on-line at a
given location and to enable users to make their own manual pages. The
preceding section demonstrated the usage of the macros themselves; the followi~g section provides examples of command lines typically used to process
the completed files.
man macros are designed to run with either nroff or troff. The first command line will process file(s) using only macros and nroff requests:
nroff -Tip -man fi'e(s) lip

File(s) is piped to the local line printer, Ip.
The next command line will process fi'e(s) containing tables as well as macros
and nroff requests:
tbl file(s)

I nroff -Tip -man I col I Ip

Notice that before it is sent to the line printer, the output is first filtered
through col, to process the reverse line feeds used by tbl.
The final example is a command line that processes an unusual manual page,
one using pic and grap. If the manual pages created with man are intended
for an on-line facility, components requiring troff, such as grap or pic, should
be avoided since the average installation of terminals will not be able to process typeset documents.
grap fi'e(s)

REFERENCE MANUAL

I pic I tbl I troff -Taps -man I typesetter

MAN(S)

grap precedes pic: because it is a preprocessor to pic; the reverse order will not
format correctly. File(s) contains one or more tables, requiring tbl, but col is
no longer necessary because typeset documents do not use reverse line feeds
with which to make tables. The -T option for specifying the output device
(Terminal type) takes the argument aps here, readying the document for processing on the APS-S phototypesetter.
SEE ALSO

eqn(l), mane1), neqn(l), nroff(1), tbl(l), tc(l), troff(1).
The "mm: Technical Discussion"
FILES

I usr I lib I tmac I tmac.an
I usr I lib I macros I an
I usr I man I [uapLman I manO I skeleton
CAVEATS

Special macros, strings, and number registers exist, internal to man, in addition to those mentioned above. Except for names predefined by troff(l) and
number registers d, m, and y, all such internal names are of the form XA,
where X is one of ), 1 and 1, and A stands for any alphanumeric character.
User defined macros should avoid these naming conventions.
The programs that prepare the Table of Contents and the Permuted Index for
this manual assume the NAME section of each entry consists of a single line of
input that has the following format:

name \- explanatory text
The macro package increases the inter-word spaces (to eliminate ambiguity) in
the SYNOPSIS section of each entry.
The macro package itself uses only the roman font (so that one can replace,
for example, the bold font by the constant-width font (CW). Of course, if the
input text of an entry contains requests for other fonts (for example, .1, .RB,
\fI), the corresponding fonts must be mounted.
BUGS

If the argument to .TH contains any blanks and is not enclosed by double
quotes (--), there will be strange irregular dots on the output.

REFERENCE MANUAL

MM(1)

NAME

mm - prints documents formatted with the mm macros
SYNOPSIS

mm [ option(s) ] [ file(s) ]
DESCRIPTION

Use mm to format documents using nroff and the mm text-formatting macro
package. mm has options to specify preprocessing by tbl(l) and/or neqn(l),
and postprocessing by various terminal-oriented output filters. The proper
pipelines and the required arguments and flags for nroff and mm are generated, depending on the options that you select.
Options for mm are given below. Any other arguments or flags (e.g., -rC3)
are passed to nroff as appropriate. You may use such options in any order,
but you must put them before the fi'e(s) arguments. If you do not specify
arguments, mm prints a list of its options.

-Ttty_type
specifies the type of output terminal.
Here is a list of recognized values for tty_type.

2631
2631-c
2631-e
300

300-12
3008

3005-12

37
382
4000a
450
450-12
832
8510
tn300
X

Hewlett-Packard 2631 printer in regular mode
Hewlett-Packard 2631 printer in compressed mode
Hewlett-Packard 2631 printer in expanded mode
DASI-300 printer
DASI-300 terminal set to 12-pitch (12 characters per
inch)
DASI-300s printer (3005 is a synonym)
DASI-300s printer set to 12-pitch (l2 characters per
inch) (3005-12 is a synonym)
Teletype Model 37 terminal
DTC-382
Trendata 4000a terminal (4000A is a synonym)
DASI-450 (Diablo Hyterm) printer
DASI-450 terminal set to 12-pitch (12 characters per
inch)
Anderson Jacobson 832 terminal
C.ITOH printer
GE Terminet 300 terminal
printers equipped with TX print train
generic name for printers that can underline and
tab.lp is the default device for mm.All text sent to Ip
requiring reverse linefeeds, such as those having
tables,must be processed with col, invoked with mm's
-c option. Ifyou do not use this option, mm uses the
value of the shellvariable STERM from the environment (see profile(4) and environ(S» as the value of
tty_typeif STERM is set; otherwise, mm uses 450 as thevalue of tty_type. If you specify several terminal
types,the last one takes precedence.

REFERENCE MANUAL

MM(l)

(Check with your system administrator for a list of locally supported devices.)
-12
indicates that the document is to be produced in 12-pitch. You may
use this op~ion when $TERM is set to one of 300, 300s, and 450.
(You must' manually set the pitch switch on the DASI 300 and 300s
terminals to 12 ~f you use this option.)
-c
causes mm to invoke col(1); note that col(l) is invoked automatically
by mm unless tty_type is one of 300, 300s, 450, 37, 4000a, 382, and X.
-e
causes mm to invoke neqn; also causes neqn to read the
lusr/pub/eqnchar file (see eqnchar(S».
-t
causes mm to invoke tbl(1).
-E
invokes the -e'option of nro~.
As an example, assume that the shell variable $TERM is set in the environment to 450. The two command lines below are then equivalent:
mm -t -rC3 -12 fUels)
tbl fUels) I nroff -mm -T4S0-12 -h -rC3
mm reads the standard input when you specify - instead of any file(s). (Mentioning other files together with - leads to undesired results.) This option
allows you to use mm as a filter, for example:
cat file (s) I mm HINTS

mm invokes nroff with the -h flag. With this flag, nroft assumes that
the terminal has tabs set every 8 character positions.
Use the -oUst option of nroft to specify ranges of pages to be output.
Note, however, that if you invoke mm with one or more of the -e,
-t, and - options, together with the -oUst option of nroff, you may
cause a harmless "broken pipe" diagnostic if you do not specify the
last page of the document in list.
If you use the -s option of nroff (to stop between pages of output),
use line-feed (rather than return or new-line) to restart the output.
The ;"'8 option of nroff does not work with the -c option of mm, or if
mm automatically invokes col(1) (see -c option above).
If you lie to mm about the kind of terminal its output will be printed
on, you will get (often subtle) garbage; however~ if you are redirecting
output into a file, use the - T37 option, and then use the appropriate
terminal'~1ter when you actually print that file.

FILES

/usr/pub/terminals list of supported terminals

REFERENCE MANUAL

MM(l)

SEE ALSO

checkmm(l), col(l), env(l), eqn(l), greek(l), mmt(l), mvt(l), neqn(l),
nroff(l), tbl(l), profile(4), mm(S), and term(S).
The "mm: Technical Discussion"
"The Macro Package mm" in the User's Guide.

REFERENCE MANUAL

MM(S)

NAME

mm - the mm macro package for formatting documents
SYNOPSIS
mm [option( 5) 1 [file( 5) 1
nroff [option( 5) 1 -mm [file(5) 1
mmt [option(s) 1 [fi'e(s) 1
troff [option( 5)] -mm [file(s) ]
DESCRIPTION

This package provides a formatting capability for a very wide variety of documents. The manner in which you type and edit a document is essentially
independent of whether the document is to be eventually formatted at a terminal or is to be phototypeset.
FILES

I usr I lib I tmac I tmac.m
I usrllib I macros I mm[nt]

pointer to the mm package
the mm package

SEE ALSO
mm(l), mmt(l), nroff(l), and troff(l).

".om: Technical Discussion."
"The Macro Package mm" in the User's Guide.

REFERENCE MANUAL

MMT(l)

MMT(l)
NAME

mmt - typeset documents
SYNOPSIS

mmt [ option(s) ] [ file(s) ]
DESCRIPTION

This command is similar to mm(l), except that it typesets its input via troff(l),
as opposed to formatting it via nroff(l); mmt uses the mm macro package.
There are options to specify preprocessing by tbl(l) and/or pic(l) and/or
eqn(l) and/or grap(l). The proper pipelines and the required arguments and
flags for troff( l) and for the macro package are generated, depending on the
options selected.
Option(s) specific to mmt are given below. Any other arguments or flags (e.g.,
-rC3) that you give mmt are passed to troff(l). You can put options in any
order, but they must appear before any file(s). If you give no arguments or
files, mmt prints a list of its options.
-e
invokes eqn(I); also causes eqn to read the
lusr/pub/eqnchar file (see eqnchar(5».
invokes tbl(l).
-t
invokes pic(l).
-p
invokes grap(I), which in turn calls pic(l).
-g
-Ttty_type
creates output for troff device tty_type (see troff(l». The
output is sent through the appropriate postprOCessor (see
daps(I».
-Odest
directs the output to device dest. Supported values for
dest are: 4014 (TEKTRONIX 4014 terminal via the tc(l)
filter); and i10 (Imagen Imprint-IO laser printer via
dilO(l) filter.
.
-z
invokes no output filter to process or redirect the output
of troff(l).
mmt reads the standard input when you specify - instead of any files.
HINT

Use the -olist option of troff(l) to specify ranges of pages to be output. Note,
however, that if you call mmt with one or more of the -e, -t, -p, -g, and options together with the -olist option of troff(I), you may cause a harmless
"broken pipe" diagnostic if the last page of the document is not specified in
list.
SEE ALSO

daps(l), di10(l), eqn(l), grap(l), mm(l), mvt(l), pic(l), tbl(l), tc(l), troff(l),
eqnchar(5), mm(5).

REFERENCE MANUAL

MPTX(S)

NAME

mptx - the macro package for formatting a permuted index
SYNOPSIS

nroff -mptx (option(s)] fi'e(s) I printer
troff -mptx (option(s) I fi'e(s) I typesetter

DESCRIPTION

This package provides a definition for the .xx macro used for formatting a permuted index as produced by ptx(l). This package does not provide any other
formatting capabilities such as headers and footers. If these or other capabilities are required, the mptx macro package may be used in conjuction with the
mm macro package. In this case, the -mptx option must be invoked after the
-mm call. For example,
nroff -mm -mptx fi'e(s) I printer
or
mmt -mptx file (s) I typesetter
FILES

/ usr/lib / tmac / tmac. ptx
/usr/lib/macros/ptx·

pointer to the macro package
macro package

SEE ALSO

mm(l), nroff(l), ptx(l), troff(l), mm(S).

REFERENCE MANUAL

MV(S)

NAME

mv - a troff macro package for typesetting view graphs and slides
SYNOPSIS

mvt [-a] [option( 5)] [file{5) ]
troff [-a] [-rXt] -mv [option(5)]

[fi'e(s)]

DESCRIPTION

This package makes it easy to typeset view graphs and projection slides in a
variety of sizes. A few macros (briefly described below) accomplish most of
the formatting tasks needed in making transparencies. All of the facilities of
troff(l), eqn(l), tbl(I), pic(l), and grap(l) are available for more difficult tasks.
The output can be previewed on most terminals, and, in particular, on the
TEKTRONIX 4014. For this device, specify the -rXt option (this option is
automatically specified by the mvt command when that command is invoked
with the -D40t4 option). To preview output on other terminals, specify the
-a option.
The available macros are:
Foil-start macro; foil size is to be 7" X7"; n is the foil
.VS [n] [I] [d]
number, i is the foil identification, d is the date; the foilstart macro resets all parameters (indent, point size, etc.) to
initial default values, except for the values of i and d arguments inherited from a previous foil-start macro; it also
invokes the .A macro (see below).
The naming convention for this and the follOWing eight
macros is that the first character of the name (V or S) distinguishes between view graphs and slides, respectively, while
the second character indicates whether the foil is square (S),
small wide (w), small high (h), big wide (W), or big high
(H). Slides are "skinnier" than the corresponding view
graphs: the ratio of the longer dimension to the shorter one
is larger for slides than for view graphs. As a result, slide
foils can be used for view graphs, but not vice versa; on the
other hand, view graphs can accommodate a bit more text.
•Vw [n] [I]
[I]
[I]
[I]
[I]
[I]
•SW [n] [I]
.SH [n] [I]
.A [x]

.Vh [n]
.VW [n]
.VH [n]
.Sw [n]
.Sh [n]

[d]
[d]
[d)
[d]
[d)
[d]
[d]
[d]

[m [5] ]

Same as .VS, except that foil size is 7" wide x 5" high.
Same as .VS, except that foil size is 5"x7".
Same as .VS, except that foil size is 7"x5.4".
Same as .VS, except that foil size is 7" x9".
Same as .VS, except that foil size is 7"x5".
Same as .VS, except that foil size is 5" x7".
Same as .VS, except that foil size is 7"x5.4".
Same as .VS, except that foil size is 7"x9".
Place text that follows at the first indentation level (left
margin); the presence of x suppresses the ~ line spacing
from the preceding text.
Place text that follows at the second indentation level; text
is preceded by a mark; m is the mark (default is a large bullet); 5 is the increment or decrement to the point size of the

REFERENCE MANUAL

MV(5)

mark with respect to the prevailing point size (default is 0);
if s is 100, it causes the point size of the mark to be the
same as that of the default mark.
.C [m [s] ]
Same as .B, but for the third indentation level; default mark
is a dash.
Same as .B, but for the fourth indentation level; default
•0 [m [s] ]
mark is a small bullet.
.T string
String is printed as an over-size, centered title.
•1 [in] [a [x] ] Change the current text indent (does not affect titles); in is
the indent (in inches unless dimensioned, default is 0); if in
is signed, it is an increment or decrement; the presence of a
invokes the .A macro (see below) and passes x (if any) to it.
.5 [P] [I]
Set the point size and line length; p is the point size
(default is "previous"); if p is 100, the point size reverts to
the initial default for the current foil-start macro; if p is
signed, it is an increment or decrement (default is 18 for
.VS, .VH, and .51:1, and 14 for the other foil-start macros); I
is the line length (in inches unless dimensioned; default is
4.2" for .Vh, 3.8" for .Sh, 5" for .SH, and 6" for the other
foil-start macros).
.OF n f [n I ...] Define font positions; may not appear within a foil's input
text (Le., it may only appear after all the input text for a
foil, but before the next foil-start macro); n is the position of
font I; up to four "n f" pairs may be specified; the first font
named becomes the prevailing font; the initial setting is (H is
a synonym for G):
.OF 1 H 2 I 3 B 4 5
.OV [a] [b] [c) [d] Alter the vertical spacing between indentation levels; a is
the spacing for .A, b is for .B, c is for .C, and d is for .0; all
non-null arguments must be dimensioned; null arguments
leave the corresponding spacing unaffected; initial setting is:
.OV .5v .5v .Sv Ov
.U strl [str2]
Underline strl and concatenate str2 (if any) to it.
The last four macros in the above list do not cause a break; the .1 macro causes
a break only if it is invoked with more than one argument; all the other macros cause a break.
The macro package also recognizes the following upper-case synonyms for the
corresponding lower-case troff requests:
.AD .BR .CE .FI .HY .NA .NF .NH .NX .50 .SP .TA .TI
The Tm string produces the trademark symbol.
See the reference cited below for further details.
FILES

/ usr/ lib / tmac / tmac.v
/ usr/ lib / macros/ vmca

REFERENCE MANUAL

MV(5)

SEE ALSO

eqn(l), grap(l), mvt(l), pic(l), tbl(l), troff(l).
"The Macro Package mv" in the User's Guide.

Bues
The .VW and .SW foils are meant to be 9" wide by 7" high, but because the
typesetter paper is generally only 8" wide, they are printed 7" wide by 5.4"
high and have to be enlarged by a factor of 9/7 before use as view graphs; this
makes them less than totally useful.

REFERENCE MANUAL

MVT(l)

NAME

mvt - typeset view graphs and slides
SYNOPSIS

mvt [ option(s) ) [ file(s) )
DESCRIPTION

This command is similar to mmt(l), except that it typesets its input with the
mv macro package for view graphs and slides. mvt has options to specify
preprocessing by tbl(l) and/or pic(l) and/or eqn(l) and/or. grap(l). The
proper pipelines and the required arguments and flags for troff(l) and for the
macro package are generated, depending on the options selected.
Option(s) specific to mvt are given below. Any other arguments or flags that
you give mvt are passed to troff(l). Options can occur in any order, but they
must appear before any file(s). If you give no arguments or filets), mvt prints
a list of its options.
-e
invokes eqn(l); also causes eqn to read the
lusr/pub/eqnchar file (see eqnchar(S».
-t
invokes tbl(l).
invokes pic( 1).
-p
invokes grap(l), which in turn calls pic(l).
-g
creates output for troff device tty_type (see troff(l». The
-TttyJype
output is sent through the appropriate postprocessor (see
daps(l».
-Odest
directs the output to device dest. Supported values for
dest are: 4014 (TEKTRONIX 4014 terminal via the tc(1)
filter); and itO (Imagen Imprint-lO laser printer via
ditO(l) filter.)
invokes no output filter to process or redirect the output
-z
of troff( 1).
mvt reads the standard input when you specify - instead of any filets).
HINT

Use the -olist option of troff(l) to specify ranges of pages to be output. Note,
however, that if you invoke mvt with one or more of the -e, -t, -p, -g, and
- options together with the -olist option of troff(l), you may cause a harmless "broken pipe" diagnostic if the you do not specify the last page of the
document in list.
SEE ALSO

daps(l), di10(l), eqn(l), grap(l), mmt(l), pic(l), tbl(l), tc(l), troff(l),
eqnchar(5), mv(5).

REFERENCE MANUAL

NDX(1)

NDX(l)

NAME

ndx - create a subject-page index for a document
SYNOPSIS

ndx [subjfile] "formatter command line"
DESCRIPTION

ndx, given a list of subjects (subjfile), searches a specified document and writes
a subject-page index to the standard output.
subjfile is the list of subjects to be included in the index. Each subject must
begin on a new line and have the following format:
wordl [word2 ...] [, wordk ... J
For example,
printed circuit boards
arrays
arrays, dynamic storage
Smith, W. P.
printed circuit boards, channel-oriented multi-layer
Aranoff
University of Illinois
PL/l
The subject must start in column 1.
The syntax for the formatter command line is

formatter [option(s)] file(s)
It is the command that will be used to create the final form of the document.
The following are examples of valid formatter command lines:
mm -TIp file(s)
oroff -mm -TIp -rW60 file(s)
troff -r82 -Taps -rOl.Si fi'e(s)
For more information on the formatter command line, see, mm(l), mmt(l),
nroff(1) and troff(l).
The document must include formatting commands for mm, nroff, or troff.
The formatter command line tells ndx whether troff, nroff, mm or mmt
would be used to produce the final version of the document.
troll or mmt
specifies troff as the formatting program.
nroff or mm
specifies nroff as the formatting program
The option(s) are those that would be given to the troff, nroff, mm or
mmt command in printing the final form of the document, and are
necessary to determine the correct page numbers for subjects as they

REFERENCE MANUAL

NDX(l)

are located in the document. ndx does not actually cause the final
version of the document to be printed. The author must create the
document separately. The indexer, of course, should not be used until
the document is complete and no further changes are expected.
EXAMPLES

The command
ndx subjfile "nroff -mm -rW70 fi'els)"

> indexfile

would produce a subject-page index for the document fi'ifs) and take its subjects from the list, subjfile. The page numbers would correspond to the document produced by
nroff -mm -rW10 filel s)
The command
ndx 5ubifi'e "mm -rW60 -rN2 -rOO cht ch2 ch3"

> i1ldexfile

would produce a subject-page index for the documents ch 1, ch2, and ch3. The
page numbers would correspond to the documents produced by
mm -rW60 -rN2 -rOo chI ch2 ch3
The command
ndx subifi'e "troff -rB2 -rWSi -rOt.Si -mm file(s)"

> i1ldexfile

would produce a subject-page index for the document filc(sJ, and the page
numbers would correspond to the document produced by
troff -rB2 -rWSi -rOl.Si -mm file( s)
SEE ALSO

mm(l), mmt(1), nroff(l), subj(l), troff(l).

REFERENCE MANUAL

NEQN(l)

NEQN(1)

NAME

neqn - format mathematical text for nroff
SYNOPSIS

neqn [ -d xx ] [ -p n ] [ -s n ] [ -f n ] [ - - ] [ file (s) ]
DESCRIPTION

neqn is a preprocessor for formatting mathematical text with nroff on
typewriter-like terminals. Normal usage is:
neqn [option(s)] file(s) I nroff [option(s)] I [printer]
If you do not specify files (or if you specify - as the last argument), neqn
reads the standard input.
SEE ALSO

eqn(l), mm(l), nroff(l), tbl(l), eqnchar(S), and mm(5).
"The Preprocessor eqn- in the User's Guide.

REFERENCE MANUAL

NROFF(l)

NAME

nroff - text formatting language
SYNOPSIS

nroff [option(s)]

[fi1e(s)]

printer

DESCRIPTION

nroff formats text contained in fi1e(s) (standard input by default) for printing
on typewriter-like devices and line printers.
An argument consisting of a minus (-) is taken to be a file name corresponding to the standard input. The option(s), which may appear in any order, but
must appear before the fi1e(s), are,

-oUst

Print only pages whose page numbers appear in the list of numbers
and ranges, separated by commas. A range N-M means pages N
through M; an i::itial -N means from the beginning to page N; and
a final N- means from N to the end. (5ee BUGS below.)
-nN
Number first generated page N.
Stop every N pages. nroff will halt after every N pages (default
-5N
Nr::::al) to allow paper loading or changing, and will resume upon
receipt of a line-feed or new-line (new-lines do not work in pipelines, e.g., with mm(I». This option does not work if the output of
nroff is piped through col(I). When nroff halts between pages, an
ASCII BEL is sent to the terminal.
-raN
Set register a (which must have a one-character name) to N.
-i
Read standard input after fi'e(s) are exhausted.
-q
Invoke the simultaneous input-output mode of the .rd request.
-z
Print only messages generated by .tm (terminal message) requests.
-mname Prepend to the input fi1e(s) the macro file lusr/lib/tmac/tmac.name.

-Ttty_type
Prepare output for specified terminal. Known tty_type(s) are

2631
2631-c
2631-e
300
300-12
3005
3005-12
37

382
4000a
450
450-12
832
8510
Ip

Hewlett-Packard 2631 printer in regular mode
Hewlett-Packard 2631 printer in compressed mode
Hewlett-Packard 2631 printer in expanded mode
DASI·300 printer
DASI·300 terminal set to 12-pitch
(12 characters per inch)
DASI·300s printer (3005 is a synonym)
DASI·300s printer set to 12-pitch
(12 characters per inch)
(3005-12 is a synonym)
Teletype Model 37 terminal (default)
DTC-382
Trendata 4000a terminal (4000A is a synonym)
DASI-450 (Diablo Hyterm) printer
DASI·450 terminal set to 12-pitch
(12 characters per inch)
Anderson Jacobson 832 terminal
C.ITOH printer
generic name for printers that can

REFERENCE MANUAL

NROFF(l)

t0300
X

-e
-h
-un

underline and tab (All text using reverse
line feeds, such as those having tables,
that is sent to Ip must be processed
with col.)
GE Terminet 300 terminal
printers equipped with TX print train

Produce equally-spaced words in adjusted lines, using the full resolution of the particular terminal.
Use output tabs dUring horizontal spacing to speed output and
reduce output character count. Tab settings are assumed to be every
8 nominal character widths.
Set the emboldening factor (number of character overstrikes) for the
third font position (bold) to n, or to zero if n is missing.

FILES

lusrllibI tmacltmac.- pointers to standard macro files
lusr/lib/macros/-

I usr I lib I olerm II usrIpub I terminals

standard macro files
terminal driving tables for nroff
list of supported terminals

SEE ALSO

col(1), neqn(l), greek(1), mm(1), mm(S), tbl(l).
The "nroff/troff: Technical Discussion."
-rhe Formatter nroff- in the User's Guide.

BUGS
nroff believes in Eastern Standard Time; as a result, depending on the time of
the year and on your local time zone, the date that nroff generates may be off
by one day from your idea of what the date is.
When nroff is used with the -olist option inside a pipeline (e.g., with one or
more of eqn(l), and tbl(l», it may cause a harmless ~roken pipe" diagnostic if
the last page of the document is not specified in list.

REFERENCE MANUAL

NTERM(5)

NAME

nterm - terminal driving tables for nroff
DESCRIPTION

nroff(l) uses driving tables to customize its output for various types of output
devices, such as printing terminals, special word-processing terminals (such as
Diablo, Qume, or NEC Spinwriter mechanisms), or special output filter programs. These driving tables are written as ASCII files, and are installed in
lusr/lib/nterm/tab.name, where name is the name for that terminal type as
given in term(S).
The first line of a driving table should contain the name of the terminal: simply a string with no embedded white space. "White space" means any combination of spaces, tabs and new-lines. The next part of the driver table is
structured as follows:
bset [integer] (not supported in all versions of nroff)
breset [integer] (not supported in all versions of nroff)
Hor [integer]
Vert [integer]
Newline [integer]
Char [integer]
Em [integer]
Halfline [integer]
Adj [integer]
twinit [character string]
twrest [character string]
twnl [character string]
hlr [character string]
hlf [character string]
fir [character string]
bdon [character string]
bdoff [character string]
iton [character string]
itoff [character string]
ploton [character string]
plotoff [character string]
up [character string]
down [character string]
right [character string]
left [character string]
The meanings of these fields are as follows:
~set
bits to set in the c_oflag field of the termio structure before output.
breset
bits to reset in the c_oflag field of the termio structure before output.
horizontal resolution in units of 1/240 of an inch.
Hor
vertical resolution in units of 1/240 of an inch.
Vert
Newline space moved by a newline (linefeed) character in units of 1/240 of
an inch.

REFERENCE MANUAL

NTERM(S)

Char

quantum of character sizes, in units of 1/240 of an inch. (i.e., a
character is a multiple of Char units wide)

size of an em in units of 1/240 of an inch.
Em
Halfline space moved by a half-linefeed (or half-reverse-linefeed) character
in units in 1/240 of an inch.
quantum of white space, in 1/240 of an inch. (i.e., white spaces are
Adj
a multiple of Adj units wide)
Note: if this is less than the size of the space character, nrolf will
output fractional spaces using plot mode. Also, if the -e switch to
"roff is used, Adj is set equal to Hor by nroff.
twinit
sequence of characters used to initialize the terminal in a mode
suitable for nroff.
twrest
sequence of characters used to restore the terminal to normal mode.
twnl
sequence of characters used to move down one line.
sequence of characters used to move up one-half line.
hlr
hlf
sequence of characters used to move down one-half line.
fir
sequence of characters used to move up one line.
bdon
sequence of characters used to turn on hardware boldface mode, if
any.
bdoff
sequence of characters used to turn off hardware boldface mode, if
any.
iton
sequence of characters used to turn on hardware italics mode, if
any.
sequence of characters used to turn off hardware italics mode, if
itoff
any.
ploton
sequence of characters used to turn on hardware plot mode (for
Diablo type mechanisms), if any.
plotoff

sequence of characters used to turn off hardware plot mode (for
Diablo type mechanisms), if any.

sequence of characters used to move up one resolution unit (Vert)
in plot mode, if any.

down

sequence of characters used to move down one resolution unit
(Vert) in plot mode, if any.

right

sequence of characters used to move right one resolution unit (Hor)
in plot mode, if any.

left

sequence of characters used to move left one resolution unit (Hor)
in plot mode, if any.
This part of the driving table is fixed format, and you cannot change the order
of entries. You should put entries on separate lines, and these lines should
contain exactly two fields (no comments allowed) separated by white space.
For example,

REFERENCE MANUAL

NTERM(S)

bset
0
breset 0
Hor
24
and so on.
Follow this first part of the driving table with a line containing the word
"charset," and then specify a table of special characters that you want to
include. That is, specify all the non-ASCII characters that nroff(l) knows by
two character names, such as \(hy. If nroff does not find the word "charset"
where it expects to, it will abort with an error message.
Each definition in the part after "charset" occupies one line, and has the following format:
chname width output
where "chname" is the (two letter) name of the special character, "width" is
its width in ems, and "output" is the string of characters and escape sequences
to send to the terminal to produce the special character.
If any field in the "charset" part of the driving table does not pertain to the
output device, you may give that particular sequence as a null string, or leave
out the entry. Special characters that do not have a definition if) this file are
ignored on output by nroff( 1).
You may put the "charset" definitions in any order, so it is possible to speed
up nroff by putting the most used characters first. For example,
charset
em 1hy 1 \- 1 bu 1 +\bo
and so on.
The best way to create a terminal table for a new device is to take an existing
terminal table and edit it to suit your needs. Once you create such a file, put
it in the directory /usr/lib/nterm, and give it the name tab.xyz where xyz is
the name of the terminal and the name that you pass nroff via the -T option
(for example, nroff -Txyz).
FILES

/usr/lib/nterm/tab.name

terminal files

SEE ALSO

nroff(1).

REFERENCE MANUAL

PIC(l)

NAME

pic - troff preprocessor for drawing pictures
SYNOPSIS

pic [-Ttty_type] [--] [fi1e(s)]
DESCRIPTION

pic is a troff(1) preprocessor for draWing simple figures on a typesetter. The
basic objects are box, circle, ellipse, line, spline, arrow, arc and text.
The optional argument -Ttty_type specifies device tty_type; currently supported devices are aps (Autologic APS-5) and itO (Imagen Imprint-tO).
Default is -Taps.
SEE ALSO

grap(1), troff( 1).

REFERENCE MANUAL

PTX(l)

NAME

ptx - make permuted index
SYNOPSIS

ptx

[option(s)]

[input [output] ]

DESCRTPTION

ptx generates the file output that can be processed with a text formatter (nroff
or troff) to produce a permuted index of file inp/lt. Standard input (-) and
standard output are default. It has three phases: the first does the permutation, generating one line for each keyword in an input line. The keyword is
rotated to the front. The permuted file is then sorted. Finally, the sorted
lines are rotated, so the ke}'word comes at the middle of each line. ptx output
is in the following form:
.xx .." "before keyword" "kt'ywllrd" "after keyword"
where .xx is assumed to be an nroff(l) or troff(l) macro provided by the user
or provided by ptx(l). The -mptx macro package provides the .xx macro
definition. The before keyword and aftt'r k£'yl('ord fields incorporate as much of
the line as will fit around the k£'yword when it is printed. The first field and
last field, at least one of which is always the empty string, are wrappedaround to fit in the unused space at the opposite end of the line.
The following option(s) can be applied:

-f
-t
-w n

-g n

-0

Fold upper- and lower-case letters for sorting.
Prepare the output for the phototypesetter.
Use the next argument, II, as the length of the output line.
The default line length is 72 characters for nroff and 100 for
troff.
Use the next argument, n, as the number of characters that pix
will reserve in its calculations for each gap among the four
parts of the line as finally printed. The default gap is 3.

only

Use as keywords any words given in the only file.
-i ignore
Do not use as keywords any words given the ignore file. If the
-i and -0 options are missing, use lusr/lib/eign as the ignore
file.
-b break
Use the characters in the break file to separate words. Tab,
new-line, and space characters are always used as break characters.
-r
Take any leading non-blank characters of each input line to be
a reference identifier (as to a page or chapter), separate from
the text of the line. Attach that identifier as a 5th field on
each output line.

REFERENCE MANUAL

PTX(l)

PTX(1)

FILES

/bin/sort
/ usr llib I eign
I usr llib I tmac I tmac.ptx
SEE ALSO

nroff(2), troff(l), mm(5), mptx(5).
BUGS

Line length counts do not account for overstriking or proportional spacing.
Lines that contain tildes C> are botched because ptx uses that character internally. ptx does not discard non-alphanumeric characters.

REFERENCE MANUAL

SUBJ(l)

SUBJ(I)

NAME

subj - generate a list of subjects from a document
SYNOPSIS

subj

file (5)

DESCRIPTION

subj searches file(s) for subjects that might be appropriate in a subject-page
index and prints the list of subjects on the standard output. The document
should contain formatting commands (from nroff, troff, and mm among others) to make the best use of subj.
SEE ALSO

ndx(l), troff(l), mm(l), nroff(l).
WARNINGS

subj selects sequences of capitalized words as subjects except the first word in
each sentence. Thus, if a sentence begins with a proper noun, the capitalization rule will not select this word as a subject. On the other hand, since each
sentence is expected to begin on a newline, the first word of a sentence that
begins in the middle of a line may be erroneously selected.
The output of 5ubj may not be appropriate for your needs and should be
edited accordingly.
BUGS

5ubj also selects as subjects modifier-noun sequences from the abstract, headings, and topic sentences (the first sentence in each paragraph), and occasionally a word is incorrectly categorized as a noun or adjective.

REFERENCE MANUAL

TBL(1)

TBL(I)

NAME

tbl - prepare tables for nroff or troff
SYNOPSIS

tbl [ -T X 1[

-- 1[ /ile(s)

][ - ]

DESCRlnION
tbl is a preprocessor that prepares tables for nroff(l) or troff(l). tbl assumes
that lines between the .TS and .TE command lines describe tables, thus they

are re-formatted; lines outside these command lines are copied to the standard
output. (tbl does not alter the .TS and .TE command lines.
Follow .TS with global options. The available global options are:
center
centers the table (default is left-adjust);
expand
makes the table as wide as the current line length;
box
encloses the table in a box;
doublebox
encloses the table in a double box;
allbox
encloses each item of the table in a box;
tab (.x)
uses the character x instead of a tab to separate items
in a line of input data.
linesize (n)
sets line or rules (e.g., from box) in n-point type;
End the global options, if any, with a semi-colon (;).
After global options come lines describing the format of each line of the table.
Each such format line describes one line of the table itself, except that the last
format line (which you must end with a period) describes all remaining lines
of the table. A single key letter describes each column of each line of the
table. You may follow this key letter with specifiers that determine the font
and point size of the corresponding item, that indicate where vertical bars are
to appear between columns, and that determine column width, inter-column
spacing, etc. The available key-letters are:
C
centers item within the column;
r
right-adjusts item within the column;
1
left-adjusts item within the column;
n
numerically adjusts item in the column: units positions of
numbers are aligned vertically;
spans previous item on the left into this column;
s
centers longest line in this column and then left-adjust all
a
other lines in this column with respect to that centered line;
spans down previous entry in this column;
replaces this entry with a horizontal line;
replaces this entry with a double horizontal line.
The characters B and I stand for the bold and italic fonts, respectively; the
character I indicates a vertical line between columns.
The format lines are followed by lines containing the actual data for the table,
followed finally by .TE. Within such data lines, data items are normally
separated by tab characters.
If a data line consists of only _ or -, a single or double line, respectively, is
drawn across the table at that point; if a single item in a data line consists of

REFERENCE MANUAL

TBL(1)

TBL(I)

only _ or -, then that item is replaced by a single or double line. Some
printers do not have the vertical resolution to produce double lines.
Full details of all these and other features of tbl are given in the tutorial and
technical discussion dted below.
The -TX option forces tbl to use only full vertical line motions, making the
output more suitable for devices -that cannot generate partial vertical line
motions (for example, line printers).
If you give no file(s) as arguments, or if you specify - as fi'e(s), tbl reads the
standard input, so it may be used as a filter. When you use it with eqn(l) or
neqn(l), put tbl first to minimize the volume of data passed through pipes.

EXAMPLE
If we let - represent a tab (which should be typed as a genuine tab), then the

input:
.TS
center box;
cB s s
c11c1s
A

Icc

I Inn.

Household Population
Town-Households
-Number-5ize
Bedminster-789-3.26
Bernards Twp.-3087-3.74
Bemardsville-2018-3.30
Bound Brook-3425-3.04
Bridgewater-7897-3.81
Far Hills-240-3.19
.TE
yields:
Household Population
Households
Town
Number Size
789
3.26
Bedminster
3.74
Bernards Twp.
3087
3.30
Bernardsville
2018
Bound Brook
3425
3.04
Bridgewater
7897
3.81
Far Hills
240
3.19

REFERENCE MANUAL

TBL(l)

SEE ALSO

eqn(l), mm(l), mmt(l), mvt(l), neqn(l), nroff(l), troff(l), mm(S), and mv(S).
The -tbl: Technical Dicussion."The Preprocessor tbl- in the User's Guide.
BUGS
See BUGS under nroff(l).

REFERENCE MANUAL

TC(I)

TC(1)

NAME

tc - troff output interpreter
SYNOPSIS

tc [ -t ] [

-0

list ] [ -a n ] [ -e ] [ file (s) ]

DESCRIPTION

te interprets its input (standard input default) as output from troff(1). The
standard output of tc is intended for a TEKTRONIX 4015 (a 4014 terminal with
ASCII and APL character sets). The various typesetter sizes are mapped into
the 4014's four sizes; the entire troff character set is drawn using the 4014'5
character generator, using overstruck combinations where necessary, pro~uc
ing an altogether displeasing effect. Typical usage:
troff tro!Loption(s) file(s) I tc
At the end of each page te waits for a new-line (empty line) from the keyboard before continuing on to the next page. In this wait state, the following
commands are recognized:
!cmd

Send cmd to the shell.

inverts state of the screen erase

-n
an

skip backward n pages.

prints list of available options.

sets the aspect ratio to n.

The command line options are:
-t
-0

does not wait between pages (for directing output into a file).
list prints only the pages enumerated in list. The list consists of pages
and page ranges (e.g., 5-17) separated by commas. The range n- goes
from n to the end; the range -n goes from the beginning to and
including page n.

-a n

sets the aspect ratio to

-e

does not erase before each page.

default is 1.5.

SEE ALSO

4014(1), nroff(1), tplot(lG), and troff(l).
BUGS

Font distinctions are lost.
It needs a -w option to wait for input to arrive.

REFERENCE MANUAL

TROFF( l)

TROFF( l)
NAME

troff - text formatt ing and typeset ting languag e

SYNOPSIS

troff [option(s)

1 [--]

[fi'e(s)

1 I

typesetter

DESCRIPTION

r or comtroff formats text in the named file for printin g on a phototy pesette
parable device.
argume nt conIf no fi'e(s) argume nt is present , the standar d input is read. An
onding to the
corresp
name
file
a
be
to
taken
is
(-)
minus
single
a
of
sisting
long as they
so
order
any
in
appear
may
standar d input. The options , which
are
files,
the
before
appear
Print only pages whose page number s appear in the comma
-olist
separat ed list of number s and ranges. A range N- M means pages
Ni
N through M; an initial -N means from the beginn ing to page
and a final N- means from N to the end. (See BUGS below.)
-nN
-sN
-mnam e

-raN
-i

-q
-z
-a
-Ttty_t ype

FILES

Numbe r first generat ed page N.
Genera te output to make typeset ter to stop every N pages.
Prepen d the macro file lusr/lib /tmac/t mac.na me to the input,
file (s).
Set register a (one character name) to N.
Read standar d input after the input files are exhaust ed.
Invoke the simulta neous input-o utput mode of the .rd request.
Print only messages generat ed by .tm requests.
d
Send a printab le ASCII approxi mation of the results to the standar
output.
Prepare output for typeset ter or laser printer tty_type. Suppor ted
n
devices are aps (Autologic APS-5 typeset ter) itO (Image
variable
ment
environ
the
tively,
Alterna
Imprint_lO).
"TYPESETTER" may be set.

lusr/lib /tmac/ tmac.·
lusr/li b/mac rosr
lusr/li b/font /dev·l·
lusr/tm p/trtm p·

pointer s to standar d macro files
standar d macro files
font width tables
tempor ary file

SEE ALSO

daps(l) , dilO(l), eqn(l), grap(l) , mmt(1), nroff(l) , pic(l), tbl(l), tc(1);
The "nroff/ troff Technical Discussion"
"The Format ter troff" in the User's Guide.

BUGS

g request in
The .tI request may not be used before the first break-p roducin
the input to troff.

REFERENCE MANUAL

TROFF( l)

TROFF(l)

troff believes in Eastern Standar d Time; as a result, depend ing on
the time of
the year and on your local time zone, the date that troff generat es
may be off
by one day from your idea of what the date is.
When troff is used with the -olist option inside a pipelin e (e.g.,
with one or
more of pic(l), eqn(l), and tbl(l», it may cause a harmless "broke
n pipe"
diagnostic if the last page of the docume nt is not specified in list.

REFERENCE MANUA L

TROFF(5)

TROFF(S)

NAUE

troff - description of output language
DESCRIPTION

The device-independent troff outputs a pure ASCII description of a typeset
document. The description specifies the typesetting device, the fonts, and the
point sizes of characters to be used as well as the position of each character on
the page. A list of all the legal commands follows. Most numbers are
denoted as n and are ASCII strings. Strings inside of ( ) are optional. troff
may produce them, but they are not required for the specification of the
language. The character \0 has the standard meaning of "newline" character.
Between commands white space has no meaning. White space characters are
spaces and newlines.
an
The point size of the characters to be generated.
fn
The font mounted in the specified position is to be used.
The number ranges from 0 to the highest font presently
mounted. 0 is a special position, invoked by troff, but
not directly accessible to the troff user. Normally fonts
are mounted starting at position 1.
ex
Generate the character x at the current location on the
page; x is a single ASCII character.
Cxyz
Generate the special character xyz. The name of the
character is delimited by white space. The name will be
one of the special characters legal for the typesetting
device as specified by the device specification found in
the file DESC. This file resides in a directory specific for
the
typesetting
device.
(See
font(5)
and
lusr/lib/font/dev·.)
8n
Change the horizonal position on the page to the
number specified. The number is in basic units of
motions as specified by DESC. This is an absolute "goto".
hn
Add the number specified to the current horizontal position. This is a relative "goto".
Vn
Change the vertical position on the page to the number
specified (down is positive).
vn
Add the number specified to the current vertical position.
This is a two-digit number followed by an ASCII characnnx
ter. The meaning is a combination of hnn followed by
ex. The two digits nn are added to the current horizontal position and then the ASCII character, x, is produced.
This is the most common form of character specification.
This command indicates that the end of a line has been
Dba
reached. No action is required, though by convention
the horizontal position is set to O. troft will specify a
resetting of the x,y coordinates on the page before

REFERENCE MANUAL

TROFF( 5)

TROFF(S)

request ing that more characters be printed . The first
number , h, is the amount of space before the line and
the second number , a, the amount of space after the line.
The second number is delimit ed by white space.
w
A w appears betwee n words of the input docume nt. No
action is require d. It is include d so that one device can
be emulate d more easily on anothe r device.
pn
Begin a new page. The new page numbe r is include d in
this command. The vertical position on the page should
be set to O.
# .... \n
A line beginn ing with a pound sign is a comment.
Dlx y
Draw a line from the current location to x, y.
Dc d\n
Draw a circle of diamete r d with the leftmost edge being
at the current location (x, y). The current location after
drawin g the circle will be x+d,y, the rightmo st edge of
the circle.
De dx dy\n
Draw an ellipse with the specified axes. dx is the axis in
the x directio n and dy is the axis in the y direction. The
leftmost edge of the ellipse will be at the current location. After drawin g the ellipse the current location will
be x+dx,y.
Da dhl dvl dh2 dv2\n Draw a counterclockwise arc from the current position
to dhli+dh2, dvl+dv 2 whose center is dhl, dvl from the
current position. The current location after drawin g the
arc will be at its end.
D-xyx y... \n
Draw a spline curve (wiggly line) betwee n each of the
x,y coordin ate pairs starting at the current location. The
final location will be the final x,y pair of the list.
x qnitf\n
Initialize the typeset ting device. The actions require d
are depend ent on the device. An init comma nd will
always occur before any output generat ion is attempt ed.
x T device\n
The name of the typeset ter is device. This is the same as
the argume nt to the -T option. The informa tion about
the typesetter will be found in the directory
I usr llibI fontl devdevice .
x 1{es) n h v\n
The resolution of the typeset ting device in increm ents
per inch is n. Motion in the horizon tal directio n can
take place in units of h basic increments. Motion in the
vertical directio n can take place in units of v basic increments. For example, the APS-S typeset ter has a basic
resolution of 723 increme nts per inch and can move in
either directio n in 723rds of an inch. Its specification is:
x res 72311

REFERENCE MANUA L

TROFF(5)

x p(ause]\n

Pause. Cause the current page to finish but do not relinquish the typesetter.

x s(top]\n

Stop. Cause the current page to finish and then relinquish the typesetter. Perform any shutdown and bookkeeping procedures required.
Generate a trailer. On some devices no operation is performed.
Load the font name into position n.

x t(railer]\n
x flont) n name\n

x H(eight) n\n

x S(lant] n\n

Set the character height to n points. This causes the
letters to be elongated or shortened. It does not affect
the width of a letter. Not all typesetters can do this.
Set the slant to n degrees. Only some typesetters can do
this and not all angles are supported.

REFERENCE MANUAL

310-009
Issue 1

ATSaT

UNIXTII System V
DOCUMENTER'S WORKBENCH til
Software Release 2.0
Handbook for New Users

NOTICE
The information in this document is sUbject to change without notice. AT&T
assumes no responsibility for any errors that may appear in this document.
APS·5 is a trademark of Autologic.
DOCUMENTER'S WORKBENCH is a trademark of AT&l:
PU1 is a trademark of Digital Research.
UNIX is a trademark of AT&l:

L·244083-6

Table of Contents
Introduction

1
1

How to Read this Handbook

nroff

3
4
4

Explanation
Command Lines

tbi

10
10
11

Explanation
Command Lines

neqn/eqn

Explanation
Command Lines

13
14

troff

15
16

Explanation
Command Lines

pic

19
20
20

Explanation
Command Lines

TABLE OF CONTENTS

III

Introduction
If you have limited experience using the DOCUMENTER'S WORKBENCH
Software, this reference handbook is designed for you. It shows various
files before and after formatting and explains the role of each request or
macro in the "input" file.

You should not use this handbook to learn how to use DOCUMENTER'S
WORKBENCH Software tools; the DOCUMENTER'S WORKBENCH Software User's

Guide (310-004) is the authoritative primer. Annotated, concrete examples
for nroff, mm, tb., neqn/eqn, troff, and pic are provided here to jog your
memory after you use the User's Guide.
Two other documents are available for the more experienced
DOCUMENTER'S WORKBENCH Software user. The DOCUMENTER'S WORKBENCH Software Technical Discussion and Reference Manual (310-005) is the
source for technical details, and the DOCUMENTER'S WORKBENCH Software

Handbook (310-008) is a memory jogger for people with technical expertise.

How to Read this Handbook
1. First, this handbook presents an input, or source, file in
unformatted form (input). The source files presented here
also appear wholly or partially in the "Sampler" of the User's
Guide, and they are available for you to copy (see the Preface
to the "Sampler").
2. Next, each macro or request in the input file is explained.
3. This handbook next suggests where in the User's Guide or in
the Technical Discussion and Reference Manual to find more
information about the DOCUMENTER'S WORKBENCH
Software components used in the example.
4. Command lines for formatting the file are presented next.
These command lines show you how to store the formatted
output in a file and how to send the formatted output to a
printer or, where appropriate, to a phototypesetter.
5. Finally, this handbook shows the formatted file (input.out).

HANDBOOK FOR NEW USERS

Introduction

This handbook observes the following rules:
[]

Italic

specifies an
t~xt

Bold text

~ptional argument

shows where you may substitute appropriate values
shows where you mus~ type exactly what is specified

Check with your system administrator fOf locally availab~e output devices (printer or phototypesetter).

HANDBO(JK FOR NEW I)SERS

nroff
input:

.in +0.5i
OCtober 14 t 1984

.sp 2

.nf
Jolm smith

aJsiness Ccmplter Systems, Inc.
190 River Boulevard
D.1rham, NC 27707

.sp 2
Dear Mr. &ai.th:
.sp 2

.n
I would like to be oonsidered for the position of Document Production OxJrd:inator
with aJsiness CatIputer Systems, Inc.
I have a B.A. in En}lish and have finished oourse work for a Masters in En}lish.
Currently, I am assisting Steve Foley t P:roducti.on Editor with ~Publishinq
in Jonesville.
My duties oonsist of proofreadin:J documents and coordinatiD] graphics production•

. sp
While I enjoy my position here, I Jmow I am ready for nore challenging work and
greater responsibility.
~ shop uses a CCIllplter runni.D] UNIX System V.
I am oanfident in my potential for growth with the Technical WritiD] Staff
at Business Canplter Systems.
I have enclosed my resume and blo letters of re input.out
or
nroff [options] input Iprinter

HANDBOOK FOR NEW USERS

nroff
input.out

October 14, 1984
John Smith
Business Computer Systems, Inc.
190 River Boulevard
Durham, NC 27707
Dear Mr. Smith:
I would like to be considered for the position of Document
Production Coordinator with Business Computer Systems, Inc.
I have a B.A. in English and have finished course work for a
Masters in English. Currently, I am assisting Steve Foley,
Production Editor with Techno-Publishing in Jonesville.
My
duties consist of proofreading documents and coordinating
graphics production.
While I enjoy my position here, I know I am ready for more
challenging work and greater responsibility. Our shop uses
a computer running UNIX System V. I am confident in my
potential for growth with the Technical Writing Staff at
Business Computer Systems. I have enclosed my resume and
two letters of recommendation. Please feel free to contact
my present supervisor with any questions you may have. I am
available for an interview at any time, and I look forward
to hearing from you.
Sincerely yours,

John Jones
41 Stanford Drive
Bridgewater, NJ 08807
Enclosures:

HANDBOOK FOR NEW USERS

mm
input:

.TL

w:>rk Progress Report -- 5ecxmd

QIJarter

1984

.AF lt8Jsiness Cal1puter Systems. Inc. It
.AJJ "W. Williams n WW XF 665414 5398 7-123 baileylwww
.M!' 0

.RO nWritinc] Assignments n

.P
I started 1/lOI'k with the Technical Writin:J Staff on April 16.
My writing' assignments are:
.BL
.LI

nxumentation for the

s::s

Fortran OCIJPiler

.DL
.LI

I oollected materials relevant to inplementinc]
on the UNIX*
.FS

progranmin:J languages

Trademark of AT&T

.FE
system•

•LE
.LI

Ibcumentation for the Dist:ribrted Transaction Processil'q System (DI'PS) 2.0

.DL
.LI
I reviewed D1'PS requirements, out.stan:iil'q c:x:q:Uaints ab:>ut D1'PS, and users'

suggestions for i.np'oving' DI'PS documentation•
•LE
.LE
.RO nOther Activities n

.P
On June 16, I went

to a conference, "Writing' Abc:ut Catplters, n at Aarte State

College •
•00

HANDBOOK FOR NEW USERS

Explanation
.TL

formats the lines that follow it (until the next macro) as
the title of a formal memorandum

.AF

formats the name of the firm, "Business Computer Systems, Inc."

.AU

formats information about the author

.MT

chooses a formal memorandum type

.HU

formats an unnumbered heading

begins a new paragraph

.DL

initializes a bullet list

.LI

specifies that the text that follows is a list item

.DL

initializes a dash list

.FS

signals the beginning of footnote text

.FE

signals the end of footnote text

.LE

signals the end of a list

.SC

prints the signature line
"The mm Macro Package: a Tutorial" in the User's Guide teaches you how to
format documents with mm using its defaults and, for some macros, teaches
you how to refine the way they work. The chapter titled "mm Technical
Discussion" in the Technical Discussion arid Reference Manual comprehensively
discusses this package. It ~lso provides manual pages for t~e mm and mmt
commands (mm(l)~ mmt(l» and the mm macro package (mm(S».

HANDBOOK FOR NEW U$ERS

Command Lines
mm [options] input> input.out
or
mm [options] input I printer
or
mmt [options] input Iphototypesetter

HANDBOOK FOR NEW USERS

mm
input.out

Business Computer Systems, Inc.

subject: Work Progress Report
Second Quarter 1984

date: December 4, 1985
from: W. Williams
XF 665414
7-123 x5398
bailey!w\tIW

Writing Assignments
I started work with the Technical Writing Staff on April 16.
My writing assignments are:
~

Documentation for the BCS Fortran compiler
- I collected materials relevant to implementing
programming languages on the UNIX· system.

Documentation for the Distributed Transaction
Processing System (DTPS) 2.0
- I reviewed DTPS requirements, outstanding
complaints about DTPS, and users' suggestions for
improving DTPS documentation.

Other Activities
On June 16, I went to a conference, "Writing About
Computers," at Acme State College.

W. Williams

Trademark of AT&T

HANDBOOK FOR NEW USERS

tbl

means to press the TAB key.

input: .

•'1'5

boX, center;
ccc

1 1 1.
~ge<'Wi>AuthorSPrimaxyUse

.sp
APL<'IlAB>m;~Mathematics,Applicaticms
Basic<'UB>Dart:m::lUth'l'eac:hiD3, AJ:plications
C<'UB>B1'LSystems, Applicati.a1s
CX>BJLMany<'lU>Business AJ:p].ications
Fort%an<"JWPMany<'lU>SCientific Applicati.a1s

Li$P<'IU>M. I.T •<'IU>Artificial Intelligence
Pascal<'l'A8>stanford'l'eac:hiD3, Systems
PLl1<'rAB>m!Applicatians
SN:B)L4<'JlAB>muApp!icatians

.TE

Explanation

.TS

signals the beginning ofa table

box, center;

tells tbl to center the output and enclose the entire table
in a box. The comma between the two words delimits
each instruction. The character ";" ends global options,
telling tbl that what follows is the format section.

HANDBOOK FOR NEW USERS

tbl
ccc
I I 1.

makes up the format section, and tells tbl that there are
three columns in the table. In the first row, each column
should be centered, and in the second and following
rows, each column should be flush left. The character "."
ends the format section, telling tbl that what follows is
text to be put in the table.

.sp

places one line of space between the lines of text that it
separates
draws a line the width of the table between the text lines
that it separates

.TE

signals the end of a table
"The Preprocessor tbl: a Tutorial" in the User's Guide teaches you how to
prepare tables of varying degrees of complexity. The chapter "tbl Technical
Discussion" in the Technical Discussion and Reference Manual comprehensively
discusses this preprocessor. It also provides a manual page for the tbl(l)
command.

Command Lines
tbl -TX input I nroff -mm -TIp [options] Icol> input.out
or
tbl -TX input I nroff -mm -TIp [options] IcoIl printer
or
mm -t -TIp [options] input> input.out
or
mm -t -TIp [options] input I printer
or
tbl input I troff -mm -Ttty_type [options] I phototypesetter
or
mmt -t -Ttty_type [options] input I phototypesetter

HANDBOOK FOR NEW USERS

tbl
input.out

Language
APL

Basic
C

COBOL
Fortran
LISP
Pascal
PL/l
SNOBOL4

Authors

Primary Use

IBM
Dartmouth
BTL
Many
Many

Mathematics, Appllcatlons
Teaching, Applications
Systems, Applications
Business Applications
Scientific Applications
Artificial Intelligence
Teaching, Systems
Applications
Applications

M. I •T.

Stanford
IBM
AT&T

HANDBOOK FOR NEW USERS

neqn/eqn
neqn prepares equations for the nroff formatter. eqn prepares them
for troff.

input:

.P
'!be mean is the arithmetic averaqe for a set of soores.
'!be fcmm.Ua for ocap1t:iD} a mean (M) is
.sp 2

.m
.m
M -=- {sum fran {i -=-1} to n {x sub i} }

0Vf!!r

.m
.DE

Explanation
.P

(an mm macro) begins a new paragraph

.sp 2

(an nroff request) places two lines of space between the
text it separates

.DS

(an mm macro) starts a static display. When you put an
equation in a document formatted with mm macros, you
must put it inside a static display (shown here) or a floating display.

.EQ

tells neqn/eqn that what follows, here
M -=- {sum fran {i-=-1} to n {x sub i} } over n

is a displayed equation to be formatted.

sum, fran, to,

sub, and over are eqn instructions. The character

n-n

translates into a space.

HANDBOOK FOR NEW USERS

neqn/eqn

.EN

ends the displayed equation

.DE

ends the static display
The chapter titled "The Preprocessor neqn/eqn: a Tutorial" in the User's
Guide teaches you about this preprocessor. The chapter "eqn Technical Discussion" in the Technical Discussion and Reference Manual comprehensively
discusses its use. The Technical Discussion and Reference Manual also provides
manual pages for neqn(l) and eqn(l).

Command Lines
neqn input Inroff [options] > input.out
or
neqn input Inroff [options] Iprinter
or
eqn input I troff [options] > input.out
or
eqn input I troff [options] Iphototypesetter
input.out:

The mean is the arithmetic average for a set of scores. The formula for computing a mean (M) is

HANDBOOK FOR NEW USERS

troff
input:

.rs
.sp 4

.ps 14
.VB 16

.15 2

.P
~

sophisticated your printer
cantrol.
By placinl} .ft on a line by itself
or \f before the ~ or woi-ds you
. ft I
'lhis is a line of italic made with

is, \fItxoff'.fR can probably handle

yOur

font

before the line of text you want to chim;Je
want. to change, you can IIOiify your typography •

.ft I (italic) .

•br

.ft B
you prefer a heavier emphasis, use bold EaMn type made with .ft B (bold) •
•br
.ft H
For the clean appearcmce of a sans serif type, use .ft H (Helvetica) •
•br
.ft R
RaDan is the IlDSt popJlar, of coUrse•
•P
'!be \f allows for a finer level of cOntrol:
'!be :individual \fIitalic\fR, \fBbold\fR, or \fHKelvetica'\tR llIOrd can be done
~

in-line •
•P

All printers were not made equal, so consult your syst:en:s manager to find what
is avai.lable •

•ps 10
.VB 12
.15 1

HANDBOOK FOR NEW USERS

troff

Explanation
.rs

turns no-space mode off

.sp 4

places four lines of space betwee n the lines it separa tes
sets the point size to 14 (ignore d by nroff)

.ps 14
.vs 16

.Is 2

sets vertica l spacin g betwee n output lines to 16 points
sets line-sp acing to 2, that is, one line of space is placed
betwee n each pair of output lines.

.ft I

(an mm macro) begins a new paragr aph
change s the font to italics

.br

forces a line break

.ft B

change s the font to bold

.ft H

change s the font to Helvet ica

.ft R

change s the font to roman

change s font in the middle of a line, e.g., \f1 change s
font to roman wherev er it appear s in the text

.ps 10

change s point size to 10

.vs 12

change s vertica l spacin g to 12

.ls 1

Sets line spacin g to 1, which is the defaul t
The tutorial titled "The Format ter troff: a Tutorial" in the User's Guide
teaches you about local motion, font and point size changes , basic
graphic s,
as well as the program ming capabilities of troff. The chapter "nroff/
troff
Technic al Discussion" in the Technical Discussion and Reference Manual
compre hensive ly discusses troff. It also provide s a manual page
for troff(l) .

HANDB OOK FOR NEW USERS

- - - - - - - - - - - - - - - - - - - - - - - - - troff

Command Lines
troff -mm [options] input I phototypesetter
or
mmt [options] input I phototypesetter

HANDBOOK FOR NEW USERS

troff
input.out:

However sophisticated your printer is, trolf can probably handle your
font control. By placing .ft on a line by itself before the line of text
you want to change or \f before the word or words you want to change,
you can modify your typography. This is a line of italic made with

.ft

I (italic).
H you prefer a heavier emphasis, use bold roman type made with .It B
(boleD.
For the clean appearance of a sans serif type, use .ft H (Helvetica).

Roman is the most popular, of course.
The \f allows for a finer level of control: The individual italic, bold, or
Helvetica word can be done in-line.

All printers were not created equal, so consult your systems manager to
find what is available.

HANDBOOK FOR NEW USERS

•

piC
input:

.P
The forms that \fIpic\fR provides are

.sp 2
.in +1i
.PS

circle llcircle ll ; nove; box lIbox"; uove;

a%rOW la%rOW"

above

.PE

.sp 2
.PS

ellipse "e llipse ll ; nove; line "line" above; uove; arc "arcll
.PE
.in -1i

.P
\fIpic\fR's language is intuitive, so mak:irY:J ywr (7;tlJl forms is not hard.
For instance,
you can talk to \flpic\fR as you woold to saneone drawin] shapes with a pencil:
.PS

.in +O.3i
ellipse; line right; arc; arc; arc; line down 1i; circle; a%rOW right; box dashed
line right; line dotted right; arc; a%rOW dashed; box lI'lhere.lI
.PE

.in ~.3i
Since you can store these instructicms in special ccmnands, you are able to
oc:mpile a personal librCl%Y of shapes, namin:J them whatever you like:
.05 I
input_outplt
m:>lecular struct
solar_system
.DE
And these you

can even tailor later to suit ywr particular needs in any doc:lmlent.
For instance, the followin;J exanple might be used to dem:mst.rate the concept of
processing:

.in +O.75i
.sp 1
.PS
l::lax ltinput lt ; arrow; ellipse "processin:]lt; a%rOW; box lIoutputll
.PE

.in -o.75i

HANDBOOK FOR NEW USERS

pic

Explanation
.P

(an mm macro) begins a new paragraph

.sp 2

(a troff request) puts two lines of space between the
lines of text it separates

.in +li

indents one inch all text that follows. Other instances of
.in in this example indent text various distances.

.PS

tells pic that what follows should be interpreted as
instructions to draw a picture. In this example, the basic
shapes that pic offers are drawn, labeled by their names;
for example, circle "circle" instructs pic to put a circle
around the word "circle." circle, nove, box, arrcM,
and above are keywords for pic. More elaborate pictures
are drawn after these shapes are labeled.

.PE

ends a picture for pic

.DS I

(an mm macro) starts an indented static display

.DE

(an mm macro) ends the static display
"The Preprocessor pic: a Tutorial" in the User's Guide teaches you how to
draw with pic. The Technical Discussion and Reference Manual provides a
manual page for the pic(l) command.

Command Lines
pic input Itroff -mm [options] I phototypesetter
or
mmt -p [options] input Iphototypesetter

HANDBOOK FOR NEW USERS

pic
input.out:

The forms that pic provides are

arrow

line

pic's language is intuitive, so making your own forms is not hard. For instance, you can talk to pic
as you would to someone drawing shapes with a pencil:

a
I

r------,
_"",---;~I
IL.

I
I

)

.JI

Since you can store these instructions in special commands, you are able to compile a personal
library of shapes, naming them whatever you like:
input_output
molecular_struct
solar_system
And these you can even tailor later to suit your particular needs in any document. For instance, the
following example might be used to demonstrate the concept of processing:

input

output

HANDBOOK FOR NEW USERS

NOTES.

NOTES

• The C Progra mmer 's Handbook Bell ubslM . I. Botsky
• The UNIX Syste m User's Handbook Bell ubslM . 1. Botsky
• The Vi User's Handbook Bell ubs/M . I. Bolsky
• UNIX Syste m Softw are Readings AT&T UNIX PACIFI C
• UNIX Syste m Readings and Applications, Volume I Bell Labs
• UNIX Syste m Readings and Applications, Volume II Bell Labs
• UNIX Syste m V Utilitie s Release Notes AT&T
• UNIX Syste m V Strea ms Prime r AT&T
• UNIX Syste m V User's Guide, Second Edition AT&T
• UNIX Syste m V User's Reference Manual AT&T
• UNIX Syste m V Progra mmer 's Reference Manual AT&T
• UNIX Syste m V Strea ms Progra mmer 's Guide AT&T
• UNIX Syste m V Netwo rk Progra mmer 's Guide AT&T
• UNIX Syste m V Progra mmer 's Guide AT&T
• UNIX Syste m V Oocum entor' s Workbench User's Guide AT&T
• UNIX Syste m V Oocum entor' s Workbench Refere nce Manua
l

AT&T

PRENT lCE·HA LL, INC., Englewood Cliffs, N.J. 07632

ISBN 0-13- 9435 98-0

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.0-c321 44.398116, Tue Aug 04 2009 14:24:30
Modify Date                     : 2010:08:04 15:07:48-07:00
Create Date                     : 2010:08:01 21:34:01-07:00
Metadata Date                   : 2010:08:04 15:07:48-07:00
Creator Tool                    : Adobe Acrobat 8.2 Combine Files
Format                          : application/pdf
Document ID                     : uuid:f8d79a69-78cd-8d42-ad77-8115d01627cf
Instance ID                     : uuid:62732351-5b49-7441-869d-cc3eaf5f8c48
Producer                        : Adobe Acrobat 8.23 Paper Capture Plug-in
Page Count                      : 402
Creator                         : Adobe Acrobat 8.2 Combine Files

EXIF Metadata provided by EXIF.tools

UNIX_System_V_ors_Workbench_Users_Guide_1989 UNIX System V Ors Workbench Users Guide 1989

Navigation menu

Versions of this User Manual:

Views

Navigation