030 0761 A_AUX_Text_Processing_Tools_1990 A AUX Text Processing Tools 1990

030-0761-A_AUX_Text_Processing_Tools_1990 030-0761-A_AUX_Text_Processing_Tools_1990

User Manual: 030-0761-A_AUX_Text_Processing_Tools_1990

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

Download
Open PDF In Browser	View PDF

A/UX® Text Processing Tools

030-0761

•

APPLE COMPUTER, INC.
© 1990, Apple Computer, Inc., and
UniSoft Corporation. All rights
reserved.
Portions of this document have been
previously copyrighted by AT&T
Information Systems and the Regents
of the University of California, and are
reproduced with permission. Under
the copyright laws, this· manual may
not be copied, in whole or part,
without the written consent of Apple
or UniSoft. The same proprietary and
copyright notices must be afftxed to
any permitted copies as were afftxed to
the original. Under the law, copying
includes translating into another
language or format.
The Apple logo is a registered
trademark of Apple Computer, Inc.
Use of the "keyboard" Apple logo
(Option-Shift-K) for commercial
purposes without the prior written
consent of Apple may constitute
trademark infringement and unfair
competition in violation of federal and
state laws.
Apple Computer, Inc.
20525 Mariani Ave.
Cupertino, California 95014
(408) 996-1010
Apple, the Apple logo, AlUX,
ImageWriter, LaserWriter, and
Macintosh are registered trademarks of
Apple Computer, Inc.
APS-5 is a trademark of Autologic.
DEC is a trademark of Digital
Equipment Corporation.
Diablo is a registered trademark of
Xerox Corporation.
Hewlett-Packard 2631 is a trademark of
Hewlett-Packard.

030-0761

MacPaint is a registered trademark of
Claris Corporation.
POSTSCRIPT is a registered trademark,
and TRANSCRIPT is a trademark, of
Adobe Systems, Incorporated.
Teletype is a registered trademark of
AT&T.
TermiNet is a trademark of General
Electric.
UNIX is a registered trademark of
AT&T Information Systems.
Versatec is a registered trademark of
Versatec.
Wang C/AlT is a trademark of Wang
Laboratories.
Simultaneously published in the
United States and Canada.

UMITED WARRANTY ON MEDIA
AND REPLACEMENT

If you discover physical defects in the
manual or in the media on which a
software product is distributed, Apple
will replace the media or manual at
no charge to you provided you return
the item to be replaced with proof of
purchase to Apple or an authorized
Apple dealer during the 90-day period
after you purchased the software. In
addition, Apple will replace damaged
software media and manuals for as
long as the software product is
included in Apple's Media Exchange
Program. While not an upgrade or
update method, this program offers
additional protection for up to two
years or more from the date of your
original purchase. See your
authorized Apple dealer for program
coverage and details. In some
countries the replacement period
may be different, check with your
authorized Apple dealer.
AIL IMPLIED WARRANTIES ON
THIS MANUAL, INCLUDING
IMPLIED WARRANTIES OF
MERCHANTABIIlTY AND FITNESS
FOR A PARTICULAR PURPOSE, ARE
LIMITED IN DURATION TO NINElY
(90) DAYS FROM THE DATE OF THE
ORIGINAL RETAIL PURCHASE OF
TInS PRODUCT.

Even though Apple has reviewed this
manual, APPLE MAKES NO
WARRANlY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED,
WITH RESPECT TO nns MANUAL,
ITS QUALI1Y, ACCURACY,
MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. AS A
RESULT, THIS MANUAL IS SOlD
"AS IS," AND YOU, THE
PURCHASER, ARE ASSUMING THE
ENTIRE RISK AS TO ITS QUAIlTY
AND ACCURACY•.
IN NO EVENT WILL APPLE BE
UABLE FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES
RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS MANUAL,
even if advised of the possibility of
such damages.
THE WARRANTY AND REMEDIES
SET FORm ABOVE ARE EXCLUSIVE
AND IN LIEU OF AIL OmERS, ORAL
OR WRfl1'EN, EXPRESS OR
IMPLIED. No Apple dealer, agent, or
employee is authorized to make any
modification, extension, or addition to
this warranty.

Some states do not allow the exclusion
or limitation of implied warranties or
liability for incidental or consequential
damages, so the above limitation or
exclusion may not apply to you. This
warranty gives you specific legal rights,
and you may also have other rights
which vary from state to state.

030-0761

A1UX Text Processing Tools
Contents

Preface
Chapter 1

Introduction to AlUX Text Processing

Chapter 2

troff/nun Tutorial

Chapter 3

nroff/troff Reference

Chapter 4

nun Reference

Chapter 5

ms and me Reference

Chapter 6

tbl. Reference

Chapter 7

eqn Reference

Chapter 8

pic Reference

Chapter 9

grap Reference

Chapter 10

Other Text Processing Tools

Appendix A

Additional Reading

Appendix B

Glossary

- v-

Preface
Conventions Used in This Manual
Throughout the A/UX manuals, words that must be typed exactly as
shown or that would actually appear on the screen are in Courier
type. Words that you must replace with actual values appear in italics
(for example, user-name might have an actual value of joe). Key
names appear in CAPS (for example, RETURN). Special terms are in
bold type when they are introduced; many of these tenns are also
defined in the glossary in the A/UX System Overview.

Syntax notation
All A/UX manuals use the following conventions to represent
command syntax. A typical A/UX command has the form
command [flag-option] [argument] ...

where:
command

Command name (the name of an executable file).

flag-option

One or more flag options. Historically, flag options
have the form
-[opt . .. ]

where opt is a letter representing an option. The
form of flag options varies from program to
program. Note that with respect to flag options, the
notation
[-a][ -b][ -c]

means you can select one or more letters from the
list enclosed in brackets. If you select more than one
letter you use only one hyphen, for example, -abo
argument

Represents an argument to the command, in this
context usually a filename or symbols representing
one or more filenames.

[]

Surround an optional item.
Follows an argument that may be repeated any
number of times.

Courier type

anywhere in the syntax diagram indicates that
characters must be typed literally as shown.

italics

for an argument name indicates that a value must be
supplied for that argument.

Other conventions used in this manual are:

indicates that the RETURN key must be pressed.
An abbreviation for CONTROL-X, where X may be
any key.

cmd(sect)

A cross-reference to an NUX reference manual.
cmd is the name of a command, program, or other
facility, and sect is the section number where the
entry resides. For example, cat(l).

Chapter 1
Introduction to A/UX Text Processing

Contents
1.

NUX text formatting tools: A brief overview
1.1
1.2
1.3
1.4
1.5
1.6
1.7

Formatting text: troff and nroff. .
Formatting text: The mm macro package •
Formatting tables: tbl. . . . . . .
Formatting equations: eqn
....
Formatting pictures: pic
Formatting graphs: grap
Other macro packages .

1
2
3
4

5
6
8
10

2. Page layout concepts
2.1 Principal units of measurement
2.2 Line length
2.3 Page length
. • • •
2.4 Paragraph types • • • • •
2.5 Margins
. . • • •
2.6 Adjusting and filling
2.7 Indentation
2.8 Headers and footers
2.9 Centered text •
2.10 Footnotes • • •
2.11 Heading levels

11
13
13
14
14
15
15
16
17
18
19
19

3. Font description concepts
3.1 Type families: Changing fonts
3.2 Point size . •
3.3 Vertical spacing • . • . •
3.4 Character set • • • • • .
3.5 Accents
3.6 Overstriking •

20
20
22
24
25
26
27

4. Other formatting features

-i-

4.1

Displays
• • • •
Table of contents
Multicolumn output •
Strings. • • •
Number registers
Defining and using macros.
Motions
• • •
Line drawing. •

4.2 Lists

4.3
4.4

29
29

4.5

4.6
4.7

4.8
4.9

.
•

5. Document printing
5.1 Output devices
5.2 The TranScript package

30
30
31
32
32
32
33
33

Figures
Figure 1-1. Producing a printed document

Figure 1-2. A simple picture

Figure 1-3. A more complicated picture

Figure 1-4. An even more complicated picture

Figure 1-5. A graph

•

Figure 1-6. A more complicated graph •

Figure 1-7. Parts of a page

- ii -

Chapter 1
Introduction to A/UX Text Processing

1. AlUX text formatting tools: A brief overview
The A/UX operating system provides a large number of tools for
editing, formatting, and printing text and graphics. You can use these
tools to prepare almost any kind or size of document, from newsletters
to books. This chapter is a general introduction to A/UX text
processing.
To understand the A/UX text processing tools, it is helpful to
understand the process involved in producing a final printed document.
The sequence typically looks something like that in Figure 1-1.

Figure 1-1. Producing a printed document

enter/edit
text

format
text file

It is a basic assumption of the A/UX text processing system that these
tasks are separable from one another and ought to be handled by
different programs. First, you use one of the standard A/UX editors to
enter and edit your text. The editor doesn't format or print the file; it
merely stores your text, exactly as you enter it. To arrange the text into
pages and paragraphs, you use aformatting program (usually troff
or nroff in conjunction with a macro package). These programs use
instructions you have entered in the text file, which indicate how you
want the final output to look. Once the text is edited and formatted,

Introduction to NUX Text Processing

1-1

you may print the document by directing the formatted output to a
printer.

1.1 Formatting text: troff and nroff
The A!UX text processing system is based on a pair of programs called
troff and nroff. troff formats its input for printing on any
high-resolution typesetter or laser printer that is capable of printing
multiple fonts and type sizes. nroff formats its input for printing on
less-capable devices such as daisy wheel and dot matrix printers, or
your terminal screen. troff and nroff are for the most part
compatible with each other, so that a single input file may be processed
with either formatting program. nroff simply ignores any troff
commands that the intended output device cannot support. From now
on in this chapter, any reference to troff means either nroff or
troff.

As mentioned above, troff searches through your file for commands.
Input consists of text, which will print, and commands, which set
parameters or call out special characters. These are troff
commands. There are two ways to callout a command:
• Begin a line with a control character (period or single quote)
optionally followed by a space or tab; followed by a one- or
two-character command name; followed by a space or a newline.
These are sometimes called "dot commands. " The single quote
suppresses the break function (the forced output of a partially
filled line) caused by certain requests. Unrecognized command
names are ignored.
• Type an escape character (\), followed by a command name
anywhere in a line. These are sometimes called "escape
sequences.' ,
The following are examples of t ro f f dot commands:

.sp 4
.ft B

These instruct t ro f f to leave four blank lines and switch into the bold
font.
The following is an example of a t ro f f escape sequence:

1-2

A/UX Text Processing Tools

The last word on this line is \s20big.\s10

This command causes troff to produce the following output:
The last word on this line is

big.

The sequence \ s 20 instructs t ro f f to switch to point size 20. The
same effect could be achieved using troff dot commands, as follows:
The last word on this line is
.ps 20
big .
. ps 10

1.2 Formatting text: The mm macro package
troff and nroff provide facilities for controlling virtually all
features affecting the appearance of the final printed page. These
programs do so, however, at a relatively low level; for instance, neither
program provides automatic margins, page headers and footers, or page
numbering. To obtain these features, as well as countless others you
will probably need, you must use a macro package in conjunction with
troff. A macro is a collection of troff commands grouped into a
useful unit, and a macro package is a collection of macros grouped
into a useful unit.
The standard NUX macro package is called rom. (For a brief
discussion of other macro packages, see' 'Other Macro Packages.' ')
The rom package provides two kinds of additions to basic t ro f f
capabilities:
• a large number of dot commands that are not included in the
troff command set but are necessary for most document
processing
• default parameter settings governing margins, page length,
paragraph indent levels, and so forth
The rom dot commands are almost universally uppercase, to distinguish
them from troff dot commands, which are all lowercase. For
example, you can use
.P

Introduction to NUX Text Processing

1-3

to indicate the beginning of a paragraph. You use these additional dot
commands exactly like troff dot commands. However, when you
mn the file through the formatting program, troff won't understand
these macros unless you get it to read their definitions first. You can do
this by invoking troff with the -rom argument:
troff -rom file

Thus, the argument to troff gives you access to the rom macro
package. You can get access to other macro packages in the same way.

1.3 Formatting tables: tbl
It's easy to produce tables in a document by using the program tbl.
Here is an example of tbl output:

Text processing programs
Program
Function
eqn
grap
Ip
nroff
pic
tbl
troff
vi

format equations
format graphs
printer spooler
low-quality output
format pictures
format tables
high-quality output
enter/edit text

The tbl program, unlike the rom package, operates as a preprocessor
to troff. tbl processes the input file containing table specifications
before it is processed by troff, as follows:
tbl file

I troff -rom

This is because tbl translates the table specifications into troff
commands. tbl recognizes these specifications when they occur
between lines beginning with the commands . T S and . TE. For
instance, the input for the table above looks like this in the text file:

1-4

AlUX Text Processing Tools

.TS
box center tab(:)
c s

c c
If7 1 .
\f6Text Processing Programs\fR
.sp .5
\f6Program:Function\fR
.sp .5
eqn:format equations
grap:format graphs
Ip:printer spooler
nroff:low-quality output
pic:format pictures
tbl:format tables
troff:high-quality output
vi:enter/edit text
.TE

For a complete discussion of the tbl program, see Chapter 6, "tbl
Reference. ' ,

1.4 Formatting equations: eqn
The A/UX text processing system also includes another troff
preprocessor, eqn, that allows you to include mathematical equations
and formulas in documents. eqn searches for equation specifications
contained within . EQ and . EN pairs. For example, the input
.EQ
x + y
.EN

= 4 sup 2

yields the output

X+y=42
And the input
.EQ
int x sup 3 dx
.EN

{ x sup 4 } over 4 +

yields the output

Introduction to NUX Text Processing

1-5

Jx3dx=~ +c
Like tbl, eqn is a preprocessor to troff. So the general command
line looks like
eqn file

I troff -rom

See Chapter 7, "eqn Reference," for further details.

1.5 Formatting pictures: pic
You may also produce simple line drawings in a document by using the
pic program, yet another troff preprocessor. You specify pictures
by including their descriptions within. PS and . PE pairs. For
example, if you include the following description in the input file
.PS

box; arrow; ellipse
.PE

and run troff with the pic preprocessor
pic file I troff -rom ...

you get the picture shown in Figure 1-2.

Figure 1-2. A simple picture

You can draw more complicated (and useful) drawings as well, such as
those in Figures 1-3 and 1-4. The descriptions of these pictures are
much more complicated than the simple description of Figure 1-2, but a
mildly experienced pic user should have no trouble producing such
diagrams.

1-6

AlUX Text Processing Tools

Figure 1-3. A more complicated picture

Vice President
Engineering

Introduction to AlUX Text Processing

1-7

Figure 1-4. An even more complicated picture

D-

I-~::;:=====~--T-I

Ethernet
Virtually all the figures in this A/UX documentation were produced
using pic. See Chapter 8, "pic Reference," for a complete
discussion of the pic language.

1.6 Formatting graphs: qrap
In addition to tables, equations, and simple line drawings, it is also
possible to include graphs in a document formatted with traff. This
is accomplished by using the grap preprocessor. Here is an example
of grap output

1-8

AJUX Text Processing Tools

Figure 1-5. A graph

sed
I
Vl.
grap
Pl.C
tbl
I
eqn
I
neqn
I
tro:t:t
nroff
psdl.t
I
Ip
I

Text
processing
programs

I
I
I

50000

100000

Program size (bytes)

Like these other preprocessors, g rap looks for a specification of how
the graph should look and the data to be graphed. These are enclosed
within . Gland . G2 pairs, as follows:

.G1
specification of graph
.G2
grap, however, is a preprocessor for pic; this simply means that
grap translates the specification of the graph into pic code, not
directly into traff code. So, to get graphical output, your command
line must look something like this one:
grap file I pic I t raff -rom
Figure 1-6 shows another example of grap's capabilities. It charts
San Francisco 4ger wide receiver Jerry Rice's total receiving yardage
per game for each of the sixteen regular season NFL football games in
1986. The height of the little football indicates the yardage, and the
number inside the football indicates how many catches Rice made that

Introduction to AlUX Text Processing

1-9

day. Finally, the number of little goalposts under the football indicates
how many touchdowns Rice scored in the game.

Figure 1-6. A more complicated graph

250

200

150

(!)

(!)
100

®
®

1 2

®®
®
<9

3 4 5 6 7 8 9 10 11 12 13 14 15 16

Jerry Rice's 1986 Season

For further information, see Chapter 9, "grap Reference."

1.7 Other macro packages
In addition to the mm macro package, there are other macro packages
that you may run into on A/UX systems. Of particular note is the ms
macro package (see Chapter 5, "rns Reference' '). This program
provides most of the same functions provided by the mm package, but
with different syntax. For instance, a left-adjusted paragraph is

1-10

NUX Text Processing Tools

indicated in ms with the macro
.LP

and in rom it is indicated with the macro
.P

For the most part, the page- and font-description concepts underlying
the rom macros (described below) will carry over into any other
common macro package. There are some rom macros, however, for
which there is no simple equivalent in other packages.
Another very common macro package is the man macro package. This
collection of macros is intended for the special purpose of formatting
manual pages as presented in AIUX Command Reference, AIUX
Programmer's Reference, and AIUX System Administrator's Reference.
See man(S) in AIUX Programmer's Reference for further details.

2. Page layout concepts
To get the most out of the A/UX text processing programs, you must
have some grasp of the terms used to describe page layout. This
section introduces you to the most important of these. Terms that are
boldfaced are also defined in "Glossary of Text Processing Terms" at
the end of this book.
If you use the rom macro package in conjunction with t ro f f, the page
is divided into a number of separate regions, some of which you can
print on and some of which you cannot. The parts of a page are
illustrated in Figure 1-7.

Introduction to AlUX Text Processing

1-11

Figure 1-7. Parts of a page

Entire physical page

~~~~~~~~~~~~0~~~~~~~f~~~~i
Title length
:;;.1 :

liE

I
I

Top margin

,....-+--

Left margin

Right margin--+--->

I
I
I
I
I
I

I
I
I

I ....

Maximum line length

Bottom margin
I

-_...Lo-,
I
I
I
I

r-----------------------,

~~~~~~===~~:~~~~~~~~~~~~~~

rPrintable portion of page
Generally, you cannot print on the entire physical page (typically a
sheet of paper); the rom macros automatically generate margins on all
four sides of the paper. You can, however, increase or reduce any of
these margins independently of the others. In addition, the rom package
automatically provides headers and footers (lines of text that are

1-12

AlUX Text Processing Tools

printed on the top and bottom, respectively, of every page). For more
detailed discussion of these points, see "Margins" and "Headers and
Footers."

2.1 Principal units of measurement
Many t ro f f and rom commands require a unit of measure as part of
the command. For instance, you must specify the line length as some
number of inches or centimeters, and so on. t ro f f and rom
understand both inches and centimeters, as well as a number of other
units that are more familiar to printers. The following table lists the
principal units of measurement:
Unit

Abbreviation

inch
centimeter
pica
point
em
en

Equivalence

c
p

p
m
n

2.54c = Ii
6P= Ii
72p = Ii
width of "m" in current font
width of "n" in current font

Of these units, only picas and points are likely to be unfamiliar to you.
Points are used mostly to specify sizes of type (also called "point
sizes"), and picas are often used for specifying line lengths and page
lengths. For the most part, you can avoid picas. but it can be difficult to
specify type sizes in any unit other than points.

2.2 Line length
The default line length using troff (with or without the mm macro
package) is 6 inches. The maximum length of a line of text (or
graphics) is the widest printable portion of the page, which is
dependent on the capabilities of the printer you are using. You may
specify the output line length with the troff command .11 followed
by some measurement; for example,
.11 7i

gives you a line length of 7 inches. There is no single rom command to
accomplish the same thing. There is a number register that controls the
length of the line and the page header and footer. You can set this
register as follows:

Introduction to A/UX Text Processing

1-13

.nr W 7i
See "Number Registers" for more information.

2.3 Page length
The length of the physical page depends on the printer you are using;
usually you will be working with one of the standard page sizes (8.5 by
11 inches, or A4). By default, the rom package assumes an II-inch
page, but you can alter the page length by setting the L number
register:

.nr L 9i
The equivalent troff command is

.pl 9i
Note that this page length includes the top and bottom (vertical)
margins. You can increase the amount of space taken by these margins
with the . VM macro:
.VM 2 5

This adds two vertical spaces to the top margin and five vertical spaces
to the bottom margin.

2.4 Paragraph types
You can specify more than one type of paragraph in a document. The
rom macro package provides one macro, . P, for specifying the
beginning of a paragraph (there is generally no need to specify the end
of a paragraph). The argument you add to this macro determines the
type of the paragraph it is. For instance, the command
.P 0

provides a left-adjusted paragraph, and the command
.P 1

provides a paragraph with the first line indented from the margin.
If there is no argument to the . P command, rom provides whatever you
have selected as the default paragraph type. You select the default type
with the command

1-14

NUX Text Processing Tools

.nr Pt n

where the argument n is as follows:

Argument

Resulting default

left adjusted
indented
indented, except
after headings, lists,
or displays

1
2

2.5 Margins
There are two horizontal margins, left and right, on every page. The
left margin is also known as the page offset, and you can change it
using the troff command .po. The default is about 1 inch, but you
can increase or decrease it.
This command would be appropriate to center a 6-inch line of text on a
piece of paper 8.5 inches wide:
.po 1.2Si

You can change the right margin by changing the line length or the
page offset.

2.6 Adjusting and filling
By default, troff both fills and adjusts the text it formats. To fill text
is to place as much text on a line as will fit, regardless of how the text
occurs in the input file. One nice feature of t ro f f is that it fills
automatically. This means you can type your text into a file in
whatever way is easiest for you to edit subsequently (for instance,
beginning all sentences on a new line). troff may have to break a
word in the middle to achieve a nice fit, but it will usually do this
hyphenation in an intelligent manner.
You can control whether or not filling occurs with the troff
commands. nf and . fie For instance, the input

Introduction to NUX Text Processing

1-15

.nf
This text should not be filled.
So the output
will be arranged just like
the input.

produces the following output:
This text should not be filled.
So the output
will be arranged just like
the input.
You can turn filling back on with the . f i command.
To adjust text is to place small amounts of space between words in a
filled line so that the line of output text is exactly the current line
length. troff automatically adjusts text, but you can turn adjustment
off with the command
.na

You can turn adjustment back on with the command
.ad

2.7 Indentation
Occasionally you need to indent some stretch of text to set it off from
the surrounding text. You can do so with the troff command. in.
For instance, the input
.P
This line
.in .5i
This line
.in Ii
This line
.in +.5i
This line
.in 0
This line

is not indented at all.
is indented .5 inch.
is indented 1 inch.
is indented 1.5 inch.
is not indented.

produces the following output:

1-16

AlUX Text Processing Tools

This line is not indented at all.
This line is indented .5 inch.
This line is indented 1 inch.
This line is indented 1.5 inch.
This line is not indented.
Notice that you can supply both absolute and relative arguments here,
and that an argument of zero (0) returns to the current left margin. The
indent persists until you reset it, or until it gets reset automatically.

2.8 Headers and footers
A header is a line of text that is printed on the top of every page.
Similarly, a footer is a line of text that is printed on the bottom of
every page. (See Figure 1-7 for the location of these lines.) Each of
these lines is further divided into a left part, a center part, and a right
part. You can specify any of these six items independently of the
others. Further, you can specify different headers and footers for odd
and even pages.
There are six rom macros affecting headers and footers:
.PH
.OH
.EH
.PF
.OF
.EF

page header (all pages)
odd header
even header
page footer (all pages)
odd footer
even footer

Each of these macros takes the same kind of argument, a string
surrounded by double quotes (,,), with each of the three parts of the
header or footer. For instance, we might specify a page header as
follows:
.PH "'Chapter 8'%'The Bill of Rights'"
This header will appear on all pages. The left header will read
"Chapter 8," the center header will be the page number, and the right
header will read "The Bill of Rights."
Note that rom interprets the percent sign specially in a header or footer
specification; each time the header or footer is printed, it is replaced by
the current page number.

Introduction to NUX Text Processing

1-17

If you want one of the three parts of the header or footer to be empty,
just leave the appropriate field in the argument string empty. For
instance, the following command will cause the page number to be
printed at the top of each page:
.PH ""%""

If you need an apostrophe in the header or footer, you can change the
delimiting character to anything you like, and rom will detect the change
automatically. For instance, you might want the following header
specification:
.PH "@Chapter 7@%@Bill's Alibi@"

You may specify a separate header or footer for odd and even pages.
The following pair represents a very common way to handle headers:
.OH "@Chapter 7@%@Bill's Alibi@"
.EH "@Bill's Alibi@%@Chapter 7@"

2.9 Centered text
You can center a line of text on the page by using the t ro f f dot
command . ceo For example,

.ce
This line is centered.

produces
This line is centered.

If you provide a numeric argument, the corresponding number of lines
will be centered. For example,
.ce 3
This is the first centered line.
This is the second centered line.
This is the third and last centered line.

produces
This is the first centered line.
This is the second centered line.
This is the third and last centered line.
Note that filling and adjusting are turned off for lines that are centered.

1-18

NUX Text Processing Tools

2.1 0 Footnotes
You can include footnotes in a document by enclosing the text to be
footnoted between . F S and . FE pairs.l For example,
.FS
This is the text of a footnote.
It is smaller than the main text,
and placed at the bottom of the page .
. FE

If you need consecutively numbered footnotes, you should include the
string \ *F at the appropriate spot in the text. For further details about
footnotes and footnote formats, see Chapter 4, "rom Reference. "

2.11 Heading levels
In addition to the grouping provided by the paragraph macros, rom
provides several macros for grouping paragraphs into sections and for
generating a table of contents listing sections and subsections.
The primary macro for grouping paragraphs into sections is . H, for
"heading leveL" A typical use of this macro might look like this:
.H 1 "The Clues to the Murder"
There was a broken window,
and the maid heard a loud scream
shortly before midnight.
In addition,

This indicates that a first-level heading is to be generated; rom
automatically numbers these headings. If this is the fourth such macro
in our text file, the output looks like this:

1. This is the text of a footnote. It is smaller than the main text, and placed at the bottom
of the page.

Introduction to AlUX Text Processing

1-19

4. The Clues to the Murder
There was a broken window, and the maid heard a loud
scream shortly before midnight. In addition,
There may also be subsections within first-level sections. These are
indicated with a second-level heading:
.H 2 "An Investigation of the Glass Shards"
The mm package allows for up to seven levels of headings (rarely are
this many needed in typical documents, however). In addition, there is
a macro for generating unnumbered headings:

.HU "Appendix A: Summary of Clues"
Many features of these heading level macros can be adjusted to taste,
such as the point size and font for each heading level and the amount of
spacing from surrounding text. See Chapter 4, "mm Reference," for a
complete list.

3. Font description concepts
troff is able to print in any font that is supported by the printer.
nroff can generally print in only one font, but depending upon the
capabilities of the printer you are using, nroff may be able to
simulate boldface by overstriking and italics by underlining.

3.1 Type families: Changing fonts
You can achieve a great deal of clarity in a document by selecting fonts
that are appropriate for your purposes. A font is a collection of letters
and characters unified by a distinctive pattern or "look." What fonts
are available to you is dependent on how troff has been configured,
but typically at least the following three fonts are available:
Times Roman

ABCDEFGHIJKLMNOPQRSTUVWXYZ

Times Roman italic

ABCDEFGHIJKLMNOPQRSTUVWXYZ

Times Roman bold

ABCDEFGIDJKLMNOPQRSTUVWXYZ

By default, text is printed in "plain" Times Roman, unless you change
fonts. You may change fonts with either a dot command (. ft) or an
in-line escape sequence (\ f), followed by a name of the font desired.
The following two lines give identical output:

1-20

AlUX Text Processing Tools

This is in Times Roman,
.ft B
and this is Times Roman bold.

This is in Times Roman,
\fBand this is Times Roman bold.
The output in either case is
This is in Times Roman, and this is Times Roman bold.
You can also use rom macros:
mm macro

Effect

bold
italics
roman

Thus, the example above could be further rewritten as
This is in Times Roman,
.B

and this is Times Roman bold.
You can also replace font names altogether with numbers. For
example, instead of \fB, you may write \f3. Many people prefer the
numbers because it is easier to pick out the escape sequence. Which
numbers correspond to which fonts depends on how your printer and
software have been configured. For example, systems using the
TranScript troff-to-PostScript translator driving the Apple
LaserWriter® have the following correspondence:

Introduction to AlUX Text Processing

1-21

Number
1

2
3
4

6
7
8

Font
Times Roman
Times I talie

Times Bold
Times Bold Italic
Helvetica
Helvetica Bold
Courier
Courier Bold

3.2 Point size
t ro f f can work with virtually any size text that the printer supports.
The program is usually configured to allow you access to only a portion
of those actually printable. A normal range is something like 2 point to
80 point. Point size 2 is so small that it's unreadable. The following
shows point size 80:

Appropriately configured, however, troff can do things like the
following, which is a Times Roman 2 at 432 points:

1-22

NUX Text Processing Tools

The default type size is 10 point. You may change point sizes in a
variety of ways. Usually this is done with the . ps command:
.ps 14
This text is now in 14 point.

This produces

This text is now in 14 point.
You may also use the in-line escape sequence \s:

Introduction to A/UX Text Processing

1-23

This is in 10 point,

\s14and this is in 14\sO.

produces
This is in 10 point,

and this is in 14.

Notice that \ s 0 returns to the previous type size, not size O.
Type size changes may also be specified relatively. For instance, you
may rewrite the previous example as follows:
This is in 10 point, \s+4and this is in 14\sO.

3.3 Vertical spacing
The vertical spacing between two lines of text is the distance from the
base of the characters on one line of text to the base of the characters
on the next line. Normally, the vertical spacing is set to 12 points,
which is enough to accommodate a 10-point character plus a small
amount of white space between lines. If you change point sizes, you
must increase or decrease the vertical spacing accordingly. You can
change the vertical spacing with the. vs command:
.ps 20
.vs 22

Two different vertical spacing settings are illustrated as follows:

Point size 12
Vertical spacing 14
Vertical spacing 16

Four score and seven
years ago, our fathers
brought forth on this
continent a new nation ...

A very common mistake is to increase the point size without increasing
the vertical spacing. In such a case you usually end up with garbage;
for example,

1-24

A/UX Text Processing Tools

You can set both the point size and the vertical spacing at once with the
rom macro . s. For instance,

24 26

sets the point size to 24 points and the vertical spacing to 26 points.

3.4 Character set
The set of characters that you can print using troff depends on the
abilities of the printer you are using. Generally, a character is
accessible to t ro f f if it is a member of some font that t ro f f knows
about. A troff font typically includes the following characters:

AB C DEFG HI JKLMNOP QR S TUV WX Y Z
abcdefghijklmnopqrstuvwxyz

1234567890
&.,:;' '-!@#$%"*()-+={}[]\I><
In addition, there may be other fonts known as "special" fonts.
Originally these fonts were used for mathematical symbols not
available on the standard Times Roman font, but a special font can
contain any sort of characters or glyphs. A typical mathematical
special font provides the following characters, which include a full
Greek alphabet:
ABS~E~reIKAMNOn~p~TYnXHZ

a~~Oe$yetKA~Vo~~pcr~uroX~~
if:.e k'V -oo=><=>~J<"<=VE 'x-.a
+-oc)=>o _c":::>D"3'V-~

There are two standard ways to get one of these characters to print in a
document. First, you can use a feature of the preprocessor eqn that
allows in-line equations. In that case, you would use the eqn name of
these symbols. For instance, we have seen that eqn translates the word
int into the symbol J(appropriately scaled, of course).

Introduction to AJUX Text Processing

1-25

A second way to get access to special font characters is to use their
troff name. A few of these are
Input

Output

\(pl

Name

plus
minus

\ (mi
\ (mu

multiplication

\(sr

square root

\(br

box rule

\(ua

up arrow

\ (da

down arrow

\(ci

circle

\ (!=

=t=

not equal

\(is

integral

For a complete list, see Chapter 3, "nroff /troff Reference."

3.5 Accents
The rom macro package provides the ability to print accent marks over
certain characters. To do this, you need to put the rom name of the
accent mark after the letter you want accented. For example, the input
re\*'sume\*'

produces the word "resume". The following accents are available:
Input
\*'
\ *,

1-26

Output

Name

grave accent
acute accent

\*~

circumflex

\*-

tilde

\ *,

cedilla

\*:

umlaut (lowercase)

\*;

umlaut (uppercase)

NUX Text Processing Tools

3.6 Overstriking
The troff formatter provides one further way of generating
characters that are not in its basic character set: overstriking two or
more characters. The in-line escape sequence \ 0 will overstrike
whatever characters (up to nine) are enclosed within single quotes. For
instance, the input
\0'>/'

produces ""j". The \ 0 sequence centers each character as it
overstrikes them. If instead you want the characters lined up on their
left sides, you could use the \ z escape sequence. This instructs
troff to print the following character but not to move to the right
after printing it. For instance, the input

\z>/
produces "1>".

4. Other formatting features
troff and the mrn macro package provide several further features that
are very useful in document production: displays, automatic list and
table of contents generation, multicolumn output, strings, and number
registers.

4.1 Displays
Occasionally you want to make sure that a certain stretch of text is kept
all together on one page. For instance, it is generally preferred that the
information in a table not be split across page breaks. tbl does not
provide this service, but mrn provides a way of doing it, with displays.
A display is a block of text that is to be kept on one page.
You can indicate a display by enclosing the relevant text within the pair
of macros . DS and . DE, as follows:

Introduction to NUX Text Processing

1-27

.DS
This text will be kept all together.
No heading macros are allowed in a display,
but paragraph macros and lists are allowed.
By default the text of a display is not
filled or adjusted, but you can override
this by providing an argument
to the .DS macro .
. DE
If there is not enough space remaining on the page to fit this entire
block, troff will break onto a new page, so that the block remains
together.

4.2 Lists
Occasionally you want to provide a list of items. The rom package
provides a number of macros designed to facilitate printing lists of
various kinds. For instance,

.P
The
.sp
.BL
.LI
Tim
.LI
Joe
.LI
the
.LI
the
.LE
.sp

remaining suspects are:
.5

butler
maid

produces

1-28

AlUX Text Processing Tools

The remaining suspects are:
• Tim
• Joe
• the butler
• the maid
The macro . BL is a list initialization macro; it instructs rom that a bullet
list follows. The macro. LI indicates the beginning of each list item,
and the macro . LE indicates the end of the list.
There are a number of other list initialization macros:
.AL
.BL
.DL
.ML
.RL
.VL

numbered or lettered list
bullet list
dashed list
marked list
reference list
variable-item list

As you would expect, the format of the list can be adjusted as needed;
see Chapter 4, "rom Reference," for details.

4.3 Table of contents
rom is able to generate a table of contents for your document by
remembering all section headings and the pages where they occur as it
formats the document. To get the table of contents printed, you must
include the following macro at the end of your input file:
.TC
This macro causes rom to print out the accumulated section headings
and page numbers. You may control the appearance of the table by
adding arguments to the macro (see Chapter 4, "rom Reference").

4.4 Multicolumn output
By default, troff outputs the text in one column. You can instruct it
to print two columns with the macro
.2C

Introduction to A/UX Text Processing

1-29

To return to one column, use the macro
.1C

4.5 Strings
A string is a sequence of characters grouped together under a name.
The mm macro package provides several predefined strings that you can
use. For instance, the string \ * (DT will be replaced by the current
date, as follows:
Today is \*(DT.

This results in
Today is September 16, 1987.
You get access to a string by preceding its name with the sequence
\ * ( (or, as we saw above, with the sequence \ * if the name of the
string is only one character). In addition, you may define your own
strings with the troff command. ds. This might be useful to
abbreviate an often-used but lengthy phrase:
.ds CU pig Farmers of America Credit Union
.P
The annual board meeting of the \*(CU
was called to order at 2:11 p.m.
Chairman Curley reported
an unexpected rise

This produces
The annual board meeting of the Pig Farmers of
America Credit Union was called to order at 2: 11 p.m.
Chairman Curley reported an unexpected rise

4.6 Number registers
t ro f f keeps track of many of the parameters governing the page
layout by storing them in number registers. You may think of a
number register as a slot having both a label (the name of the register)
and something inside it (the value of the number register), Some of
these registers are created and manipulated by t ro f f and mm
themselves, but you may also define your own number registers.

1-30

NUX Text Processing Tools

You can create a number register with the command . nr:
.nr YR 86
The profit in year 19\n(YR was $250,000.

In the text, you must precede the number register (here, YR) with \n.
The value you defined in the number register then appears in the
output:
The profit in year 1986 was $250,000.
A more typical use of the . nr command is to change built-in
parameters. For instance, you can use the command
.nr pi 10

to change the paragraph indent to 10 ens. See Chapter 4, "rom
Reference, " for a complete list of num ber registers.

4.7 Defining and using macros
If you find yourself repeating the same sequence of t ro f f commands,
or almost the same sequence, you may find it useful to define a macro
encapsulating that sequence of commands. You define a macro with
the . de macro. For instance,
.de
.in
.11
.ps

QP
+5n
-IOn
-2

The line consisting of two dots indicates the end of the macro. Here
we have defined a rudimentary quote paragraph macro: it indents the
text from both sides and reduces the point size by 2.
You can also define macros with "arguments," like many of the rom
macros. The arguments are indicated in the definition with the
sequences \ \ $1, \ \ $2, and so on. For example,
.de xx
Today is \\$1 the \\$2 .

. xx

Friday 6th

yields

Introduction to AlUX Text Processing

1-31

Today is Friday the 6th.
Macro names should be chosen carefully to avoid conflicts with
predefined rom macro names. To be safe, user-defined macros should
be two characters with the first lowercase and the second uppercase.
For example,

.de

roN

4.8 Motions
troff includes commands for making arbitrary motions in a
horizontal or vertical direction, \ h and \ v. For example,
There is a gap \h'O.5i' in this sentence.
yields
There is a gap

in this sentence.

Both \h and \ v require a distance specification within single quotes;
the two escape sequences \ u and \ d, however, move up and down a
fixed distance and so require no argument. For example,

This sentence contains a superscript\ul\d.
yields
This sentence contains a superscript 1.

4.9 Line drawing
There are two t ro f f commands for drawing horizontal and vertical
lines, \ 1 and \ L. For example,

\1'O.5i'\L'O.5i'
prints

5. Document printing
t ro f f produces output that is device independent. This means that
you will need to process the output of troff with a program (usually
called an "interface program") that translates this output into a form

1-32

A/UX Text Processing Tools

that the printer understands. This step of the printing process may be
done automatically, or you may need to invoke this program yourself.
Check with local administrators to see what is appropriate for your
installation. On the A/UX system, an interface program is provided to
allow t ro f f output to be printed on the LaserWriter; it is called
psdi t and is discussed below in "The TranScript Package."

5.1 Output devices
The A/UX family of text processing tools is designed to be as
independent of any particular type of output device as possible, thereby
allowing the user to get output on any of a wide number of printers or
display devices. On the high end of the spectrum, t ro f f is capable of
producing output on modem digital typesetters and phototypesetters,
and on laser-driven printers, whose quality approaches that of much
more expensive typesetters. troff can also send output to certain
high-resolution video display terminals. On the low end of the
spectrum, nroff can format its input for output on virtually any
terminal screen, dot matrix printer, or daisy wheel printer.

5.2 The TranScript package
As indicated above, a printer interface program is needed to translate
the output of troff into a form that is understood by your printer. If
you wish to produce output on an Apple LaserWriter, you must pipe
the output of t ro f f through a program that translates it into
PostScript, the page-description language used by the LaserWriter. For
this purpose, the A/UX system contains a package of programs called
TranScript.
The most important program in this package is psdi t, which
translates troff output into PostScript. For instance, the command
line used in producing this chapter was
grap chap.l I pic I tbl I eqn I traff -Tpsc -mm I psdit I Ip

The only thing new here, aside from the postprocessor psdi t, is the
-Tpsc option to troff. This tells troff which type of printer it
should format its output for; t ro f f needs this information so that it
can know which point sizes are legal for that printer and which fonts
are available on the printer (among other things). The psc stands for
"PostScript device" and is the appropriate option for the LaserWriter.

Introduction to A/UX Text Processing

1-33

For more information on the TranScript package, consult
transcript(1M) in AIUX System Administrator's Reference.

1-34

AlUX Text Processing Tools

Chapter 2
troff/mm
Tutorial

Contents
Introduction

Lesson 1: Producing a formatted letter
Using mm displays .
Paragraphs and spaces. • . •
Lists . . .
Font changes
Indented text
Formatting your file
. . . •
Obtaining your printout
Lesson 2: Producing letterhead
Top-of-page processing
The size of your text
The size of your page . .
Designing your letterhead. .
Printing your letter on letterhead.

2
.

2
3
4
4
5

Lesson 3: Modifying the appearance of a page
Producing a footnote . . . • .
Producing graphics. . . . • . .

7
8
8
8
9
11
13
13
15

Figures
Figure 2-1. Contents of your file with text and troff/mm
code . . . . • • . • .

Figure 2-2. File printed on a LaserWriter

Figure 2-3. A sample letterhead

Figure 2-4. Sample letter

-i-

Figure 2-5. A sample letter with a footnote
Figure 2-6. Sample line graphic

- ii -

•

14
•

•

Chapter 2
troff/mm

Tutorial
Introduction
troff is the A/UX text processing program that formats text for

typeset-quality output on a typesetter or laser printer. rom (for
"Memorandum Macros") is a general-purpose package of text
formatting macros for use with troff. The examples in this tutorial
were produced on the Apple® LaserWriter printer. This chapter
assumes that you have already been through the v i tutorial in Getting
Started With AIUX.
This chapter takes you through some of the basics of t ro f f in three
tutorial lessons. The first lesson concentrates on producing a business
letter. The second lesson shows you how to create a simple design for
letterhead stationery. The third and final lesson takes you through some
modifications of the letter's appearance.
While these three lessons don't by any means teach you all that troff
has to offer, they should get you well on your way to using troff
(with the rom macros) to produce typeset-quality output.

Lesson 1: Producing a formatted letter
To create a business letter using t ro f f and mrn, you must first create a
new file by invoking one of the A/UX text editors, such as vi. Type
vi letter

and press RETURN.
Once you have opened the new file, you can use vi commands to enter
text and t ro f f and mrn commands. The t ro f f and rom commands
you enter affect how the text will appear on the printed page.
You can enter t ro f f and rom commands just as you enter text, but
they are preceded by a period at the beginning of a line, or by a
backslash (\). For example, the troff command

troff/mm

2-1

.sp

tells the printer to leave one blank line on the printed page. The
command
\fCtroff\fR

causes the word "troff' to print out in Courier font, but words after
"troff" will return to roman font.

Using mm displays
By default, troff "adjusts" text to fill a line up to the right margin. If
you want to print a small section of short lines, for example the name
and address of the person to whom you are writing, enter the text in a
display; this tells troff to print the text just as you have entered it.
Type
.DS
Ms. Pandora S. Bach
Comparative Surveys, Inc.
79 Downing Street
San Jose, California 95128
.DE

The . D S and . DE are mm macros that stand for" display start" and
"display end."
When you print the letter, the name and address print out as follows:
Ms. Pandora S. Bach
Comparative Surveys, Inc.
79 Downing Street
San Jose, California 95128

Paragraphs and spaces
You can leave a space and a half on the printed page between the
address and the salutation by using . P, the paragraph macro. Type
.P

on the line below. DE, and follow it with
Dear Ms. Bach:

on the next line, followed with another . P on the line after that. The

2-2

AlUX Text Processing Tools

file now looks like
.DS
Ms. Pandora S. Bach
Comparative Surveys, Inc.
79 Downing Street
San Jose, California 95128
.DE
.P
Dear Ms. Bach:
.P

where. P stands for "paragraph." Use the paragraph macro wherever
you want to leave extra space or start a paragraph.

Lists
The body of this letter lists four items. To print them out in a bullet
list, with each item preceded by a bullet and indented five spaces, use
the bullet list macro. Starting at the line below the second . P, type
.P
Enclosed please find the following items:
.BL 5
.LI
A copy of a message from Ms. Gail Smith
dated March 6 .
. LI
A copy of the worksheet you requested .
. LI
A \f(BIComparative Surveys\fR records
form and relevant information .
. LE
.P
Thank you for your attention to this account .
•P

Printing the file produces the following output:

troff/mm

2-3

Enclosed please find the following items:
• A copy of a message from Ms. Gail Smith dated March 6.
• A copy of the worksheet you requested.
• A Comparative Surveys records form and relevant
information.
Thank you for your attention to this account.

Font changes
Note that in the text above, the phrase "Comparative Surveys" prints
out in bold italic and the words after in roman. This is caused by the
troff commands \f (B1 and \fR.
The first command
\f(B1

instructs the printer to print the following text in bold italic Times
Roman font.

The second command

\fR
instructs the printer to print the following text in Times Roman font.

Indented text
To finish off your letter, you can use the indent command (. in) to
print text indented on the page. Type
.in +2i
Sincerely yours,
.sp 3
John C. Doe
.in -2i
.sp
Enclosures

When you print the file, this prints out as follows:

2-4

AlUX Text Processing Tools

Sincerely yours,

John C. Doe
Enclosures

Formatting your file
When you have entered all the above text and commands in your file
let ter, save the file on disk and exit vi. When you see the shell
prompt on your screen again, you are ready to format your file and send
it to the printer. (See AIUX Local System Administration for
information about setting up a printer.)
At the shell prompt, type
traff -Tpsc -rom letter I psdit

I lp

This command line sends your file through the t raff program and rom
macros, then sends it to a postprocessor, psdi t, that prepares it for the
LaserWriter, and finally sends it to the printer. See Chapter 1,
"Introduction to A/UX Text Processing," and the reference chapters
that follow for more information.

Obtaining your printout
When the printer has received your file, you will see a message on your
screen. Figures 2-1 and 2-2 show your file letter as it appears on
your screen and on the printed page that is produced.

troff/rrrm

2-5

Figure 2-1. Contents of your file with text and troff/mm code
.DS
Ms. Pandora S. Bach
Comparative Surveys, Inc.
79 Downing Street
San Jose, California 95128
.DE
.P

Dear Ms. Bach:
.P
.P

Enclosed please find the following items:
.BL 5
.LI
A copy of a message from Ms. Gail Smith
dated March 6 .
. LI
A copy of the worksheet you requested .
. LI
A \f(BIComparative Surveys\fR
records form and relevant information .
. LE
.P

Thank you for your attention to this account .
•P

.in +2i
Sincerely yours,
.sp 3
John C. Doe
.in -2i
.sp
Enclosures

2-6

AlUX Text Processing Tools

Figure 2-2. File printed on a LaserWriter
Ms. Pandora S. Bach
Comparative Surveys, Inc.
79 Downing Street
San Jose, California 95128
Dear Ms. Bach:
Enclosed please find the following items:
• A copy of a message from Ms. Gail Smith dated March 6.
• A copy of the worksheet you requested.
• A Comparative Surveys records form and relevant information.
Thank you for your attention to this account.
Sincerely yours,

John C. Doe
Enclosures

Lesson 2: Producing letterhead
To create letterhead stationery, you may first create a new file by
invoking one of the NUX text editors such as vi. Create the new file,
let terhead, by typing
vi letterhead

Once you have opened the new file, you can use vi commands to enter
text and traff and mrn commands to format it.
This simple letterhead will consist of John Doe's name and address at
the top of a page. Because of the physical size of this manual, the
stationery will print out smaller than standard 8.5-by-ll-inch paper. In
"The Size of your Page" you will see how to change the code to print
out a larger version of this letterhead.

troff/mm

2-7

Top-of-page processing
The t ra f f program uses several internal defaults to define how text
will print out. You can change these defaults to fine-tune the format of
your printed page.
For example, traff prints a page number at the top of each page. To
prevent this, you can change the "page header" macro's definition.
The page header macro accepts three fields: the left side of the page,
the center, and the right side. In the definition, the three fields are
separated by single quotes.
At the top of the file, type
.PH " " " "

This defines all three fields as empty.
You may define how many spaces are left at the top of the page, using
the definition
.de TP
.sp 2
This tells the printer to start printing text two spaces below the default
of 1 inch. Enter this definition in the file, below the page header macro.

The size of your text
The traff program uses point size 10 by default. This is the point
size used in this manual. If you want the text of your letter (and any
text in your letterhead) to appear in point size 10, you don't need to
specify this to traff. However, if you want the text to appear slightly
larger. for example. point size 11. you can use the rom command

11 13

This changes the default point size to 11 and the vertical spacing to
13.

The size of your page
Because of the physical size of this manual, the stationery will print out
smaller than standard 8.5-by-ll-inch paper. The length of a line of
text, the width of the margin, and the length of the page itself are
defined using number registers. Number registers are assigned values

2-8

A/UX Text Processing Tools

as follows:
.nr W 4i
.nr 0 2i
.nr L IIi

specifies a 4-inch line
specifies 2-inch margins
specifies an II-inch page

The wnumber register stands for the "width" of the text, and the 0
register stands of the "offset" from the physical width of the page.
To print out a standard-size page, change these definitions as follows:
.nr W 6i
.nr 0 Ii
.nr L IIi

specifies a 6-inch line
specifies I-inch margins
specifies an II-inch page

Designing your letterhead
Enter the following commands in your file:
.sp
\1'4i'
.sp
\s14John C. Doe\sO
.br
\1'4i'
.sp -1.75m
\1'4i'
.sp .25
.tl "'\s9\&P.O. Box 14, Carter, CA 94530\sO'
.sp
.tl "'\*(DT'
.sp 2

These commands are listed below with comment lines that describe
what each one tells the printer to do.

troff/mm

2-9

. sp
\1'4i'
. sp
\s14John C. Doe\sO
. br
\1'4i'
. sp -1.75m
\1'4i'
. sp .25

Leave one blank line .
Draw a line 4 inches long.
Leave one blank line .
Print this text in point size 14.
Break line here (go to next line) .
Draw a line 4 inches long.
Go back up 1.75 "m" units .
Draw a line 4 inches long.
Leave 1/4 vertical space .

.tl "'\s9\&P.O. Box 14, Carter, CA 94530\sO'

. sp
.tl "'\*(DT'
. sp 2

Print this text in point size
9, on the right side of the line.
Leave one blank line .
Print the current date on the
right side of the line.
Leave two blank lines .

Note that the string \ * (DT will print the current date (the date on
which you format your letter). The "title" request

.tl ""
is similar to the page header macro described above in that it defines
three separate fields, enclosed in single quotes. The three fields are the
left side of the page, the center, and the right side. In the letterhead
definition above, the title request is used to justify a string of text on the
right side of the page.
If you format your letterhead file using the troff command line
shown under' 'Obtaining your Printout," your letterhead looks like the
output in Figure 2-3.

2-10

AlUX Text Processing Tools

Figure 2-3. A sample letterhead

John C. Doe
P.O. Box 14, Carter, CA 94530

August 28, 1987

Printing your letter on letterhead
Now that you have created a file containing the traff and rom codes
to produce letterhead stationery, save the file on disk and exit vi. You
can now use this letterhead with any letters you write by formatting it
on the same command line as your letter. Because the letterhead must
print before the text of your letter, the command line should look like
this:
troff -Tpsc -mm letterhead letter I psdit I lp

This command line sends both files through the traff program and
rom macros. The letter this produces looks like the one in Figure 2-4.

troff/mm.

2-11

Figure 2·4. Sample letter

John C. Doe
P.O. Box 14, Carter, CA 94530

August 28, 1987

Ms. Pandora S. Bach
Comparative Surveys, Inc.
79 Downing Street
San Jose, California 95128
Dear Ms. Bach:
Enclosed please find the following items:
• A copy of a message from Ms. Gail Smith dated March 6.
• A copy of the worksheet you requested.
• A Comparative Surveys records form and relevant information.
Thank you for your attention to this account.
Sincerely yours,

JohnC. Doe
Enclosures

2-12

A/UX Text Processing Tools

Lesson 3: Modifying the appearance of a page
Now that you have created a simple letter and printed it out on
letterhead stationery, you may want to modify the letter to include
more information. In this lesson, you will learn how to produce a
footnote and line graphics in your letter.

Producing a footnote
To include a footnote in your file named letter, first open the file
using an editor such as vi:
vi letter

Move your cursor to the place in the file where you want the footnote
to be referenced. This example uses a "dagger" symbol rather than a
number. For example, move to the line in your file that reads
A copy of the worksheet you requested.

and place the dagger symbol at the end of the line:
A copy of the worksheet you requested.\(dg

When you include a footnote in your text, use the rom footnote macros .
. FS stands for "footnote start" and. FE for "footnote end." These
should be placed as close as possible to the footnote reference (in this
case, \ (dg). On the next line in your file, type
.FS \(dg
Note that the worksheet is dated March 20 .
. FE

Your letter will look like the one in Figure 2-5.

troff/ram

2-13

Figure 2-5. A sample letter with a footnote

John C. Doe
P.O. Box 14, Carter, CA 94530

August 28, 1987

Ms. Pandora S. Bach
Comparative Surveys, Inc.
79 Downing Street
San Jose, California 95128
Dear Ms. Bach:
Enclosed please find the following items:
• A copy of a message from Ms. Gail Smith dated March 6.
• A copy of the worksheet you requested. t
• A Comparative Surveys records form and relevant information.
Thank you for your attention to this account.
Sincerely yours,

John C. Doe
Enclosures

Please note that the worksheet is dated March 20.

2-14

AJUX Text Processing Tools

Producing graphics
You can include simple line drawings in a document by using the
preprocessor pic after you've entered appropriate picture
specifications in your file.
Graphics can be useful in documents. For example, you might want to
order some printed envelopes to go along with your custom stationery.
A good way to let the printer know how you want it to look is to
enclose a picture of the printed envelope (a picture is worth ...). You
can specify such a picture by including the following input in your file:
.PS
A: box ht 2i wid 4i
line from A.nw to A.c
line from A.ne to A.c
box invis ht .75i "John C. Doe" "P.O. Box 14"\
"Carter, CA" "94350" with .n at A.n
.PE

You can then process this with the command line
pic letter I troff -Tpsc -rom I psdit

I Ip

The output, in part, will look like Figure 2-6.

Figure 2-6. Sample line graphic

John C. Doe
P.O. Box 14
Carter, CA
94350

troff/mm

2-15

Chapter 3

nroff/troff Reference

Contents
1. Introduction

2. Usage.

•

6
6
6

3. General information
. • • • •
3.1 Form of input
.•.•.
3.2 Formatter and device resolution
3.3 Numeric parameter input
3.4 Numeric expressions
3.5 Notation • • . . •
4. Font and character size control
4.1 Character Set. . • • .
4.2 Fonts • • • . . . •
4.3 Character size
5. Page control.

•

•
.

8
9
. • • .
• •

9
9
10
10
13

6. Text filling, adjusting, and centering
•.•••
6.1 Filling and adjusting
6.1.1 Interrupted text

16
16
17

7. Vertical spacing
• • • . . . . • .
7.1 Base-line spacing
7.2 Extra line space • .
•••••.
7.3 Blocks of vertical space

18
18
19
19

8. Line length and indenting.

•

• .

9. Macros, strings, diversions, and position traps •
9.1 Macros and strings . • • • . . .
9.2 Copy mode input interpretation
9.3 Arguments
9.4 Diversions

-i-

22
22
23
23
25

9.5

Traps

10. Number registers
11. Tabs, leaders, and fields
11.1 Tabs and leaders.
11.2 Fields • • • .

•
•
.

•
.
.

•

30
30

•

12. Input/output conventions and character
translations • • • . . • . •
12.1 Input character translations
12.2 Ligatures • • . • . • •
12.3 Backspacing, underlining, and overstriking
12.4 Control characters . . • • . . . •
12.5 Output translation
• . • • .
12.6 Transparent throughput. • • •
12.7 Comments and concealed newline
characters • • • • • . • •

33
33
33

33
•

34
34

36
36
36
36
36

13. Local horizontal/vertical motion and width
...••
13.1 Local motion. . • •
13.2 Width function . . . • • . • .
13.3 Mark horizontal place

14. Overstrike, zero-width, bracket, and line drawing
functions. • • • . •
14.1 Overstrike
14.2 Zero-width characters
14.3 Large brackets
14.4 Line drawing •

37
37
37
38
38

15. Hyphenation •

16. Three-part titles

17. Output line numbering .

18. Conditional acceptance of input

19. Environment switching

20. Insertions from standard input

21. Input/output file switching

- ii -

22. Miscellaneous

23. Output and error messages

24. Reference tables
24.1 Escape sequences for characters, indicators, and
functions • •
••••
....
24.2 Naming conventions for special characters on the
standard fonts
.•••
...•
24.3 Naming conventions for Greek characters on the
....
special font
. • •.
24.4 Naming conventions for special characters on the
special font
. . . .
24.5 Predefined general number registers • .
24.6 Predefined read-only number registers

- iii -

51
53
54
55
56
57

Chapter 3
nroff/troff Reference

1. Introduction
This document is not geared toward the beginner but toward someone
who is already familiar with using macro packages and is interested in
altering or writing macros. It is also a useful reference for n ro f f and
t ro f f commands that are not available in existing macro packages.
The nroff text formatter formats text for typewriter-like terminals.
The troff formatter formats text destined to be printed on a
phototypesetter, but is intended to be converted by a postprocessor into
codes that will drive a particular phototypesetter.
Both nroff and troff processors accept lines of text interspersed
with lines of format control information. They format the text into a
printable, paginated document having a user-designed style. The
nroff and troff formatters offer unusual freedom in document
styling, including
•
•
•
•
•
•
•
•

Versatile paragraph and section control
Flexible-style headers and footers
Generation of footnotes
Automatic sequence numbering for paragraphs and sections
Multiple column output
Font and point-size control (troff only)
Arbitrary horizontal and vertical local motions at any point
Overstriking, bracket construction, and line drawing functions.

Because nroff and troff formatters are reasonably compatible, it is
usually possible to prepare input acceptable to both. Conditional input
is provided that enables you to embed input expressly destined for
either program (see "Conditional acceptance of input"). For example,
.if n .sp
.if t .sp .5

\"if nroff, then go one space
\"if troff, then go one-half space

nroff/troff Reference

3-1

The major dissimilarity between the two formatters is spacing. nraff
does not have fractional-space capabilities. A traff vertical-space
request, such as . sp .5, will be ignored or . sp 1.3 will be treated
as one space by nraff. Keep in mind that nraff output devices use
constant-width characters, whereas in traff, character widths vary.
This is important when determining distances for setting tabs. Localmotion escape characters also have different effects in nraff and
traff (see "Local Motion").
The nraff formatter can prepare output directly for a variety of
terminal types and is capable of utilizing the full resolution of each
terminal.
The traff text formatter is a program that can drive virtually any
phototypesetter, because its output is an ASCII code describing the
position, font, size, and so on, of characters to be typeset on a page.
This output must be converted by another program, called a
postprocessor, into codes a particular phototypesetter will understand.
Parameters such as fonts, character sizes, and special characters depend
on the phototypesetter being driven.
Full user control over fonts, sizes, and character positions, as well as
the usual features of a formatter (right-margin justification, automatic
hyphenation, page titling and numbering, and so on) are provided by
the traff processor. It also provides macros, arithmetic variables and
operations, and conditional testing for complicated formatting tasks.

2. Usage
The general form of invoking an nraff or traff formatter at the
NUX operating system command level is
nraff [options] [files]

or
traff [options] [files]

where options represents any of a number of flag options and files
represents the list of files containing the document to be formatted. An
argument consisting of a single minus sign ( - ) is taken to be a filename
corresponding to the standard input. Input is taken from the standard
input if no filenames are given. Options may appear in any order but
must appear before the files.

3-2

A/UX Text Processing Tools

Option

Effect

-a

(troff only.) Send a printable approximation in
American Standard Code for Information Interchange
(ASCII) character set of the results to the standard output.
This approximates a display of the document.

-e

(nroff only.) Produce equally spaced words in adjusted
lines using full terminal resolution.

-Fdir

Get access to font information from the directory
di r / devname where name is the default output device.
The default font information directory is
/usr / lib/ font/ devname.

-h

(nroff only.) Use output tabs during horizontal spacing
to speed output and to reduce output byte count. Device
tab settings are assumed to be every eight nominal
character widths. The default settings of logical input tabs
are also every eight nominal character widths.

-i

Read standard input after the input files are exhausted.

-mname

Prefix the / u s r /1 ib / tma c / tma c .name macro file to
the input files. Multiple -m macro package requests on a
command line are accepted and are processed in sequence.

-nn

Number the first generated page n.

-olist

Print only pages whose page numbers appear in list, which
can consist of comma-separated numbers, number ranges,
or both.
• A list of comma-separated numbers such as n, m
means pages n and m.
• A number range has the form n -m and means pages
n through m.
• An initial-n means from the beginning to page n.
• A final n - means from page n to the end.

-q

Invoke the simultaneous input/output mode of the . rd
request.

nroff/troff Reference

3-3

- rxn

Set register x (one character) to n.

-sn

Stop every n pages. The nroff formatter will halt after
every n pages (default n=l) to allow paper loading or
changing and will resume upon receipt of a new line.
When using troff, it is probably preferable to use the -s
option on the postprocessor if one exists.

-Tname

Specify the name of the output terminal type. Currently
defined names are: 1 p for generic printers that can
underline and tab, 2631 for the Hewlett-Packard 2631
printer in regular mode, 2 631- c for the Hew lett-Packard
2631 printer in compressed mode, 26 31-e for the
Hewlett Packard 2631 printer in expanded mode, 300 for
the DASI 300,300-12 for DASI 300 terminal set to 12pitch, 300 s for the DASI 300s, 300 s -12 for DASI 300s
terminal set to 12-pitch, 37 for the TELETYPE Model 37
(nroff default), 382 for the DCT-382 terminal, 4000a
for the TRENDATA 400a terminal, 450 for the DASI
450, 450 -12 for the DASI 450 set to 12-pitch, 832 for
the Anderson Jacobson 832 terminal, 8510 for the
C.ITOH printer, tn300 for the GE TermiNet 300 (or any
terminal without half-line capabilities), X for the EBCDIC
TX train printer.
In troff, the -T option may be used to specify the output
device. The psc argument ("troff -Tpsc") is
required for PostScript output on a LaserWriter. (This is
the NUX t roff default.)

-u[n]

(nroff only.) Set the emboldening factor (number of
character overstrikes) in the formatter for the third font
position (bold) to be n (zero if n is missing). It is not
possible to turn off the emboldening in nroff if the
overstriking is controlled locally by the printing device.

-z

Suppress formatted output. Only message output will
occur (from. tm requests and diagnostics).

Each option is invoked as a separate argument. For example,

3-4

AlUX Text Processing Tools

nroff -04,8-10 -T300s -mabc chapter1 chapter2

requests formatting of pages 4,8,9, and 10 of a document contained in
the files named chapterl and chapter2, specifies the output
terminal as a DASI 3OOs, and invokes the macro package abc.
Various preprocessors and postprocessors are available for use with the
nroff and troff formatters:
• The equation preprocessors are neqn and eqn (for nroff and
troff formatters, respectively).
• The table-construction preprocessor is tbl.
• The picture drawing preprocessor for the t ro f f formatter is
pic.
• A reverse-line postprocessor for multiple-column nroff
formatter output on terminals without reverse-line ability is col.
The TELETYPE Model 37 escape sequences that the nroff
formatter produces by default are expected by col.
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:
tbl file I eqn I troff [options] I typesetter
The first pipe (I) indicates the piping of tbl output to eqn input; the
second pipe indicates the piping of eqn output to the troff formatter
input. Finally, the accumulated output from these processes is piped to
a postprocessor that interprets troff's output language for the output
device.
tc 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:
pic file I tbl I eqn I troff [options] I tc
The troff formatter depends on a postprocessor to convert its output
into codes for a particular phototypesetter.

nroff/troff Reference

3-5

3. General information
This section describes some general principles of the nroff and
troff formatters.

3.1 Form of Input
Input data consists of text lines, which are destined to be printed,
interspersed with control lines, which set parameters or otherwise
control subsequent processing. Control lines begin with a control
character, normally a period or an acute accent ('), followed by a 1- or
2-character name that specifies a basic request or the substitution of a
user-defined macro in place of the control line. The acute accent
control character suppresses the break function (the forced output of a
partially filled line) caused by certain requests. Control characters may
be separated from request/macro names by white space (spaces, tabs or
both) for aesthetic reasons. Names must be followed by either a space
or a newline character. Control lines with unrecognized request/macro
names are ignored. There are tables in each section of this chapter that
contain explanations of the request/macro names.
Various special functions may be introduced anywhere in the input by
means of an escape character (\). For example, the function \nr
causes the interpolation of the contents of the number register r in place
of the function. Number register r is either x for a single letter register
name or (xx for a 2-character register name. These escape sequences
for characters, indicators, and functions are summarized at the end of
this chapter.

3.2 Formatter and device resolution
The nroff processor internally uses 240 units/inch, corresponding to
the least common multiple of the horizontal and vertical resolutions of
various typewriter-like output devices. Units in troff are devicedependent. t ro f f rounds horizontaVvertical numeric parameter input
to its internal horizontaVvertical resolution. nroff similarly rounds
numeric input to the actual resolution of the output device indicated by
the -T option (default TELETYPE Model 37).

3.3 Numeric parameter input
Both nroff and troff fonnatters accept numeric input with the
appended scale indicators shown in the following table, where S is the
current type size in points, V is the current vertical line spacing in basic
units, and C is a nominal character width in basic units. The number of

3-6

AlUX Text Processing Tools

basic units is device-dependent in troff.

Scale
indicator

c
p

m
n

p
u
v

none

Meaning

Inch
Centimeter
Pica = 1/6 inch
em =S points
en =em/2
Point = 1/72 inch
Basic unit
Verticalline space
Default

Number of basic units
nro££

240
240x50/127
240/6
C
C, same as em

240n2
1
V

In nroff processors, both em and en are taken to be equal to C, which
is output-device dependent; common values are 1/10 and 1/12 inch.
Actual character widths in the nroff formatter need not be all the
same. Constructed characters (such as -» are often extra wide.
Default scaling is:
• em for horizontally oriented requests (.11, . in, . ti, . ta,
.It, .po, . me) and functions (\h, \1).
• V for vertically oriented requests (. pI, . wh, . eh, . dt, . sp,
. sv, . ne, . rt) and functions (\ v, \x, \L)
• p for requests. vs, . vs and functions \H and \s.
• u for. nr, . if, and. ie requests.
All other requests ignore scale indicators. When a number register
containing an already appropriately scaled number is interpolated to
provide numeric input, the basic unit scale indicator (u) may need to be
appended to 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 prefixed to a number n to
generate the distance to the vertical or horizontal place n.
• For vertically oriented requests and functions, I n becomes the
distance in basic units from the current vertical place on the page

nroff/troff Reference

3-7

or in a diversion (see "Macros, Strings, Diversions, and Position
Traps") to the vertical place n.
• For all other requests and functions, I n 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.2 centimeters from the top of
the page.

3.4 Numeric expressions
Wherever numeric input is expected, the following may be used:
• an expression involving parentheses
• the arithmetic operators +, -, I, *, % (mod)
• the logical operators <, >, <=, >=, =, ==, & (and), : (or)
Except where controlled by parentheses, evaluation of expressions is
left to right; there is no operator precedence. In the case of certain
requests, an initial + or - is stripped and interpreted as an increment or
decrement indicator. 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+3m)/2u
sets the line length to Y2 the sum of 4.25 inches + 2 picas + 3 ems (30
points because the point size is 10).

Note: The use of white space in arithmetic expressions is not
permitted. There is no precedence among arithmetic and
logical operators. n ro f fit ro f f expressions do not recognize
decimal multipliers or divisors; a high level of precision may be
achieved by mixing scales within expressions.

3-8

NUX Text Processing Tools

3.5 Notation
Numeric parameters are indicated in this chapter in two ways. A ±n
means that the argument may take the forms n, +n, or -n and that the
corresponding effect 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, numeric input is either ignored or truncated to a
reasonable value. For example, most requests expect to set parameters
to non-negative values; exceptions are . sp, . wh, . ch, . nr, and. if.
If no argument is specified, then the . ps, . ft, . po, . VS, .1s, .11,
. in, and . It requests restore the previous value.
Single character arguments are indicated by single lowercase letters
and one- or two-character arguments are indicated by a pair of
lowercase letters. Character string arguments are indicated by
multicharacter mnemonics.

4. Font and character size control
4.1 Character Set
The t ro f f character set consists of the so-called Commercial II
character set plus a Special Mathematical font character set. The
ASCII characters are entered as themselves (with three exceptions);
and non-ASCII characters are entered in the form \ (xx, where xx is a
two-character name given at the end of this chapter. The three ASCII
character exceptions are mapped as follows:
ASCII Input
Character

Name

Acute accent
Grave accent
Minus

Printed by troff
Character

Name

Close quote
Open quote
Hyphen

The characters " " and - may be entered by typing \ " \ ' , and \ -,
respectively, or by typing their names (\ (aa, \ (g a, and \ (mi). The
ASCII characters @, #, It, " ',<, >, \ {, }, -, ", and _ exist on the
Special Mathematical font and are printed as a one-em space if that
font is not mounted.

nroff/troff Reference

3-9

The nroff processor understands the entire troff character set but
can print only:
• ASCII characters
• Additional characters that are available on the output device
• Characters that can be constructed by overstriking or by other
combinations
• Characters that can be mapped into other printable characters.
Each printer's capability is determined by a driving table prepared for
each device. The characters " ", and - print as themselves.

4.2 Fonts
Default fonts may differ from device to device. Typically, the fonts
will include at least the following: Times Roman (R), Times Italic (I),
Times Bold (B), and Special Mathematical (8). The current font may
be changed by use of the . f t 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 numeric font position. It is not necessary to
change to the Special Font; characters on that font are automatically
handled. They are invoked by their four-character input names (see
"Character Set").
A request for a named but not mounted font is translated into a request
to mount the font at position zero. This position is reserved for such
dynamic requests and is otherwise inaccessible. The troff processor
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,jrepresents either a oneor two-character font name or the numeric font position. The current
font is available as numeric position in the read-only number register
.f.

Font control is understood by the nroff formatter which normally
underlines italic characters and overstrikes bold characters. Other font
changes are usually ignored.

4.3 Character size
The available character point sizes depend on the individual printing
device. The . ps request is used to change or to restore the default
point size. Alternatively, the point size may be changed between any
two characters by embedding a \ sn at the desired point to set the size

3-10

NUX Text Processing Tools

to n or a \ s±n (1 ~ n ~ 9) to increase or decrease the size by n; \ s 0
restores the previous size. Requested point size values that are between
two valid sizes yield the closer legal size. The current size is available
in the . s number register.
In traff the escape sequence \H' n' sets the height ofa character
without affecting its width. n can be expressed in absolute values or in
relative values of the form ±no
Note that the nraff formatter ignores type size control.
Request
form
• cs

[n] [m]

• ps [±n]

Initial
value

If no
.
Explanation
argument

off

10 point

Set constant character space (width)
mode on for font/(if mounted). The
width of every character is assumed to
be n(36 ems. If m is absent, the em is
that of the character 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 / are also so treated. If n is
absent, the mode is turned off. The
mode must still (or again) be in effect
when the characters are printed. There
is no effect in the nroff formatter .
previous

nroff/troff Reference

Set point size to ±n. Any valid 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

3-11

Request
form

Initial
value

If no
t Explanation
argumen
remembered. For point size changes
within a line of text, sequences \sn or
\s±n can be used. Relevant
parameters are a part of the current
I!nvironment. There is no effect in the
nroff formatter.

• S5

12/36 em

ignored

Set space-character size to n/36 ems .
This size is the minimum word spacing
in adjusted text. Relevant parameters
are a part of the current environment.
There is no effect in the nroff
formatter .

[n]

off

Embolden font/by n-l units.
Characters in font/will be artificially
emboldened by printing each one twice,
separated by n-l basic units. A
reasonable value for n is 3 when the
character size is in the vicinity of 10
points. If n is missing, the embolden
mode is turned off. The mode must
still (or again) be in effect when the
characters are physically printed.

.bd sin

off

Embolden special font when current
font is f. The characters in the special
font will be emboldened whenever the
current font is f. The mode must still
(or again) be in effect when the
characters are physically printed.

. bd

• fp n

3-12

[file]

R,I,B,S

ignored

Position font. A font named / is
mounted on position n. It is a fatal
error if/is not known. . fp accepts a
third optional argument, file, which is
an alternate version of the fontf.

A/UX Text Processing Tools

form

Request

Initial
value

If no
t Explanation
argumen

. ft [f]

roman

Change to font f if is x, oU, n, or P) .
Font P means the previous font. For
font changes within a line of text,
sequences \fx, \f (xx, or \fn can be
used. Relevant parameters are a part of
the current environment.

. 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, \S,
used to slant output characters by a number of specified degrees. This
escape sequence is stated as \ S' n' where n may be any integer.
negative or positive. 0 turns slanting off.

5. Page control
Top and bottom margins are not automatically provided. They may be
defined by two macros which set traps at vertical positions 0 (top) and
-n (n from the bottom) (see "Traps"). 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.
References to the current diversion mean that the mechanism being
described works during both ordinary and diverted output (the former
is considered as the top diversion level).
Physical limitations on the nroff and troff processor output are
output-device dependent.

Note: Values separated by a semicolon (;) in the "Initial
value"field below are for the nroff and troff formatters,
respectively.

nroff/troff Reference

3-13

Request
form

In itia I If no
value argument Explanation

.bp [±n]

n=l

.mk [r]

none

• ne [n]

Begin page. The current page is
ejected and a new page is begun. If ±n
is given, the new page nwnber will be
±n. The scale indicator is ignored if
not specified in the request. The
request causes a break:. The use of' as
the control character (instead of .)
suppresses the break: function. The
request with no n is inhibited by the
. n s request.
internal

Mark current vertical place in an
internal register (associated with the
current diversion level) or in register r,
if given. The request is used in
conjunction with "return to marked
vertical place in current diversion"
request (. rt). Mode or relevant
parameters are associated with current
diversion level.

n = Iv

Need n vertical spaces. The scale
indicator is ignored if not specified in
the request.
• If the distance to the next trap
position (d) is less than n, 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 d is less than vertical spacing (v),
another line could still be output
and spring the trap.
In a diversion, d is the distance to the
diversion trap (if any) or is very large.
Mode or relevant parameters are
associated with current diversion level.

3-14

AJUX Text Processing Tools

Request
form

Initial
value

If no
argument

.pl [±n]

11 in

Set page length to ±n. The internal
limitation is about 75 inches in the
troff formatter and 136 inches in the
nroff formatter. Current page length
is available in the . p register. The
scale indicator is ignored if not
specified in the request.

.pn ±n

n=l

ignored

Set page number. The next page (when
it occurs) will have the page number
±n. The request must occur before the
initial pseudopage transition to affect
the page number of the first page. The
current page number is in the %
register.

.po [±n]

O;lin

Set page offset. The current left margin
is set to ±n. The scale indicator is
ignored if not specified in the request.
The troff formatter initial value
provides about 1 inch of paper margin.
The current page offset is available in
the .0 register.

. rt [±n]

none

internal

Return (upward only) to marked
vertical place in current diversion. If
±n (with respect to place) is given, the
vertical place is ±n from the top of the
page or diversion. If n is absent, the
vertical place is marked by a previous
• mk .. The . sp request may be used in
all cases instead of . r t by spacing to
the absolute place stored in an explicit
register; for example, using the
sequence • mk r . ..• sp I \ \nru.
Mode or relevant parameters are
associated with current diversion level.
The scale indicator is ignored if not
specified in the request.

nroff/troff Reference

Explanation

3-15

6. Text filling, adjusting, and centering
6.1 Filling and adjusting
Normally, words are collected from input text lines and assembled into
an output text line until some word does not fit. An attempt may be
made to hyphenate the word in an effort to assemble a part of it into the
output line. The spaces between the words on the output line are
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 or the beginning or the end of the input line. 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 using a backslash-space character (\SPACE); this separates the
words with an unpaddable space. The adjusted word spacings are
uniform in the traff formatter, and the minimum interword spacing
can be controlled with the . s s request. In the nraff formatter, they
are normally nonuniform because of quantization to character-size
spaces; however, the flag option -e causes uniform spacing with full
output device resolution.
Filling, adjustment, and hyphenation can all be prevented or controlled.
The text length on the last line output is available in the . n number
register, and text base-line position on the page for this line is in the nl
number register. The text base-line high-water mark (lowest place) on
the current page is in the . h register.
An input text line ending with period (.), question mark (?), or
exclamation mark (!) is taken to be the end of a sentence, and an
additional space character is automatically provided during filling.
Multiple interword space characters found in the input are retained,
except for trailing spaces; initial spaces also cause a break.
To obtain a specific break in a line when filling is in effect, a \p
sequence may be embedded in or attached to a word to cause a break at
the end of that word and have the resulting output of the line containing
that word spread out to fill the current line length.
A text input line that happens to begin with a control character (such as
a period) can be made to be interpreted as the actual character itself by
prefacing it with the nonprinting, zero-width filler character (\ &).
Another way is to specify output translation of some convenient

3-16

A/UX Text Processing Tools

character into the control character using the . t r request.

6.1.1 Interrupted text
Copying an input line in no-fill mode can be interrupted by terminating
the partial line with a \ c escape sequence. 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 or partial word will be
forced out.
Request Initial If no
t Explanation
form
value argumen
. ad [n]

adjust

Adjust. Output lines are adjusted with
mode n. If the type indicator (n) is
present, the adjustment type is as
follows:
Indicator Adjust type
1
adjust left margin only

r
c

born
absent

adjust right margin only
center
adjust both margins
unchanged

The adjustment type indicator n may
also be a number obtained from the • j
register. If fill mode is not on,
adjustment will be deferred. Relevant
parameters are a part of the current
environment.
. br

nroff/troff Reference

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

3-17

Request Initial
form
value

If no
.
argument Explanation

• ce [n]

off

n=l

. fi

fill

Set fill mode. The request causes a
break. Subsequent output lines are
filled to provide an even right margin.
Relevant parameters are a part of the
current environment.

.na

adjust

Set no adjust. Output line adjusting is
not done. Since adjustment is turned
off, the right margin will be ragged.
Adjustment type for the . ad request is
not changed. Output line filling still
occurs if fill mode is on. Relevant
parameters are a part of the current
environment.

.nf

fill

Set no-fill mode. Subsequent output
lines are neither filled nor adjusted.
The request nonnally causes a break.
Input text lines are copied directly to
output lines without regard for the
current line length. Relevant
parameters are a part of the current
environment.

Center. The next n input text lines are
centered within the current line-length
(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.
The request nonnally causes a break.
Relevant parameters are a part of the
current environment.

7. Vertical spacing
7.1 Base-line spacing
Vertical spacing size (v) between base lines of successive output lines
can be set using the . vs request with a device-dependent resolution.
Spacing size must be large enough to accommodate character sizes on

3-18

AJUX Text Processing Tools

affected output lines. For the common type sizes (9 through 12 points),
usual typesetting practice is to set v to two points greater than the point
size; traff default is lO-point type on a l2-point spacing. The
current v is available in the . v register. Multiple-v line separation (for
example, double spacing) may be obtained with a . 1 s (line spacing)
request.

7.2 Extra line space
If a word contains a vertically tall construct requiring the output line
containing it to have extra vertical space before or after it or in both
places, the extra line space function \ x, n' can be embedded in or
attached to that word. In this and in other functions having a pair of
delimiters around their parameters, the delimiter choice is arbitrary
except that it cannot look like the continuation of a number expression
forn.
• If n is negative, the output line containing the word will be
preceded by n extra vertical spaces.
• If n is positive, the output line containing the word will be
followed by n extra vertical spaces.
• If successive requests for extra space apply to the same line, the
maximum value is used.

The most recently used post-line extra line space is available in the. a
register.

7.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 the . s v
request.

Note: Values separated by a semicolon (;) in the "Initial
value"field below are for the nraff and traff formatters,
respectively.

nroff/troff Reference

3-19

Request
form

Initial
value

If no
.
Explanation
argumen t

.ls [n]

n=l

.ns

space

Line spacing set to ±n. Output n-l
blank lines (vs) after each output text
line. If the text or previous appended
blank line reached a trap position,
appended blank lines are omitted.
Relevant parameters are a part of the
current environment.
Set no-space mode. The no-space
mode inhibits • sp and • bp requests
without a next page number. It is
turned off when a line of output occurs
or with the . r s request. Mode or
relevant parameters are associated with
current diversion level.

.os

Output saved vertical space. The
request is used to output a block of
vertical space requested by an earlier
. sv request. The no-space mode
( . n s) has no effect.

.rs

Restore spacing. The no-space mode
(. ns) is turned off. Mode or relevant
parameters are associated with current
diversion level.

• sp [n]

3-20

n= Iv

Space vertically. The request provides
spaces 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 of the nearest trap. If the nospace mode ( • n s) is on, no spacing
occurs. The scale indicator is ignored
if not specified in the request. The
request causes a break.

A/UX Text Processing Tools

Request
form

Initial
value

.sv [n]

. vs [n]

I/6in;I2pts

Blank line

If no
Explanation
argument
n= Iv

Save a contiguous vertical block of size
n. If the distance to the next trap is
greater than n, n vertical spaces are
produced. If the distance to the next
trap is less than n, no vertical space is
immediately produced; but n is
remembered for later output (. os).
Subsequent. sv requests overwrite any
still remembered n. The no-space
mode ( • n 5) has no effect. The scale
indicator is ignored if not specified in
the request.

Set vertical base-line spacing size v.
Transient extra vertical spaces are
available with \x' n' . The scale
indicator is ignored if not specified in
the request. Relevant parameters are a
part of the current environment.
This condition causes a break and
output of a blank line (just as does. sp
1).

8. Line length and indenting
The maximum line length for fill mode may be set with a .11 request.
The indent may be set with a . in request; an indent applicable to only
the next output line may be set with the . t i (temporary indent)
request.
The line length includes indent space but not page offset space. The
line length minus the indent is the basis for centering with the . ce
request. If a partially collected line exists, the effect of .11, . in, or
. t i is delayed until after that line is produced. 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 . 1 and . i,
respectively. The length of three-part titles produced by . t l is

nroff/trof£ Reference

3-21

independently set by . 1 t (see "Three-Part Titles").
Request
form

Initial If no
Explanation
value argument

. in [±n]

n =0

. 11 [±n]

6.5 in previous

Indent. The indent is set to ±n and
prefixed to each output line. The scale
indicator is ignored if not specified in
the request. Relevant parameters are a
part of the current environment. The
request causes a break.
Line length. The line length is set to

±no The scale indicator is ignored if
not specified in the request. Relevant
parameters are a part of the current
environment.

.ti ±n

ignored

Temporary indent. The next output
text line will be indented a distance ±n
with respect to the current indent. The
resulting total indent may not be
negative. The current indent is not
changed. The value of the current
indent (stored in the . i register) is
unchanged. The scale indicator is
ignored if not specified in the request.
Relevant parameters are a part of the
current environment. The request
causes a break.

9. Macros, strings, diverSions, and position traps
9.1 Macros and strings
A macro is a named set of arbitrary lines that can be invoked by name
or with a trap. A string is a named string of characters, not including a
newline character, that can be interpolated by name at any point.
Request, macro, and string names share the same name list. Macro and
string names may be 1- or 2-characters long and may usurp previously
defined request, macro, or string names. Any of these entities may be
renamed with . rn or removed with . rm.

3-22

AlUX Text Processing Tools

• Macros are created by . de and . di and appended by . am and
. da ( . di and . da cause nonnal output to be stored in a
macro).
• Strings are created by . ds and appended by . as.
A macro is invoked in the same way as a request; a control line
beginning . xx will interpolate the contents of macro xx. The remainder
of the line can contain up to nine arguments. The strings x and xx are
interpolated at any desired point with \ *x and \ * (xx, respectively.
String references and macro invocations can be nested within text.

9.2 Copy mode input interpretation
During the definition and extension of strings and macros in the current
environment, the input is read in copy mode. The input is copied
without interpretation except that:
• Contents of number registers indicated by \n are interpolated.
• Strings indicated by \
strings").

* are interpolated (see' 'Macros and

• Arguments indicated by \ $ are interpolated.
• Concealed newline characters indicated by \ are
eliminated.
• Comments indicated by \ " are eliminated (see' 'Comments and
Concealed Newline Characters").
• \ t and \ a are interpreted as ASCII horizontal tab and start of

heading (SOH), respectively (see "Tabs and Leaders").
• \ \ is interpreted as "\".
• \. is interpreted as " . ".
These interpretations can be suppressed by prefixing a \. For example,
because \ \ maps into a \, \ \n will copy as \n which will be
interpreted as a number register indicator when the macro or string is
reread.

9.3 Arguments
When a macro is invoked by name, the remainder of the line can
contain up to nine arguments. The argument separator is the space

nroff/troff Reference

3-23

character, and arguments may be surrounded by double-quotes to
permit embedded space characters. Pairs of double-quotes may be
embedded in double-quoted arguments to represent a single doublequote. If the desired arguments will not fit on a line, a concealed
newline character 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 previous level become unavailable until the
macro is completely read and the previous level is restored. A macro's
own arguments can be interpolated at any point within the macro with
\ $n, which interpolates the nth argument (1 ~ n ~ 9). If an invoked
argument does not exist, a null string results. For example, the macro
xx may be defined by

.de xx
\" begin definition
Today is \\$1 the \\$2.
\" end definition
and called by

.xx Monday 14th
I

to produce the text
Today is Monday the 14th.
The \ $ was concealed in the definition with a preceding backslash.
The number of currently available arguments is in the . $ register.
No arguments are available:
• at the top (nonmacro) level in this implementation
• from within a string because string referencing is implemented as
an input-level pushdown
• 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 (interpolated at copy time),
and it is advisable to conceal string references (with an extra \) to
delay interpolation until argument reference time.

3-24

AlUX Text Processing Tools

9.4 Diversions
Processed output may be diverted into a macro for purposes such as
footnote processing or detennining the horizontal and vertical size of
some text for conditional changing of pages or columns. A single
diversion trap can 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
( . c s) 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 . c s or
. bd request with the transparent mechanism described in
"Transparent Throughput' ').
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 diversion level 0). These parameters and
registers are
•
•
•
•
•
•

diversion trap and associated macro
no-space mode
internally saved marked place (see . mk and . rt)
current vertical place ( . d register)
current high-water text base line ( . h register)
current diversion name ( . z register).

9.5 Traps
Three types of trap mechanisms are available:
• page trap
• diversion trap
• input-line-count trap.
Macro-invocation traps can be planted using . wh requests at any page
position including the top. This trap position can be changed using the
. ch request. 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

nroff/troff

Reference

3-25

unless and until the first one is moved. If the first planted trap 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 generated
whose vertical size reaches or sweeps past the trap position. 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.
Macro-invocation traps, effective in the current diversion, can be
planted using. dt requests. The . t register works in a diversion. If
there is no subsequent trap, a large distance is returned.
Request
form
• am xx [yy]

Initial If no
Explanation
value argument
.yy= ..

Append to macro xx (append version of
. de).

· a s xx string

ignored

• ch xx [n]

Append string to string xx (append
version of . ds).
Change trap location. Change the trap
position for macro xx to be n. In the
absence of n, the trap, if it exists, is
removed. The scale indicator is
ignored if not specified in the request.

.da [xx]

end

Divert and append to macro xx (append
version of the . di request). Mode or
relevant parameters are associated with
current diversion level.

.de xx [yy]

.yy= ..

Define or redefine macro xx. The
contents of the macro begin on the next
input line. Input lines are copied in
copy mode until the definition is
terminated by a line beginning with
. yy. The macro yy is then called.

3-26

A/UX Text Processing Tools

Request
form

Initial If no
Explanation
value argument
In the absence of yy, the definition is
terminated by a line beginning with ...
A macro may contain . de requests
provided the tenninating macros differ
or the contained definition tenninator is
concealed; . • can be concealed as
\ \ .• which will copy as \ .. and be
reread as •..

. di [xx]

end

Divert output to macro xx. Nonnal text
processing occurs during diversion
except that page offsetting is not done.
The diversion ends when the request
. di or . da is encountered without an
argument; extraneous requests of this
type should not appear when nested
diversions are being used. Mode or
relevant parameters are associated with
current diversion level.

. ds xx string

ignored

Define a string xx containing string.
Any initial double-quote in string is
stripped to pennit initial blanks .

. dt [n] [xx]

off

Install a diversion trap at position n in
the current diversion to invoke macro
xx. Another. dt will redefine the
diversion trap. If no arguments are
given, the diversion trap is removed.
Mode or relevant parameters are
associated with current diversion leveL
The scale indicator is ignored if not
specified in the request.

none

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

.em xx

none

nroff/troff Reference

3-27

Request
form

Initial If no
Explanation
value argument

. it [n] [xx]

off

Input-line-count trap. An input-linecount trap is set to invoke the macro xx
after n lines of text input have been
read (control or request lines do not
count). Text may be in-line or
interpolated by in-line or trap-invoked
macros. Relevant parameters are a part
of the current environment.

.rm xx

ignored

Remove. A request, macro, or string is
removed. The name xx is removed
from the name list and any related
storage space is freed. Subsequent
references have no effect.

.rn xx yy

ignored

Rename. Rename request, macro, or
string from xx to yy. If yy exists, it is
first removed.

• wh n [xx]

When. A location trap is set to invoke
macro xx at page position n; a negative
n is interpreted with respect to the page
bottom. Any macro previously planted
at n is replaced by xx. A zero n refers
to the top of a page. In the absence of
xx, the first found trap at n, if any, is
removed. The scale indicator is
ignored if not specified in the request.

10. Number registers
A variety of predefined number registers are available to the user. In
addition, the user may define his own named registers. Register names
are 1- or 2-characters long and do not conflict with request, macro, or
string names. Except for certain predefined read-only number
registers, a number register can be read, written, automatically
incremented or decremented, and interpolated into the input in a variety
of formats. One common use of user-defined registers is to
automatically number sections, paragraphs, lines, and so on. A number
register can be used any time numeric input is expected or desired and
can be used in numeric expressions.

3-28

A/UX Text Processing Tools

Number registers are created and modified using the . nr request,
which specifies name, numeric value, and automatic increment size.
Registers are also modified if invoked with an automatic incrementing
sequence. If the registers x and xx both contain n and have the
automatic 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

Value
Interpolated

none
none
x incremented by m
x decremented by m
xx incremented by m
xx decremented by m

n
n
n+m
n-m
n+m
n-m

According to the format specified by the . af request, a number
register is converted (when interpolated) to
•
•
•
•
•
•

decimal (default)
decimal with leading zeros
lowercase roman
uppercase roman
lowercase sequential alphabetic
uppercase sequential alphabetic

The escape sequence" \ gx" 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 of . a f to restore a
previous format.

nro££/tro££ Reference

3-29

Request
form

Initial If no
Explanation
value argumen t

. af r c

Arabic -

Assign format. Format c is assigned to
register r. Available formats are:

1 0,1,2, ...
001000,001,002, ...
i
O,i,ii, .. .
I
O,I,II, .. .
O,a,b, ... ,z aa,ab, ... ,zz aaa, ...
a
A
O,A,B, ... ,Z AA,AB, ... ,ZZ
AAA, .. .
An Arabic format having n digits
specifies a field width of n digits.
Read-only registers and width function
are always Arabic .
• nr

r ±n m

. rr

Number register. The number register
r is assigned the value ±n with respect
to the previous value, if any. The
automatic incrementing value is set to
m. The number register value (n) is
ignored if not specified in the request.
Remove register. The number register

r is removed. If many registers are
being created dynamically, it may be
necessary to remove registers that are
no longer used in order to recapture
internal storage space for newer
registers.

11. Tabs, leaders, and fields
11.1 Tabs and leaders
Both the ASCII horizontal tab character and the ASCII SOH character
(the leader) can 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 specified with a . t a request. The default
difference is that tabs generate motion and leaders generate a string of
periods; . te and .le offer the choice of repeated character or motion.

3-30

AlUX Text Processing Tools

There are three types of internal tab stops: left justified, right justified,
and centered. In the following table,

• next-string consists of the input characters following the tab (or
leader) up to the next tab (or leader) or end of line.

• d is the distance from the current position on the input line
(where a tab or leader was found) to the next tab stop.
• w is the width of next-string.
Tab
type

Length of motion or
repeated characters

Left
Right
Centered

d
d-w
d-w/2

Location of
next-string

Following d
Right justified within d
Centered on right end of d

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 prefixed
as motion. Tabs or leaders found after the last tab stop are ignored, but
they may be used as next-string terminators.
Tabs and leaders are not interpreted in copy mode. The \ t and \ a
always generate an un interpreted tab and leader, respectively, and are
equivalent to actual tabs and leaders in copy mode.

11.2 Fields
A field is contained between a pair of field delimiter characters. It
consists of substrings separated by padding indicator characters. The
field length is the distance on the input line from the position where the
field begins to the next tab stop. The difference between the total
length of all the substrings 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 ~, then
#~xxx~right#

specifies a right-justified string with the string xxx centered in the
remaining space.

nroff/troff

Reference

3-31

Note: Values separated by a semicolon (;) in the "Initial
value"field below are for the nroff and troff formatters,
respectively.
Request
form

Initial
value

If no
.
t Explanation
argumen

. fc [a] [b]

off

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

none

Leader repetition character becomes c
or is removed specifying motion.
Relevant parameters are a part of the
current environment.

none

Set tab stops and types. The
adjustment within the tab is as follows:

. le [c]

.ta nt ...

8n;O.5 in

type

result

right
centering
left

absent

Tab stops for the troff formatter are
preset every 0.5 inch; Tab stops for the
nroff fonnatter are preset every eight
nominal character widths. Stop values
are separated by spaces, and a value
preceded by + is treated as an
increment to the previous stop value.
Relevant parameters are a part of the
current environment. The scale
indicator is ignored if not specified in
the request.
. t e [c]

3-32

none

Tab repetition character becomes c or is
removed specifying motion. Relevant
parameters are a part of the current
environment.

AlUX Text Processing Tools

12. Input/output conventions and character
translations
12.1 Input character translations
The newline character delimits input lines. In addition, STX, ETX,
ENQ, ACK, and BEL are accepted and can be used as delimiters or
translated into a graphic with a . t r request. All others are ignored.
The escape character (\) introduces sequences that indicate some
function such as a font change or the printing of a special character.
The escape character
• should not be confused with the ASCII control character ESC of
the same name
• can be input with the sequence \ \
• can be changed with. ec, and all that has been said about the
default \ becomes true for the new escape character.
A \e sequence can be used to print the current escape character. If
necessary or convenient, the escape mechanism can be turned off with
. eo and restored with . ec.

12.2 Ligatures
Two ligatures are available in the troff character set: fi and fl.
They may be entered (even in the nroff formatter) by \ (fi and
\ (f 1, respectively. Note that ligature mode is normally on in the
troff formatter; that is, ligatures are automatically produced.
Constant-width fonts normally do not use ligatures.

12.3 Backspacing, underlining, and overstriking
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 and, as a generalized
overstriking function, is described in "Overstrike, Zero-Width,
Bracket, and Line Drawing Functions."
The nroff processor underlines characters automatically in the
underline font, specifiable with the . uf request. The underline font is
normally on font position 2 (Times Italic). In addition to . ft request
and \f[escape sequence, the underline font may be selected by . ul
and. cu requests. Underlining is restricted to an output-devicedependent subset of reasonable characters.

nroff/troff Reference

3-33

12.4 Control characters
Both the break: control character ( .) and the no-break control character
(') may be changed, if desired. Such a change must be compatible
with the design of any macros used in the span of the change and
particularly with any trap-invoked macros.

12.5 Output translation
One character can be made a stand-in for another character using the
· t r request. All text processing (for example, character comparisons)
takes place with the input (stand-in) character which appears to have
the width of the final character. Graphic translation occurs at the
moment of output (including diversion).

Note: Values separated by a semicolon (;) in the "Initial
value"field below are for the nroff and troff formatters,
respectively.

Request
form

Initial If no
.
t Explanation
value argumen

• ec [c)

· ell [n]

Set control character to c or reset to ..
Relevant parameters are a part of the
current environment.
off

n=l

· c2 [c)

Set no-break control character to c or
reset to '. Relevant parameters are a
part of the current environment.

· ec [c)

.eo

3-34

Continuous underline in the n ro f f
formatter. A variant of . ul that causes
every character to be underlined.
Identical to • ul in the troff
formatter. Relevant parameters are a
part of the current environment.

Set escape character to \ or to c if
given.
Turn escape character mechanism off.

AlUX Text Processing Tools

Request
form

Initial If no
Explanation
value argument

.lg [n]

off;on

Ligature mode is turned on if n is
absent or nonzero and turned off if n=O.
If n=2, only the 2-character ligatures
are automatically invoked. Ligature
mode is inhibited for request, macro,
string, register, file names, and copy
mode. There is no effect in the n ro f f
formatter .

. tr

abed ...

none

. uf

Italic

Underline font set to! (to be switched
to by • ul). In the nroff formatter!
may not be on position 1 (initially
Times Roman) .

off

n= 1

Underline in the nroff formatter
(italicize in troff) the next n input
text lines. 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 • t l is
affected by the font change but does
not decrement n. If n is greater than 1,
there is the risk that a trap interpolated
macro may provide text lines within the
span, which environment switching can
prevent. Relevant parameters are a part
of the current environment.

. ul [n]

Translate a into b, c into d, and so forth
on output. If an odd number of
characters is given, the last one will be
mapped into the space character. To be
consistent, a particular translation must
stay in effect from input to output time.
Initially there are no translate values .

nroff/troff Reference

3-35

12.6 Transparent throughput
An input line beginning with a \ ! is read in copy mode and
transparently output (without the initial \ !); the text processor is
otherwise unaware of the line's presence. This mechanism may be
used to pass control information to a post-processor or to embed
control lines in a macro created by a diversion.

12.7 Comments and concealed newline characters
An unusually long input line that must stay one line (for example, a
string definition or no-filled text) can be split into many physical lines
by ending all but the last one with the escape character (\). The
sequence \ is ignored except in a comment. Comments can be
embedded at the end of any line by prefacing them with \ n. The
newline character at the end of a comment cannot be concealed. A line
beginning with \ n will appear as a blank line and behave like . s pI;
a comment can be on a line by itself by beginning the line with . \ " .

13. Local horizontal/vertical motion and width
13.1 Local motion
The functions \ v' n' and \ h ' n' can be used for local vertical and
horizontal motion, respectively. The distance n may be negative; the
positive directions are rightward and downward. A local motion is one
contained within a line. To avoid unexpected vertical dislocations, it is
necessary that the net vertical local motion (within a word in filled text
and otherwise within a line) balance to zero.
As an example, E2 is generated by the sequence

E\v'-.5'\s-4\&2\sO\v' .5'

13.2 Width function
The width function \ w' string' generates the numeric width of string
in basic units. Size and font changes may be embedded in string and
will not affect the current environment. For example,

.ti -\w'l.'u
could be used to temporarily indent leftward a distance equal to the size
of the string" 1. " .
The width function also sets three number registers. The registers s t
and sb are set respectively to the highest and lowest extent of string

3-36

AlUX Text Processing Tools

relative to the baseline; then, for example, the total height of the string
is \n (stu-\n (sbu. In the troff formatter, the number register ct
is set to a value between 0 and 3:
• 0 means that all characters in string are short lowercase
characters without descenders (like the character e)
• 1 means that at least one character has a descender (like the
character y)
• 2 means that at least one character is tall (like the character H)
• 3 means that both tall characters and characters with descenders
are present

13.3 Mark horizontal place
The escape sequence \ kx will cause the current horizontal position in
the input line to be stored in register x. As an example, the
construction:
\kx\flword\fR\h'l\nxu+2u'\flword\fR

will embolden word by backing up to almost its beginning and
overprinting it, resulting in
word

14. Overstrike, zero-width, bracket, and line
drawing functions
14.1 Overstrike
Automatically centered overstriking of up to nine characters is
provided by the overstrike function \ 0' string'. Characters in string
are overprinted with centers aligned; the total width is that of the
widest character. The string should not contain local vertical motion.
For example:

\0' e \ "produces
\ 0'

>/' produces ;f

14.2 Zero-width characters
The function \ zc will generate c without spacing over it and can be
used to produce left-aligned overstruck combinations.

nroff/troff Reference

3-37

14.3 Large brackets
The Special Mathematical Font contains a number of bracket
construction pieces that can be combined into various bracket styles.
The function \ b' string' can be used to pile up vertically the
characters in string (the first character on top and the last at the
bottom); the characters are vertically separated by one em and the total
pile is centered one-half em above the current base line (one-half line
in the nroff formatter). For example:

\b'\(lc\(lf'\IE\I\b'\(rc\(rf'\x'-O.5m'\x'O.5rn'
produces

14.4 Line drawing
The \1' nc' function will draw a string of repeated c's toward the
right for a distance n (1 is lowercase L).

• If c looks like a continuation of an expression for n, it can be
insulated from n with a \ &.
• If c is not specified, the base-line 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 base-line rule (_), underrule (\ (ul),
and root en (\ (ru), 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' IO\(ul'
or a macro can draw a box around a string:

3-38

A/UX Text Processing Tools

·de bx
\ (br\ 1\ \$1 \ 1\ (br\l' 10\ (rn' \1' 10\ (ul'

such that
.us "underlined words"

and
.bx "words in a box"

yield
underlined words
and

;------::---:---::---.......

Iwords in a box I
The function \ L' nc' will draw a vertical line consisting of the
optional character c stacked vertically apart one em (one line in
nroff), with the first two characters overlapped, if necessary, to form
a continuous line. The default character is box rule (\ (br); the other
suitable character is bold vertical (\ (bv). The line is begun without
any initial motion relative to the current base line. A positive n
specifies a line drawn downward, and a negative n specifies a line
drawn upward. After the line is drawn, no compensating motions are
made; the instantaneous base line is at the end of the line.
The horizontal and vertical line drawing functions may be used in
combination to produce large boxes. The zero-width box-rule and the
one-half em wide underrule were designed to form comers when using
one em vertical spacings. For example, the macro
.de eb
.sp -li
\"compensate for automatic base-line spacing
.nf
\"avoid possibly overflowing word buffer
\h'-.5n'\L'I\\nau-l'\1'\\n(.lu+ln\(ul'\L'-I\\nau+l'\
\1' IOu-.5n\(ul'
\"draw box
. fi

will draw a box around some text whose beginning vertical place was
saved in number register a (for example, using . mk a).

nroff/troff Reference

3-39

In addition, troff provides drawing functions capable of drawing
arcs and splines.
Request
form

Explanation

\0'1 dh dv'

Draw a line for the current position by dh, dv.

\O'c d'

Draw a circle of diameter d with its left side
at the current position.

\O'e dl d2'

Draw an ellipse of diameters dl and d2 with
its left side at the current position.

\O'a dhl dvl dh2 dv2'

Draw a counterclockwise arc from the current
position to dhl +dh2, dvl +dv2, with its center
at dhl ,dv1 from the current position.

\0' - dhl dvl dh2 dv2 ... '

Draw a B-spline from the current position by
dhl, dv1, then by dh2, dv2, then ...

The current position after using these drawing functions is at the end of
the drawn line, which for circles and ellipses is at the right side.

15. Hyphenation
The automatic hyphenation may be switched off and on. When
switched on with . h y, several variants may be set. A hyphenation
indicator character may be embedded in a word to specify desired
hyphenation points or may precede a word to suppress hyphenation. In
addition, the user may specify a small exception word list. The default
condition of hyphenation is off.
Only words that consist of a central alphabetic string surrounded by
nonalphabetic strings (usually null) are considered candidates for
automatic hyphenation. Words that were entered containing hyphens
(minus), em-dashes (\ (em), or hyphenation indicator characters (such
as mother-in-law) are always subject to splitting after those characters
whether or not automatic hyphenation is on or off.

3-40

AlUX Text Processing Tools

Request
form

Initial
value

t Explanation
If no
argumen

.he [c]

Hyphenation character. Hyphenation
indicator character is set to c or to the
default \ %. The indicator does not
appear in the output. Relevant
parameters are a part of the current
environment.

ignored

Exception words. Hyphenation points
in words are specified with embedded
minus signs. Versions of a word with
terminal s are implied; that is, dig-it
implies dig-its. This list is examined
initially and after each suffix stripping.
Space available is small-about 128
characters.

on,n=l

Hyphenate. Automatic hyphenation is
turned on for n~l or off for n=O. If
n=2, last lines (ones that will cause a
trap) are not hyphenated. For n=4 the
last two characters of a word are not
divided. For n=8 the first two
characters of a word are not divided.
These values are additive; that is, n=14
invokes all three restrictions. Relevant
parameters are a part of the current
environment.

.hw wordl ...

.hy [n]

off,n=O

.nh

no hyphen

No hyphenation. Automatic
hyphenation is turned off. Relevant
parameters are a part of the current
environment.

16. Three-part titles
The titling function . t 1 provides for automatic placement of three
fields at the left, center, and right of a line with a title length specifiable
with . 1 t. The . t 1 may be used anywhere and is independent of the
normal text collecting process. A common use is in header and footer
macros.

nroff/troff Reference

3-41

form

Initial
value

If no
.
Explanation
argument

. It [±n]

6.5 in

Length of title set to ±no Line length
and title length are independent.
Indents do not apply to titles; page
offsets do. Relevant parameters are a
part of the current environment. The
scale indicator is ignored if not
specified in the request.

.pe [c]

off

Page number character set to c or
removed. The page number register
remains %•

Request

. tl' left' center' right'

Three-part title. The strings left, center,
and right are respectively left-adjusted,
centered, and right-adjusted in the current
title length. Any of the strings may be
empty, and ,overlapping is pennitted. If
the page number character (initially %) is
found within any of the fields, it is
replaced by the current page number
having the format assigned to register %.
Any character may be used as the string
delimiter.

17. Output line numbering
Automatic sequence numbering of output lines can be requested with
. nm. When in effect, a three-digit, Arabic number plus a digit-space is
prefixed to output text lines. Text lines are offset by four digit-spaces
and otherwise retain their line length. A reduction in line length may
be desired to keep the right margin aligned with an earlier margin.
Blank lines, other vertical spaces, and lines generated by . t 1 are not
numbered. Numbering can be temporarily suspended with. nn or with
a . nm followed by a later. nm +0. In addition, a line number indent i
and the number-text separation s can be specified in digit-spaces.
Further, it can be specified that only those line numbers that are
multiples of some number m are to be printed (the others will appear as
blank number fields).

3-42

AlUX Text Processing Tools

Request
form

Initial If no
Explanation
value argument

. nm [in] [m] -

off

Line number mode. If ±n is given, line
numbering is turned on, and the next
output line is numbered ±n. Default
values are m=l, s=l, and i=O.
Parameters corresponding to missing
arguments are unaffected; a nonnumeric argument is considered
missing. In the absence of all
arguments, numbering is turned off,
and the next line number is preserved
for possible further use in number
register In. Relevant parameters are a
part of the current environment.

n=l

Next n lines are not numbered.
Relevant parameters are a part of the
current environment.

[s] [i]

.nn [n]

The following illustrates output line numbering. Paragraph portions
are numbered with m=2.
Automatic sequence numbering of output lines may be requested
2 with. nm. When in effect, a 3-digit, Arabic number plus a digitspace is prefixed to output text lines. Text lines are offset by four
4 digit-spaces and otherwise retain their line length. A reduction in
line length (such as . 11 - \ w' 0 0 0 0 ' u in this example) may be
6 desired to keep the right margin aligned with an earlier margin.
Blank lines, other vertical spaces, and lines generated by . t 1 are
8 not numbered. Numbering can be temporarily suspended with
. nn or with a . nm followed by a later . nm + O.

10 In addition, a line number indent i and the number-text separation
s may be specified in digit-spaces. Further, it can be specified that
12 only those line numbers that are multiples of some number m are
to be printed (the others will appear as blank number fields). This
example uses the multiple of 2.
• . 11 - \ w' 0000' u was placed at the beginning to keep the

right margin aligned

nroff/troff Reference

3-43

• . nm 1 2 was placed at the beginning
• . nm +0 was placed in front of the second and third paragraphs
• . nm was placed at the end
• .11 + \ w' 0000' u was placed at the end to return to the
original line length
Another example is
.nm +5 5 x 3
which turns on numbering with the line number of the next line to be
fi ve greater than the last numbered line, with m=5, spacing s
untouched, and the indent i set to 3.

18. Conditional acceptance of input
In the table below, which is a summary and explanation of conditional
acceptance requests:
• c is a I-character, built-in condition name.
• ! signifies not.
• n is a numeric expression.
• string1 and string2 are strings delimited by any nonblank, nonnumeric character not in the strings.
• anything represents what is conditionally accepted.
Request
form

Explanation

· el anything

The "else" portion of "if-else".

· ie c anything

The "if" portion of "if-else." The c can
be any of the fonns acceptable with the
. i f request.

· i f c anything

If condition c true, accept anything as
input; for multiline case, use
\ {anything \ }. The scale indicator is
ignored if not specified in the request.

· i f ! c anything

If condition c false, accept anything.

3-44

NUX Text Processing Tools

Request
form

Exp lanatlon

· if n anything

If expression n > 0, accept anything. The
scale indicator is ignored if not specified in
the request.

· i f ! n anything

If expression n ~ 0 accept anything. The
scale indicator is ignored if not specified in
the request.

· if ' string1' string2' anything
If string1 is identical to string2, accept

anything.
· if !' string1 ' string2' anything
If string1 is not identical to string2, accept

anything.

The built-in condition names are
Condition
name
0

e
t
n

True if

Current page number is odd
Current page number is even
Formatter is troff
Formatter is nroff

If condition c is true, if number n is greater than zero, or if strings
compare identically (including motions and character size and font),
anything is accepted as input. If a ! precedes the condition, number, or
string comparison, the sense of the acceptance is reversed.

Any spaces between the condition and the beginning of anything are
skipped over. The anything can be either a single input line (text,
macro, or whatever) or a number of input lines. In the multiline case,
the first line must begin with a left delimiter \ { and the last line must
end with a right delimiter \ }.
The request. ie (if-else) is identical to • if except that the acceptance
state is remembered. A subsequent and matching. el (else) request

nroff/troff Reference

3-45

then uses the reverse sense of that state. The . i e - . e 1 pairs may be
nested. For example
.if e .tl ' Even Page %'"

generates a title if the page number is even, and
.ie
'sp
.tl
'sp
.el

\n%>l\{\
O.Si
'Page %'"
Il.2i\}
.spI2.Si

treats page 1 differently from other pages.

19. Environment switching
A number of parameters that control text processing are gathered
together into an environment, which can be switched by the user.
Environment parameters are those associated with some requests. The
request tables in this chapter indicate in the Explanation column those
requests so affected. In addition, partially collected lines and words are
in the environment. Everything else is global; examples are pageoriented parameters, diversion-oriented parameters, number registers,
and macro and string definitions. All environments are initialized with
default parameter values.
Request Initial If no
Explanation
form
value argument
. ev [n]

n=0

Environment switched to 0, 1, or 2. Switching
is done in pushdown fashion so that restoring a
previous environment must be done with . ev
rather than specific reference.

20. Insertions from standard input
The input can be switched temporarily to the system standard input
with . rd and switched back when two newline characters 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 A/UX
operating system, the standard input can be the user keyboard, a pipe,
or a file.

3-46

NUX Text Processing Tools

If insertions are to be taken from the tenninal keyboard while output is
being printed on the terminal, the flag 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 can be prepared
by entering insertions for all copies in one file to be used as the
standard input and causing the file containing the letter to reinvoke
itself by using the . nx request. The process would be ended by a . ex
request in the insertion file.
Request
form

Initial If no
value argument

.ex

· rd [prompt]

Explanation
Exit from the nroff/troff
formatter. Text processing is
terminated exactly as if all input had
ended.

prompt=BEL

Read insertion from the standard input
until two newline characters in a row
are found. If standard input is the user
keyboard, a prompt (or a BEL) is
written onto the user terminal. The
request behaves like a macro;
arguments may be placed after prompt.

21. Input/output file switching
Request
form

Initial If no
value argument Explanation

· cf filename

· nx [filename]

Copy the contents offile, uninterpreted
into troff output file at this point.
Havoc ensues unless the motions in the
file restore the current horizontal and
vertical position.
end-of-file

nroff/troff Reference

Next file is filename. The current file is
considered ended, and the input is
immediately switched to filename.

3-47

Request
form

Initial If no
Explanation
value argumen t

.pi program

Pipe output to program. This request
must occur before any printing occurs.
No arguments are transmitted to
program .

. so filename

Switch source file (pushdown). The
top input level (file reading) is switched
to filename. Contents are interpolated
at the point the request is encountered.
When the new file ends, input is again
taken from the original file. The . so
requests may be nested .

• 1£ n file

Corrects troff's idea of the current
line number, n, and the current file, file,
for use in error messages

22. Miscellaneous
Request
form

Initial If no
Explanation
value argument

.fl

. ig [yy]

3-48

Flush output buffer. Used in interactive
debugging to force output. The request
causes a break.
.yy= ..

Ignore input lines until call of yy. This
request behaves like the • de request
except that the input is discarded. The
input is read in copy mode, and any
automatically incremented registers will
be affected.

A/UX Text Processing Tools

Request
form

Initial If no
Explanation
value argument

.me c [n]

off

Sets margin character c and separation n.
Specifies that a margin character c appear
a distance n to the right of the right
margin after each nonempty text line
(except those produced by . t 1). 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 the n ro f f formatter and 1 em
in troff. Relevant parameters are a
part of the current environment. The
scale indicator is ignored if not specified
in the request.

.pm [t]

all

Print macros. The names and sizes of all
defined macros and strings are printed on
the user terminal. If t is given, only the
total of the sizes is printed. Sizes are
given in blocks of 128 characters .

. sy cmd args

. tm [string]

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

Print string on terminal (NUX operating
system standard message output). After
skipping initial blanks, string (rest of the
line) is read in copy mode and written on
the user terminal.

23. Output and error messages
output from . tm, . pm, and prompt from . rd, as well as various error
messages are written onto the NUX operating system standard
message output. The latter is different from the standard output, when
compared to the nroff formatted output. By default, both are written
onto the user's terminal, but they can be independently redirected.

nroff/troff Reference

3-49

Various error conditions can occur during the operation of the nroff
and troff formatters. 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) .
• 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) or a => (in troff). The usual procedure 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. Error conditions that can cause this
include the inability to create, read, or write files, and the exceeding of
certain intemallimits that make future output unlikely to be useful.
Request
form

Initial If no
Explanation
value argument

. ab [text]

3-50

Prints text on the message output and
terminates without further processing. If
text is missing, User Abort. is
printed. This request does not cause a
break. The output buffer is flushed.

NUX Text Processing Tools

24. Reference tables
24.1 Escape sequences for characters, indicators, and
functions
Escape
sequence
\\
\e

\ '
\'
\-

\.
\SPACE

\0
\1
\A
\&
\!
\"
\$n
\%
\ (xx

\ *X, \ * (xx
\{
\}
\
\a
\b' abc ... '
\c
\d
\0
\fx, \f (xx, \fn
\gx,\g (xx

Meaning
\ (to prevent or delay the interpretation of \)
Printable version of current escape character
Acute accent (equivalent to \ (aa)
Grave accent (equivalent to \ (ga)
- (minus sign in the current font)
Period (dot)
Unpaddable space-size space character
Unpaddable digit width space
1/6 em narrow space character (zero width in nroff)
1/12 em half-narrow space character (zero width in nroff)
Nonprinting zero width character
Transparent line indicator
Beginning of comment
Interpolate argument (1~n$9)
Default optional hyphenation character
Character named xx
Interpolate string x or xx
Begin conditional input
End conditional input
Concealed (ignored) newline character
Uninterpreted leader character
Bracket building function
Continuation of interrupted text
Forward (down) lh em vertical motion (lh line in nroff)
Line-drawing functions
Change to font named x or xx or position n
Return the . af -t ype format of the register x or xx
(returns nothing if x or xx has not yet been referenced)

Note: Escape sequences \ \, \., \", \$, \*, \a, \n, \t, \ are
interpreted in copy mode.

nro££/tro££ Reference

3-51

Escape
sequence
\h'n'

\H'n'
\kx

\l'ne'
\L' ne'

\nx, \n (.:0:
\0' abc . .. '
\p

\r
\sn, \s±n
\t
\u
\v'n'

\w'string'
\x'n'
\zc
\X

Meaning
Local horizontal motion, move right n (negative left)
Height control of characters (does not affect width).
Mark horizontal input place in register x
Horizontal line drawing function (optionally with c)
V erticalline drawing function (optionally with c)
Interpolate number register x or xx
Overstrike characters a, b, c ...
Break and spread output line
Reverse 1 em vertical motion (reverse line in nroff)
Point-size change function
Uninterpreted horizontal tab
Reverse (up) 112 em vertical motion (112 line in nroff)
Local vertical motion, move down n (negative up)
Interpolate width of string
Extra line-space function (negative before, positive after)
Print c with zero width (without spacing)
Any character not listed above

Note: Escape sequences \ \, \., \", \$, \*, \a, \n, \t, \ are
interpreted in copy mode.

3-52

A/UX Text Processing Tools

24.2 Naming conventions for special characters on
the standard fonts
Char

Input Character
name name

,
,

\ (hy

\ (em

•

\ (bu
\(sq
\(ru
\(14

0
-

Close quote
Open quote
%Emdash
Hyphen or
Hyphen
Current font minus
Bullet
Square
Rule
One-fourth

nroff/troff Reference

Char

lh
%
fi
fl
0

t,
¢
®

Input Character
name name

\(12
\(34
\(fi
\(f1
\ (de
\ (dg
\(fm
\(ct
\(rg
\(co

One-half
Three-fourths
fi
fl
Degree
Dagger
Foot mark
Cent sign
Registered
Copyright

3-53

24.3 Naming conventions for Greek characters on the
special font
Char

A
B

r
.1
E
Z
H

E>
I
K
A
M
N

....
0
II

P
L
T
y

X
\{I

Input
name

Character
name

\(*A
\(*B
\(*G
\(*D
\(*E
\(*z
\(*Y
\(*H
\(*1
\(*K
\(*L
\(*M
\(*N
\(*c
\(*0
\(*P
\(*R
\(*8

Alphat
Betat
Gamma
Delta
Epsilont
Zetat
Etat
Theta
Iotat
Kappat
Lambda
Mut
Nut
Xi
Omicront
Pi
Rhot
Sigma

\(*T
\(*U
\(*F
\(*x
\(*Q
\(*w

Taut
Upsilon
Phi
Chit
Psi
Omega

Char

a.
~
'Y

8
E

~
11

e
t

A
Jl
v
~
0
1t

p
cr
~
't
'\)

'"
ro

Input
name

Character
name

\(*a
\(*b
\(*g
\(*d
\(*e
\(*z
\(*y
\(*h
\(*i
\(*k
\(*1
\(*m
\(*n
\(*c
\(*0
\(*p
\(*r
\(*s
\(ts
\(*t
\(*u
\(*f
\(*x
\(*q
\(*w

alpha
beta
gamma
delta
epsilon
zeta
eta
theta
iota
kappa
lambda
mu
nu
xi
omicron
pi
rho
sigma
terminal sigma
tau
upsilon
phi
chi
psi
omega

t Mapped into uppercase English letters in the font mounted on font position
one.

3-54

NUX Text Processing Tools

24.4 Naming conventions for special characters on the
special font
Char Input Character
name name

+
±

x
+

=
~
~

:::::::

"
-

c
:J
~

;;d

0
00

a
V

J
oc

\ (pI math plus
\(rni math minus
\ (+-

plus-minus

\ (rnu multiply
\ (di divide
\ (eq math equals

\
\
\
\

(>=
«=
(==
(-=

\(ap
\ ( !=
\(sr
\(rn
\(cu
\(ca
\(sb
\(sp
\(ib
\(ip
\ (rno
\(es
\ (i f
\ (pd
\ (gr
\ (i s
\ (pt
\ (no

greater than or equal
less than or equal
identically equal
approximately equal
approximates
not equal
square root
root en extender
cup (union)
cap (intersection)
subset of
superset of
improper subset
improper superset
member of
empty set
infinity
partial derivative
gradient
integral sign
proportional to
not

nroff/troff Reference

Char Input Character
name name

*
I

I
§
,

~
~

i
J,

:/:

•

<=
=>

I
0

1
L

J
i

\ (* * "math star"
\ (or or
\ (sl slash
\ (s c section
\ (aa acute accent
\ (ga grave accent
\ (u 1 underrule
\ (-> right arrow
\ « - left arrow
\ (ua up arrow
\ (da down arrow
\ (dd double dagger
\ (bs "Bell System logo"
\ (lh "left hand"
\ (rh "right hand"
\ (b r box vertical rule
\ (ci circle
\ (bv bold vertical
\ (Ie left ceiling (bracket)
\ (re right ceiling
\ (1 f left floor
\ (rf right floor
\ (1 t left top (brace)
\ (rt right top
\ (lb left bottom
\ (rb right bottom
\ (lk left center
\ (r k right center

3-55

24.5 Predefined general number registers
Register
Description
name
%

.b
c.

.R
ct
dl
dn

dw
dy
In
mo
nl
sb
st
yr

3-56

Current page number.
Emboldening factor of the current font.
Provides general register access to the input line number in the
current input file. Contains the same value as the read-only
. c register.
Number of number registers that remain available for use .
Character type (set by width function).
Width (maximum) of last completed diversion.
Height (vertical size) of last completed diversion.
Current day of the week (1 through 7).
Current day of the month (1 through 31).
Output line number.
Current month (1 through 12).
Vertical position of last printed text base line.
Depth of string below base line (generated by width function).
Height of string above base line (generated by width function).
Last two digits of current year.

A/UX Text Processing Tools

24.6 Predefined read-only number registers
Register
name
.$
$$

.A
.F

.H
.L

.v
.a
•c

.d
.f
.h

.i
.j

•k

.1
.n
•0

.p
.s

Description
Number of arguments available at the current macro level.
Identification number (process ill) for nraff or troff
processes .
Set to 1 in the troff formatter if -a option used: always
1 in the nroff formatter.
Value is a string that is the name of the current input file .
Available horizontal resolution in basic units .
Contains the current line spacing parameter (the value of
the most recent . 1 s request).
Contains the value 1 if the current page is being printed and
is zero otherwise, that is, if the current page did not appear
in the -0 option list.
Set to 1 in the nraff formatter if -T flag option used:
always 0 in the traff formatter.
Available vertical resolution in basic units .
Post-line extra line space most recently utilized using
Number of lines read from current input file .
Current vertical place in current diversion: equal to n1 if
no diversion .
Current font as physical quadrant (1 through 4) .
Text base-line high-water mark on current page or
diversion .
Current indent.
Indicates the current adjustment mode and type. Can be
saved and later given to the . ad request to restore a
previous mode .
Contains the horizontal size of the text portion (without
indent) of the current partially collected output line, if any,
in the current environment.
Current line length.
Length of text portion on previous output line .
Current page offset .
Current page length .
Current point size .

nroff/troff Reference

3-57

.w
.x
.y
.z

3-58

Description
Distance to the next trap .
Equal to 1 in fill mode and 0 in no-fill mode .
Current vertical line spacing .
Width of previous character.
Reserved version-dependent register.
Reserved version-dependent register.
N arne of current diversion .

A/UX Text Processing Tools

Chapter 4

mm Reference

Contents
1. Introduction
• • • .
1.1
Document structure
1.2
Input text structure
1.3
Definitions. • .

• •

1
1
2
2

2. Usage • . • • • • • •
2.1
The mm command
2.2
The -em or -mm flag. •
2.3
Typical command lines •
2.4
Parameters set from command line
2.5
Omission of -:mm flag

4
4
5
5
8
11

3. Formatting concepts • . . . • .
3.1
Basic terms
•.•.•..•.•
3.2
Arguments and double quotes .
3.3
Unpaddable spaces . • . •
3.4
Hyphenation • • . .
3.5
Tabs
3.6
BEL character •
3.7
Bullets. • .
3.8
Dashes, minus signs, and hyphens. •
3.9
Trademark string . • •
3.10 Use of formatter requests

12
12
13
13
14
15
16
16
16
17
17

4. Paragraphs and headings. • •
4.1
Paragraphs. • . • •
4.1.1 Paragraph indentation • .
4.1.2 Numbered paragraphs • .
4.1.3 Spacing between paragraphs
4.2
Numbered headings • •
4.2.1 Default headings

18
18
18
19

-i-

20
20
20

4.3
4.4
4.5
4.6
4.7

4.2.2 Altering appearance
• • • • •
4.2.2.1 Prespacing and page ejection •
4.2.2.2 Spacing after headings. • •
4.2.2.3 Centered headings • • • •
4.2.2.4 Bold, italic, and underlined
headings
4.2.2.4.1 Control by level
4.2.2.4.2 nroff underlining
style
.•••
4.2.2.4.3 Heading point sizes
4.2.2.5 Marking styles-numerals and
concatenation
Unnumbered headings • • • . • •
Headings and table of contents. • • •
First-level headings and page-numbering
style. • • • • • •
User exit macros • • •
Hints for large documents

5. Lists. • • • •
5.1
List spacing
5.2
List macros
5.2.1 List-initialization macros
5.3
Automatically numbered or alphabetized
list
5.4
Bullet list
5.5
Dash list
5.6
Marked list
5.7 Reference list
5.8
Variable-item list •
5.9 List-item macro
5.10 List-end macro
5.11 Example of nested lists •
5.12 List-begin macro and customized lists
5.13 User-defined list structures • •

21
21
22
23
23
23
23
24
24
25

26
26
27

29
30
30
30
31
31
32
32
33
33
34
35
36
37
38
40

6. Memorandum and released-paper style
documents • • • • • • • •
6.1
Sequence of beginning macros
6.2 Title
•••••••

- ii -

44
44
45

6.3
6.4
6.5
6.6
6.7
6.8
6.9
6.10
6.11

Authors
TM numbers . • . .
Abstract
Other keywords
Memorandum types • .
Date changes • •
Alternate first-page format .
Example
• • • . . . . . . .
End of Memorandum Macros
6.11.1 Signature block. . . .
6.11.2 "Copy to" and other notations
• • • .
6.11.3 Approval signature line
6.12 One-page letter
6.13 Define file information
6.14 Business letter style . . . . • . •
6.14.1 Letter-type macro .
6.14.2 Writer's address macros . . . .
6.14.3 Inside address macros .
6.14.4 Letter-options macro
6.14.4.1 Confidential notation
6.14.4.2 Reference notation .
6.14.4.3 Attention. .
6.14.4.4 Salutation
6.14.4.5 Subject line .
6.14.5 Multipage letters
. • • .
6.14.6 Sequence of beginning letter
macros. •

46
47
47

49
49
51
51
52
52
52
53
55
55
56
56
56
58
60
61
61
62
62
62
63
63
63

7. Displays
7.1
Static displays. •
7.2
Floating displays •
7.3
Tables • • •
7.4
Equations . • •
7.5
Figure, table, equation, and exhibit titles .
7.6
List of figures, tables. equations. and
exhibits. • • • . . • . .

64
65
67
70
72
72

8. Footnotes • . • • • . . • . .
8.1
Automatic numbering of footnotes
8.2
Delimiting footnote text. . . .

74
74
74

- iii -

•

8.3
8.4

Fonnat style of footnote text
.
Spacing between footnote entries

9. Page headers and footers
• . • • .
9.1
Default headers and footers. . . . .
9.2
Header and footer macros
9.2.1 Page header • • •
9.2.2 Even-page header .
9.2.3 Odd-page header . . . • • .
9.2.4 Page footer • • .
9.2.5 Even-page footer
....
9.2.6 Odd-page footer
9.2.7 First page footer
. . • . . . . ..
9.3
Default header and footer with section-page
numbering . . . . . . . . . .
9.4
Strings and registers in header and footer
macros . • • . • • • • •
9.5
Header and footer example • • • • .
9.6
Generalized top-of-page processing
9.7
Generalized bottom-of-page processing .
9.8
Top and bottom margins
.••.....
9.9
Proprietary marking macro .
9.10 Private documents
10. Table of contents and cover sheet
10.1 Table of contents
10.2 Cover sheet

•
. .

• .

75
77
77
77
78
78
78
78
79
79
79
79
79
80
80
81
82
82
83
83
84
84
87

11. References . . • • • • •
11.1 Automatic numbering of references
11.2 Delimiting reference text
. • • • •
11.3 Subsequent references
• • • •
11.4 Reference page
• • • • .

87
88
88
88
88

12. Miscellaneous features
12.1 Bold, italic, and roman fonts
12.2 Justification of right margin. • • • .
12.3 SCCS release identification . .
.•..
12.4 Two-column output • • • •
12.5 Column headings for two-column output. .
12.6 Vertical spacing . • . . . . • .

89
89
91
91
92
93

- iv-

12.7
12.8
12.9
12.10
12.11
12.12

Skipping pages
• • • • • • •
Forcing an odd page • • • • • •
Setting point size and vertical spacing
Reducing point size of a string • • • • •
Producing accents
Inserting text interactively

13. Errors and debugging
13.1 Error tenninations
13.2 Disappearance of output.

....

95
95

96
97
97
98
98

14. Extending and modifying memorandum macros .
14.1 Naming conventions • • . • • . .
14.1.1 Names used by formatters
.
14.1.2 Names used by memorandum
macros. • • • • • • •
14.1.3 Names used by cw, eqn/neqn, and
tbl

. • •
• • •

99
99
100
100
100
101
101
101
102

14.1.4 Names defined by user
14.2 Sample extensions
• • • •
14.2.1 Appendix headings. • •
14.2.2 Hanging indent with tabs •
15. Summary

103

16. nmlExamples and reference tables •
16.1 Memorandum macro names
16.2 String names • • • •
16.3 Number register names •
16.4 Error messages

104
109
117
119
124

Figures
Figure 4-1. Example of a simple letter - input
file

•

106

Figure 4-2. Example of a simple letter - nroff
output

•

-v-

•

107

Figure 4-3. Example of a simple letter - troff
output • • . • • • • • •

- vi -

108

Chapter 4
rom Reference

1. Introduction
This chapter is a guide and reference for users of the Memorandum
Macros. These macros provide a general-purpose package of text
formatting macros for use with the NUX operating system text
formatters nroff and troff (refer to nroff(l) and troff(l) in
AIUX Command Reference for more details).

1.1 Document structure
Input for a document to be formatted with the rom text-formatting
macro package has four major segments, any of which may be omitted.
If present, the segments must occur in the following order:
• The parameter-setting segment sets the general style and
appearance of a document. The user can control page width,
margin justification, numbering styles for headings and lists,
page headers and footers, and many other properties of the
document. Also, the user can add macros or redefine existing
ones. This segment can be omitted entirely if the user is satisfied
with default values; it produces no actual output, but performs
only the formatter setup for the rest of the document.
• The beginning segment includes those items that occur only
once, at the beginning of a document; for example, title, author's
name, and date.
• The body segment is the actual text of the document. It may be
as small as a single paragraph or as large as hundreds of pages.
It may have a hierarchy of headings up to seven levels deep (see
"Paragraphs and Headings"). Headings are automatically
numbered (if desired) and can be saved to generate the table of
contents. Five additional levels of subordination are provided by
a set of list macros for automatic numbering, alphabetic
sequencing, and "marking" of list items (see "Lists"). The
body may also contain various types of displays, tables, figures,

mm Reference

4-1

footnotes, and references (see "Displays," "Footnotes," and
"References' ').
• The ending segment contains those items that occur only once at
the end of a document. Included are signatures and lists of
notations (for example, "Copy to" lists) (see "End of
Memorandum Macros' '). Certain macros may be invoked here
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 for a document (see' 'Table of Contents and Cover
Sheet").
Existence and size of these four segments varies widely among
different document types. Although a specific item (such as date, title,
author names) of a segment may differ depending on the document,
there is a uniform way of typing it into an input text file.

1.2 Input text structure
To make it easy to edit or revise input file text at a later time,
• Input lines should be kept short.
• Lines should be broken at the end of clauses.
• Each new sentence should begin on a new line.

1.3 Definitions
Formatter refers to either the nroff or the troff text-formatting
program.

Requests are built-in commands recognized by the formatters.
Although a user seldom needs to use these requests directly (see "Use
of Formatter Requests' '), this chapter contains references to some of
the requests. For example, the request

.sp
inserts a blank line in the output at the place the request occurs in the
input text file.

Macros are named collections of requests. Each macro is an
abbreviation for a collection of requests that would otherwise require
repetition. The rom package supplies many macros, and the user can
define additional ones. Macros and requests share the same set of

4-2

AlUX Text Processing Tools

names and are used in the same way. The first line of each item lists
the name of the macro, a brief description, and a reference to the
section in which the macro is described. The second line illustrates a
typical macro structure.
Strings provide character variables, each of which names a string of
characters. Strings are often used in page headers, page footers, and
lists. These registers share the pool of names used by requests and
macros. A string can be given a value via the . ds (define string)
request, and its value can be obtained by referencing its name,
preceded by \ * (for one-character names) or \ * ( (for two-character
names). For instance, the string DT in mm normally contains the current
date. Thus the input line
Today is \*(DT.

may result in the following output:
Today is September 15, 1988.
The current date can be replaced, for example,
.ds DT 01/01/85

by invoking a macro designed for that purpose (see "Date Changes").
A brief description, paragraph reference, and initial (default) values are
given for each.
Number registers fill the role of integer variables. These registers are
used for flags and for arithmetic and automatic numbering. A register
can be given a value using a . nr request and be referenced by
preceding its name by \n (for one-character names) or \n ( (for twocharacter names). For example, the following sets the value of the
register d to one more than that of the register dd :
.nr d l+\n(dd

"Extending and Modifying Macro Names" contains naming
conventions for requests, macros, strings, and number registers.

rom Reference

4-3

2. Usage
This part describes how to access rom, illustrates A/UX operating
system command lines appropriate for various output devices, and
describes command line flags for the rom text-formatting macro
package.

2.1 The mm command
The rom(1) command can be used to prepare documents using the
nroff formatter and the Memorandum Macros. The rom command
has options to specify preprocessing by tbl or neqn, or both, and for
postprocessing by various output filters.

Note: Options can occur in any order but must appear before
the filenames.
Any arguments or flag options that are not recognized by the rom
command (for example, -rC3) are passed to the nroff formatter or
to rom, as appropriate. Options are as follows:

Option

Meaning

-e

The neqn preprocessor is to be invoked; also
causes neqn to read /usr /pub/ eqnchar (see
eqnchar(7».

-t

The tbl(l) preprocessor is to be invoked.

-c

The col (1) postprocessor is to be invoked.

-E

The -e option of the nroff formatter is to be
invoked.

-12

The 12-pitch mode is to be used. The pitch switch
on the terminal should be set to 12 if necessary.

-T2631

Output is prepared for an HP2631 printer where
-T2631-e and -T2631-c maybe used for
expanded and compressed modes, respectively
(implies -c).

-T300

Output is to a DASI 300 terminal.

-T300s

Output is to a DASI 300S.

4-4

AlUX Text Processing Tools

-T37

Output is to a Teletype Model 37.

-T382

Output is to a DTC-382.

-T4000a

Output is to a Trendata 4000A.

-T450

Output is to a DASI 450. This is the default
terminal type (unless $TERM is set; see sh(l». It
is also equivalent to -T1620.

-T832

Output is to an Anderson Jacobson 832 terminal.

-T8510

Output is to a C.ITOH printer.

-TIp

Output is to a device with no reverse or partial line
motions or other special features (implies -c).

-Ttn300

Output is to a GE terminet 300 terminal.

-TX

Output is prepared for an EBCDIC line printer.

Any other

-T

option given does not produce an error; it is equivalent to

-TIp.

A similar command is available for use with the traff formatter (see
romt(l».

2.2 The -em or -mm flag
The rom package can also be invoked by including the -rom flag as an
argument to the formatter. The -rom flag causes the file
/ u s r / lib / tma c / tma c . 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

2.3 Typical command lines
The prototype command lines are as follows (various options are
explained in "Parameters Set From the Command Line' '):
• Text without tables or equations:
rnm [options] filename ...

mm Reference

4-5

nroff [options] -rom filename ...
mmt [options] filename ...

or
troff [options] -rom filename ...

• Text with tables:
mm -t [options] filename ...

or
tbl filename ... I nroff [options] -mm
mmt -t [options] filename ...

or
tbl filename ... I troff [options] -rom

• Text with equations:
mm -e [options] filename ...

or
neqn /usr/pub/eqnchar filename ... I nroff [options] -rom
mmt -e [options] filename ...

or
eqn /usr/pub/eqnchar filename ... I troff [options] -mm

• Text with both tables and equations:
mm -t -e [options] filename ...

or
tbl filename ... I neqn /usr/pub/eqnchar\
I nroff [options] -mm
mmt -t -e [options] filename ...

4-6

A/UX Text Processing Tools

tbl filename ... I eqn /usr/pub/eqnchar\
I troff [options] -nun

When formatting a document with the nroff processor, the output
should normally be processed for a specific type of terminal because
the output may require some features that are specific to a given
terminal (for example, reverse paper motion or half-line paper motion
in both directions). Some commonly used terminal types and the
command lines appropriate for them are given below. For more
information, see "Parameters Set From Command Line" and 300(1),
450(1),4014(1), hp(1), col(1), termio(4), and term(5).
• DASI 450 in 10-pitch, 6 lines/inch mode, with 0.75-inch offset,
and a line length of 6 inches (60 characters) where this is the
default terminal type so no -T option is needed (unless $TERM is
set to another value):
rom filename ...
or
nroff -T450 -h -rom filename ...
• DASI 450 in 12-pitch, 6 lines/inch mode, with 0.75-inch offset,
and a line length of 6 inches (72 characters):
rom -12 filename ...
or
nroff -T450-12 -h -rom filename ...
or to increase the line length to 80 characters and decrease the
offset to 3 characters:
rom -12 -rWSO -r03 filename ...
or
nroff -T450-12 -rWSO -r03 -h -rom filename ...
• Hewlett-Packard HP264x CRT family:
rom -Thp filename ...
or

Reference

4-7

nroff -rom filename ... I col I hp

• Any tenninal incapable of reverse paper motion and also lacking
hardware tab stops (Texas Instruments 700 series, and so on):
rom -T745 filename ...

or
nroff -rom filename ... I col -x

The tbl(l) and eqn/neqn(l) fonnatters must be invoked as shown in
the command lines illustrated earlier.
If two-column processing is used with the nroff fonnatter, either the
-c option must be specified to rom (rom uses the col program
automatically for many terminal types) or the nroff fonnatter output
must be postprocessed by col. See col(l) in AIUX Command
Reference, "Two-Column Output" and "The rom Command." In the
latter case, the -T37 tenninal type must be specified to the nroff
formatter, the -h option must not be specified, and the output of
col(l) must be processed by the appropriate tenninal filter (for
example, 450(1»; rom(l) with the -c option handles all this
automaticall y.

2.4 Parameters set from command line
Number registers are commonly used within rom to hold parameter
values that control various aspects of output style. Many of these
values can be changed within the text files with. nr requests. In
addition, some of these registers can be set from the command line.
This is a useful feature for those parameters that should not be
permanently embedded within the input text. If used, the number
registers (with the exception of the P register) must be set on the
command line or before the rom macro definitions are processed. The
number register meanings are as follows:

4-8

-rAn

n = 1, has the effect of invoking the . AF macro without
an argument (see "Alternate First-Page Format").

-rCn

Sets type of copy (for example, DRAFT) to be printed at
the bottom of each page (see "Page Footer").
n = 1, OFFICIAL FILE COPY.
n = 2, DATE FILE COPY.

NUX Text Processing Tools

n = 3, DRAFf with single spacing and default
paragraph style.
n = 4, DRAFf with double spacing and 10-space
paragraph indent.

- rD 1

Sets debug mode. This flag requests the formatter to
continue processing even if rom detects errors that would
otherwise cause termination. It also includes some
debugging information in the default page header (see
"Page Header" and "SCCS Release Identification").

- rEn

Controls the font 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 un scaled number
representing lines.
For the troff formatter, k must be scaled (i for
inches, v for vertical spaces).
Default value is 66 lines per page.

- rNn

Specifies page numbering style.
n = (default), all pages get the prevailing header
n = 1, page header replaces footer on page 1 only.
n =2, page header is omitted from page 1.
n = 3, "section-page" numbering occurs (. FD and. RP
define footnote and reference numbering in sections).
(See "Page Header," "First-Level Headings and PageNumbering Style," "Format Style of Footnote Text"
and "Reference Page.' ')
n =4, default page header is suppressed; however, a
user-specified header is not affected.
n = 5, "section-page" and "section-figure" numbering
occurs.

Reference

4-9

Page 1

Pages 2ff

0
1
2
3
4

Header
Header replaces footer
No header
"Section-page" as footer
No header
"Section-page" as footer
and "section-figure"

Header
Header
Header
Same as page 1
No header unless . PH defined
Same as page 1

Contents of the prevailing header and footer do not
depend on number register N value; N controls only
whether the header (N=3) or the footer (N=5) is printed,
as well as the page-numbering style. If header and
footer are null (see "Page Header" and "Page
Footer' '), the yalue of N is irrelevant.

- rok

Offsets output k spaces to the right.
For the nroff formatter, k is an unscaled number
representing character positions.
For the troff formatter, k must be scaled.
This flag is helpful for adjusting output positioning on
some terminals. If this register is not set on the
command line, the default offset is 0.75 inch in nroff
and 0.5 inch in troff.
Note: Register name is the capital letter o.

-rPn

Specifies that pages of the document are to be numbered
starting with n.
This register may also be set via a . nr request in the
input text.

-rSn

Sets point size and vertical spacing for the document.
The default n is 10, that is, 10-point type on l2-point
vertical spacing, giving 6 lines per inch (see" Setting
Point Size and Vertical Spacing").
This flag applies to the troff formatter only.

-rTn

Provides register settings for certain devices.
n = 1, line length and page offset are set to 80 and 3,

4-10

A/UX Text Processing Tools

respectively.

n =2, changes the page length to 84 lines per page and
inhibits underlining; it is meant for output sent to the
Versatec printer.
The default value for n is O.
This flag applies to the nroff formatter only.
- rUl

Controls underlining of section headings.
This flag causes only letters and digits to be underlined.
Otherwise, all characters (including spaces) are
underlined (see "nroff Underlining Style").
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 un scaled 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).

2.5 Om ission of -mm flag
If a large number of arguments is required on the command line, it may
be convenient to set up the first (or only) input file of a document as
follows:

zero or more initializations of registers
listed in "Parameters Set From Command Line"
.so /usr/lib/tmac/tmac.m
remainder of text
In this case, the user must not use the -rom flag (nor the mm(l) or
mmt(l) command); the . so request has the equivalent effect, but
registers shown in "Parameters Set From Command Line" must be
initialized before the . so request because their values are meaningful
only if set before macro definitions are processed. When using this
method, it is best to lock into the input file only those parameters that
are seldom changed. For example,

Reference

4-11

.nr W 80
.nr 0 10
.nr N 3
.so /usr/lib/tmac/tmac.m
.H 1 "INTRODUCTION"

specifies, for the nroff fonnatter, a line length (w) of 80, a page offset
(0) of 10, and section-page (N) numbering.

3. Formatting concepts
3.1 Basic terms
Normal action of the formatters is to fill output lines from one or more
input lines. Output lines may be justified so that both the left and right
margins are aligned. As lines are being filled, words may also be
hyphenated as necessary (see "Hyphenation"). It is possible to tum
any of these modes on and off by using. SA (see "Justification of
Right Margin"), Hy (see "Hyphenation") and the. nf and. fi
formatter requests. Turning off fill mode also turns off justification and
hyphenation.
Certain formatting commands (requests and macros) cause filling of the
current output line to cease, the line (of whatever length) to be printed,
and subsequent text to begin a new output line. This printing of a
partially filled output line is known as a break. A few formatter
requests and most of the rom macros cause a break.
Formatter requests can be used with rom (see "Use of Formatter
Requests"); however, there are consequences and side effects that each
such request might have. A good rule is to use formatter requests only
when absolutely necessary. The rom macros described herein should be
used in most cases because

• It is much easier to control (and change at any later point in time)
the overall style of the document.
• Complicated features such as footnotes or tables of contents can
be obtained with ease.

4-12

A/UX Text Processing Tools

• The user is insulated from the complexities of the formatter
language.

3.2 Arguments and double quotes
For any macro call, a null argument is an argument whose width is
zero. Such an argument often has a special meaning; the preferred
form for a null argument is n n. Omitting an argument is not the same
as supplying a null argument (for example, the . MT macro; see
"Memorandum Types"). Omitted arguments can occur only at the
end of an argument list; null arguments can occur anywhere in the list.
Any macro argument containing ordinary (paddable) spaces must be
enclosed in double quotes. A double quote (n) is a single character
which should not be confused with two close quotes (' , ) or open
quotes ( , '). Unless you enclose an argument containing spaces in
double quotes, it will be treated as several separate arguments.
Double quotes are not permitted as part of the value of a macro
argument or of a string that is to be used as a macro argument. If it is
necessary to have a macro argument value, two close quotes (' , ) or
open quotes ( , ') or acorn bination of the two may be used instead.
This restriction is necessary because many macro arguments are
processed (interpreted) a variable number of times. For example,
headings are first printed in the text and may be reprinted in the table of
contents.

3.3 Unpaddable spaces
When output lines are justified to give an even right margin, existing
spaces in a line may have additional spaces appended to them. This
may distort the desired alignment of text. To avoid this distortion, it is
necessary to specify a space that cannot be expanded during
justification, that is, an unpaddable space. There are several ways to
accomplish this:
• Type a backs lash followed by a space. This pair of characters
directly generates an unpaddable space.
• Sacrifice some seldom-used character to be translated into a
space when output is generated.
Because this translation occurs after justification, the chosen character
may be used anywhere an unpaddable space is desired. The tilde (-) is

mm Reference

4-13

often used with the translation macro for this purpose. To use the tilde
in this way, the following is inserted at the beginning of the document:
.tr -

If a tilde must actually appear in the output, it can be temporarily
, 'recovered" by inserting
.tr --

before the place where needed. Its previous usage is restored by
repeating the . t r - after a break or after the line containing the tilde
has been forced out.

Note: Use of the tilde in this fashion is not recommended for
documents in which the tilde is used within equations.

3.4 Hyphenation
Formatters do not perform hyphenation unless it is requested.
Hyphenation can be turned on in the body of the text by specifying
.nr Hy 1

once at the beginning of the document input file. "Format Style of
Footnote Text" describes hyphenation within footnotes and across
pages.
If hyphenation is requested, formatters will automatically hyphenate
words if need be. However, the user may specify hyphenation points
for a specific occurrence of any word with a special character known as
a hyphenation indicator or may specify hyphenation points for a small
list of words (about 128 characters).
If the hyphenation indicator (initially, the two-character sequence \ %)
appears at the beginning of a word, the word is not hyphenated.
Alternatively, this sequence can be used to indicate legal hyphenation
points inside a word. All occurrences of the hyphenation indicator
disappear when output is generated.
The user may specify a different hyphenation indicator.

. He [hyphenation-indicator]

4-14

A/UX Text Processing Tools

The circumflex ( ... ) is often used for this purpose by inserting the
following at the beginning of a document input text file:
.HC ...

Note: Any word or phrase containing hyphens or dashes (also
known as em dashes) will be hyphenated immediately after a
hyphen or dash if it is necessary to hyphenate, even if the
formatter hyphenation function is turned off.
The user may supply, via the exception word . h w request, a small list
of words with the proper hyphenation points indicated. For example, to
indicate the proper hyphenation of the word "printout," the user may
specify
.hw print-out

3.5 Tabs
Macros. MT (see "Memorandum Types"), . TC (see "Table of
Contents"), and . Cs (see "Cover Sheet") use the formatter. ta (tab)
request to set tab stops and then restore the default values of tab
settings (every eight characters in the nroff formatter; every ~ inch
in the troff formatter). Setting tabs to other than the default values
is the user's responsibility.
Default tab setting values for nroff are 9,17,25, ... , 161 for a total
of 20 tab stops. Values may be separated by commas, spaces, or any
other non-numeric character. A user may set tab stops at any value
desired. For example,
.ta 1.Si 3i 4.Si
A tab character is interpreted with respect to its position on the input
line rather than its position on the output line. In general, tab
characters should appear only on lines processed in no-fill (. nf) mode
(see "Basic Terms").
The tbl(l) program (see "Tables") changes tab stops but does not
restore default tab settings.

mm Reference

4-15

3.6 BEL character
The nonprinting character BEL is used as a delimiter in many macros
to compute the width of an argument or to delimit arbitrary text, for
example, in page headers and footers, headings, and lists. Users who
include BEL characters in their input text file (especially in arguments
to macros) will receive mangled output. See' 'Page Headers and
Footers," "Paragraphs and Headings," and "Lists."

3.7 Bullets
A bullet ( • ) is often obtained on a typewriter terminal by using an "0"
overstruck by a "+". For compatibility with the t ro f f formatter, a
bullet string is provided by rom with the following sequence:
\*(BU

The bullet list (. BL) macro uses this string to generate automatically
the bullets for bullet-listed items (see "Bullet List").

3.8 Dashes, minus signs, and hyphens
The troff formatter has distinct graphics for a dash, a minus sign,
and a hyphen; the nroff formatter does not.
• Users who intend to use the nroff formatter only may use the
minus sign ( -) for the minus, hyphen, and dash.
• Users who plan to use the troff formatter primarily should
follow troff escape conventions (that is, \ (mi for minus,
\ (em for dash, and \ (hy for hyphen).
• Users who plan to use both formatters must 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

* (EM for each text dash for both nroff and
troff formatters. This string generates an em dash
(-) in the troff formatter and two hyphens (--) in
the nroff formatter. Dash list (. DL) macros (see

Type \

"Dash List' ') automatically generate the em dash
for each list item.

4-16

A/UX Text Processing Tools

Hyphen

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

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

3.9 Trademark string
A trademark string \ * (Tm is available with mm. This places the letters
"TM" one-half line above the text that it follows. For example,

The
A/UX\*(Tm manual
is available from the library.
yields
The NUX™ manual
is available from the library.

3.10 Use of formatter requests
Most fonnatter requests should not be used with mm because mm
provides the corresponding formatting functions in a much more useroriented and surprise-free fashion than do the basic formatter requests.
However, some fonnatter requests are useful with mm, namely the
following:

.af
.br
.ce
.de
.ds
.fi
.hw
.ls
.nf
.nr
.nx
.rm
.rr

mm Reference

Assign format
Break
Center
Define macro
Define string
Fill output lines
Hyphen word exceptions
Line spacing
No filling of output lines
Number register define and set
Next file (does not return)
Remove macro
Remove register

4-17

.rs
.so
.sp
.ta
.ti
.tl
.tr
. !

Restore spacing
Source file and return
Space
Tab stop settings
Temporary indent
Title
Translate
Escape

The . fp (font position), .lg (ligature mode), and. S3 (spacecharacter size) requests are also sometimes useful for the troff
formatter. Use of other requests without fully understanding their
implications very often leads to disaster.

4. Paragraphs and headings
4.1 Paragraphs
.p

[type]

one or more lines of text

The . P macro is used to control paragraph style.

4.1.1 Paragraph indentation
An indented or an unindented paragraph is defined with the type
argument

o
1

Left justified
Indented

In a left-justified paragraph, the first line begins at the left margin. In
an indented paragraph, the paragraph is indented the amount specified
in the pi register (default value is 5 ens). For example, to indent
paragraphs by ten spaces in nroff the following is entered at the
beginning of the document input file:
.nr pi 10

A document input file possesses a default paragraph type obtained by
specifying . P before each paragraph that does not follow a heading
(see "Numbered Headings"). Default paragraph type is controlled by
the Pt number register.

4-18

A/UX Text Processing Tools

(
'~

• The initial value of Pt is 0, which provides left-justified
paragraphs.
• All paragraphs can be forced to be indented by inserting the
following at the beginning of the document input file:

.nr Pt 1
• All paragraphs can be indented (except when they occur after
headings, lists, and displays) by entering the following at the
beginning of the document input file:

.nr Pt 2
Both the pi and Pt register values must be greater than zero for any
paragraphs to be indented.

Note: Values that specify indentation must be unscaled and are
treated as character positions, that is, as a number of ens. In the
nroff fonnatter, an en is equal to the width of a character. In
the troff formatter, an en is the number of points (1 point =
1/72 of an inch) equal to half the current point size.
Regardless of the value of Pt, an individual paragraph can be forced to
be left-justified or indented. The. P 0 macro request forces left
justification; . P 1 causes indentation by the amount specified by the
register Pi.
If . P occurs inside a list, the indent (if any) of the paragraph is added
to the current list indent (see' 'Lists' ').

4.1.2 Numbered paragraphs
Numbered paragraphs may be produced by setting the Np register to 1.
This produces paragraphs numbered within first-level headings, for
example, 1.01, 1.02, 1.03,2.01, and so forth.
A different style of numbered paragraphs is obtained by using the. nP
macro rather than the . P macro for paragraphs. This produces
paragraphs that are numbered within second-level headings.

Reference

4-19

.H 1 "FIRST HEADING"
.H 2 "Second Heading"
.nP
one or more lines of text

The paragraphs contain a double-line indent in which the text of the
second line is indented to be aligned with the text of the first line so
that the number stands out.

4.1.3 Spacing between paragraphs
The P s number register controls the amount of spacing between
paragraphs. By default, Ps is set to 1, yielding one blank space in
nroff, one-half a vertical space in troff.

4.2 Numbered headings
• H level [heading-text] [heading-suffix]
zero or more lines of 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. If the heading
contains more than one word or contains spaces, the entire argument
must be enclosed in double quotes.
The heading-suffix argument may be used for footnote marks which
should not appear with heading text in the table of contents.
There is no need for a . P macro immediately after a . H or . HU (see
"Unnumbered Headings") because the. H macro also performs the
function of the . P macro. Any immediately following . P macro is
ignored. It is, however, good practice to start every paragraph with a
• P macro, thereby ensuring that all paragraphs begin with a . P
throughout a document.

4.2.1 Default headings
The effect of the . H macro varies according to the level argument.
First-level headings are preceded by two blank lines in nroff and one
vertical space in troff; all other levels are preceded by one blank line
in nroff and one-half a vertical space in troff. The following
describes the default effect of the level argument.

4-20

A/UX Text Processing Tools

. H 1 heading-text

Produces an underlined (italicized) font heading, followed by a
single blank line. The text that follows begins on ~ new line and
is indented according to the current paragraph type. Full capital
letters can be used to make the heading stand out.
.H

n heading-text
Produces an underlined (italicized) font 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 (horizontal and vertical) occurs
even if the heading-text argument is omitted from a . H macro call.
Note: Users satisfied with the default appearance of headings
may skip to the section entitled "Unnumbered Headings."

4.2.2 Altering appearance
The user can modify the appearance of headings quite 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.
4.2.2.1 Prespacing and page ejection
A first-level heading (. H 1) normally has two blank lines (one vertical
space) preceding it, and all other headings are preceded by one blank
line (nroff) or one-half a vertical space (troff). If a multiline
heading were to be split across pages, it is automatically moved to the
top of the next page. Every first-level heading may be forced to the top
of a new page by inserting
.nr Ej 1

at the beginning of the document input text file. Long documents may
be made more manageable if each section starts on a new page. Setting
the E j (eject) 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 E j value.

Reference

4-21

4.2.2.2 Spacing after 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 the value of Hb, a break (see
"Basic Terms' ') occurs after the heading.
If the heading level is less than or equal to the value of Hs, a blank line
(nraff) or one-half a vertical space (traff) is inserted after the
heading.
If a heading level is greater than the value of Hb and also greater than
the value of Hs, then the heading (if any) is run into the following text.
These registers permit headings to be separated from the text in a
consistent way throughout a document while allowing easy alteration
of white space and heading emphasis. The default value for Hb and Hs
is 2.
For any stand-alone heading, that is, a heading not run into the
following text, alignment of the next line of output is controlled by the
Hi number register.

• If Hi is 0, text is left-justified.
• If Hi is 1 (the default value), text is indented according to the
paragraph type as specified by the Pt register (see "Paragraph
Indentation") .

• If Hi is 2, text is indented 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 (nraff) or one-half a vertical space (traff) 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), the following should appear at the
beginning of the document input text file:
.nr Hs 3
.nr Hb 7
.nr Hi 0

4-22

AlUX Text Processing Tools

(
''\I

4.2.2.3 Centered headings
The He register can be used to obtain centered headings. A heading is
centered if its level argument is less than or equal to He and if it is also
a stand-alone heading. The He register is 0 initially (no centered
headings).

4.2.2.4 Bold, ItaliC, and underlined headings
4.2.2.4.1 Control by level
Any heading that is underlined by the nraff formatter is italicized by
the traff formatter. The string HF (heading font) contains seven
codes that specify fonts for heading levels 1 through 7. You can use
any font number defined on your output device, for example:

Formatter
nraff
traff

HF Code
2

Default
HF Code

no underline
roman

underline
italic

bold
bold

2222222
2222222

Thus, levels 1 through 7 are underlined by the nraff formatter and
italicized by the traff formatter. The user 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 levels 1 through 5 in bold font
and levels 6 and 7 in roman font:
.ds HF 3 3 3 3 3

4.2.2.4.2 nroff underlining style
The nraff formatter underlines in either of two styles:
• The normal style (. ul request) is used to underline only letters
and digits .
• The continuous style (. eu request) underlines all characters
including spaces.
By default, rom 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 (only letters and digits).

mm Reference

4-23

All underlining of headings can be forced to the nonnal style by using
the -rU1 flag option when invoking the nroff fonnatter (see
"Parameters Set From Command Line").

4.2.2.4.3 Heading point sizes
The user can specify the desired point size for each heading level with
the HP string (for use with the troff fonnatter only) .
. ds HP [psi] [ps2] [ps3] [ps4] [ps5] [ps6] [ps7]
By default, the text of headings ( . H and . HU) is printed 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. The string HP, similar to the
string HF, can be specified 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
12-point 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
If absolute point sizes are specified, then absolute sizes will be used
regardless of the point size of the body of the document. If relative
point sizes are specified, then point sizes for headings will be relative to
the point size of the body even if the latter is changed.

Null or zero values imply that default size will be used for the
corresponding heading level.

Note: Only the point size of the headings is affected.
Specifying a large point size without providing increased
vertical spacing (via. HX or . HZ) may cause overprinting.

4.2.2.5 Marking styles-numerals and concatenation
The registers named H1 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.

4-24

AlUX Text Processing Tools

· HM [argJ] ... [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

1
0001

Arabic (default for all levels)
Arabic with enough leading zeros
to get the specified number of digits
Uppercase alphabetic
Lowercase alphabetic
Uppercase roman
Lowercase roman
Interpreted as 1 (arabic)
No effect

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,
input for a commonly used outline style is

.HM I A 1 a i
.nr Ht 1

4.3 Unnumbered headings
The . HU macro is a special case of . H; it is handled in the same way as
• H except that no heading mark is printed.
• HU heading-text

In order to preserve the hierarchical structure of headings when . H and
• HU calls are intermixed, each . HU heading is considered to exist at
the level given by register Hu, whose initial value is 2. Thus, in the
normal case, the only difference between
• HU heading-text

and

mm Reference

4-25

• H 2 heading-text

is the printing of the heading mark for the latter. Both macros have the
effect of incrementing the numbering counter for level 2 and resetting
to zero the counters for levels 3 through 7. Typically, the value of Hu
should be set to make unnumbered headings (if any) be the lowestlevel headings in a document.
The . HU macro can be especially helpful in setting up appendixes and
other sections that may not fit well into the numbering scheme of the
main body of a document (see "Appendix Headings").

4.4 Headings and table of contents
The text of headings and their corresponding page numbers can be
collected automatically for a table of contents. This is accomplished by
doing the following:
• specifying in the contents level register, CI, what level headings
are to be saved
• invoking the . TC macro (see "Table of Contents") at the end of
the document.
Any heading whose level is less than or equal to the value of the CI
register is saved and later displayed in the table of contents. The
default value for the C I register is 2, that is, the first two levels of
headings are saved.
Due to 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 (see "Displays") and
footnotes (see "Footnotes"). If this happens, the "Out of temp file
space" formatter error message will be issued; the only remedy is to
save fewer levels, to have fewer words in the heading text or do both.

4.5 First-level headings and page-numbering style
By default, pages are numbered sequentially at the top of the page. For
large documents, it may be desirable to use page numbering of the
section-page form where section is the number of the current first-level
heading. This page numbering style can be achieved by specifying the
-rN3 or -rNS flag option on the command line (see "Default Header
and Footer with Section-Page Numbering"). This also has the effect of
setting Ej to 1, which causes each first-level section to begin on a new

4-26

AlUX Text Processing Tools

page. In this style, the page number is printed at the bottom of the page
so that the correct section number is printed.

4.6 User exit macros
Note: This section is intended primarily for users who are
accustomed to writing formatter macros.
• HX dlevel rlevel heading-text
• HY dlevel rlevel heading-text
• HZ dlevel rlevel heading-text

The . HX, • HY, and . HZ macros are the means by which the user
obtains a final level of control over the previously described heading
mechanism. These macros are not defined by mm, they are intended to
be defined by the user. The . H macro call invokes . HX shortly before
the actual heading text is printed; 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
. ti for temporary indent, to be lost. Mter the size calculation, . HY is
invoked so that the user may specify these features again. All default
actions occur if these macros are not defined. If . HX, • HY, or . HZ are
defined by the user, user-supplied definition is interpreted at the
appropriate point. These macros can influence handling of all headings
because the . HU macro is actually a special case of the . H macro.
If the user first invokes the . H macro, then the derived level argument
(dleve!) and the real level argument (rlevel) both are equal to the level
given in the . H invocation. If the user first invokes the . HU macro (see
"Unnumbered Headings' '), 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, produced blank lines (vertical spaces) to
precede the heading (see' 'Prespacing and Page Ejection' '), and
accumulated the "heading mark", that is, the string of digits, letters,
and periods needed for a numbered heading. When . HX is called, all
user-accessible registers and strings can be referenced, as well as the
following:

rom

Reference

4-27

string } a

If rlevel is nonzero, this string contains the heading
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.

This register indicates the type of spacing that is to
follow the heading (see "Spacing after Headings").
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 of2 means that a blank line (nraff) or
one-half a vertical space (traff) is to follow the
heading.

string} 2

If register; a is 0, this string contains two
unpaddable spaces that will be used to separate the
(run-in) heading from the following text.
If register ; a is nonzero, 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 a value of 1 otherwise. The . ne request is for
the following number of lines: the contents of the
register; a taken as blank lines (nraff) or halves
of vertical space (troff) plus the contents of
register; 3 as blank lines (nroff) or halves of
vertical space (traff) plus the number of lines of
the heading.

The user 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 } a

\ \ n (H 1 . a\ \

(where stands for a space)
• Separate run-in heading from the text with a period and two
unpaddable spaces:

4-28

AlUX Text Processing Tools

. if \ \ n ( ; 0 = 0 . ds }2 . \ \
• Assure that at least 15 lines are left on the page before printing a
first-level heading:
.if \\$1=1 .nr;3 (15-\\n(;O)v
• Add three additional blank lines before each first-level heading:
.if \\$1=1 .sp 3
• Indent level 3 run-in headings by five spaces:
.if \\$1=3 .ti 5n
If temporary strings or macros are used within . HX, their names should
be chosen with care (see "Naming Conventions").
When the . HY macro is called 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 permit user-controlled
actions after the heading is produced. In a large document, sections
may correspond to chapters of a book; and the user may want to change
a page header or footer, for example,
.de HZ
.if \\$1=1 .PF "Section \\$3"

4.7 Hints for large documents
A large document is often organized for convenience into one input
text file per section. If the files are numbered, it is wise to use enough
digits in the names of these files for the maximum number of sections,
that is, use suffix numbers 01 through 20 rather than 1 through 9 and 10
through 20.
Users often want to format individual sections of long documents. To
do this with the correct section numbers, it is necessary to set register
H1 to one less than the number of the section just before the
corresponding . H 1 call. For example, at the beginning of Part 5,

mm Reference

4-29

insert
.nr HI 4

It will also be necessary to set the correct page number by using the
. pn request or the - r P n flag option.

Note: This is not good practice. It defeats the automatic
(re)numbering of sections when sections are added or deleted.
Such lines should be removed as soon as possible.

5. Lists
This part describes different styles of lists; automatically numbered and
alphabetized lists, bullet lists, dash lists, lists with arbitrary marks, and
lists starting with arbitrary strings, that is, with terms or phrases to be
defined.

5.1 List spacing
Spacing at the beginning of the list and between items can be
suppressed by setting the list space register (Ls). The Ls register is set
to the innermost list level for which spacing is done. For example,
.nr Ls

specifies that no spacing will occur around any list items. The default
value for Ls is six (which is the maximum list-nesting level).

5.2 List macros
In order to avoid repetitive typing of arguments to describe the style or
appearance of items in a list, rom provides a convenient way to specify
lists. All lists share the same overall structure and are composed of the
following basic parts:
• A list-initialization macro (. AL . BL, . DL, • ML, . RL, or . VL)
determines the style of the list: line spacing, indentation,
marking with special symbols, and numbering or alphabetizing
of list items .
• One or more list-item macros (. LI) identify unique items to the
system. They are followed by the actual text of the
corresponding list items.

4-30

A/UX Text Processing Tools

• The list-end macro ( . LE) identifies the end of the list. It
terminates the list and restores the previous indentation.
Lists may be nested up to six levels. The list-initialization macro saves
the previous list status (indentation, marking, style, and so forth); the
. LE macro restores it.
With this approach, the format of a list is specified only once at the
beginning of the list. In addition, by building onto the existing
structure, users may create their own customized sets of list macros
with relatively little effort (see "List-Begin Macro and Customized
Lists" and "User-Defined List Structures").

5.2.1 list-Initialization macros
List-initialization macros are implemented as calls to the more basic
. LB macro (see "List-Begin Macro and Customized Lists"). They are
• AL
• BL
.DL

• ML
• RL
· VL

Automatically Numbered or Alphabetized List
Bullet List
Dash List
Marked List
Reference List
V ariable-Item List

5.3 Automatically numbered or alphabetized list
The . AL macro is used to begin sequentially numbered or alphabetized
lists.
· AL [type] [text-indent] [1]

If there are no arguments, the list is numbered; and text is indented by
Li (default is six) spaces from the indent in force when the. AL is
called. This leaves room for a space, two digits, a period, and two
spaces before the text. Values that specify indentation must be
unscaled and are treated as character positions, that is, number of ens.
The string . AL A 5 is used to initialize the following list:
A.

The type argument may be given to obtain a different type of
sequencing. Its value indicates the first element in the sequence
desired. If type argument is omitted or null, the value 1 is
assumed. Listed below are the arguments and interpretations:

Reference

4-31

Argument

Interpretation

Arabic (default for all levels)
Uppercase alphabetic
Lowercase alphabetic
Uppercase roman
Lowercase roman

a
I

If text-indent argument is non-null, it is used as the number of
spaces from the current indent to the text, that is, it is used
instead of the Li register for this list only. If text-indent
argument is null, the value of Li will be used.

If the third argument is given, a blank line (nroff) or one-half a
vertical space (troff) will not separate items in the list. A
blank line will occur before the first item however.

5.4 Bullet list
The . BL macro begins a bullet list.
· BL [text-indent] [1]

Each list item is marked by a bullet ( .) followed by one space. The
string . BL 5 is used to initialize the following list:
.. If the text-indent argument is specified (non-null), it overrides the
default indentation which is the amount of paragraph indentation
as given in the Pi register (see "Paragraphs"). In the default
case, the text of a bullet list lines up with the first line of indented
paragraphs.
• If the second argument is specified, no blank lines will separate
items in the list.

5.5 Dash list
The . D L macro begins a dash list.
· DL [text-indent] [1]

Each list item is marked by a dash (-) followed by one space. The
string . D L 5 is used to initialize the following list:
-

4-32

If the text-indent argument is specified (non-null), it overrides the
default indentation which is the amount of paragraph indentation
as given in the pi register (see "Paragraphs"). In the default

AlUX Text Processing Tools

case, the text of a dash list lines up with the first line of indented
paragraphs.

If the second argument is specified, no blank lines will separate
items in the list.

5.6 Marked list
The . ML macro is much like . BL and . DL macros but expects the user
to specify an arbitrary mark which may consist of more than a single
character.
. ML

mark [text-indent] [1]

The string. ML \ (sq 5 is used to initialize the following list:

Text is indented text-indent spaces if the second argument is
specified (non-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.

Note: The mark must not contain ordinary (paddable) spaces
because alignment of items will be lost if the right margin is
justified (see "Unpaddable Spaces").

5.7 Reference list
A . RL macro call begins an automatically numbered list in which the
numbers are enclosed by square brackets ([ ]) .
. RL [text-indent] [1]

The string . RL 5 is used to initialize the following list:
[1]

If text-indent argument is specified (non-null), it is used as the
number of spaces from the current indent to the text, that is, it is
used instead of Li for this list only. If text-indent argument is
omitted or null, the value of Li is used.

[2]

If the second argument is specified, no blank lines will separate
the items in the list.

mm Reference

4-33

5.8 Variable-item list
When a list begins with a . VL macro, there is effectively no current
mark; it is expected that each . L I will provide its own mark.
• VL text-indent [mark-indent] [1]

This form is typically used to display definitions of terms or phrases.

• 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 the third argument is specified, no blank lines will separate
items in the list.
An example of . VL macro usage is shown below:
.VL 20 5
.LI "First\ Mark"
This is the first mark specified for this list .
. LI "Second\ Mark"
.br
This is the second mark specified for this list.
The .br request causes a break so that this
text will appear one line below the mark .
. LI "Third\ Mark\ Longer\ Than\ Indent:"
This item shows the effect of a long mark;
one space separates the mark from the text .
. LI "\ "
This item has a nonprinting mark and effectively
produces a list item that is indented .
. LI
This item has an omitted mark
and produces a "hanging indent."
The first line of text is at the left margin and
the second is indented .
• LE

when formatted, it yields

4-34

A/UX Text Processing Tools

First Mark

This is the first mark specified for this list.

Second Mark
This is the second mark specified for this list.
The . b r request causes a break so that this
text appears one line below the mark.
Third Mark Longer Than Indent: This item shows the effect of a
long mark; one space separates the mark from
the text.
This item has a nonprinting mark (an
unpaddable space) and effectively produces a
list item that is indented.
This item has an omitted mark and produces a "hanging indent."
The first line of text is at the left margin and
the second is indented.

Note: The mark must not contain ordinary (paddable) spaces
because alignment of items will be lost if the right margin is
justified (see "Unpaddable Spaces"). If you do not escape the
spaces within the double quotes containing the list item, the first
line of the text will be slightly adjusted for the paddable spaces
and will not line up with the rest of the text blocks in your list.

5.9 List-Item macro
The . L I macro is used with all lists and for each list item.
· LI [mark]. [1]
one or more lines of text that make up the list item

It normally causes output of a single blank line (nroff) or one-half a
vertical space (troff) before its list item although this may be
suppressed.

• If no arguments are given, . LI labels the item with the current
mark (except in . VL lists) which is specified by the most recent
list-initialization macro.
• If a single argument is given, that argument is output instead of
the current mark.

mm Reference

4-35

• If two arguments are given, the first argument becomes a prefix
to the current mark thus allowing the user to emphasize one or
more items in a list. One unpaddable space is inserted between
the prefix and the mark.

For example,
.BL 5
.LI
This is a simple bullet item .
. LI +
This replaces the bullet with a "plus."
.LI + 1
This uses a "plus"
as prefix to the bullet .
. LE

when formatted yields
• This is a simple bullet item.

+ This replaces the bullet with a "plus."

+. This uses a "plus" as prefix to the bullet.
Note: The mark must not contain ordinary (paddable) spaces
because alignment of items will be lost if the right margin is
justified (see' 'Unpaddable Spaces' ').
If the current mark (in the current list) is a null string and the first
argument of . LI is omitted or null, the result is that of a "hanging
indent, " that is, the first line of the following text is moved to the left
starting at the same place where mark would have started (see
"Variable-Item List").

5.10 List-end macro
The . LE macro restores the state of the list to that existing just before
the most recent list-initialization macro call.
. LE [1]

If the optional argument is given, the . LE generates a blank line
(nroff) or one-half a vertical space (troff). This option should

4-36

AlUX Text Processing Tools

(
~

generally be used only when the . LE is followed by running text but
not when followed by a macro that produces blank lines of its own,
such as the . P or . H macro.
The . H and . HU macros automatically clear all list information. The
user may omit the . LE macros that would normally occur just before
either of these macros and not receive the "LE : mismatched" error
message. Such a practice is not recommended because errors will
occur if the list text is separated from the heading at some later time
(for example, by insertion of text).

5.11 Example of nested lists
An example of input for the several lists and the corresponding output
is shown below. The . AL and . DL macro calls (see "Automatically
Numbered or Alphabetized List," and "Dash List") contained therein
are examples of list-initialization macros. Input text is
.AL A 5
.LI
This is automatically alphabetized list item A.
This list item has an indentation of 5 ens .
• AL

.LI
This is automatically numbered list item 1.
This list item also has an indentation of 5 ens .
. DL
.LI
This is a dash list item .
. LI + 1
This is another dash item in the same list
as the above item with a "plus" as prefix.
This is the last item in the dash list .
. LE

.LI
This is item 2 in the automatically numbered list.
This is the last item in the automatically
numbered list .
. LE

mm Reference

4-37

.LI

This is item B in the automatically alphabetized list.
This is the last item in the automatically
numbered list .
• LE

The output is
A.

This is automatically alphabetized list item A. This list item has
an indentation of 5 ens.

1. This is automatically numbered list item 1. This list item
also has an indentation of 5 ens.
-

2.
B.

This is a dash list item.
This is another dash item in the same list as the above item
with a "plus" as prefix. This is the last item in the dash
list.
This is item 2 in the automatically numbered list. This is
the last item in the automatically numbered list.

This is item B in the automatically alphabetized list. This is the
last item in the automatically numbered list.

5.12 List-begin macro and customized lists
List-initialization macros described above suffice for almost all cases.
However, if necessary, the user may obtain more control over the
layout of lists by using the basic list-begin macro (. LB) .
• LB text-indent mark-indent pad type [mark] [LI-space] [LB-space]

The . LB macro is used by the other list-initialization macros. Its
arguments are as follows:
• The text-indent argument provides the number of spaces that text
is to be indented 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

4-38

NUX Text Processing Tools

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 are appended 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 the text.
• Arguments type and mark interact to control the type of marking
used. If type is 0, simple marking is performed using the mark
character or characters found in the mark argument. If type is
greater than 0, automatic numbering or alphabetizing is done.
Then, mark is interpreted as the first item in the sequence to be
used for numbering or alphabetizing and is chosen from the set
(1, A, a, I, i) as in "Automatically Numbered or Alphabetized
List." This is summarized in the following table:
type

Argument
mark

0
0
>0
>0

Omitted
String
Omitted
One of:
1, A, a, I, i

Result

Hanging indent
String is the mark
Arabic numbering
Automatic numbering or
alphabetic sequencing

Each nonzero 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:

Value

Appearance

1
2

x.
x)
(x)
[x]

{x}

3
4

5
6

where x is the generated number or letter.

mm Reference

4-39

Note: mark must not contain ordinary (paddable) spaces
because alignment of items will be lost if the right margin is
justified (see "Unpaddable Spaces").

(

• The U-space argument gives the number of blank lines (nroff)
or halves of a vertical space (troff) that should be generated
by each . LI macro in the list. If omitted, U-space defaults to 1;
the value 0 can be used to obtain compact lists. If LI-space is
greater than 0, the . L I macro issues a . ne request for two lines
just before printing the mark.
• The LB-space argument is the number of blank lines (nroff) or
half vertical spaces (t ro f f) to be generated by . LB itself. If
omitted, LB-space defaults to O.
There are three combinations of U-space and LB-space:
• The normal case is to set U -space to 1 and LB -space to 0
yielding one blank line (nroff) or one-half a vertical space
(troff) before each item in the list; such a list is usually
terminated with a . LE 1 macro to end the list with a blank line
(nroff) or one-half a vertical space (troff).
• For a more compact list, LI-space is set to 0, LB-space is set to 1,
and the . LE 1 macro is used at the end of the list. The result is
a list with one blank line (nroff) or one-half a vertical space
(t ro f f) before and after it.
• If both U -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.

"User-Defined List Structures" shows how to build upon the supplied
list of macros to obtain other kinds of lists.

5.13 User-defined list structures
Note: This section is intended for users accustomed to writing
formatter macros.
If a large document requires complex list structures, it is useful to
define the appearance for each list level only once instead of having to

4-40

AlUX Text Processing Tools

define the appearance at the beginning of each list. This permits
consistency of style in a large document. A generalized listinitialization macro might be defined in such a way that what the macro
does depends on the list-nesting level in effect at the time the macro is
called. Levels 1 through 5 of the lists to be formatted may have the
following appearance:

A.
[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.
To understand it, the user should know that the number register: g is
used by the rom list macros 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.
.\"
.\"
.\"
.de
.nr
.if
.if
.if
.if
.if

register g is used as a local
temporary to save :g before
it is changed below
aL
g \ \n (:g
\\ng=O .AL A
\"
\\ng=l .LB \\n(Li 0 1 4
\"
\\ng=2 .EL
\"
\\ng=3 .LE \\n(Li 0 2 2 a
\"
\\ng=4 .ML +
\"

produces
produces
produces
produces
produces

an A.
a [1 ]
a bullet
an a)
a +

This macro can be used (in conjunction with. LI and. LE) instead of
. AL, . RL, . BL, . LB, and . ML. For example, the following input:

mm Reference

4-41

.AL
.LI

First line .
. aL
.LI

Second line .
. LE
.LI

Third line .
. LE

when formatted yields
1.

First line.
[1] Second line.

Third line.

There is another approach to lists that is similar to the . H mechanism.
List-initialization, as well as the . LI and the . LE macros, are all
included in a single macro. That macro, defined as . 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 issues a . L I macro call to produce the
item
.de bL
.ie \\n(.$ .nr g \\$1
\" if there is an argument, that is the level
. el .nr g \ \n (: g
\" if no argument, use current level
.if \\ng-\\n(:g>1 .)D
\" **ILLEGAL SKIPPING OF LEVEL
\" increasing level by more than 1
.if \\ng>\\n(:g \{.aL \\ng-1
\" if g > :g, begin new list
. nr g \ \n (: g\}
\" and reset g to current level
\" (. aL changes g)

4-42

A/UX Text Processing Tools

.if \ \n (:g>\ \ng .LC \\ng
\" if :g > g, prune back to correct level
\" if :g = g, stay within current list
.LI
\" in all cases, get out an item

For . bL to work, the previous definition of the . aL macro must be
changed to obtain the value of g from its argument rather than from
: g. Invoking. bL without arguments causes it to stay at the current
list level. The . LC (list clear) macro removes list descriptions until the
level is less than or equal to that of its argument. For example, the . H
macro includes the call . LC o. If text is to be resumed at the end of a
list, insert the call . LC 0 to clear out the lists completely. The
example below illustrates the relatively small amount of input needed
by this approach. The input text
The quick brown fox jumped over the lazy dog's back .
. bL 1
First line .
. bL 2
Second line .
. bL 1
Third line .
. bL
Fourth line .
. LC 0
Fifth line.

when formatted yields
The quick brown fox jumped over the lazy dog's back.
A.

First line.
[1] Second line.

Third line.

C. Fourth line.
Fifth line.

Reference

4-43

6. Memorandum and released-paper style
documents
Note: Some of the information in this section is applicable to

Bell Laboratories documents only. However, most of the
features discussed here can be tailored to specific needs.
One use of the Memorandum Macros is the preparation of memoranda
and released-paper documents that have special requirements for the
first page and for the cover sheet. Data needed (title, author, date, case
numbers, and so forth) are entered the same for both styles; an
argument to the . MT macro indicates which style is being used.

6.1 Sequence of beginning macros
If the following macros are present they must be given in the following
order:
• ND new-date

· TL [charging-case] [filing-case]

one or more lines of text
• AF

[company-name]

• AU name [initials] [loc] [dept] [ext] [room] [arg] [arg]
• AT

[title]

• TM [number] ...
· AS

[arg] [indent]
one or more lines of abstract text

.AE
.NS

[arg]
one or more lines of Copy to notation

.NE
· OK [keyword] ...
· MT

4-44

[type] [addressee]

AlUX Text Processing Tools

The only required macros for a memorandum for file or a releasedpaper document are . TL, • AU, and. MT; all other macros (and their
associated input lines) may be omitted if the features are not needed.
Once . MT has been invoked, none of the above macros (except. NS
and . NE) can be reinvoked because they are removed from the table of
defined macros to save memory space.
If neither the memorandum nor released-paper style is desired, the
.TL, .AU, .TM, .AE, .OK, .MT, .ND, and .AFmacrosshouldbe
omitted from the input text. If these macros are omitted, the first page
will have only the page header followed by the body of the document.

6.2 Title
The . TL macro generates a centered title.
• TL [charging-case] [filing-case]
one or more lines of title text

Arguments to the . TL macro are the charging-case number(s) and
filing-case number(s).
• The charging-case argument is the case number to which time
was charged for the development of the project described in the
memorandum. Multiple charging-case numbers are entered as
subarguments by separating each from the previous with a
comma and a space and enclosing the entire argument within
double quotes.
• The filing-case argument is a number under which the
memorandum is to be filed. Multiple filing case numbers are
entered similarly. For example,
.TL "12345, 67890" 987654321
Construction of a Table of Even Prime Numbers

The title of the memorandum or released-paper document follows the
. TL macro and is processed in fill mode. The . br request may be
used to break the title into several lines as follows:

rom Reference

4-45

.TL 12345
First Title Line
.br
\! .br
Second Title Line
On output, the title appears after the word "Subject" in the
memorandum style and is centered and bold in the released-paper
document style.
If only a charging case number or only a filing case number is given, it
will be separated from the title in the memorandum style by a dash and
will appear on the same line as the title. If both case numbers are given
and are the same, then "Charging and Filing case" followed by the
number will appear on a line following the title. If the two case
numbers are different, separate lines for "Charging Case" and "File
Case" will appear after the title.

6.3 Authors
The . AU and . AT macros take arguments that describe an author.

. AU name [initials] [loc] [dept] [ext] [room] [arg] [arg]
. AT [title] ...
If any argument contains blanks, that argument must be enclosed
within double quotes. The first six arguments must appear in the order
given. A separate . AU macro is required for each author.
The . AT macro is used to specify the author's title. Up to nine
arguments may be given. Each will appear in the signature block for
memorandum style (see "End of Memorandum Macros") on a
separate line following the signer's name. The. AT must immediately
follow the. AU for the given author. For example,

.AU "S. J. Jones" SJJ PY 9876 5432 1Z-234
.AT Director "Materials Research Laboratory"
In the' 'From" portion in the memorandum style, the author's name is
followed by location and department number on one line and by room
number and extension number on the next line. The' 'x" for the
extension is added automatically. Printing of the location, department
number, extension number, and room number can be suppressed on the
first page of a memorandum by setting the register Au to 0; the default

4-46

NUX Text Processing Tools

value for Au is 1. Arguments 7 through 9 of the .AU macro. if present,
will follow this normal author infonnation in the "From" portion. each
on a separate line. These last three arguments can be used for
organizational numbering schemes, and so on. For example,
.AU

"s.

P. Lename" SPL IH 998 7766 5H-44 654-3210.01MF

The name, initials, location. and department are also used in the
signature block. Author information in the "From" portion, as well as
names and initials in the signature block will appear in the same order
as the . AU macros.
Note: Names of authors in the released-paper style are centered
below the title. Following the name of the last author, "Bell
Laboratories" and the location are centered. The paragraph on
memorandum types contains information regarding authors
from different locations (see "Memorandum Types").

6.4 TM numbers
If the memorandum is a technical memorandum, the TM numbers are
supplied via the . TM macro .
. TM [number] ...
Up to nine numbers may be specified. For example •
. TM 7654321 77777777
This macro call is ignored in the released-paper and external-letter
styles (see "Memorandum Types").

6.5 Abstract
If a memorandum has an abstract, the input is identified with the . AS
(abstract start) and . AE (abstract end) delimiters .
• AS [arg] [indent]
text of abstract
.AE

Abstracts are printed on page one of a document. on its cover sheet or
on both. There are three styles of cover sheet:

mrn Reference

4-47

• released paper
• technical memorandum
• memorandum for file (also used for engineer's note,
memorandum for record, and so forth)
Cover sheets for released papers and technical memoranda are obtained
by invoking the. CS macro (see "Cover Sheet").
In released-paper style (first argument of the . MT macro is 4) and in
technical memorandum style, if the first argument of . AS is

Abstract will be printed on page one and on the cover
sheet (if any).

Abstract will appear only on the cover sheet (if any).

(See "Memorandum Types.")
In memoranda for file style and in all other documents (other than
external letters), if the first argument of . AS is

Abstract will appear on page one and there will be no
cover sheet printed.

Abstract will appear only on the cover sheet which 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 memoranda 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. (See' 'Copy To and Other Notations," "Numbered
Headings," "Unnumbered Headings" and "Displays.")
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 unscaled and are treated as
"character positions," that is, as the number of ens.

4-48

NUX Text Processing Tools

6.6 Other keywords
Topical keywords may be specified on a technical memorandum cover
sheet using the . OK macro .
. OK

[keyword] ...

Up to nine such keywords or keyword phrases can be specified as
arguments to the . OK macro; if any keyword contains spaces, it must
be enclosed within double quotes.

6.7 Memorandum types
The . MT macro controls the format of the top part of the first page of a
memorandum or of a released-paper document and the format of the
cover sheets .
• MT

[type] [addressee]

The type arguments and corresponding values are

No memorandum type printed

none

MEMORANDUM FOR FILE is printed

PROGRAMMER'S NOTES is printed

ENGINEER'S NOTES is printed

Released-paper style

External-letter style

" string"

string is printed

If the type argument indicates a memorandum style document, the
corresponding statement indicated under Value will be printed after the
last line of author information. If type is longer than one character,
then the string itself will be printed. For example,

.MT "Technical Note #5"
A simple letter is produced by calling . MT with a null (but not omitted)
or 0 argument.

mm Reference

4-49

The second argument to . MT is the name of the addressee of a letter. If
present, that name and the page number replace the normal page header
on the second and following pages of a letter. For example,
.MT 1 "Steve Jones"

produces
Steve Jones - 2
The addressee argument cannot be used if the first argument is 4
(released-paper style document).
The released-paper style is obtained by specifying
.MT 4 [1]

This results in a centered, bold title followed by centered names of
authors. The location of the last author is used as the location
following' 'Bell Laboratories" (unless the . AF macro specifies a
different company). If the optional second argument to . MT 4 is
given, the name of each author is followed by the respective company
name and location. Information necessary for the memorandum style
document but not for the released-paper style document is ignored.
If the released-paper style document is used, most Bell Telephone
Laboratories location codes are defined as strings that are the addresses
of the corresponding BTL locations. These codes are needed only until
the . MT macro is invoked. Thus, following the . MT macro, the user
may reuse these string names. In addition, the macros for the end of a
memorandum (see "End of Memorandum Macros") and their
associated lines of input are ignored when the released-paper style is
specified.

Authors from non-BTL locations may include their affiliations in the
released-paper style by specifying the appropriate . AF macro (see
"Alternate First-Page Format") and defining a string (with a 2character name such as zz) for the address before each. AU. For
example,

4-50

NUX Text Processing Tools

.TL
A Learned Treatise
.AF "Getem Inc."
.ds ZZ "22 Maple Avenue, Sometown 09999"
.AU "F. Swatter" "" ZZ
.AF "Bell Laboratories"
.AU "Sam P. Lename" "" CB
.MT 4 1

In the external-letter style document, only the title without the word
"Subject:" and the date are printed in the upper left and right comers,
respectively, on the first page. It is expected that preprinted stationery
will be used with the company logo and address of the author.

6.8 Date changes
The . ND macro alters the value of the string DT, which is initially set
to produce the current date .
• ND new-date

If the argument contains spaces, it must be enclosed within double
quotes.

6.9 Alternate first-page format
An alternate first-page format can be specified with the

.AF

macro .

. AF [company-name]

The words "Subject," "Date," and "From" (in the memorandum
style) are omitted and an alternate company name is used.
If an argument is given, it replaces "Bell Laboratories" without
affecting other headings. If the argument is null, "Bell Laboratories"
is suppressed; and extra blank lines are inserted to allow room for
stamping the document with a Bell System logo or a Bell Laboratories
stamp.

The . AF with no argument suppresses "Bell Laboratories" and the
"Subject/Date/From" headings, allowing output on preprinted
stationery. The use of .AF with no arguments is equivalent to the use
of - rAl except that the latter must be used if it is necessary to change
the line length, page offset, or both (these default to 5.8i and Ii,
respectively, for preprinted forms). The flag options -rOk and -rWk

mm Reference

4-51

are not effective with . AF. The only . AF use appropriate for the
traff formatter is to specify a replacement for "Bell Laboratories".
The flag option - rEn controls the font of the "Subject/Date/From"
block. (See' 'Parameters Set From Command Line. ")

6.10 Example
Input text for a document may begin as follows:
.TL
MM\*(EMMemorandum Macros
.AU "D. W. Smith" DWS PY
. AU "J . R. Mashey" JRM PY
. AU "E . C. Pariser (January 1980 Rev.)" ECP PY
.AU "N. W. Smith (June 1980 Rev.)" NWS PY

.MT 4

Figures 4-1, 4-2, and 4-3 at the end of this chapter show the input text
file for a simple letter as well as the formatted output from both the
nraff and traff formatters.

6.11 End of Memorandum Macros
At the end of a memorandum document, signatures of authors and a list
of notations can be requested. The following macros and their input
are ignored if the released-paper style document is selected.

6.11.1 Signature block
The . Fe and . SG macros print a formal closing and signature block.
· Fe [closing]
· SG [arg] [1]

The. Fe macro prints "Yours very truly," as a fonnal closing, if no
closing argument is used. It must be given before the . SG macro. A
different closing may be specified as an argument to . Fe.
The. SG macro prints the author's name after the formal closing, if
any. Each name begins at the center of the page. Three blank lines are
left above each name for the actual signature.
• If no arguments are given, the line of reference data (location
code, department number, author's initials, and typist's initials
all separated by hyphens) will not appear.

4-52

NUX Text Processing Tools

• A non-null first argument is treated as the typist's initials and is
appended to the reference data.
• A null first argument prints reference data without the typist's
initials or the preceding hyphen.

• If there are several authors and if the second argument is given,
reference data is placed on the line of the first author.
Reference data contains only the location and department number of
the first author. Thus, if there are authors from different departments or
from different locations, the reference data should be supplied
manually after the invocation (without arguments) of the. SG macro.
For example,
.SG

.rs
.sp -lv
PY/MH-9876/5432-JJJ/SPL-cen

6.11.2 "Copy to" and other notations
Many types of notations (such as a list of attachments or "Copy to"
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 .
. NS [arg]

zero or more lines of the notation
.NE

Codes for arg and the corresponding notations are

mm Reference

4-53

Argument Notation
none

""
0
1
2

3
4

5
6
7
8
9
" string"

Copy to
Copy to
Copy to
Copy (with att.) to
Copy (without att.) to
Att.
Atts.
Enc.
Encs.
Under Separate Cover
Letter to
Memorandum to
Copy (string) to

If arg consists of more than one character, it is placed within
parentheses between the words "Copy" and "to". For example,
.NS "with att. 1 only"
will generate
Copy (with att. 1 only) to
as the notation. More than one notation may be specified before the
• NE macro because a . N S macro terminates the preceding notation, if
one exists. For example,
.NS 4
Attachment I-List of register names
Attachment 2-List of string and macro names
.NS 1
S. J. Jones
.NS 2
S. P. Lename
G. H . Hurtz
. NE
would be formatted as

4-54

AlUX Text Processing Tools

Atts.
Attachment 1-List of register names
Attachment 2-List of string and macro names
Copy (with atl) to
S. J. Jones
Copy (without att.) to
S.P.Lename
G. H. Hurtz
The . NS and . NE macros can also be used following . AS 2 and . AE
to place the notation list on the memorandum for file cover sheet (see
"Abstract' '). If notations are given at the beginning without . AS 2,
they will be saved and generated at the end of the document.

6.11.3 Approval signature line
The . AV macro can be used after the last notation block to
automatically generate a line with spaces for the approval signature and
date .
. AV approver's-name
For example,

.AV "Jane Doe"
produces
APPROVED:

lane Doe

Date

6.12 One-page letter
To increase the page length temporarily, for example, to force space for
a signature at the bottom of a letter, you can use the -rLn flag option.
For example, using -rL9 0 has the effect of making the formatter
believe that the page is 90 lines long and therefore providing more
space than usual to place the signature or the notations.

mm Reference

4-55

Note: This will work only for a single-page letter or memo.

6.13 Define file Information
The /usr/lib/macros/ strings .mmfile contains pre-defined
strings for the . MT and . PM macros. These strings are proprietary
disclaimers for AT&T Bell Laboratories, and may be redefined by
system administrators to contain different string and font information.
Only system administrators have write permissions to change the define
file.

6.14 Busl ness letter style
An alternative to the format memorandum style is the business letter
style, which produces four types of business letters: blocked,
semiblocked, full-blocked, and simplified.

6.14.1 Letter-type macro
The letter-type macro. LT formats a letter in one of four business
styles:
. LT [arg]

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

Argument Format
none
BL
SB
FB
SP

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/troff attempts to process the file
according to the first formatting specific macro it encounters. mm
ignores . MT-specific macros and . MT-Specific command line

4-56

A/UX Text Processing Tools

parameters if you use them with . LT; conversely, if you use . LTspecific macros with . MT, rom ignores them.

If you use these business letter macros, the macro pairs, . wA/. WE, and
. IA/. IE, and the page formatting macros. 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 userspecified indentations will override. Specification of the Pt and pi
registers must occur after specification of the . LT macros.
• In the block format all lines of text begin at the left margin
except the dateline, 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.)
• 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.
The following table 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 Reference

4-57

Macro and function BL
. wA/. WE

center

SB
center

left

SP
left

left

center

left

none

left

indented

left

indented

left

center

left

Writer's address
· LO CN [arg]

Confidential notation
.LO RN[arg]

Reference notation
· IA/. IE

Inside address
• LO AT [arg]

Attention
· LO SA [arg]

Salutation
.LO SJ [arg]

Subject line
.P

Paragraphs
.FC

Closing
.SG

center

left

Signature
.NS/.NE

Copy notation
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.
• If rom does not recognize an argument to . LT, the file processing
aborts and an appropriate error message prints.

6.14.2 Writer's address macros
Use this macro pair to specify the writer of the letter and the writer's
return address.

4-58

AlUX Text Processing Tools

· WA writer-name [title]
return address

.WE

For example,
.WA "James Lorrin, Ph.D." Director
Summit Research Company
38 River Road
Summit, 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 "James Lorrin, Ph.D." 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.
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 Reference

4-59

.WA "James Lorrin, Ph.D." Director
Summit Research Company
38 River Road
Summit, New Jersey 07901
.WE
.WA "John Smith" Supervisor
.WE
.WA "Diane Kane" "Technical Support"
.WE

For blocked and semiblocked letter styles the writer return address
begins on line 12 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 of the page and each line begins at the
left margin.
Note: Top of page processing can be controlled directly
through nroff. The beginning of the printed page is userdefined. See the requests. wh and . ch in "nroff/troff
Reference. "

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

6.14.3 Inside address macros
. IA and. IE are a macro pair that you use to specify the addressee
and the addressee's address. There are two ways that you can use this
macro pair:

.IA
text
.IE
or

. IA [addressee-name] [title]
text
.IE
For example,

4-60

NUX Text Processing Tools

·IA
Fred Smith, Ph.D.
Columbia University
116th Street
New York, New York 10019
.IE
or

.IA "Fred Smith, Ph.D."
.IE
For all four styles of . LT, the inside address prints on the fifth line
below the date (if a reference notation or confidential notation appears
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.

6.14.4 Letter-options macro
The letter-options macro provides the capability for specifying five
common business letter components:
. LO 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. . LO' S arguments and their corresponding
components are below:

confidential notation

reference notation

attention

salutation

subject line

6.14.4.1 Confidential notation
The confidential notation shows that a business letter should be read
only by the person to whom it is addressed. The confidential notation

mm Reference

4-61

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,
.LO eN "RESTRICTED"

The default of CN prints CONF IDENT IAL.

6.14.4.2 Reference notation
The reference notation supplies specific information to be used by the
addressee. For example,
.LO RN "meeting of 1/25"

The reference note appears two lines below the dateline of the letter or
on the second line below any notation that follows the date and is left
aligned with the dateline 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.

6.14.4.3 Attention
The attention line directs the letter to the attention of a specific person
or department. For example,
.LO 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.

6.14.4.4 Salutation
The salutation specifies the letter's opening greeting. For the blocked,
semiblocked, and the full-blocked formats the salutation appears on the
second line below the inside address (or on the second line below the

4-62

A/UX Text Processing Tools

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,

.La SA "Dear Dr. Smith"
6.14.4.5 Subject line
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 begins at the left margin. For the
semi-blocked 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 you 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 . La .

. La SJ "Staff Meeting"
The format string" SUBJECT: " cannot be redefined. There is not a
default value for the optional argument.
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 . La macro without an argument or the argument you
specify is unrecognized, the file processing aborts and an appropriate
error message prints.

6.14.5 Multlpage letters
The . LT macro controls the format for the first page of the letter. The
letter macros will not alter the default nroff/troff page processing
following the first page of the letter.
6.14.6 Sequence of beginning letter macros
Macros. WA, . WE, . lA, . IE, and. LT must be given in the order
listed in the following table. . La can be specified multiple times with

Reference

4-63

different argument types. The. La argument types do not have to be in
any specific order. All . La requests must be specified before . LT .
• ND

newdate

• 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
· La type [arg]
· LT [arg]
.P
Text
.Fe
· SG [arg [1]]
• NS [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, rom processes the file as if you had not specified . LT.

7. Displays
Displays are blocks of text that are to be kept together on a page and
not split across pages. They are processed in an environment that is
different from the body of the text (see the . ev request in
"nroff/troff Refererence"). The Memorandum Macros package
provides two styles of displays-a static (. DS) style and a floating
( • DF) style.

4-64

AlUX Text Processing Tools

• In the static style, the 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 long to fit in the remaining page space.
• In the floating style, the display "floats" through the input text to
the top of the next page if there is not enough space on the
current page. Thus input text that follows a floating display may
precede it in the output text. A queue of floating displays is
maintained so that their relative order of appearance in the text is
not disturbed.
By default, a display is processed in no-fill mode with single spacing
and is not indented from the existing margins. The user can specify
indentation or centering as well as fill-mode processing.

Note: Displays and footnotes can never be nested in any
combination. Although lists and paragraphs are permitted, no
headings ( . H or . HU) can occur within displays or footnotes.

7.1 Static displays
A static display is started by the . D S macro and terminated by the . DE
macro.
• DS [format] [fill] [rindent]
one or more lines of text
.DE

With no arguments, . DS accepts lines of text exactly as typed (no-fill
mode) and will not indent lines from the prevailing left margin
indentation or from the right margin.
• The format argument is an integer or letter used to control the
left margin indentation and centering with the following
meanings:

mm Reference

4-65

format

Meaning

no indent
no indent
no indent
indent by standard amount
center each line
center as a block

omitted
o or L
lor I

20rC
30rCB

• The fill argument is an integer or letter and can have the
following meanings:

fill

Meaning

no-fill mode
no-fill mode
no-fill mode
fill mode

omitted
o orN
10rF

• The rindent argument is the number of characters that the line
length should be decreased, that is, an indentation from the right
margin. This number must be unsealed in the nroff formatter
and is treated as ens. It may be scaled in the troff formatter or
else it defaults to ems.
The standard amount of static display indentation is taken from the S i
register, a default value of five spaces. Thus, text of an indented
display aligns with the first line of indented paragraphs, whose indent is
contained in the pi register (see "Paragraphs"). Even though their
initial values are the same default values, these two registers are
independent.
The display format argument value 3 (or CB) horizontally centers the
entire display as a block, as opposed to . DS 2 and. DF 2, which
center each line individually. All collected lines are left justified, and
the display is centered based on the width of the longest line. This
format must be used in order for the eqn/neqn mark and lineup
feature to work with centered equations (see "Equations' ').
By default, a blank line (nroff) or one-half a vertical space (troff)
is placed before and after static and floating displays. These blank
lines before and after static displays can be inhibited by setting the
register Ds to O.

4-66

AlUX Text Processing Tools

The following example shows usage of all three arguments for static
displays. This block of text will be indented five spaces (ems in
t ro f f) from the left margin, filled, and indented five spaces (ems in
troff) from the right margin (that is, centered). The input text
.DS I F 5
"We the people of the United 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."
.DE

produces the output
"We the people of the United 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."

7.2 Floating displays
A floating display is started by the . DF macro and terminated by the
.DE macro .
• DF [format] [fill] [rindent]
one or more lines of text
.DE

Arguments have the same meanings as static displays described above,
except indent, no indent, and centering are calculated with respect to
the initial left margin. This is because prevailing indent may change
between when the formatter first reads the floating display and when
the display is printed. One blank line (nroff) or one-half a vertical
space (t ro f f) occurs before and after a floating display.
The user may exercise precise control over the output positioning of
floating displays through the use of two number registers, De and D f
(see below). When a floating display is encountered by the nroff or

Reference

4-67

ro f f formatter, it is processed and placed onto a queue of displays
waiting to be generated. Displays are removed from the queue and
printed in the order entered, which is the 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. Immediate output is governed by size of display
and the setting of the D f register code. The De register code controls
whether text will appear on the current page after a floating display has
been produced.
t

As long as the display queue contains one or more displays, new
displays will be automatically entered there, rather than being
generated. When a new page is started, or the top of the second
column in 2-column mode, the next display from the queue becomes a
candidate for output if the Df register code has specified top-of-page
output. When a display is generated, it is also removed from the queue.
When the end of a section (using section-page numbering) or the end of
a document is reached, all displays are automatically removed from the
queue and are generated. This occurs before a . SG, . CS, or . TC
macro is processed.
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. A wide (full-page
width) display will not fit in the second column of a 2-column
document.
The De and D f number register code settings and actions are as
follows:

4-68

A/UX Text Processing Tools

Code

Action

No special action occurs (also the default condition).

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

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

Code

Action

Floating displays will not be generated until end of
section (when section-page numbering) or end of
document.

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

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

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

Generate as many displays as will fit (but at least one)
starting at the top of a new page or column.

If the De register is set to 1, each display will be followed
by a page eject, causing a new top of page to be reached
where at least one more display will be generated (this
also applies to code 5).

Generate a new floating display on the current page if
there is room (default condition). Generate as many
displays (but at least one) as will fit on the page starting at
the top of a new page or column.

Reference

4-69

Note: For any code greater than 5, the action performed is the
same as for code 5. If the De register is set to 1, each display
will be followed by a page eject, causing a new top of page to
be reached where at least one more display will be generated.
The. we macro (see "Two-Column Output") can also be used to
control handling of displays in double-column mode and to control the
break in text before floating displays.

7.3 Tables
The rom macros interact with the tbl macros and provide some extra
functionality (see "tbl Reference" for a description of the tbl
program) .
. TS [H]

global options;
column descriptors.
title lines
[. TH [N]]

data within the table .
• TE

The . TS (table start) and. TE (table end) macros make possible the
use of the tbl(l) program. These macros are used to delimit text to be
examined by tbl and to set proper spacing.around the table.
The display function and the tbl delimiting function are independent.
In order to permit the user to keep together blocks that contain any
mixture of tables, equations, filled text, unfilled text, and caption lines,
the. TS/. TE block should be enclosed within a display (. DS/. DE).
Floating tables may be enclosed inside floating displays (. DF/. DE).
Macros . T sand . TE permit processing of tables that extend over
several pages. If a table heading is needed for each page of a
multipage table, the H argument should be specified to the . T S macro
as above. Following the options and format information, the table title
is typed on as many lines as required and is followed by the . TH
macro. The . TH macro must occur when . T S H is used for a
multipage table. This is not a feature of tbl but of the definitions
provided by the Memorandum Macros package.

4-70

A/UX Text Processing Tools

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. This option is used when it is necessary to
build long tables from smaller . T S HI. TE segments. For example,
.TS H

global options;
column descriptors.
title lines
.TH

data
.TE
.TS H

global options;
column descriptors.
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 will still appear at the
top of each page that contains the table. This feature is used 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 HI. TH sequence, it would have its own header. However, if
each table segment after the first uses . T S HI. T H N, the table header
will appear only at the beginning of the table and the top of each new
page or column that contains the table.
For the nroff formatter, the -e flag option (-E for rom(l» can be
used for terminals, for instance the 450, that are capable of finer
printing resolution. This will cause better alignment of features such as
the lines forming the corner of a box. The -e flag option is not
effective with col(l). (See "The rom Command.")

Reference

4-71

7.4 Equations
Mathematical typesetting programs eqn/neqn(l) expect to use the
· EQ (equation start) and . EN (equation end) macros as delimiters in
the same way that tbl(l) uses. TS and. TE; however, when
processed with the rom macros, . 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.
.DS
· EQ [label]
equation(s)
.EN
.DE

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

7.5 Figure, table, equation, and exhibit titles
The . FG (figure title), . TB (table title), . EC (equation caption), and
· EX (exhibit caption) macros are normally used inside. DS/. DE pairs
to automatically number and print captions for figures, tables, and
equations.
· FG
· TB
· EC
· EX

[title]
[title]
[title]
[title]

[override]
[override]
[override]
[override]

[flag]
[flag]
[flag]
[flag]

These macros use registers Fg, Tb, Ec, and Ex, respectively (See
"Parameters Set From Command Line" on - rN 5 to reset counters in
sections.) For example,
.FG "This is a Figure Title"

yields

4-72

A/UX Text ProceSSing Tools

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 the first are indented to line up with
the first character of the title. The format of the numbers can be
changed using the . af request of the formatter. By setting the Of
register to 1, the format of the caption may be changed from
Figure 1. title
to
Figure 1 - title
The override argument is used to modify normal numbering. If the flag
argument is omitted or 0, override is used as a prefix to the number; if
the flag argument is 1, override is used as a suffix; and if the flag
argument is 2, override replaces the number. If -rN5 is given,
"section-figure" numbering is set automatically and user-specified
override argument is ignored. (See' 'Parameters Set From Command
Line.")
As a matter of formatting style, table headings are usually placed above
the text of tables, while figure, equation, and exhibit titles are usually
placed below corresponding figures and equations.

7.6 List of figures, tables, equations, and exhibits
Lists of figures, tables, exhibits, and equations are printed following the
table of contents if the number registers Lf, Lt, Lx, and Le
(respectively) are set to 1. The Lf, Lt, and Lx registers are 1 by
default; Le is by default.

Titles of these lists can be changed by redefining the following strings,
which are shown here with their default values:
.ds
.ds
.ds
.ds

Lf
Lt
Lx
Le

LIST
LIST
LIST
LIST

mm Reference

OF
OF
OF
OF

FIGURES
TABLES
EXHIBITS
EQUATIONS

4-73

8. Footnotes
There are two macros ( . F S and . FE) that delimit text of footnotes, a
string (F) that automatically numbers footnotes, and a macro ( . FD)
that specifies the style of footnote text. Footnotes are processed in an
environment different from that of the body of text (refer to . ev
request in "nroff/troff Reference").

8.1 Automatic numbering of footnotes
Footnotes may be automatically numbered by typing the three
characters \ *F (that is, invoking the string F) immediately after the
text to be footnoted without any intervening spaces. This will place the
next sequential footnote number (in a smaller point size) a half line
above the text to be footnoted.

8.2 Delimiting footnote text
. FS [label]
one or more lines offootnote text
.FE

There are two macros that delimit the text of each footnote. The . F S
(footnote start) macro marks the beginning of footnote text, and the
. FE (footnote end) macro marks the end. The label on the . F S macro,
if present, will be used to mark footnote text. Otherwise, the number
retrieved from the string F will be used. Automatically numbered and
user-labeled footnotes can be intermixed. If a footnote is labeled (. FS
label), the text to be footnoted must be followed by label, rather than
by \ *F. Text between . F S and . FE is processed in fill mode.
Another. FS, a . DS, or a . DF is not permitted between. FS and. FE
macros. If footnotes are required in the title, abstract, or table (see
"Tables"), only labeled footnotes will appear properly. Everywhere
else automatically numbered footnotes work correctly. For example,
the input for an automatically numbered footnote is
This is the line containing the word\*F
.FS
This is the text of the footnote.
.FE
to be footnoted and automatically numbered.

and the input for labeled footnote is:

4-74

AlUX Text Processing Tools

This is a labeled*
.FS *
The footnote is labeled with an asterisk .
• FE

footnote.
Text of the footnote (enclosed within the . F S / . FE pair) should
immediately follow the word to be footnoted in the input text, so that
\ *F or label occurs at the end of a line of input and the next line is the
• F S macro call. It is also good practice to append an unpaddable
space (see "Unpaddable Spaces") to \ *F or label when they follow
an end-of-sentence punctuation mark (a period, question mark, or
exclamation point).

8.3 Format style of footnote text
Within footnote text, the user can control formatting style by specifying
text hyphenation, right margin justification, and text indentation, as
well as left or right justification of the label when text indenting is used.
The . FD macro is invoked to select the appropriate style.
• FD [arg] [1]

The first argument (arg) is a number from the left column of the
following table. Formatting style for each number is indicated in the
remaining four columns. Further explanation of the first two of these
columns is given in the definitions of the. ad, . na, . hy, and. nh
(adjust, no adjust, hyphenation, and no hyphenation, respectively)
requests in "nroff/troff Reference."

mm Reference

4-75

Argument

0
1
2
3
4

5
6
7

8
9

10
11

Hyphenation

Adjust

Text
indent

Label
justification

.nh
.hy
.nh
.hy
.nh
.hy
.nh
.hy
.nh
.hy
.nh
.hy

.ad
.ad
.na
.na
.ad
.ad
.na
.na
.ad
.ad
.na
.na

yes
yes
yes
yes
no
no
no
no
yes
yes
yes
yes

left
left
left
left
left
left
left
left
right
right
right
right

If the first argument to . FD is greater than 11, the effect is as if . FD 0
were specified. If the first argument is omitted or null, the effect is
equivalent to . FD 10 in the nraff formatter and to . FD o in the
traff formatter; these are also the respective initial default values.
If the second argument is specified, then when a first-level heading is
encountered, automatically numbered footnotes begin again with 1.
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 rom except for long footnotes
that continue to the following page. If hyphenation is permitted, it is
possible for the last word on the last line on the current page footnote
to be hyphenated. The user has control over this situation by
specifying 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 traff formatter, footnotes are set in
type two points smaller than the point size used in the body of text.

4-76

AlUX Text Processing Tools

8.4 Spacing between footnote entries
Normally, one blank line (nroff) or a 3-point vertical space (troff)
separates footnotes when more than one occurs on a page. To change
this spacing, the F s number register is set to the desired value. For
example,
.nr Fs 2

will cause two blank lines (nroff), a 6-point vertical space (troff)
to occur between footnotes.

9. Page headers and footers
Text printed at the top of each page is called a page header. Text
printed at the bottom of each page is called a page footer. There can
be up to three lines of text associated with the header--every page,
even page only, and odd page only. Thus the page header may have up
to two lines of text-the line that occurs at the top of every page and
the line for the even- or odd-numbered page. The same is true for the
page footer.
This part describes the default appearance of page headers and page
footers and ways of changing them. The term header (not qualified by
even or odd) is used to mean the page header line that occurs on every
page, and similarly for the term footer.

9.1 Default headers and footers
By default, each page has a centered page number as the header. There
is no default footer and no even or odd default headers or footers
except as specified in "Default Header and Footer with Section-Page
Numbering. "
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 type ( . 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)

rom Reference

4-77

• The . nr and . ds requests.

9.2 Header and footer macros
For header and footer macros (. PH, . EH, .OH, . PF, . EF, and. OF)
the argument [arg] is of the form

", left-part' center-part' right-part' "
If it is inconvenient to use an apostrophe (' ) as the delimiter because it
occurs within one of the parts, it may be replaced uniformly by any
other character. The . fc request redefines the delimiter. In formatted
output, the parts are left justified, centered, and right justified,
respectively.

9.2.1 Page header
The . PH macro specifies the header that is to appear at the top of every
page.
• PH [arg]

The initial value is the default centered page number enclosed by
hyphens. The page number contained in the P register is an Arabic
number. The format of the number may be changed by the. af macro
request.
If debug mode is set using the flag option - rD 1 on the command line,
additional information printed at the top left of each page is included in
the default header. This consists of the Source Code Control System
(SCCS) release and level of Memorandum Macros (thus identifying the
current version followed by the current line number within the current
input file). (See "Parameters Set From Command Line" and "sccs
Release Identification.' ')

9.2.2 Even-page header
The . EH macro supplies a line to be printed at the top of each evennumbered page immediately following the header.
• EH [arg]

Initial value is a blank line.

9.2.3 Odd-page header
The . OH macro is the same as the . EH except that it applies to oddnumbered pages.

4-78

NUX Text Processing Tools

.OH [arg]

9.2.4 Page footer
The . PF macro specifies a line that is to appear at the bottom of each
page.
· PF [arg]

Its initial value is a blank line. If the - rCn flag option is specified on
the command line, the type of copy follows the footer on a separate
line. In particular, if -rC3 or -rC4 (DRAFT) is specified, the footer
is initialized to contain the date instead of being a blank line.

9.2.5 Even-page footer
The . EF macro supplies a line to be printed at the bottom of each
even-numbered page immediately preceding the footer.
· EF [arg]

Initial value is a blank line.

9.2.6 Odd-page footer
The . OF macro supplies a line to be printed at the bottom of each oddnumbered page immediately preceding the footer.
• OF [arg]

Initial value is a blank line.

9.2.7 First page footer
By default, the first page footer is a blank line. If, in the input text file,
the user specifies. PF, . OF, or both, before the end of the first page of
the document, these lines will appear at the bottom of the first page.
The header, whatever its contents, replaces the footer on the first page
only if the -rNl flag option is specified on the command line (see
"Parameters Set From Command Line").

9.3 Default header and footer with section-page
numbering
Pages can be numbered sequentially within sections by section number
and page number (see "First-Level Headings and Page- Numbering
Style"). To obtain this numbering style, -rN3 or -rN5 is specified on
the command line. In this case, the default footer is a centered sectionpage number, for example, 7-2; and the default page header is blank.

Reference

4-79

9.4 Strings and registers in header and footer macros
String and register names can 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 will be processed three times:
1.

As the argument to the header or footer macro

In a formatting request within the header or footer macro

In a . t 1 request during header or footer processing

For example, page number register P must be escaped with four
backslashes in order to specify a header in which the page number is to
be printed at the right margin:

.PH ""'Page \\\\nP'"
creates a right-justified header containing the word "Page" followed
by the page number. Similarly, to specify a footer with the sectionpage style, the user specifies

.PF " " ' - \\\\n(Hl-\\\\nP -'"
If the user arranges for the string a] to contain the current section
heading that is to be printed at the bottom of each page, the . P F macro
call would be

.PF ""\\\\*(a]""
If only one or two backslashes were used, the footer would print a
constant value for a] , namely, its value when . PF appeared in the
input text.

9.5 Header and footer exam pie
The following sequence specifies blank lines for header and footer
lines, page numbers on the outside margin of each page (that is, top left
margin of even pages and top right margin of odd pages), and
"Revision 3" on the top inside margin of each page. Nothing is
specified for the center.

4-80

AJUX Text Processing Tools

.PH
.PF
.EH
.OH

""
""
"'\\\\nP"Revision 3'"
"'Revision 3"\\\\nP'"

9.6 Generalized top-of-page processing
Note: This part is intended only for users accustomed to
writing formatter macros.
During header processing, rom 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
.if e ' t l \ \* (}e
· if 0 ' tl \ \ * ( } 0
.sp 2

The string} t contains the header, the string} e contains the even-page
header, and the string} 0 contains the odd-page header as defined by
the. PH, . EH, and. OH macros, respectively. To obtain more
specialized page titles, the user may redefine the . TP macro to cause
the desired header processing (see "Column Headings for TwoColumn Output"). 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, that is, document number, issue date, and revision date, the user
could define the . TP macro as follows:

Reference

4-81

.de TP
.sp
.ce 3
777-888-999
Iss. 2, AUG 1977
Rev. 7, SEP 1977
.sp

('
'II

The . PX macro can be used to provide text that is to appear at the top
of each page after the normal header and that can have tab stops to
align it with columns of text in the body of the document.

9.7 Generalized bottom-of-page processing
Lines of text that are specified between the . BS (bottom-block start)
and. BE (bottom-block end) macros will be printed at the bottom of
each page after the footnotes (if any) but before the page footer.
.BS

zero or more lines of text
.BE

This block of text is removed by specifying an empty block, that is,
.BS
.BE

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

9.8 Top and bottom margins
The . VM (vertical margin) macro allows the user 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. The
• VM macro takes two unscaled arguments that are treated as vertical
spaces (v). For example,
.VM 10 15

adds 10 vertical spaces to the default top of page margin and 15

4-82

NUX Text Processing Tools

(

vertical spaces to the default bottom of page margin. Both arguments
must be positive (default spacing at the top of the page may be
decreased by redefining. TP).

9.9 Proprietary markl ng macro
The . PM (proprietary marking) macro appends a proprietary disclaimer
to the page footer. The proprietary disclaimers are constructed from
strings defined in the file /usr / lib/macros/ strings .mm.
• PM [code]

The argument is selected from among the following:
PMl
PM2 orCA
PM30rCP
PM4
PM5
PM6

Use . PM at the beginning of your document, before you use footnotes
or macros that define the memorandum style. Otherwise, an interaction
between this macro and another that redefines the appearance of the
bottom of the page may cause you problems.
The default disclaimers are in a form approved for use by AT&T.
Markings are underlined. (They are italicized in troff.)
System administrators can change the contents of the s t ring. mm file
to match your needs. This file is described in "Define File
Information. " In cases where the disclaimer message for a code
argument has been removed, the argument issues a currently approved
disclaimer message. Because the code argument may produce a shorter
or longer disclaimer message, the page formatting of the document
may be affected.

9.10 Private documents
.nr Pv value

The word ' 'PRN ATE" may be printed, centered, and underlined on
the second line of a document (preceding the page header). This is

Reference

4-83

done by setting the Pv register value:

o
1

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

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

10. Table of contents and cover sheet
The table of contents and the cover sheet for a document are produced
by invoking the. TC and. CS macros, respectively.
Note: This section refers to cover sheets for technical
memoranda and released papers only. The mechanism for
producing a memorandum for file cover sheet was discussed
earlier (see" Abstract").

These macros normally appear once at the end of the document, after
the Signature Block and Notations macros, and may occur in either
order. (See "Signature Block," "Copy To and Other Notations.")
The table of contents is produced at the end of the document because
the entire document must be processed before the table of contents can
be generated. Similarly, the cover sheet may not be desired by a user
and is therefore produced at the end.

10.1 Table of contents
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 Cl register (see' 'Headings and Table of Contents' ') .
• TC [slevel] [spacing] [tlevel] [tab] [headl] [head2] [head3] [head4] [head5]

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 level is less than or
equal to slevel will have spacing blank lines (nroff) or half-vertical

4-84

AlUX Text Processing Tools

spaces (traff) before them. Both sieve I and spacing default to 1.
This means that first-level headings are preceded by one blank line
(nraff) or one-half a vertical space (traff). The slevel argument
does not control what levels of heading have been saved; saving of
headings is the function of the Cl 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.
For headings whose level is less than or equal to tlevel (default 2), page
numbers are justified at the right margin. In this case, the value of tab
determines the character used to separate heading text from page
number. If tab is (default value), dots (leaders) are used. If tab is
greater than 0, spaces are used.

For headings whose level is greater than tlevel, page numbers are
separated from heading text by two spaces (that is, page numbers are
ragged right, not right justified).
Additional arguments (head1 ... head5) are horizontally centered on
the page and precede the table of contents.
If the . TC macro is invoked with at most four arguments, the user-exit
macro. TX is invoked (without arguments) before the word
"CONTENTS" is printed or the user-exit macro. TY is invoked and
the word "CONTENTS" is not printed.

By defining. TX or . TY and invoking. TC with at most four
arguments, the user can specify what needs to be done at the top of the
first page of the table of contents. For example,

Reference

4-85

.de TX
.ce 2
Special Application
Message Transmission
.sp
.in +lOn
Approved: \1'3i'
.in 0
.sp
.TC
yields the following output when the file is formatted.
Special Application
Message Transmission
Approved: _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
CONTENTS

If the . TX macro were defined as . TY, the word "CONTENTS"
would be suppressed. Defining . TY as an empty macro will suppress
"CONTENTS" with no replacement:

.de TY
By default, the first-level headings will appear in the table of contents
left justified. Subsequent levels will be aligned with the text of
headings at the preceding level. These indentations can be changed by
defining the Ci string, which takes a maximum of seven arguments
corresponding to the heading levels. It must be given at least as many
arguments as are set by the Cl register. Arguments must be scaled.
For example, with Cl = 5

.ds Ci .25i .5i .75i Ii Ii

\"troff

4-86

NUX Text Processing Tools

ods Ci 0 2n 4n 6n 8n

\"nroff

Two other registers are available to modify the format of the table of
contents-Oc and Cpo
By default, table of contents pages will have lowercase roman numeral
page numbering. If the Oc register is set to 1, the . TC macro will not
print any page number but will instead reset the P register to 1. It is the
user's 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 will be adequate.
0

The list of figures, tables, exhibits and equations will be produced as
separate pages unless Cp is set to 1, which causes these lists to appear
on the same page as the table of contents.

10.2 Cover sheet
The cs macro generates a cover sheet in either the released paper or
technical memorandum style (see" Abstract" for details of the
memorandum for file cover sheet).
0

[pages] [other] [total] [figs] [tbls] [refs]

All other information for the cover sheet is obtained from data given
before the MT macro call (see" Sequence of Beginning Macros' '). If
the technical memorandum style is used, the CS macro generates the
"Cover Sheet for Technical Memorandum." The data that appear in
the lower left comer of the technical 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).
These values can be changed by supplying the corresponding
arguments to the CS macro. If the released-paper style is used, all
arguments to CS are ignored.
0

11. References
There are two macros ( RS and RF) that delimit the text of
references, a string that automatically numbers the subsequent
references, and an optional macro ( RP) that produces reference pages
within the document.
0

rmn Reference

4-87

11.1 Automatic numbering of references
Automatically numbered references can be obtained by typing \ * (Rf
(invoking the string Rf) immediately after the text to be referenced.
This places the next sequential reference number (in a smaller point
size) enclosed in brackets one-half line above the text to be referenced.
Reference count is kept in the Rf number register.

11.2 Delimiting reference text
The . RS and . RF macros are used to delimit text of each reference .
. RS [string-name]
.RF

For example,
A line of text to be referenced.\*(Rf
.RS

reference text
.RF

11.3 Subsequent references
The . RS macro takes one argument, a string-name. For example,
.RS aA
reference text
.RF

The string aA is assigned the current reference number. This string
may be used later in the document as the string call, \ * (aA, to
reference text which must be labeled with a prior reference number.
The reference is output enclosed in brackets one-half line above the
text to be referenced. No . RS/. RF pair is needed for subsequent
references.

11.4 Reference page
The . RP macro causes a reference page, entitled by default
"References," to be generated automatically at the end of the
document (before table of contents and cover sheet) and to be listed in
the table of contents .
• RP [argJ] [arg2]

This page contains the reference items enclosed within . RS/. RF pairs.
Reference items will be separated by a space (nroff) or one-half a

4-88

AJUX Text Processing Tools

(

vertical space (troff) unless the Ls register is set to 0 to suppress
this spacing. The user may change the reference page title by defining
the Rp string:
.ds Rp "New Title"

The . RP (reference page) macro may be used 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 document.
Two . RP macro arguments allow the user to control resetting of
reference numbering and page skipping.

arg1

Meaning

reset reference counter (default)
do not reset reference counter

arg2

o
1
2

Meaning
put on separate page (default)
do not cause a following . S K
do not cause a preceding . S K
no . SK before or after

If no . SK macro is issued by the . RP macro, a single blank line will
separate the references from the following and preceding text. The
user 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 Section"

12. Miscellaneous features
12.1 Bold, italic, and roman fonts
When called without arguments, the . B macro changes the font to bold
and the . I macro changes to underlining (nroff) or italic (troff).
This condition continues until the occurrence of the . R macro which
causes the roman font to be restored.

mm Reference

4-89

• B [bold-arg] fpreviouslont-arg] .. .
· I [italic-arg] fpreviouslont-arg] .. .
•R

Thus,
·I

here is some text .
•R

yields underlined text via nroff(l) and italic text via troff(I).
If the . B or . I macro is called with one argument, that argument is
printed in the appropriate font (underlined in the nroff formatter for
. I). Then the previous font is restored; underlining is turned off in the
nroff formatter. If two or more arguments (maximum six) are given
with a . B or . I macro call, the second argument is concatenated to the
first with no intervening space (1/12 space if the first font is italic) but
is printed in the previous font. Remaining pairs of arguments are
similarly alternated. For example,
.1 one" two" three -four

produces
one two three-four

The . B and . I 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
· RI
· RB
• BR

italic bold
bold italic
italic roman
roman italic
roman bold
bold roman

Each macro takes a maximum of six arguments and alternates
arguments between specified fonts.
When using a terminal that cannot underline, the following can be
inserted at the beginning of the document to eliminate all underlining:

4-90

A/UX Text Processing Tools

.rm ul
.rm eu

Note: Font changes in headings are handled separately (see
"Control by Level").

12.2 Justification of right margin
The . SA macro is used to set right-margin justification for the main
body of text.
• SA [arg]

Two justification flags are used-current and default. Initially, both
flags are set for no justification in the nroff formatter and for
justification in the troff formatter. The argument causes the
following action:

Sets both flags to no justification, the same as the
. na request.

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

omitted

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

In general, the no adjust request (. na) can be used to ensure that
justification is turned off, but . SA should be used to restore
justification, rather than the . ad request. In this way, justification or
no justification for the remainder of the text is specified by inserting
. SA 0 or . SA 1 once at the beginning of the document.

12.3

sees release Identification

The RE string contains the SCCS release and the Memorandum Macros
text formatting package current version level. For example,

This is version \*(RE of the macros.
produces
This is version 10.129 of the macros.

mm Reference

4-91

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 - rD 1 (see' 'Parameters Set From Command
Line' ') on the command line. This causes the RE string to be generated
as part of the page header (see "Page Header").

12.4 Two-column output
The . 2 C macro begins 2-column processing which continues until a
.le macro (I-column processing) is encountered .
. 2C

text andformatting requests (except another. 2C)
.1C

In 2-column processing, each physical page is thought of as containing
2-columnar "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, although default action is for footnotes and displays to
be narrow in 2-column mode and wide in I-column mode. Footnote
and display width is controlled by the . wc (width control) macro,
which takes the following arguments:

arg
N

WF
-WF

FF
-FF
WD
-WD

4-92

Meaning
Default mode (-WF, -FF, -WD, FB).
Wide footnotes (even in 2-column mode).
DEFAULT: Tum offwF. Footnotes follow column mode;
wide in I-column mode (lC), narrow in 2-column mode
(2C), unless FF is set.
First footnote. All footnotes have same width as first
footnote encountered for that page.
DEFAULT: Tum offFF. Footnote style follows settings
OfWF or -WF.
Wide displays (even in 2-column mode).
DEFAULT: Displays follow the column mode in effect
when display is encountered.

AlUX Text Processing Tools

DEFAULT: Floating displays cause a break when output
on the current page.

Floating displays on current page do not cause a break.

- FB

Note: The . WC WD FF command will cause all displays to be
wide and all footnotes on a page to be the same width while
. WC N will reinstate default actions. If conflicting settings are
given to . WC, the last one is used. A . WC WF -WF command
has the effect of a . WC -WF.

12.5 Column headings for two-column output
Note: This section is intended only for users accustomed to
writing formatter macros.
In 2-column processing output, it is sometimes necessary to have
headers over each column, as well as headers over the entire page.
This is accomplished by redefining the . TP macro to provide header
lines both for the entire page and for each of the columns. For
example,
.de TP
.sp 2
.tl 'Page \\nP'OVERALL"
.tl ' 'TITLE' ,
.sp
.nf
.ta 16C 31R 34 SOC 6SR
leftAIcenterAlrightAIleftAIcenterAlright
Alfirst columnAIAIAIsecond column
.fi
.sp 2
where I stands for the tab character.
A

The above example will produce two lines of page header text plus two
lines of headers over each column. Tab stops are for a 65-en overall
line length. See "Generalized Top-of-Page Processing" for more

mm Reference

4-93

information on headers.

12.6 Vertical spacing
. SP [lines]

There are several ways of obtaining vertical spacing, all with different
effects. The . sp request spaces the number of lines specified unless
the no space (. ns) mode is on, in which case the . sp request is
ignored. The no space mode is set 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. This mode can be turned off by the . r s (restore
spacing) request.
The . SP macro is used to avoid the accumulation of vertical space by
successive macro calls. 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 Memorandum Macros use . SP for spacing. For example, . LE
1 (see "List-Item Macro") immediately followed by . P (see
"Paragraphs") produces only a single blank line (nraff) or one-half
a vertical space (traff) between the end of the list and the following
paragraph. An omitted argument defaults to one blank line (nraff) or
one vertical space (traff). Negative arguments are not permitted.
The argument must be un scaled , but fractional amounts are permitted.
The . SP macro (as well as . sp) is also inhibited by the . ns (no
space) request.

12.7 Skipping pages
The. SK macro skips pages but retains the usual header and footer
processing .
• SK [pages]

If the pages argument is omitted, null, or 0, . SK skips to the top of the
next page unless it is currently at the top of a page (in which case it
does nothing). A . SK n command skips n pages. A . SK positions text
that follows it at the top of a page, while. SK 1 leaves one page blank

4-94

AlUX Text Processing Tools

except for the header and footer.

12.8 Forcing an odd page
The . op macro is used 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.

12.9 Setting point size and vertical spacing
The prevailing point size and vertical spacing can be changed by
invoking the . S macro.
· S [point size] [vertical spacing]

In the traff formatter, the default point size obtained from the rom
register S is 10 points; the vertical spacing is 12 points, six lines per
inch. The mnemonics D (default value), c (current value), and p
(previous value) can be used for both arguments. See "Parameters Set
From Command Line" for an alternative way to set these parameters.
• 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 is used as the new value.
• If there are no arguments, the . S macro defaults to P.
• If the first argument is specified but the second is not, then D, the
default, is used for the vertical spacing.

Default value for vertical spacing is always two points greater than the
current point size. Footnotes are two points smaller than the body with
an additional3-point space between footnotes. A null (" n) value for

rom Reference

4-95

either argument defaults to C, the current value. Thus, if n is a numeric
value:
.S
nn
n
·S
.S n nn
·S n
.S nn
.S nn nn
· S nn

=
=
=
=
=
=
=

.S
.S
.S
.S
.S
.S
.S

p p

C n
n C

n D
C D
C C

If the first argument is greater than 99, the default point size, 10 points,
is restored. If the second argument is greater than 99, the default
vertical spacing (current point size plus two points) is used. For
example,
.S 100
.S 14 111

.S 10 12
.S 14 16

12.10 Reducing point size of a string
The . SM macro allows the user to reduce by one point the size of a
string.
• SM string1 [string2] [string3]

If the third argument (string3) is omitted, 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,
.SM X

produces
X
.SM Y XYX nn

produces
YXYX

and

4-96

AJUX Text Processing Tools

• SM

( YXYX

)

produces
(YXYX)

12.11 Producing accents
Strings can be used to produce accents for letters as shown in the
following examples:

Input

Output

Grave accent

c\*'

Acute accent

e\*'

Circumflex

o\*n

Tilde

n\*-

Cedilla

c\*,

Lower case umlaut

u\*:

Upper case umlaut

u\*;

12.12 Inserting text interactively
• RD [prompt] [diversion] [string]

The . RD (read insertion) macro allows a user to stop the standard
output of a document and to read text from the standard input until two
consecutive newline characters are found. When newline characters
are encountered, normal output is resumed.
• The prompt argument will be printed at the terminal. If not
given, . RD signals the user with a BEL on terminal output
• The diversion argument allows the user to save all text typed in
after the prompt in a macro whose name is that of the diversion.
• The string argument allows the user to save for later reference
the first line following the prompt in the named string.
The . RD macro follows the formatting conventions in effect. Thus, the
following examples assume that the . RD is invoked in no-fill mode
(.nf):

mm Reference

4-97

.RD Name aA bB
produces
Name: S. Jones (user types name)
16 Elm Rd.,
Piscataway
The diverted macro . aA will contain
S.Jones
16 Elm Rd.,
Piscataway
The string bB (\ * (bB) contains "S. Jones".
A newline character followed by an eof(user-specifiable end-of-file
character) also allows the user to resume normal output. See st ty(l)
in AIUX Command Reference for information about the user-specifiable
sequences.

13. Errors and debugging
13.1 Error terminations
When a macro detects an error, the following actions occur:
• A break occurs.
• The formatter output buffer (which may contain some text) is
printed to avoid confusion regarding location of the error.
• A short message is printed 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. Error
messages are explained in "Error Messages."
• Processing terminates unless register D has a positive value. In
the latter case, processing continues even though the output is
guaranteed to be deranged from that point on. (See "Parameters
Set From Command Line.")
The error message is printed by generating the message directly to the
user terminal. If an output filter, such as 3 0 0(1), 450(1), or hp(l) is
being used to post-process the nroff formatter output, the message
may be garbled by being mixed with text held in that filter's output

4-98

AlUX Text Processing Tools

buffer.

Note: If any of cw(l), eqn/neqn(l), and tbl(l) programs are
being used and if the -olist flag option of the formatter causes
the last page of the document not to be printed, a harmless
"broken pipe" message may result.

13.2 Disappearance of output
Disappearance of output usually occurs because of an unclosed
diversion (for example, a missing. DE 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 concerning a missing. DE or . FE, the appropriate action is to
search backwards from the termination point looking for the
corresponding associated . DF, . D S, or . F S (because these macros are
used in pairs).
The following command:

grep -n

,~\. [EDFRT] [EFNQS]'

filenamel.filename2

prints all the .DF, .DS, .DE, .EQ, .EN, .FS, .FE, .RS, .RF, .TS,
and. TE macros found infilenamel andfilename2. Each is preceded
by its filename and the line number in that file. This listing can be used
to check for illegal nesting, omission of these macros, or both.

14. Extending and modifying memorandum
macros
14.1 Naming conventions
In this part, the following conventions are used to describe names:

a:
A:
x:

Digit
Lowercase letter
Uppercase letter
Any alphanumeric character (n, a, or A, that is, letter or
digit)
Any nonalphanumeric character (special character)

All other characters are literals, that is, they are characters that stand
for themselves.

mm Reference

4-99

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.

14.1.1 Names used by formatters
requests:

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

registers: aa (normal)

.x (normal)

. s (only one, currently: .)

a. (only one, currently: e.)
% (page number)

14.1.2 Names used by memorandum macros
macros and strings:

A, AA, Aa (accessible to users; for example, macros P and
HU,

strings F, BU, and Lt)

nA (accessible to users; only two, currently: IC and 2C)

aA (accessible to users; only one, currently: nP)

s (accessible to users; only the seven accents, currently.
(See' 'Reducing Point Size of a String. ")

) x, }x, ] x, >x, ? x (internal)
registers: An, Aa (accessible to users; for example, HI, Fg)

A (accessible to users; meant to be set on the command line;
for example, C)

: x, ; x, #x, ? x, ! x (internal)
14.1.3 Names used by cw, eqn/neqn, and tbl
The ew(!) program is the constant-width font preprocessor for the
traff formatter. It uses the following five macro names:
.CD

4-100

.CN

.CP

.CW

.PC

A/UX Text Processing Tools

This preprocessor also uses the number register names eE and eW.
Mathematical equation preprocessors, eqn(l) and neqn(1), use
registers and string names of the form nne The table preprocessor,
tbl(l), uses T&, T#, and TW, and names of the form:

a- a+ a I nn na ""a #a #s
14.1.4 Names defined by user
Names that consist either of a single lowercase letter or a lowercase
letter followed by a character other than a lowercase letter (names. e2
and . nP are already used) should be used to avoid duplication with
already used names. The following is a possible naming convention:
macros:
strings:
registers:

aA (for example, bG, kW)
c) , f] , p })
a (for example, f, t)

as (for example,

14.2 Sample extensions
14.2.1 Appendix headings
The following is a way of generating and numbering appendix
headings:
.nr
.nr
.de
.nr
.nr
.PH
.SK
.HU

Hu 1
a 0
aH
a +1
P 0
""'Appendix \\na-\\\\\\\\nP'"
"\\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 can be saved for
the table of contents. To center appendix titles the He register must be
set to 1 (see "Centered Headings").

mm Reference

4-101

14.2.2 Hanging indent with tabs
The following example illustrates the use of the hanging indent feature
of variable-item lists (see "Variable-Item List"). 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 will
not interpret such a line as a formatter request or macro call.

Note: 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. The user-defined macro and an example of its use are
.de aX
.LI
\&\\$1\t\\$2\t\\$3\t\\$4\t\c

.ta .5i Ii 1.Si 2i
.VL 29
.aX .nh off \- no
No hyphenation.
Automatic hyphenation is turned off.
Words containing hyphens
(for example, mother-in-law) can still be
split across lines .
. aX .hy on \- no
Hyphenate.
Automatic hyphenation is turned on .
. aX .hc\ c none none no
Hyphenation indicator character is set to "c"
or removed.

4-102

AlUX Text Processing Tools

During text processing, the indicator is
suppressed and will not appear in the output.
Prefixing the indicator to a word has the
effect of preventing hyphenation of that word .
. LE
Note that the space following " . hc\" is required.
The resulting output is

.nh

off

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

.hy

Hyphenate. Automatic
hyphenation is turned on.

.hc

none

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

none

15. Summary
The following are qualities of rom that have been emphasized in its
design in approximate order of importance:

• Robustness in the face of error - A user need not be an
nroff/troff expert to use the Memorandum Macros. When
the input is incorrect, either the macros attempt to make a
reasonable interpretation of the error or an error message
describing the error is produced. An effort has been made to
minimize the possibility that a user will get cryptic system
messages or strange output as a result of simple errors .
• Ease of use for simple documents - It is not necessary to write
complex sequences of commands to produce documents.

mm Reference

4-103

Reasonable macro argument default values are provided where
possible.

• Setting parameters - There are many different preferences in
the area of document styling. Many parameters are provided so
that users can adapt input text files to produce documents that
meet their respective needs with a wide range of styles.
• Extension by moderately expert users - A strong effort has been
made to use mnemonic naming conventions and consistent
techniques in construction of macros. Naming conventions are
given so that a user can add new macros or redefine existing ones
if necessary.
• Device independence - A common use of rom is to produce
documents on hard copy via teletypewriter terminals using the
nroff formatter. Macros can be used conveniently with both
10- and 12-pitch terminals. In addition, output can be displayed
on an appropriate CRT terminal. Macros have been constructed
to allow compatibility with the troff(l) formatter so that
output can be produced on both a phototypesetter and a
teletypewriter/CRT terminal.
• Minimization of input - The design of macros attempts to
minimize repetitive typing. For example, if a user wants to have
a blank line after all first- or second-level headings, the user need
only set a specific parameter once at the beginning of a document
rather than type a blank line after each such heading.
• Uncoupling of input format from output style - There is but one
way to prepare the input text although the user may obtain a
number of output styles by setting a few global flags. For
example, the . H macro is used for all numbered headings, yet the
actual output style of these headings can be made to vary from
document to document or within a single document.

16. mm Examples and reference tables
This section contains an example of an input file of a simple letter that
is also shown formatted by both nroff and troff using the
Memorandum Macros. This example illustrates how the formatters
work and what to expect from your input file.

4-104

A/UX Text Processing Tools

There are also four tables in this section that are useful reference tools
when using the Memorandum Macros. The tables are

Macro Names:

This table is an alphabetic summary of all the
Memorandum Macro names available for
producing a document.

String Names:

This table is a summary of all the predefined
string names in the Memorandum Macro
package.

Number Register Names:
This table is a summary of all the predefined
number register names in the Memorandum
Macro package.

Error Messages:

mm Reference

This table is a list of error messages that you
may encounter when formatting a document.
Memorandum Macro error messages as well
as nroff/troff error messages are
explained.

4-105

Figure 4-1. Example of a simple letter - input file
INPUT:
.nr N 2
\" specifies header to be omitted from page 1
.ta 3i
September 5, 1987
.SP 2
Mr. Steven J. Jones
.br
386 Broderick Street
.br
San Francisco, CA 94111
.SP
Dear Mr. Jones:

.P
Enclosed please find a copy of
.I

A/UX\*F Text Processing Tools .
•R

.FS
A/UX is a trademark of Apple Computer, Inc .
. FE

.P
This manual covers using the
\s-lUNIX\s+l\*F
.FS
\s-lUNIX\s+l is a registered trademark of AT&T Information
Systems .
. FE
operating system for preparing documentation, and includes
topics such as:
.VL 17
.LI Formatters:
the \fBnroff/troff\fR formatters,
with tables listing defaults and explanations of all requests
.LI Tables:
the \fBtbl\fR program,
with examples of code at the end of the chapter
.LI Equations:
the \fBeqn\fR program, for printing mathematical expressions
.LI "Macro\ Package:"
the \fBmm\fR macro package chapter gives a complete outline of
all the capabilities of this powerful document processing tool
.LE

.P
I hope you will find this guide useful in preparing your report .
. SP
.nf
Sincerely,
.SP 2
Rosemary Clooney
Documentation Specialist
RC/dcb
Enc .
. fi

4-106

AlUX Text Processing Tools

Figure 4-2. Example of a simple letter - nroff output

nroff OUTPUT:

September 5, 1987

Mr. Steven J. Jones
386 Broderick Street
San Francisco, CA 94111
Dear Mr. Jones:
Enclosed please find a copy of A/UX1 Text Processing
Tools.
This manual covers using the UNIX2 operating system for
preparing documentation, and includes topics such as:
Formatters:

the nroff/troff formatters, with tables
listing defaults and explanations of all
requests

Tables:

the tbl program, with examples of code at
the end of the chapter

Equations:

the eqn program, for printing
mathematical expressions

Macro Package:

the mm macro package chapter gives a
complete outline of all the capabilities
of this powerful document processing tool

I hope you will find this guide useful in preparing your
report.
Sincerely,
Rosemary Clooney
Documentation Specialist
RC/dcb
Enc.

A/UX is a trademark of Apple Computer, Inc.

UNIX is a registered trademark of AT&T Information
Systems.

mm Reference

4-107

Figure 4-3. Example of a simple letter - troff output
September 5, 1987

troff OUTPUT:

Mr. Steven J. Jones
386 Broderick Street
San Francisco, CA 94111
Dear Mr. Jones:
Enclosed please find a copy of AIUXJ Text Processing Tools.
This manual covers using the UNIX2 operating system for preparing
documentation, and includes topics such as:
Formatters:

the nroff/troff formatters, with tables listing
defaults and explanations of all requests

Tables:

the tbl program, with examples of code at the end
of the chapter

Equations:

the eqn program, for printing mathematical
expressions

Macro Package:

the mm macro package chapter gives a complete
outline of all the capabilities of this powerful
document processing tool

I hope you will find this guide useful in preparing your report.
Sincerely,
Rosemary Clooney
Documentation Specialist
RC/dcb
Enc.

1. AfUX is a trademark of Apple Computer, Inc.

2. UNIX is a registered trademark of AT&T Information Systems.

4-108

AlUX Text Processing Tools

16.1 Memorandum macro names
Macro

Description

I-column processing
.1C

2-column processing
.2C

Abstract end
.AE

Alternate format of "Subject/Date/Prom" block
• AF [company-name]

Automatically incremented list start
• AL [type] [text-indent] [1]

Abstract start
• AS [arg] [indent]

Author's title
• AT [title] ...

Author information
• AU name [initials] [loc] [dept]

[ext] [room] [arg] [arg] [arg]
AV

Approval signature
.AV [name]

Bold
• B [bold-arg] [prevjontarg] [bold] [pre v] [bold] [prev]

Bottom block end
.BE

Bold/italic
· BI [bold-arg] [italicarg] [bold] [italic] [bold] [italic]

Bullet list start
· BL [text-indent] [1]

mm Reference

4-109

Macro

Description

Bold/roman
• BR [bold-arg] [roman-arg]

[bold] [roman] [bold] [roman]
BS

Bottom block start
.BS

Cover sheet
• CS [pages] [other] [total] [figs] [tbls] [refs]

Display end
.DE

Display floating start
• DF [format] [fill] [right-indent]

Dash list start
• DL [text-indent] [1]

Display static start
• DS [format] [fill] [right-indent]

Equation caption
• EC [title] [override] [flag]

Even-page footer
• EF [arg]

Even-page header
• EH [arg]

End equation display
.EN

Equation display start
• EQ [label]

Exhibit caption
• EX [title] [override] [flag]

Formal closing
· FC [closing]

4-110

NUX Text Processing Tools

Macro

Description

Footnote default format
• FD [arg] [1]

Footnote end
.FE

Figure title
· FG [title] [override] [flag]

Footnote start
· FS [label]

Heading-numbered
• H level [heading-text] [heading-suffix]

Hyphenation character
• HC [hyphenation-indicator]

Heading mark style
(arabic or roman numerals, or letters)
• HM [argl] ... [arg7]

Heading-unnumbered
• HU heading-text

HX*

Heading user exit X (before printing heading)
· HX dlevel rlevel heading-text

HY*

Heading user exit Y (before printing heading)
• HY dlevel rlevel heading-text

HZ*

Heading user exit Z (after printing heading)
• HZ dlevel rlevel heading-text

Macros marked with an asterisk are not, in general, called directly by the user. They
are "user exits" defined by the user and called by rom from inside header, footer, or
other macros.

Reference

4-111

Macro

Description

Italic (underline in the nro f f fonnatter)
· I [italic-arg] [prevlontarg] [italic] [prev] [italic] [prev]

Inside address start
· IA [addressee-name] [title]

Italic/bold
· IB [italic-arg] [bold-arg] [italic]
[bold] [italic] [bold]

Inside address end
.IE

Italic/roman
· IR [italic-arg] [roman-arg] [italic]
[roman] [italic] [roman]

List begin
· LB text-indent mark-indent pad type [mark]
Ell-space] [LB-space]

List-status clear
· LC [list-level]

List end
· LE [1]

List item
· LI [mark] [1]

Letter options
· LO type [arg]

Letter type
· LT [arg]

Marked list start
· ML mark [text-indent] [1]

Memorandum type
· MT [type] [addressee] or .MT 4 1

4-112

AlUX Text Processing Tools

Macro

Description

New date
• ND new-date

Notation end
.NE

Notation start
.NS [arg]

Double-line indented paragraphs
.nP

Odd-page footer
· OF [arg]

Odd-page header

.OH [arg]

Other keywords for Technical Memo cover sheet

· OK [keyword] ...

Odd page

.oP
Paragraph

• P [type]

Page footer

· PF [arg]

Page header

· PH [arg]

Proprietary marking

• PM [code]

Reference

4-113

Macro

Description

px*

Page-header user exit
.PX

Return to regular (roman) font
.R

Roman/bold
• RB [roman-arg] [bold-arg] [roman] [bold]
[roman] [bold]

Read insertion from terminal

• RD [prompt] [diversion] [string]

Reference end
.RF

Roman/italic
• RI [roman-arg] [italicarg] [roman] [italic] [roman] [italic]

Reference list start

· RL [text-indent] [1]

Produce reference page
· RP [arg] [arg]

Reference start
· RS [string-name]

Set t ro f f formatter point size and vertical
spacing

• S [size] [spacing]

Macros marked with an asterisk are not, in general, called directly by the user. They
are "user exits" defined by the user and called by rnm from inside header, footer, or
other macros.

4-114

AJUX Text Processing Tools

Macro

Description

Set adjustment (right-margin justification) default
· SA [arg]

Signature line
• SG [arg] [1]

Skip pages
• SK [pages]

Make a string smaller
• SM stringl [string2] [string3]

Space vertically

· SP [lines]
TB

Table title
· TB [title] [override] [flag]

Table of contents
• TC [sieve/] [spacing] [tlevel]
[tab] [headl] [head2] [head3]

Table end
.TE

Table header

[head4] [head5]

• TH [N]
TL

Title of memorandum
· TL [charging-case] [filing-case]

Technical memorandum number(s)
· TM [number] ...

TP*

Top-of-page macro
.TP

Macros marked with an asterisk are not, in general, called directly by the user. They
are "user exits" defined by the user and called by rom from inside header, footer, or
other macros.

mm Reference

4-115

Macro

Description

Table start
• TS [H]

TX*

Table of contents user exit
.TX

TY*

Table of contents user exit (suppress CONTENTS)
.TY

Variable-item list start

· VL text-indent [mark-indent] [1]

Vertical margins

• VM [top] [bottom]

Writer's address start

• WA writer-name [title]

Footnote and display width control

· we [format]

Footnote and display width control

· we [format]

Macros marked with an asterisk are not, in general, called directly by the user. They
are' 'user exits" defined by the user and called by mm from inside header, footer, or
other macros.

4-116

NUX Text Processing Tools

16.2 String names
String

Description

Bullet (nroff:

Table of contents indent list
Up to seven scaled arguments for heading levels

Date (current date, unless overridden)
Month, day, year (for example, May 1, 1988)

Em dash string
Produces an em dash in the troff formatter and a
double hyphen in nroff

Footnote number generator
nroff: \u\\n+(:p\d
t ro f f: \v' -.4m '\s- 3\\n+(:p\sO\v'.4m'

Heading font list
Up to seven codes for heading levels 1 through 7
3 3 2 2 2 2 2 (levels 1 and 2 bold, 3 through 7
underlined by nroff and italicized by troff)

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

Title for LIST OF EQUATrONS

Title for LIST OF FIGURES

Title for LIST OF TABLES

Title for LIST OF EXHIBITS

sees Release and Level of Memorandum Macros
Release.Level (for example, 15.129)

Reference number generator

Title for References

Trademark string
Places' 'TM" lh line above text that it follows
Seven accent strings are also available.

rom Reference

~,troff:

4-117

Note: If the released-paper style is used, then, in addition to the
above strings, certain BTL location codes are defined as strings
and are needed only until the . MT macro is called. The
following codes are recognized: AK, AL, ALF, CB, CH, CP, DR,
FJ,HL, HO,HOH, HP, IH,IN,INH, IW,MH,MV,PY,RD,RR,
WB, WH, and wv.

4-118

AlUX Text Processing Tools

16.3 Number register names
Register
A

Au
C

Description
Handles preprinted forms and Bell System logo
0, [0:2]
Inhibits printing of author information
1, [0: 1]
Copy type (original, DRAFT, etc.)

o(Original), [0:4]

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

Placement of list of figures, etc.
1 (on separate pages), [0:1]

Debug flag
0, [0:1]

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

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

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

*
t

Controls font of the Subject/Date/From fields
1 (nroff) 0 (troff), [0:1]
Equation counter, used by . EC macro
0, [O:?], incremented by one for each. EC call

An asterisk attached to a register name indicates this register can be set only from the
command line or before the macro definitions are read by the fonnatter.
Section 1.3 has notes on setting and referencing registers. Any register having a
single-character name can be set from the command line.

rom Reference

4-119

Description

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

Equation label placement
o(right-adjusted), [0:1]

Exhibit counter, used by . EX macro
0, [O:?], incremented by one for each . EX call

Figure counter, used by . FG macro
0, [O:?], incremented by one for each. FG call

Footnote space (i.e., spacing between footnotes)
1, [O:?]

Hl-H7

Heading counters for levels 1 through 7
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 0 by
any . H ( . HU) macro at a lower-numbered level.

Heading break level (after . Hand . HU)
2, [0:7]

Heading centering level for . H and . HU

o(no centered headings), [0:7]

Heading temporary indent (after. Hand. HU)
1 (indent as paragraph), [0:2]

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

Heading type (for. H: single or concatenated numbers)

An asterisk attached to a register name indicates this register can be set only from the
command line or before the macro definitions are read by the formatter.

Section 1.3 has notes on setting and referencing registers. Any register having a
single-character name can be set from the command line.

4-120

NUX Text Processing Tools

Description

o (concatenated numbers: 1.1.1, etc.), [0:1]
Heading level for unnumbered heading (. HU)
2 (. HU at the same level as . H 2), [0:7]

Hyphenation control for body of document

o (automatic hyphenation oft), [0: 1]
L

Length of page
66, [20:?] (Ui, [2i:?] in troff formatter)

List of equation
o (list not produced) [0: 1]

List of figures
1 (list produced) [0: 1]
List indent

6 (nroff) 5 (troff), [O:?]
Ls

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

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

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

Numbering style
0, [0:5]
Numbering style for paragraphs
o (unnumbered) [0: 1]

An asterisk attached to a register name indicates this register can be set only from the
command line or before the macro definitions are read by the formatter.

Section 1.3 has notes on setting and referencing registers. Any register having a
single-character name can be set from the command line.

rom

Reference

4-121

Description
Offset of page
.75i, [O:?] (O.5i, [Oi:?] in traff formatter)
For nraff formatter, these values are unscaled
numbers representing lines or character positions.
For traff formatter, these values must be scaled.
Table of contents page numbering style

o(lowercase Roman), [0: 1]
Of

Figure caption styIe
(period separator), [0:1]

Page number managed by Memorandum Macros
0, [O:?]

Paragraph indent
5 (nraff) 3 (traff), [O:?]

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

Paragraph type
(paragraphs always left justified), [0:2]

"PRIVA1E" header

o(not printed), [0:2]
Rf

Reference counter, used by . RS macro
0, [O:?], incremented by one for each. RS call
The traff formatter default point size
10, [6:36]
Standard indent for displays

An asterisk attached to a register name indicates this register can be set only from the
command line or before the macro definitions are read by the formatter.

Section 1.3 has notes on setting and referencing registers. Any register having a
single-character name can be set from the command line.

4-122

AlUX Text Processing Tools

Description
5 (nroff) 3 (troff), EO:?]

Table counter, used by . TB macro
0, [O:?], incremented by one for each . TB call

Tb
U

w*t

*
t

Type of nroff output device
0, [0:2]

Underlining style (nro f f) for . Hand . HU
o(continuous underline when possible), [0: 1]
Width of page (line and title length)
6i, [10:1365] (6i, [2i:7.54i] in the troff formatter)

Reference

4-123

16.4 Error messages
Memorandum Macro Error Messages
An mm error message has a standard part followed by a variable part.
The standard part has the form:

ERROR: (filename)input line n:
Variable part n consists of a descriptive message usually beginning
with a macro name. They are listed below in alphabetical order by
macro name t each with a more complete explanation.

Error Message

Description

Check TL, AU, AS,
AE, MT sequence

The correct order of macros at the start of a
memorandum is shown in section 6.1.
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 6.1.
Something has disturbed this order. Occurs
if the . AS 2 macro was used.

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 DF
acti ve

A . DE macro has been encountered t 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.

DF :missing DE

A . DF macro occurs within a displaYt that
iS t a . DE macro has been omitted or
mistyped.

DF : mi s sing FE

A display starts inside a footnote. The likely
cause is the omission (or misspelling) of a
. FE macro to end a previous footnote.

4-124

NUX Text Processing Tools

Error Message

Description

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 . F S 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 . F S macro was not matched by
a closing . FE, that is, an attempt is being
made to begin a footnote inside another one.

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.

LB:missing arg(s)

The . LB macro requires at least four
arguments.

mm Reference

4-125

Error Message

Description

LB : too many nested
lists

Another list was started when there were
already six active lists.

LE:mismatched

The . LE macro has occurred without a
previous. LB or other list-initialization
macro. This is not a fatal error. The
message is issued because there exists some
problem in the preceding text.

LI:no lists active

The. LI macro occurred without a
preceding list-initialization macro. The latter
probably has been omitted or entered
incorrect!y.

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.

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.

4-126

A/UX Text Processing Tools

Error Message

Description

SG:missing FE

The . SG macro occurred inside a footnote.

SG:no authors

The. SG macro occurred without any
previous. AU macro(s).

Check WA, WE, lA,
IE, LT sequence

Something has disturbed the correct order of
these macros.

)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

)W:WA, WE, or IE
macro missing

You have omitted either or both of the . IA
and. IE macros.

VL:missing arg

The . VL macro requires at least one
argument.

WC:unknown option

An incorrect argument has been given to the
. WC macro.

Reference

the other member of the macro pair.

4-127

Formatter Error Messages

Most messages issued by the formatter are self-explanatory. Those
error messages over which the user has some control are listed below.
Any other error messages should be reported to the local system
support group.

Error Message

Description

Cannot do ev

Can be caused by:
• setting a page width that is negative or
extremely short
• setting a page length that is negative or
extremely short
• reprocessing a macro package (for
example, performing a . so request on a
macro package that was already requested
on the command line)
• requesting the troff formatter -sl
option on a document that is longer than
ten pages.

Cannot execute

filename;

Given by the . ! request if the filename is
not found.

Cannot open filename;

Indicates one of the files in the list of files to
be processed cannot be opened.

Exception word
list full;

Indicates too many words have been
specified in the hyphenation exception list
(via. hw requests).

4-128

NUX Text Processing Tools

Error Message

Description

Line overflow

Indicates output line being generated was
too long for the fonnatter line buffer
capacity. The excess was discarded. Likely
causes for this message are very long lines
or words generated through the misuse of
\ c of the . cu request, or very long
equations produced by eqn/neqn(l).

Nonexistent font
type;

Indicates a request has been made to mount
an unknown font.

Nonexistent macro
file;

Indicates the requested macro package does
not exist.

Nonexistent
terminal type;

Indicates the terminal options refer to an
unknown terminal type.

Out of temp file
space;

Indicates additional temporary space for
macro definitions, diversions, and so on
cannot be allocated. This message often
occurs because of unclosed diversions
(missing. FE or . DE), unclosed macro
definitions (for example, missing" .. "), or a
huge table of contents.

Too many page
numbers;

Indicates the list of pages specified to the -0
fonnatter option is too long.

Too many number
registers;

Indicates the pool of number register names
is full. Unneeded registers can be deleted
by using the . r r request.

Too many
strings/macros;

Indicates the pool of string and macro
names is full. Unneeded strings and names
macros can be deleted using the . rm
request.

mm Reference

4-129

Error Message

Description

Word overflow

Indicates a word being generated exceeded
the formatter word buffer capacity. Excess
characters were discarded. Likely causes
for this message are very long lines, words
generated through the misuse of \ c of the
. cu request, or very long equations
produced by eqn/neqn(l).

4-130

NUX Text Processing Tools

Chapter 5
and me Reference

Contents
1. Introduction
1.1 Definitions
. . • .
1.1.1 Formatter •
1.1.2 Requests
•••••.
1.1.3 Macros
1.1.4 Strings.
1.1.5 Number registers •
1.2 How input is read
• • • • • . • .
1.2.1 Arguments and double quotes •
1.3 Sequence of beginning macros
•••.

1
1
1
1
2
2
2
3
3
3

2. Changing the overall look of the document
2.1 Multiple column output. • • • •
2.2 Setting point size and vertical spacing
2.3 Changing the top and bottom margins
• . • .
2.4 Changing line length
2.5 Changing page offset
2.6 Changing the tab setting

3
4
5

6
6
7

3. Paragraphs • • . •
3.1 Standard paragraph
3.2 Left paragraph
3.3 Indented paragraph •
3.4 Exdented paragraph •
3.5 Quote paragraph. •
3.6 Indenting paragraphs
3.7 Changing the spacing between paragraphs

7
8
8
8
11
11
11
12

4. Headings. • . . • • •
4.1 Numbered headings. •
4.2 Unnumbered headings •

12
12
14

-i-

5. Page headers and footers •
5.1
5.2
5.3

Standard headers
Standard footers • •
Custom headers and footers
• • • •
504 Printing a header and/or footer on the first
page
• • • • • • • •
5.5 Multiline headers and footers •
5.6 Set title length

• •

15
16
16
17
18
19
19

6. Keeps. • • • •
6.1 Static keeps
6.2 Floating keeps

19
20
20

7. Displays • • • •
7.1 InS Displays • • • • • •
7.1.1 InS Standard display format
7.1.2 InS Indented display. •
7.1.3 InS Left-adjusted display
7.104 InS Centered display
7.1.5 InS Block display
7.1.6 InS Display distance
7.2 me Displays • • • •
7.2.1 me Major quotes •
7.2.2 me Standard lists •
7.2.3 me Custom lists •

21
21
21
22
22
22
23
23
23
23
24
24

8. Indenting blocks of text
8.1 InS Right shift
8.2 me Centered blocks

24
24
25

9. Tables and equations
9.1 Tables •
9.2 Equations • •

25
25
26

10. Footnotes
10.1 Format of a footnote call
10.2 Changing the footnote style
10.3 Changing footnote indent
lOA Changing footnote length

27
27
28
28
29

11. References

- ii -

12. Creating an index or table of contents
12.1 Index format • • • • • • •
12.2 Printing the index in ms
12.3 Printing the table of contents in ms
12.4 Printing the index in me
••••
13. Basic document formats
13.1 Basic ms formats
13.1.1 ms Cover sheets •
13.1.2 ms Title
•
13.1.3 ms Authors
13.1.4 ms Abstract
13.1.5 ms Paper styles •
13.1.6 ms Chapter title .
13.1.7 ms UNIX trademark
13.2 Basic me formats
13.2.1 me Title pages
13.2.2 me Chapter titles
13.2.3 me Thesis format

•
•

•
•
•
•

30
31
32
33
33
•
•
•

•

• • • • •
• • • • •
.••.

•

14. Changing fonts • • • • • •
14.1 Changing the string point size •
15. Changing and removing the date in ms •
15.1 Changing the date
15.2 Removing the date . . • • .

33
33
33
34
34
35
35
36
36
37
37
37
38
38

40
•
.

.
•

• • • .
• •
••.•

41
41
41

16. Drawing boxes • • • •
16.1 Boxing a word
. • • •
16.2 Boxing a block of text •
16.2.1 Boxing a block of text in ms
16.2.2 Boxing a block of text in me

42
42
42
42
42

17. Checking your work

18. Using nroff/troff commands in ms

19. Creating your own macros
•••••.••••
19.1 Conventions used in this reference
• • • •
19.2 Defining a macro in me
. • • •
19.3 Format of names used by ms • • • . . • • .
19.3.1 Names used by eqn/neqn and tbl .

44
44
44
44
45

-iii-

· 20. How ms formats
•
20.1 Filling • • •

• • •

21. Reference tables
21.1 Macro summaries
21.1.1 ms Macro summary . . • • •
21.1.2 me Macro summary • •
21.2 Number register summary
21.3 String summary • • •

- iv -

45
45

46
46
46
51
53
55

Chapter 5
ms and me Reference

1. Introduction
This is a reference for the ms and me macro packages. ms and me are
collections of text-formatting macros for the A/UX text formatters
nraff and traff. ms was designed for writing general-purpose
documents, and me was designed for writing thesis papers at the
University of California at Berkeley. Some features of me are not
available in ms, so A/UX Release 2.0 supports both packages. You can
only use one of these packages at a time, however, so you may wish to
read this chapter and make a decision about which package to use
before you actually begin formatting a document.
It's a good idea to skim this chapter for a general understanding of the
ms macro package and then read specific sections in detail as needed.
Unless otherwise indicated, information in this chapter pertains to the
ms package. In those cases where only me is discussed, or where the
ms and me packages provide alternate ways of performing similar
tasks, the macro package to which the information applies is always

specified.
For a complete discussion of text-formatting concepts and principles,
see Chapter 1, "Introduction to A/UX Text Processing. "

1.1 Definitions
1.1.1 Formatter
Formatter refers to the nraff and traff text formatting programs.
nraff and traff behave similarly, except where noted.
1.1.2 Requests
Requests are built-in commands recognized by the formatters.
Although you seldom need to use these requests directly, this chapter
refers to some of them. These requests have lowercase names. ms
macros have uppercase names and me macros have lowercase names
(for example, . sp is a formatter request, .lp is an me macro, and

ms and me Reference

5-1

· pp

is an ms macro).

1.1.3 Macros
Macros are named collections of requests. The macro name is used as
an abbreviation for a collection of commands that you would otherwise
have to enter explicitly each time they were used. ms and me supply
many macros, and you can define additional ones. A table at the end of
this chapter lists the ms and me macros alphabetically.

(

1.1.4 Strings
In ms, strings provide character variables, each of which names a
string of characters. You can define a string with the . ds (define
string) command, and call it out in the form \ *x (for one-character
names), or \ * (xx (for two-character names). For instance, the string
DY in ms contains the current date. The input line
Today is \*(DY.

prints
Today is October 17, 1989
You can replace the current date with the command
.ds DY 02/21/90

A table at the end of this chapter lists the ms string names
alphabetically.
1.1.5 Number registers
Number registers are integer variables. ms uses them to set default
measurements such as line length, header and footer margins, and page
offset. You can give a register a value with the . nr command. For
example, the following sets the value of the line length register, LL:
.nr LL 4i

This instructs the formatter to generate all text lines at 4 inches. To
reset this value to the default, enter the following:
.nr LL 0

A table at the end of this chapter lists the ms number registers
alphabeticall y.

5-2

A/UX Text Processing Tools

(
~

1.2 How Input Is read
Formatters fill output lines from one or more input lines. You can
justify output lines so that both the left and right margins are aligned.
As lines are being filled, words may also be hyphenated as necessary.
You can turn any of these modes on and off (with the . na, . ad, . hy,
. nf, and. fi formatter requests). Turning off fill mode also turns off
justification and hyphenation. Certain formatting commands (requests
and macros) stop filling the current output line, print the line (of
whatever length), and begin subsequent text on a new output line. This
printing of a partially filled output line is called a break. A few
formatter requests and most of the ms macros cause a break. See
"How ms Formats" for more information.

1.2.1 Arguments and double quotes
In ms and me, you can use an argument to modify a macro. For
example, the ms macro . D S begins a standard display. When you add
a C to the macro
.DS C
the material in the display is centered.
Any macro argument containing ordinary (paddable) spaces must be
enclosed in double quotes. A double quote (n) is a single character that
must not be confused with two apostrophes (' '), acute accents (~ ~), or
grave accents (' '). If an argument containing such spaces is not
enclosed in double quotes, it will be treated as several separate
arguments.

1.3 Sequence of beginning macros
Text files processed by the ms macros must begin with one of the
following macros: . TL, . SH, .NH, • PP, or . LP.
Text files processed by the me macros must begin with one of the
following macros: . pp, .lp, . ip, . np, . sh, or . uh.
These macros initialize the file and must precede a break caused by
blank lines, leading spaces, or . sp, . br, and. ce troff requests.

2. Changing the overall look of the document
A document formatted with the ms or me macros is produced in a
standard page layout. By default, text is generated in a single column

and me Reference

5-3

and a line of text is 6 inches from margin to margin. The left margin is
1 inch (in troff) from the edge of the paper, point size is set to 10
points, vertical space is set to 12 points, and tab stops are set every 5
spaces.
The following macros and number registers permit you to change these
default features and customize your page layout.

2.1 Multiple column output
Output from troff is normally a single column of text By placing
the ms command. 2C or the me command. 2c in your file, the output
is printed in two-column format. Each column is printed with a width
of 7/15 of the current line length and the gap between the two columns
is IllS of the full line length.
To print text in more than two columns, use the ms . MC macro:
• MC

column-width gutter-width

The number of columns is computed automatically, based on the
maximum number of columns of the specified width that can fit within
the current line length. The column width argument must be numeric,
and unless indicated otherwise, the unit of measurement is assumed to
be in ens.
The gutter-width argument permits you to control the distance between
columns.
To return to single-column output, use the . 1 C command.
Any change in the number of columns specified (except from one to
two or greater) causes a page break.
In me, you can request a new column with . bc. To revert back to
single column output, use. lc.

5-4

A/UX Text Processing Tools

Type

Form

Explanation

. 2C

Print text in two equal columns .

. 2e

Print text in two equal columns.

.MCxy

Print text in multiple columns. x is the
column width, and y is the gutter width.

. be

Begin new column .

. 1C

Restore one-column printing .

.1e

Restore single-column output.

ioms:
macro

iome:
macro

ioms:
macro

iome:
macro

ioms:
macro

iome:
macro

2.2 Setting point size and vertical spacing
Number registers are used to set default point size and vertical spacing.
In ms the registers are called p s and v s. In me, there is a register for
paragraph point size, . nr pp; a register for section header point size,
. nr sp; and a register for title point size, . nr tp. (To change
relative point size using macros, see "Changing the String Point
Size. ") The defaults for point size and vertical spacing in the ms
macro package are 10 and 12 points, respectively. In me, the default
point size for regular text is 10 points, and the default point size for
footnotes is 8 points. The 2-point difference allows for adequate
spacing between lines.
When using ms, remember to change the vertical spacing register when
changing the point size. Otherwise, the output will be either too widely
or too closely spaced. In me, the vertical spacing is set to be
proportional to the type size.

ms and me Reference

5-5

Type

Form

Explanation

inms:
register

Point size.
Initial value: 10

in me:
register

.nr pp

.nr sp

.nr tp

Paragraph point size.
Initial value: 10
Section heading point size.
Initial value: 10
Title point size.
Initial value: 10

Vertical spacing.
Initial value: 12v

2.3 Changing the top and bottom margins
By default, the distance between the header and footer text and the top
and bottom edges of the paper is 1 inch. In ms, you can change these
values by resetting registers HM and FM.

Type

Form

Explanation

Vertical distance of the header margin.
Initial value: Ii

Vertical distance of the footer margin.
Initial value: Ii

2.4 Changing line length
The default length of a line of text is 6 inches from left to right margin.
In ms, you can change this by resetting the number register LL.

Type

Form

Explanation

Line length.
Initial value: 6i

5-6

A/UX Text Processing Tools

2.5 Changing page offset
The position of the left margin is determined by two dimensions: page
offset and indentation. Indentation controls the current left margin,
whereas page offset controls the absolute left margin.

Page offset is the distance betweeen the left margin and the left edge of
the paper. Indentation is expressed as a distance to the right of page
offset. You can change indentation within your document (see
"Indenting Paragraphs"), but page offset is defined at the beginning of
your document and usually remains constant throughout.
The default page offset is 1 in troff and 0 in nroff. In ms, you can
change this by resetting number register PO. The value of number
register PO multiplied by 2 plus the line length (register LL) must
always equal 8. For example,
lx2+6=8
where 1 is the default page offset and 6 is the default line length in
troff.

Type

Form

Explanation
Absolute limit of the left margin.

Initial value: Ii in troff, 0 in nroff

·2.6 Changing the tab setting
In ms, you can set tabs with the . TA command. The default settings
are in increments of 5 ens, but you may substitute any value needed.

Type

Form

Explanation

macro

.TA x

Set tabs to x, where X is the number of
ens.
Initial settings: increments of 5 ens

3. Paragraphs
The ms and me macro packages provide several commands that
determine the style of your paragraph. In all cases, the formatter skips
one vertical space before generating the text of the paragraph.

InS

and me Reference

5-7

3.1 Standard paragraph
The first line of a standard paragraph is indented. All other lines are
generated at the left margin. The default indentation is 5 ens, but can
be changed by setting the number register PI (see "Indenting
Paragraphs," later in this chapter.)

Form

Explanation

macro

.PP

Standard paragraph. The first line is
indented the value of register PI (5
ens). The paragraph is preceded and
followed by a vertical space equal to the
value set in register PD (Iv).

in me:
macro

.pp

Standard paragraph.

Type
inms:

3.2 Left paragraph

The text of a left-block paragraph is generated as a left-adjusted block.

Type

Form

Explanation

inms:
macro

.LP

Left-block paragraph. The paragraph is
offset vertically by the value of register
PD (Iv).

in me:
macro

. lp

Left-block paragraph .

3.3 Indented paragraph
All lines of an indented paragraph are indented a certain value. In ms,
the . IP command can'be used in three ways:
.IP
. IP label
. I P label value

5-8

AlUX Text Processing Tools

The first example produces a basic indented paragraph. Text is
generated as a block five spaces from the left margin.
The other two forms of the indented paragraph command permit you to
label your paragraph with some alphanumeric character. These can be
used to produce numbered or bulleted lists. For example,
· IP

(1)

This is a labeled indented paragraph.

produces
(1) This is a labeled indented paragraph.
You can substitute any character for the number. For example,
.IP

This is a labeled indented paragraph.

produces

* This is a labeled indented paragraph.
You can also assign a value for the indentation level:
.IP

(1)

Instead of the default indentation (5 ens), the formatter now indents the
text 10 ens.
In me, the similar command. ip can also be used in three ways:
.ip
· ip label
· ip label value

InS

and me Reference

5-9

produces

(1) This is a labeled indented paragraph.
You can substitute any character for the number. For example,
.ip *
This is a labeled indented paragraph.

produces

* This is a labeled indented paragraph.
You can also assign a value for the indentation level:
.ip (1) 10

Instead of the default indentation (5 ens), the formatter now indents the
text 10 ens.

Form

Explanation

. IP [x y]

Indented paragraph, where x is the label
and y is the indentation. Default
indentation is 5 ens, as set in the
register PI. The paragraph is offset
vertically by the value of register PD
(Iv).

macro

. ip [x y]

Indented paragraph, where x is the label
and y is the indentation. Default
indentation is 5 ens. The number
register for setting paragraph
indentation is i i.

macro

.np

Numbered indented paragraph. The
numbering is reset at the next. pp,
.lp,or . sh.

Type
inms:
macro

in me:

5-10

AlUX Text Processing Tools

3.4 Exdented paragraph
The first line of text in an exdented paragraph (hanging indent) is flush
with the left margin; all subsequent lines are indented the default 5 ens.
This ms macro is often used to format bibliographic references.

Type

Form

Explanation

macro

.xP

Paragraph with the first line exdented
by the value of register PI·(5 ens). The
paragraph is offset vertically by value
of register PD (1 v).

3.5 Quote paragraph
In ms, a quote paragraph is indented 5 ens from both the left and right
margins. Subsequent text is centered and generated as an offset block.

Type

Form

Explanation

macro

.QP

Quote paragraph. The paragraph is
centered and indented left and right by
the value of register QI (5 ens), and
offset vertically by the value of register
PD (Iv).

3.6 Indenting paragraphs
In ms, the registers P I and Q I determine the amount of indentation for
paragraphs. Values for each must be un scaled and are always read as
ens. For example,

.nr PI Ii
will not work. The value 1 i (1 inch) will not be understood by
troff; it must be given in ens.
P I sets the indentation level for all paragraphs except quote
paragraphs. For quote paragraphs, use the QI form.

InS

and me Reference

5-11

Type

Form

Explanation

inms:
register

Paragraph indentation. The values must
be unscaled and are read as ens.
Initial value: 5 ens

in me:
register

Paragraph indentation. The values are
unscaled and are read as ens.

inms:
register

Quoted paragraph indent. The values
must be unscaled and are read as ens.
Initial value: 5 ens

3.7 Changing the spacing between paragraphs
The default distance between paragraphs is one vertical space. To
change this value in ms, reset register PD.
Type

Form

Explanation

Paragraph distance.
Initial value: Iv in nroff, O.3v in
troff

4. Headings
Two types of section headings are available with these macro
packages: unnumbered and numbered. In both cases, the heading is on
the left margin and is preceded by one blank line, and the text of the
section is immediately following the heading (without a blank line). In
troff the heading is printed in boldface; in nroff it is underlined.
A paragraph macro must follow the heading macro if a vertical space
or indentation is desired.

4.1 Numbered headings
In ms, the . NH macro produces automatically numbered section
headings. An optional level number indicates a subsection from I to 5.
For example,

5-12

AlUX Text Processing Tools

.NH 1
First-level heading
.LP

text
.NH 2
Second-level heading
.LP

text

produces
1. First-level beading
text

1.1 Second-level beading
text

In me, the same thing can be accomplished with the . sh macro. For
example,
.sh 1 First-level heading
.lp
text
.sh 2
Second-level heading
.lp
text

produces the output:
1. First-level beading
text

1.1 Second-level heading
text

InS

and me Reference

5-13

Type

Form

inms:
macro

.NH

Explanation

[xl

Begin automatically numbered heading,
where x is the heading level number (l
through 5). If x=0, numbering is reset
toO.

. sh [xl

Begin automatically numbered heading,
where x is the heading level.
Numbering is reset at new paragraph
request. (The argument number can
also be placed after the title of the
section, as in . sh "title" 1).

in me:

macro

me also

has the ability to indent sections proportionally to the depth of
the section. The command
.nr siNx

will cause each section to be indented by N. N must have a scaling
factor of the form x, where x is the unit N is measured in. The most
common units are i for inches, c for centimeters, and n for ens (the
width of a single character).

Type

Form

Explanation

. si [Nxl

Indented section heading. Indents each
section by N in x units in the section
number.

in me:

macro

4.2 Unnumbered headings
The ms macro . SH produces section headings that are not numbered.
In me, you can accomplish the same thing with the macro . uh.

5-14

AlUX Text Processing Tools

Type

Form

Explanation

inms:
macro

oSH

Begin left-adjusted section heading,
separated from the preceding text by
one vertical space.

in me:
macro

ouh

Begin left-adjusted section heading,
separate from the preceeding text by
one vertical space.

5. Page headers and footers
Text printed at the top of each page is called a page header Text
printed at the bottom of each page is called a page footer. You can
specify three separate headers and footers (left, center, and right) using
either string registers or macros.
0

In ms, six string registers set up the standard layout of headers and
footers. Those registers that do not have predetermined default values
are set with the following command:

. ds register-name text
For example, to print the word "DRAFT" in the lower-right comer of
every page of a document, define register RF (right footer) as follows:

ods RF DRAFT
To clear the register, use this command:
orm RF
You can use these macros to create custom headers and footers that
appear on even or odd pages. Argument~ to these macros must be
enclosed within a set of four apostrophes indicating placement on the
line within three fields (left, center, and right). For example,
o

OH 'left' center' right'

In me, simple requests handle headers and footers. They are three-part
titles, as in ms, and a percent sign is used for the current page number:

ms and me Reference

5-15

· he '%'
.fo 'Successful Author"My Story'
This will produce output with the current page number centered at the
top of each page, "Successful Author" in the lower left corner, and
"My Story" right-adjusted in the lower right comer.
The ms macro package has many other ways of dealing with headers
and footers. The next sections explain these ms macros.

5.1 Standard headers
In ms, use the following string registers to store text put in the left,
center, and right headers. Only the center header (register CH) contains
a default string. In both nroff and troff, unless specified
otherwise, register CH contains the current page number surrounded by
hyphens. If you don't want a centered page number, you can easily
remove it or move it to another position. The remaining fields must be
set manually.

Type

Form

Explanation

Left header

Center header
Initial value: current page number
surrounded by hyphens

Right header

5.2 Standard footers
In ms, use the following string registers to store text put in the left,
center, and right footers. In nroff the center footer (CF) contains the
current date as the default string. In troff this field is empty.

5-16

A/UX Text Processing Tools

Type

Form

Explanation

Left footer

Center footer
Initial value: current date (nroff
only)

Right footer

5.3 Custom headers and footers
You can specify headers and footers on even- and odd-numbered pages
by defining macros . EH t .OHt • EF t and . OF.
For example if you want the title of your document to be in the left
footer on even-numbered pages and in the right footer on oddnumbered pages use the following commands:
t

• EF 'title'"
• OF '" title'

InS

and me Reference

5-17

Type

Form

Explanation

macro

· EH[' I' c' r'] Print page header only on even pages.

The three strings specified between the
four apostrophes indicate left, center,
and right When used without
arguments, cancel previously specified
even header.
macro

• OH[' I' c' r'] Print page header only on odd pages.

The three strings specified between the
four apostrophes indicate left, center,
and right When used without
arguments, cancel previously specified
odd header.
macro

· EF[' I' c' r'] Print page footer only on even pages.

The three strings specified between the
four apostrophes indicate left, center,
and right When used without
arguments, cancel previously specified
even footer.
macro

· OF[' I' c' r']

Print page footer only on odd pages.
The three strings specified between the
four apostrophes indicate left, center,
and right When used without
arguments, cancel previously specified
odd footer.

5.4 Printing a header and/or footer on the first page
By default, the printing of headers and footers begins on page two of
your document To print a header, a footer, or both on page one of your
document, use the ms macro . P 1; this will print whatever is defined as
your header or footer in the registers or in the macros. It must be used
before the beginning of the text.

5-18

AlUX Text Processing Tools

Type

Form

Explanation

macro

.Pl

Print header and/or footer on the first
page of the document. Must be placed
at the beginning of the text.

5.5 Multiline headers and footers
In mSt the . PT (page title) and . BT (bottom title) commands are used
to define macros for multiline page headers and footers. Define this
macro at the beginning of your file. For example
t

· de PT (or . BT)
· t l ' left' center' right'
· tl ' left' center' right'

If you need a three-line header or footer add the formatting instruction
t

, sp-l

before the first . t 1 instruction so the header lines will begin one line
higher on the page. Make sure you use an apostrophe (' ) and not a
period (.) with the' sp-l instruction. (See Chapter 3
"nraff/traff Reference/ for a full explanation of the difference
between the apostrophe and the period in traff requests.)
t

After you have defined these macros the system automatically uses the
new definition when a page is begun.
t

5.6 Set title length
In mSt register LT determines horizontal distance available for headers
and footers. By default it is equal to the line length (LL).
t

Type

Form

Explanation

Total length of headers and footers.
Initial value: 6i (or the same as register
LL)

6. Keeps
The ms and me macro packages provide commands to keep a block of
text together on one page. There are two ways to do this: the standard

InS

and me Reference

5-19

(or static) keep and the floating keep.

6.1 Static keeps
In ms, the static keep begins with. KS and ends with. KE. In me this
is accomplished with the block macros. (b and . ) b. If the number of
lines within these two macros exceeds the remaining lines on the page,
a page break is forced and the material in the block is printed on the
next page.

Type

Form

Explanation

inms:
macro

• KS

Begin static keep .

in me:
macro

. (b

Begin static keep .

inms:
macro

• KE

End static or floating keep .

in me:
macro

. )b

End static keep.

6.2 Floating keeps
In ms, the floating keep begins with. KF and ends with. KE. In me
this is accomplished with the . (z and . ) z macros. If the number of
lines in a block of text exceeds the remaining lines on the page and it is
necessary to force a page break, the regular text material continues to
print until it reaches the end of the page, and the block of text is
printed. It differs from a static keep in that it waits for a natural page
break rather than forcing one.

5-20

AlUX Text Processing Tools

Type

Form

Explanation

inms:
macro

. KF

Begin floating keep .

inms:
macro

• (z

Begin floating keep .

inms:
macro

. KE

End static or floating keep.

in me:
macro

•) z

End floating keep .

7. Displays
Displays format text without filling or adjusting. Several types of
displays are available with ms and me, both those with keep and those
without. However, the philosophy of displays is slightly different in
each macro package, so the ms and me display macros are discussed
separately in the sections that follow.
If you want text to be kept on a single page, use the standard ms
display (. DS [x]), where x can designate left, right, centered, or block.
If you don't want the text to be kept on a single page, use the ms
displays without keep (. ID, • LD, • CD, • BD).

7.1 ms Displays
7.1.1 ms Standard display format
A standard display is automatically put into a keep (see "Keeps"). A
standard display can be indented, left adjusted, centered, or in block
format depending on the argument you use.

ms and me Reference

5-21

Type

Form

Explanation

macro

• DS [xy]

Start displayed text. The text is
formatted without filling or adjusting. x
determines the format of the display:
.x=I indented
.x=L left adjusted
.x=C each line centered
.x=B lines centered as a group
y sets the amount (in ens) of indentation
(the default is the value of register PI,
or 5 ens).

macro

. DE

End display .

7.1.2

InS

(

Indented display

The indented display is the same as . DS I except that it does not
invoke a keep. Displayed material is formatted 5 ens to the right of the
left margin (or the value of register PI).
/

Type

Form

Explanation

macro

. ID

Indented display (no keep) .
Initial value: amount of register PI (5
ens)

7.1.3

InS

Left-adjusted display

The left-adjusted display is the same as . DS L except that it does not
invoke a keep. Displayed text is formatted in a block at the left margin.

Type

Form

Explanation

macro

• LD

Left-adjusted display (no keep) .

7.1.4

InS

Centered display

The centered display is the same as . D S C except that it does not
invoke a keep. Each line of text is centered individually.

5-22

A/UX Text Processing Tools

Type

Form

Explanation

macro

.CD

Centered display (no keep). Lines are
centered individually.

7.1.5 ms Block display
The block display is the same as . 0 S B except that it does not invoke
a keep. Displayed text is centered and left adjusted as a group.

Type

Form

Explanation

macro

.BD

Left adjusted then centered display (no
keep).

7.1.6 ms Display distance
Display distance is the amount of vertical space surrounding a display.
The default settings are one vertical space (nroff) or one-half vertical
space (troff). It is set with register DO.

Type

Form

Explanation

Vertical distance surrounding displays.
Initial value: one vertical space in
nroff; one-half vertical space in
troff

7.2 me Displays
7.2.1 me Major quotes
Major quotes are more than one line long and need to be set apart from
the rest of the text without quote marks around them. This can be
accomplished with the . (q and . ) q macros.

Type

Form

Explanation

macro

. (q

Begin major quote display .

macro

. )q

End major quote display .

InS

and me Reference

5-23

7.2.2 me Standard lists
Lists are indented, single spaced, unfilled displays. They're used when
the text should stand out from the normal text, as with columns of
figures or examples. The macros . (1 and . ) 1 are used to display
lists.

Type

Form

Explanation

macro

· (1

Begin list display.

macro

· )1

End list display.

7.2.3 me Custom lists
You can build fancier lists in me by utilizing the fill mode. By default
lists are normally collected in Dofill mode, but the addition of a capital
F as an argument to the list macro will cause the list to be indented
from both margins.

If you wish to center a list, use the c argument, and use the
to left justify your list.

Type

Form

Explanation

macro

· (1 F

Begin list in fill mode.

macro

·)1

End list in fill mode.

macro

· (1 C

Begin centered list display.

macro

. )1

End list display .

macro

·)1 L

Begin left-adjusted list display.

macro

· (1

End list display.

argument

8. Indenting blocks of text
Both ms and me have facilities for indenting blocks of text. ms can
shift text to the right, and me can center text blocks.

8.1 ms Right shift
The . RS macro shifts the text to the right. The default value for the
shift is 5 ens, but this can be changed by resetting number register PI.
You can use more than one . RS to increase the amount of indentation.
The only limit is the right margin. For each . RS entered, you must

5-24

A/UX Text Processing Tools

enter an . RE to cancel it. For example, if you enter five . RS macros,
you must enter five . RE macros.

Type

Form

Explanation

macro

.RS

Right shift. Move indentation to the
right by the value of register PI (5 ens) .
. RS macros can be nested.

macro

.RE

End right shift. Move indentation to the
left by the amount that the
corresponding . RS is moved to the
right.

8.2 me Centered blocks
Sometimes you may want to center several lines of text as a group,
rather than centering each line separately. This can be accomplished
with the . (c and . ) c macros. All the lines between these macros will
be centered as a unit, with the longest line centered on the page and the
rest of the lines centered around it. Centered blocks are not keeps, but
you may use them inside keeps.

Type

Form

Explanation

macro

• (c

Begin centered block .

macro

. )c

End centered block.

9. Tables and equations
The following ms macros are used with the NUX system
preprocessors tbl and eqn to produce tables and equations. For
complete instructions on using these programs, see Chapter 6, "tbl
Reference," and Chapter 7, "eqn Reference."

9.1 Tables
Text placed between the delimiters . T S and . TE (table start and table
end) are processed by the table formatting program tbl. If you are
producing a multipage table and you want a standard heading to be
printed on each page of the table, you should use the . TS H form of
the command. Type . TH at the end of the heading material. For
example,

and me Reference

5-25

.TS H

center tab ( : )
c c .
. TH

heading:data
table: data
table:data
.TE
repeats the heading

heading data
on every page. (This is not a feature of tbl but of ros.)

Type

Form

Explanation

macro

. TS [H]

Table start. Supplies one-half vertical
space between preceding text and table.
Argument H indicates that the material
that follows (until a . TH) is heading
text to be repeated for multipage tables.

macro

. TE

Table end .

macro

.TH

End table heading. Used only with the
. TS H macro.

9.2 Equations
Text placed between the delimiters. EQ and . EN (equation start and
equation end) are processed by the equation formatting program eqn.
You must use displays with keep (. DS/ • DE) around displayed
equation specifications. (See Chapter 7, "eqn Reference," for a
discussion of the difference between displayed and in-line equations.)

By default, displayed equations are centered. You can specify the
placement (centered, left adjusted, or indented) by supplying the
appropriate argument to the . EQ command. Following this argument,
you can also specify an equation number to label the equation. The
label is generated at the right margin. For example,

5-26

NUX Text Processing Tools

.DS
• EQ

(1)

sum from i=O to {i
.EN
.DE

inf} x sup i

4 over pi

produces
i=- .

i=O

LX'-

(1)

Type

Form

Explanation

macro

• EQ [xy]

Begin equation. Output preceded by
one vertical space and automatically
centered. x controls the placement of
the equation:
x=L left adjusted
x=I indented
x=C centered
Argument y supplies an equation
number and prints it at the right margin.

macro

. EN

End equation .

10. Footnotes
10.1 Format of a footnote call
You can produce footnotes with ms by placing text between footnote
start and end macros, . F Sand . FE. In me this is accomplished with
. (f and . ) f. The material is collected, saved, and printed at the
bottom of the current page. The footnote is printed 2 points smaller
than the text, and is separated from the main body of text by a
horizontal line.
You can produce footnotes that are numbered automatically by placing
the string \ * * immediately following the text to be footnoted. ms also
penn its you to define your own footnote label. For example, if you
want your footnotes to be labeled alphabetically, you can enter the
following:

InS

and me Reference

5-27

.LP
This is the sentence I am referencing [A] .
.FS
[A] This is the text of the footnote .
. FE

Type

Form

Explanation

inms:
macro

. FS

Begin footnote .

in me:
macro

. (f

Begin footnote .

inms:
macro

. FE

End footnote .

in me:
macro

. )f

End footnote .

10.2 Changing the footnote style
In a standard footnote, a label is printed as a superscript and the first
line is indented. You can suppress both these features with ms, as well
as produce the footnote text as an indented paragraph. Use the number
register FF to modify the default format of a footnote.

Type

Form

FF x

Explanation
Footnote format.
Suppress superscripting of
footnote label.
x=2 Suppress indentation of first line
of footnote text.
x=3 Footnote as indented paragraph.
x=1

10.3 Changing footnote indent
In ms, the footnote indent register is used to change a footnote's
distance from the left margin. The default is 2 ens.

5-28

AlUX Text Processing Tools

Type

Form

Explanation

Footnote indent Controls the amount
of indentation from the left margin.
Initial value: 2 ens

10.4 Changing footnote length
By default, the length of a footnote is 5.5 inches, just slightly shorter
than the default line length. You can change this value with ms by
resetting register FL.

Type

Form

Explanation

Footnote line length.
Initial value: 5.5i

In addition to standard footnotes, me has a delayed text facility. This is
similar to a footnote except that it is printed only when explicitly called
for (usually at the end of a chapter). The macro to identify delayed text
in me is * #. Even if you are using the delayed text as your standard
reference mechanism, you may still use the footnote facility, but in this
case you may wish to reference the footnotes with special characters
rather than numbers.

11. References
You can classify books, journal articles, book chapters, and reports
with the ms macros . ] -, . [0, and . [n. They must be used in
conjunction with the troff preprocessor refer. See refer(1) in

AIUX Command Reference.

and me Reference

5-29

Type

Form

Explanation

macro

·] -

Begin re fer reference.

macro

• [0

End of unclassifiable reference.

macro

• [n

Classifiable reference.
n=l journal article
n=2 book
n=3 book article
n=4 report

12. Creating an index or table of contents
You should enclose all entries you want placed in an index in the ms
begin and end delimiters. XA and. XE. Additional entries are
preceded by the macro . XA.
In ms, these macros can be used throughout the body of text in
combination with section heading macros to automatically generate a
table of contents with page numbers. For example,
.SH

heading-text
.XS 1

heading-text
.XE

If you are using numbered headings in ms and you want these numbers
included in the table of contents, use this format:
.NH

heading-text
.XS 1

\ * (SN

heading-text

.XE

The \ * (SN string will be replaced with the number of the heading
when the table of contents or index is printed.
The final output of the index or table of contents is produced with
either the . PX or the . TC macro. The difference between these
macros is that. TC prints a centered "CONTENTS" heading at the top

5-30

A/UX Text Processing Tools

of the page and page numbering is reset to roman numerals (as in this
document).

12.1 Index format
Material to be printed in an index or table of contents should be placed
between the . xs and. XE macros, if you're using ms, or between. (x
and . ) f, if you're using me. In ms, use the . XA macro for additional
ms entries:

.xs
index-entry
.XA

additional-index-entry
.XA

additional-index-entry
.XE

You can designate the page number of the indexed material as an
argument to . XS or . (x:

. xs
• (x

page-number
page-number

In ms, you can change the indentation level by assigning a value to the
argument following the page number:

.xs

1 5

ms and me Reference

5-31

Type

Form

Explanation

inms:
macro

.XS [xy]

Begin index entry, where x is the page
number of the entry and y is the amount
of indentation (in ens).

macro

• (x [n]

Begin index entry, where n is the page
number of the entry. If n=_, no page
number or line of dots will be printed.
If n=" " , a line of dots will appear with
no page number. If n is any other
character, it will be understood as the
name of the index, thus allowing
several indices to be run
simultaneously.

inms:
macro

.XA [xy]

Additional index entry, where x is the
page number of the entry and y is the
amount of indentation (in ens).

(

in me:

macro

• XE

End index entry .

. )x

End index entry .

in me:

macro

12.2 Printing the index in ms
The . PX macro is used in ms to print a formatted list of the text items
designated by the index macros. This is accomplished in me by . xp.

Type

Form

Explanation

inms:
macro

• PX

Print index.

.xp

Print index.

in me:

macro

5-32

AlUX Text Processing Tools

!
\~

12.3 Printing the table of contents in ms
The . TC macro prints a list of the text items designated by the index
macros. It differs from the . PX macro described above in two ways:
• It provides a centered heading (' 'CONTENTS") at the top of the
page.
• It resets page numbering to lowercase roman numerals.

Type

Form

Explanation

macro

.TC

Print table of contents. Preceded by
page break, and the page numbering is
reset to lowercase roman numerals.

12.4 Printing the index in me
In me, the index must be printed at the end of the paper, rather than at
the beginning. You will have to rearrange the paper physically after
printing if you wish to use the me index as a table of contents.

13. Basic document formats
Both the ms and the me macro packages have facilities for formatting
the basic elements of a document, such as the cover page, margins, and
spacing. The philosophy is slightly different for each (me was
developed to follow the specifications for doctoral dissertations at the
University of California at Berkeley), so the basic formatting facilities
of each macro package are described separately in the sections that
follow.

13.1 Basic ms formats
13.1.1

InS

Cover sheets

You can generate a separate cover sheet containing any of the
following: title (. TL), author (. AU) , author's institution (. AI), and
abstract ( . AB). Precede these macros with . RP and enter them in the
order indicated. The current date is printed on the cover sheet (unless
you suppress this feature with the . ND macro; see "Removing the
Date").
You can also include this information without producing a cover sheet.
Title, author, abstract, and so on are then printed on the first page of the

InS

and me Reference

5-33

document.
13.1.2 ms Title

The title macro (. TL) creates a centered title (as opposed to the threepart title format of the traff request. tl). In traff the title is
printed 2 points larger than the remaining text and is in boldface. In
nraff the title is underlined. When used with the . RP macro, the title
is centered on the cover sheet.
Type

Form

Explanation

macro

.TL

Print centered title in boldface, 2 points
larger than current font.

13.1.3

InS

Authors

The macros. AU and. AI print the author's name and institution
centered and in italics. For example,
.AU

author's-name
.AI

author's-institution
produces

author's-name
author's-institution
Multiple authors (and institutions) can also be used. Precede each
additional entry with . AU or . AI, as appropriate. For example,
.AU

author}
.AU

author2

5-34

AlUX Text Processing Tools

Type

Form

Explanation

macro

.AU

Print centered author's name, in current
point size and in italics. Multiple
names are printed on separate lines if
entered on separate input lines.

macro

.AI

Print centered information about the
author's institution.

13.1.4 ms Abstract
An abstract is a brief summary of the text it precedes. The . AB macro
prints this summary after the author's institution, if used, with an
optional centered heading.
Type

Form

macro

.AB

macro

.AE

[no]

Explanation
Begin abstract. The abstract text is
preceded by a centered heading titled
"ABSTRACT." Argument no
suppresses the heading. The abstract
text is filled and adjusted on a line 5/6
the normal text line length.
End abstract.

13.1.5 ms Paper styles
You can produce cover sheets in two basic formats: standard released
paper or thesis mode.
Released paper format ( . RP) provides a separate cover sheet
containing title, author, institution, and abstract. (See' 1m3 Cover
Sheets.")
Thesis mode ( . TM) formats your document according to university
specifications for doctoral dissertations. The page number is printed on
each page, text is double-spaced, the current date is removed from the
center footer, and the chapter title macro (. CT) is defined and
activated.

ms and me Reference

5-35

Type

Form

macro

• RP

macro

.TM

Explanation
[no]

Released paper format. Provides a
separate cover sheet for title, author,
author's institution, and abstract. This
information is repeated on the first page
of the document unless the argument
no is specified.
Thesis mode. Automatically numbers
each page; double-spaces all text except
displays, quotes, and keeps; suppresses
the printing of the date in the center
footer; and defines the chapter title
macro (. CT).

13.1.6 InS Chapter title
The chapter title macro is defined only when you have invoked thesis
mode. It begins a new page, moves the page number from the right
header to the center footer, centers the lines that follow until a
paragraph macro is reached, and, in the case of t ro f f, prints these
lines in boldface.
Type

Form

Explanation

macro

.CT

Move the page number from right
header to the center footer, generate a
page break, and center and boldface the
lines following the request (thesis mode
only).

13.1.7

InS

UNIX trademark

Type

Form

Explanation

macro

.ux

Prints "UNIXt" in the text plus a
footnote that reads' 'UNIX is a
Trademark of Bell Laboratories. "

5-36

A/UX Text Processing Tools

13.2 Basic me formats
13.2.1 me Title pages

There are no headers or footers on a title page, and unlike other pages,
you are allowed to leave blank space by spacing down from the top.
The . t P macro produces a title page.
Type

Form

Explanation

macro

. tp

Print title page .

13.2.2 me Chapter titles

The. +c T macro can be used to start chapters in me. Each chapter is
automatically numbered from one, and a heading is printed at the top of
each chapter with the chapter number and the name T. This
information is moved to the footer of the first page of the chapter. If
the name T is not specified, the output is a chapter with no heading.
Although a document's preliminary sections-the abstract, table of
contents, and so on-are normally placed at the beginning, you should
format and print them last when using me. This is so that index entries
can be collected and then printed for the table of contents. At the end
of the document's main text, you can use the . ++ P macro, which
begins the preliminary sections. After issuing this request, you can use
the . +c macro to begin one preliminary section of the document and
print the page numbers in lowercase roman numerals.
You can use the . +c macro repeatedly to begin different preliminary
sections, such as the abstract, table of contents, or acknowledgements.
Then you can use the . ++ B macro to begin the bibliography at the end
of the document. You will have to rearrange the document physically
after printing to place the preliminary sections at the beginning.

ms and me Reference

5-37

Type

Form

Explanation

macro

. +c [1]

Print chapter heading, where T is the
name of the chapter. If T is omitted, the
chapter page is printed with no heading.

macro

.++p

Print preliminary section of paper with
lower case Roman numeral page
numbers.

macro

.++B

Print the bibliographic section of the
paper.

13.2.3 me Thesis format
The . th macro sets up the headers, footers, margins, and spacing of
the formatter to format a thesis according to the rules established at the
University of California at Berkeley. The correct headers, footers,
margins, and spacing are set up.
Type

Form

Explanation

macro

.th

Set up Berkeley thesis format.

14. Changing fonts
You can use the following macros to emphasize words or groups of
words. Typewritten or line-printed material is usually emphasized with
underlining. Typeset and typeset-quality material is emphasized with
boldface or italics.
In ms, the . Band . I macros produce boldface and italics,
respectively, with troff and underlining with nroff. In me, use. b
for bold and . i for italics. There are several ways of using these
macros in your text.
In ms, • B or . I can be followed by RETURN, and all subsequent text
will be printed in boldface or italics. This usage must be terminated by
a • R command, indicating that printing should return to roman, as
follows:

5-38

AlUX Text Processing Tools

.B
This text will be printed in boldface .

In ms, • B or . I can be followed by a single word on the same line.
The same is true in me, where . b or . i can be followed by a single
word. In that case, only that word is emphasized and no . R is needed
for the ms text:
.B

word

In both macro packages, the macros for boldfacing and italicizing can
be followed by a group of words on the same line. These must be
enclosed in double quotes. Again, only those words are emphasized
and no . R is needed. For example, in ms you could use:
• B " group-oj-words"

The underline macros, . UL (ms) and . u (me), apply only to text
processed with t ro f f. They underline one word at a time. If multiple
word underlining is desired, you must enter individual underlining
commands for each word. Enclosing multiple words in quotes does not
work. For example, in ms you could use:
text
• UL
• UL
• UL

InS

word1
word2
word3

and me Reference

5-39

Type

Form

Explanation

inms:
macro

• B [x]

Print x in boldface (traff only). If x
is not present, print all subsequent text
in boldface.

in me:
macro

. b [x]

Print x in boldface (traff only) .

inms:
macro

· I [x]

Print x in boldface. If x is not present,
print all subsequent text in italics.

in me:
macro

· i [x]

Print x in italics.

Return to roman font.

inms:
macro

• UL

in me:
macro

.ux

Underline x (traff only) .
Underline x (traff only).

14.1 Changing the string point size
In ms, three macros are provided to control the relative size of traff
type. . 8M and . LG decrease and increase point size by 2 points,
respectively, and both can be repeated to increase the effect. In me
there is only the one . sm macro to set a word or phrase in a smaller
point size. The ms . NL command restores point size to the default.
These macros are used for temporary size changes for a single word or
a small group of words. (See" Setting Point Size and Vertical
Spacing" to change absolute point size.)

5-40

AlUX Text Processing Tools

Type

Form

Explanation

inms:
macro

. SM

Decrease point size by 2 .

in me:
macro

.sm

Decrease point size by 2.

inms:
macro

. LG

Increase point size by 2 .

inms:
macro

.NL

Set point size back to normal.
Initial value: 10

15. Changing and removing the date in ms
When you use nroff with the ms macros, the current date is printed
at the bottom center of every page. With both nroff and troff,
when you use . RP format (see "Paper Styles") the current date is
printed on the cover sheet of the document. The following macros are
provided to change these default features.

15.1 Changing the date
Type

Form

Explanation

macro

.DA [x]

In troff print the current date at the
bottom of each page (in nroff this is
the default). Argument x replaces the
current date with a different value.
(The current date is kept in string
register \ * (DY.)

15.2 Removing the date
Use the . ND macro to suppress printing of the date. If you add a date
as an argument, that date is printed on the cover sheet in released paper
format.

ms and me Reference

5-41

Type

Form

Explanation

macro

.ND [x]

Suppress printing of the date. If a date
is given as an argument, it is printed on
the cover sheet in . RP format

16. Drawing boxes
You can draw a box around a single word or a group of words with the
box macros.

16.1 Boxing a word
Use the . BX command in ms or the . bx command in me to draw a box
around a single word. The word to be boxed is entered as an argument
to the macro. For example, in ms:
.BX

word

Type

Form

inms:
macro

.BX

in me:
macro

.bx

Explanation
Draw a rectangular box around a word,
where x is any word.
Draw a rectangular box around a word,
where x is any word.

16.2 Boxing a block of text
16.2.1 Boxing a block of text in InS
You can draw a box around a group of words with the . BI and . B2
macros. Text to be boxed is entered on the line following the . Bl.
Type

Form

Explanation

macro

.BI

Begin boxed text.

macro

.B2

End boxed text

16.2.2 Boxing a block of text in me
You can box a phrase in me by grouping the arguments to the . bx
macro in double quotes, but you can't box more than one line at a time.

5-42

A/UX Text Processing Tools

17. Checking your work
You can check your file for formatting errors with the checknr
program. checknr examines your file and reports any unrecognized
macros or unbalanced macro constructions. For example, it will find
any. DS commands that are not terminated with. DE, and it will verify
that each . RS command has a corresponding . RE command.
To run checknr, enter the command
checknr file
Any discrepancies are written to the standard output. Or, if you prefer,
you can direct the output from checknr to a file so you can examine
it later:
checknr file > output-file
For more detailed instructions on using this program, refer to the
checknr(l) inA/UX Command Reference.

18. Using nroff/troff commands in ms
The ms macro package was designed to meet most text processing
needs, making it unnecessary to learn the details of the complicated
nroff/troff formatting language. However, you can use
nroff/troff commands in conjunction with thems macros without
losing the benefits and simplicity of using a macro package.
In addition to the . n rand . ds commands used to define number and
string registers, you can use the following nroff/troff commands
in a file processed with the ms macros:

InS

.cen

Center n lines of text. If n is omitted, only the line
following is centered.

.spn

Print n blank lines. If n is omitted, one blank line is
printed.

. br

Start a new output line.

. bp

Begin a new page .

. pl n

Set the page length to n.

. ls n

Set the line spacing to n .

and me Reference

5-43

. na

No adjust. Turns off right-margin justification .

. ad

Adjust both margins.

Note that you can use .ls, . na, and. ad anywhere in your document;
the remaining requests, however, must not appear until after the
initializing macro (see "Sequence of Beginning Macros").

19. Creating your own macros
You can create your own macro out of a sequence of nroff /troff
commands and other defined macros. The basic procedure is to set up
a definition string and then name the macro. Because ms uses
uppercase macro names, it is probably a good idea to use ms custom
macro names that are either a single lowercase letter or an uppercase
letter followed by a lowercase letter. The opposite is true for me,
where macros are already in lowercase. If you are using me you
probably want to name your macros with uppercase letters. In me,
avoid using TS, TH, TE, EQ, and EN.

19.1 Conventions used in this reference
The following conventions are used to describe macro names:
n
x

digit
alphanumeric character

All other characters are literals (characters that stand for themselves).
Macro and string names are kept in a single internal table. Therefore,
there must be no duplication among such names. Number register
names are kept in a separate table.

19.2 Defining a macro in me
To define a macro in me, start the definition with . de XX, where XX is
the name you wish to call the macro. List any requests, or other macro
commands that will be included, then end the macro with .. on a
separate line. Your macro will now be named XX.
19.3 Format of names used by InS
Macros are in the form X,.xx, or xn (for example, macros. I, . PP, and
. Pl), and registers are in the form.xx (for example, po).

5-44

A/UX Text Processing Tools

19.3.1 Names used by eqnlneqn and tbl
The mathematical equation preprocessors, eqn and neqn, use
registers and string names of the form nn. The table preprocessor,
tbl(l), uses T&, T#, and TW, and names of the form
x- x+

20. How ms formats
20.1 Filling
ms processes text by filling and adjusting the character input to fit the
page dimensions and formatting instructions. Words are collected from
the input and are placed on each output line until no more text will fit
within the line length. The text fills the line. Spaces are inserted
between words as necessary to bring the text exactly to the right
margin. Formatting macros then provide further instructions such as
paragraph separation, top and bottom margins, footnotes, and headings.
A break is any interruption of the filling or adjusting process. t ro f f
automatically skips to the next output line when a break occurs.
The ms macros that cause a break are

InS

.AB

Begin abstract.

. AI

Author's institution .

. AU
.BI

Author's name .
Begin boxed text.

.B2

End boxed text.

. BD

Block display (no keep) .

. CD

Centered display (no keep) .

. CT

Chapter title .

. DE

End display .

. DS
. EN

Start standard display .
End equation .

. EQ

Start equation .

. ID

Indented display (no keep) .

. IP

Indented paragraph .

and me Reference

5-45

. KE

End keep.

. KS

Start keep .

. LD

Left-adjusted display (no keep) .

. LP

Left-block paragraph .

.MC

Begin multiple column text.

. NH

Numbered heading .

. PP

Standard paragraph .

. QP

Quote paragraph .

.RE

End right shift.

.RS

Begin right shift.

. SH

Unnumbered section heading.

. TC

Print table of contents .

. TE

End table .

. TL

Print centered title in boldface.

. TS

Start table.

. XA

Additional index entry.

. XS

Begin index entry .

. IC

Resume one-column printing .

. 2C

Begin two-column printing .

21. Reference tables
21.1 Macro summaries

21.1.1 ms Macro summary
Name

Description

.AB

Begin abstract.

.AE

End abstract.

. AI

Author~ s

5-46

institution .

AlUX Text Processing Tools

Name

Description

. AU

Author's name .

· B [xl

Print x in boldface. If x is not present, print all
subsequent text in boldface.

.B1

Begin boxed text

.B2

End boxed text

.BD

Block display; center entire block.

. BT

Bottom title, printed at foot of page.

.BX [xl

Print x in a box.

. CD

Centered display (no keep) .

.CT

Chapter title. Page number is moved to register CF
(thesis mode only).

• DA

[xl

Print current date at the bottom of each page. With
a date as an argument, uses that date in place of the
current date.
End display.

• DE
• DS [x yl

Begin display with keep.
indented
left adjusted
centered
block
y=amount of indentation

x=I
x=L
x=C
x=B

• EF ['

I' c' r' 1

Even footer.

• EH ['

I' c' r' 1

Even header.

• EN

End equation.

and me Reference

5-47

Name
• EQ [xy]

Description
Begin equation .

x=I indented
x=L left adjusted

x=C centered
y=E equation label

. FE

End footnote .

· FS [x]

Start footnote, where x is a user-defined label.

· I [x]

Print x in italics. If x is not present, print all
subsequent text in italics.

· ID

Indented display (no keep).

· IP [xy]

Indented paragraph, where x is a label and y is the
indentation.

. KE

End keep (static or floating) .

. KF

Begin floating keep .

. KS

Begin static keep .

• LD

Left-adjusted display (no keep) .

• LG

Increase point size by 2 .

• LP

Left-block paragraph .

.MC [xy]

Print text in multiple columns, where x is the
column width and y is the gutter width.

• ND [x]

Suppress printing of date in page footer, where x is
the date on the cover sheet (released paper format).

• NH [x]

Begin numbered heading, where x is the heading
level. If x=O, level is reset to zero.

5-48

A/UX Text Processing Tools

Name

Description

• NL

Return pomt SIze to normal.
Initial Value: 10

• OF [' l' c' r']

Odd footer .

• OH [' l' c' r']

Odd header.

· P1

Print header (including page number) on the first
page.

· PP

Standard paragraph with the first line indented.

• PT

Page title, printed at the head of each page.

• PX

[no]

Print index. no suppresses the title.

· QP

Quote paragraph, centered and indented 5 ens from
both margins.

•R

Return to roman font.

• RE

End right shift.

• RP

[no]

Begin released paper format. no suppresses the
title on the first page.

• RS

Begin right shift; start relative indentation.

• SH

Begin unnumbered section heading, left adjusted
and boldfaced.

• SM

Decrease point size by 2.

· TA

Set tabs to x, where x is the number of ens.
Initial value: increments of 5 ens

• TC [no]

Print table of contents. no suppresses the title.

• TE

End table.

• TH

End running table heading.

ms and me Reference

5-49

Name

Description

.TL

Print centered title in boldface 2 points larger.

. TM

Thesis mode.

.TS [H]

Begin table. Hindicates a multipage header.

. UL x

Underline x .

. UX

UNIX trademark message.

· XA [xy]

Additional index entry. x is the page number of the
entry and y is the amount of indentation (in ens).

. XE

End index entry .

. XP

Exdented paragraph .

.XS [xy]

Begin index entry. x is the page number of the
entry and y is the amount of indentation (in ens).

. le

Resume one-column printing .

. 2C

Begin two-column printing .

· ]-

Begin reference.

• [0

End unclassifiable reference.

· [n

Classifiable reference.
n=l journal article
n=2 book
n=3 book article
n=4 report

5-50

A/UX Text Processing Tools

/
"

/'
~

21.1.2 me Macro summary
Name

Description

.b [xl

Print x in boldface. If x is not present, print all
subsequent text in boldface.

. bc

Begin new column .

.bi [xl

Print x in bold italics. If x is not present, print all
subsequent text in bold italics.

. bp

Begin new page.

. bx

Print inside a box .

· (b

Begin block text.

.) b

End block text.

++B

Print bibliography.

.ce [xl

Center x lines. x defaults to 1.

· (c

Begin centered block.

. )c

End centered block.

. +c T

Print chapter with title T .

. EN

End equation .

.EQ [x y]

Begin equation.
indented
left adjusted
centered
equation label

x=I
x=L
x=C
y=E

. fo

Print footer .

· (f

Begin footnote.

InS

and me Reference

5-51

Name

Description

.)f

End footnote .

.in [+n]

Indent n spaces. n can be a negative number for
left indent.

. he

Print header.

(
~

·i

[x]

Print x in italics. If x is not present, print all
subsequent text in italics.

.ip [xy]

Indented paragraph, where x is a label, and y is the
indentation.

. lp

Left-adjusted paragraph .

· (1

Begin list.

.) 1

End list.

.np

Numbered paragraph.

. nr

Numbered register.

. pp

Standard paragraph .

. ++p

Print preliminary part of paper.

· (q

Begin major quote.

• )q

End major quote.

·r

[x]

Print x in roman. If x is not present, print all
subsequent text in roman.

. sh

Print section heading .

. sm

Decrease point size by 2 .

.sp [n]

Space down n. n defaults to 1.

. TE

End table .

5-52

A/UX Text Processing Tools

Name

Description

.th

Set up Berkeley thesis environment.

. TH

End running table heading.

· ti [+n]

Temporarily indent n spaces. n can be a negative
number for left indent

.TS [II]

Begin table. H indicates multipage header.

. uh

Unnumbered section heading .

. ul [x]

Underline x .

. xp

Print index .

· (x

[x y]

Begin index entry. x is the page number and y is
the amount of indentation in ens.

· )x

End index entry.

· (z

Begin floating keep.

•)z

End floating keep.

. le

Resume I-column printing .

. 2e

Begin 2-column printing .

21.2 Number register summary

Name

Description

in me:
pp

Standard paragraph point size.
Initial value: 10

Section header point size.

ms and me Reference

5-53

Name

Description
Initial value: 10

Title page point size.
Initial value: 10

inms:
CF

Center footer.
Initial value: current date (nroff only)

Center header.
Initial value: current page number surrounded by
hyphens

Display distance.
Initial value: Iv in nroff, .5v in troff

FF [x]

Footnote format.
Suppress superscripting of footnote label.
Suppress indentation of first line of footnote
text.
x=3 Footnote as indented paragraph.
Initial value: 0
x=l
x=2

Footnote indent.
Initial value: 2 ens

Footnote length.
Initial value: 5.5i

Footer margin.
Initial value: 1i

Header margin.
Initial value: 1i

Left footer.

Left header.

5-54

A/UX Text Processing Tools

Name

Description

Line length.
Initial value: 6i

Title length.
Initial value: same as LL (6i)

Paragraph distance.
Initial value: Iv in nroff, O.3v in troff

Paragraph indent.
Initial value: 5 ens

Page offset.
Initial value: 0 in nroff), -Ii in troff

Point size.
Initial value: 10

Right header.

Quote paragraph indent.
Initial value: 5 ens

Vertical spacing.
Initial value: 12v

21.3 String summary
You can use the following strings in your text files.

Name

Description

inms:

\*Q

quote (" in nroff, " in troff)

\*U

unquote (" in nroff, " in troff)

\*-

dash (-- in nroff, - in troff)

\*(MO

month

ms and me Reference

5-55

Name

Description

\*(DY

day (current date)

\**

automatically numbered footnote

\*'

acute accent (before letter)

\*'
\*A

grave accent (before letter)
circumflex (before letter)

\*,

cedilla (before letter)

\*:

umlaut (before letter)

\*-

tilde (before letter)

in me:
\*=If:

delayed text

5-56

AlUX Text Processing Tools

Chapter 6
tbl Reference

Contents
1. tbl: a table formatting program

2. Using tbl
•.....
2.1 Command line syntax
• . • •
2.2 Running tbl with other A/UX preprocessors
3. Defining your table format •

•

4. Global format options
4.1 Table width and positioning
• • • .
4.2 Drawing boxes
4.3 Changing the thickness of your lines •
4.4 Setting a new tab character • • •
4.5 Mathematical equations in your table •
5. Column alignment: keyletters • • • • •
5.1 Numeric columns are different • .
5.2 How tbl reads your keyletter instructions
5.3 Fine tuning your keyletter specification
5.3.1 Drawing horizontal lines
5.3.2 Drawing vertical lines
5.3.3 Column spacing •
5.3.4 Vertical spacing •
5.3.5 Vertical spanning
5.3.6 Column width
5.3.7 Equal-width columns
5.3.8 Staggered columns
5.3.9 Font changes • •
5.3.10 Point size changes
5.3.11 Zero-width items •
5.3.12 Default column spacing •

-i-

1
1
2

•
•

•

3
4
4
4
5
5
5

6
7
8
8

8
9
9
9
9
10
10
10
11
11
11

6. Refining your format
6.1
6.2
6.3
6.4

11
11
11
12
13
13
13
14
14

••••••••
Tabs separate data in columns • • • •
Inserting troff commands in your table
Text blocks: multiline entries
More ways to draw lines. • • •
6.4.1 Full width horizontal lines •
6.4.2 Single-column width lines
6.4.3 Character repetition • •
6.4.4 Vertical spanning

7. Multipage tables and variable format. • • •
7.1 Multipage tables with repeated headings •
7.2 Adding new tbl. format instructions in the
• • • •
text

•

8. Restrictions
9. Examples

14
14

16
•

•

Figures
Figure 6-1. Table using the expand option

Figure 6-2. Table using the al.l.box and center
options •

•

Figure 6-3. Table using the vertical bar keyletter
feature •

•

Figure 6-4. Table using horizontal lines in place of
keyletters

•

Figure 6-5. Table using additional command
lines.

•

Figure 6-6. Table using text blocks

Figure 6-7. Table using eqn delimiters

Figure 6-8. Table using horizontal lines in place of
data.

•

- ii -

•

Figure 6-9. Table showing the versatility of the tbl.
program
• • • • . • •

Figure 6-10. Table showing font changes • • • .

- iii -

(

Chapter 6
tbl Reference

1. tbl: a table formatting program
The tbl program is a document formatting preprocessor for troff
and nroff. Tables consist of columns that can be independently
centered, right adjusted, left adjusted, or aligned by decimal points.
Headings can be placed over single columns or groups of columns. A
table entry can contain equations or consist of several rows of text.
Horizontal or vertical lines can be drawn within the table, and any table
or element can be enclosed in a box.
The tbl program converts table formatting instructions into
nroff/troff commands, and these processors do the actual
formatting of the text.
The following chapter shows you how tbl works and how to use it to
obtain the output you desire. However, the best way to learn tbl is by
studying the "Examples" section and creating your own practice
exercises based on the samples provided.

2. Using tbl
2.1 Command line syntax
tbl can be run on a simple table with the command
tbl file

I troff

For more complicated use, where there are several input files and
macro package commands (such as rom) as well as tables, the command
would be
tbl filel file2file3

I troff -rom

The files are processed in sequence, and then this data is passed on to
the remaining processors.

If a filename is not specified on the command line or if the filename
given is a minus sign (-), tbl reads the standard input.

tbl Reference

6-1

Using tbl with the nroff formatter is similar to using it with
troff, but only certain hard-copy tenninals can print vertical lines or
boxed tables.
For the convenience of those using line printers without adequate
driving tables or post-filters, there is a special -TX command line
option to tbl that produces output without fractional-line motions (see
tbl(l) in A/UX Command Reference).
The only other command line options recognized by tbl are the ms
and the rom macros. These arguments are accepted by tbl, but it is
usually more convenient to place them on the nroff /troff
fonnatter portion of the command line.

2.2 Running tbl. with other A/UX preprocessors
When pic, tbl, and eqn operate on the same file, pic is always
called first:
pic file I tbl I eqn I troff

If only eqn and tbl are present, tbl should be called first. eqn
produces a larger expansion of the input, and it is faster and more
efficient to execute it after tbl. If there are no equations within tables,
either sequence works. But, if there are equations within tables, tbl
must be called first or the output will be scrambled.
When there are several input files containing tables, equations, and rom
macros, the correct command sequence is
tbl filel file2 file3 I eqn I troff -rom

If you also use the extended mathematical character set in
/usr/pub/eqnchar (see Chapter 7, "eqn Reference"), the
command reads
tbl /usr /pub/ eqnchar file I eqn I troff -rom

3. Defining your table format
The general format of tbl input in a document is

6-2

A/UX Text Processing Tools

preceding text
.TS

global options;
column formatting instructions .
table data
.TE

more text
The global format line defines the overall format of the table. The
column formatting line defines the column alignment of the table
entries. These specifications are preceded and followed by a table start
(. TS) and table end (. TE) command. The. TS and. TE lines are then
used by troff as command delimiters.
If there isn't enough space on the page for a table, it is continued on the
next page; however, boxes and vertical lines aren't drawn properly if a
table is split between two pages. Enclosing your table in display
macros keeps your table on one page (see Chapter 4, "mrn Reference,"
and Chapter 5, "ms Reference" for a discussion of the display
macros).

4. Global format options
The global format line affects the format of the whole table. It consists
of a single line of instructions and must immediately follow the . T S
command. Option names must be separated by spaces, tabs, or
commas, and the line must be terminated by a semicolon.
The allowable options are

Global option

Description

center

Center the entire table

expand

Expand the table to the width of the current
line length

box

Enclose the table in a box

allbox

Enclose each table entry in a box

doublebox

Enclose the table in a double-ruled box

tbl Reference

6-3

Global option

Description

tab(x)

Separate data items with character x instead
of tab

linesize n

Increase line thickness (for example, box
and allbox) to n-point size

delim xx

Specify that characters xx will be used as
eqn delimiters

Global options are discussed in the following sections.

4.1 Table width and positioning
The default positioning for a table produced by tbl is left adjusted.
The center option places the table in the center of the page, as in the
above example. The expand option spreads the table across the full
width of the current line length of the page (see Figure 6-1).

4.2 Drawing boxes
There are three ways to globally specify boxed tables: box encloses
the table in a single box, allbox encloses each item of the table in a
box, and doublebox encloses the table in a double-lined box. Each
is illustrated in "Examples."
The tbl program tries to keep a boxed table on one page by issuing
the appropriate. ne (need) t roff command. This command is
calculated from the number of lines in the table. If there are spacing
commands embedded in the input, however, the . ne commands may
be inaccurate. In that case, you can use troff keep-release macros or
can manually specify the . ne n command. If a multipage table is
required, use the . TS Hand. TH macros designed for this purpose
(see "Multipage Tables and Variable Format").

4.3 Changing the thickness of your lines
The linesize n (where n is a point size) option permits you to
specify a heavier line in your table than the default 10-point; for
example,linesize 30 produces

6-4

AlUX Text ProceSSing Tools

4.4 Setting a new tab character
tbl uses the tab character to separate items of data. Because tabs are
invisible, it is useful to reset the tab character to some other character
that can be seen. You do this with the t~b (x) option, where x is a
character you will not need in your table. For example, to change the
tab character to a colon (:), use the following command:
tab ( :)

4.5 Mathematical equations in your table
When tbl processes columns of numbers it looks for a decimal point
and attempts to split numeric format items into two parts (see
"Numeric Columns are Different"). This feature interferes with the
way eqn processes equations. The delirnxx global option enables
you to define eqn delimiters within your table which prevents this
interference.
Note: It is still better to avoid putting equations in numeric (nstyle) columns.

5. Column alignment: keyletters
The format line(s) specifies column layout. It contains a "keyletter"
for each column of the table that represents a particular column format
instruction.
Keyletter instructions may be entered in either upper or lowercase, and
the last entry in the format section is always followed by a period.
Keyletter
1

Description
Left adjusted column entry

Right adjusted column entry

Centered column entry

Numeric column entry; entries are aligned
so the numbers line up at a decimal point

tbl Reference

6-5

Keyletter

,Description

Alphabetic column entry; entries are left
adjusted and positioned so the widest entry
is centered within the column

Spanned heading; the entry from the
previous column continues across this
column
Verticall y spanned heading; the entry from
the previous row continues down through
this row

5.1 Numeric columns are different
When numeric column alignment (n-style) is specified, 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. If an alignment or
alignment character isn't specified, the item is centered. However, the
special nonprinting character string (\ &) can be used to override dots
and digits or to align alphabetic data. This string lines up where a dot
normally would (the \ & disappears from the final output).
In the following example, items shown in the "Input" column will be
aligned in a numeric column as shown in the "Output" column.

Input

Output

Comments

13
4.2
26.4.12
abcdefg
abcdefg\&
749.12

13
4.2
26.4.12
abcdefg
abcdefg
749.12

(no alignment character)
(aligned by decimal point)
(aligned by decimal point)
(centered)
(\ &as alignment character)
(aligned by decimal point)

If numeric data is used in the same column with wider 1- or r-type
table entries, the widest number is centered relative to the widest
nonnumeric item; for example,

6-6

AlUX Text Processing Tools

.TS
center tab ( : )
1 1
n n.
shortest:1ongest entry
13:13
42,347.99:42,347.99
0.5: 0.5
.TE

will send the output
shortest
13
42.347.99
0.5

longest entry
13
42.347.99
0.5

This is similar to alphabetic subcolumns (a-style) which are always
slightly indented relative to left adjusted items. If necessary. the
column width is increased to force this.

5.2 How tbl. reads your keyletter instructions
The layout of keyletters in the format section represents the layout of
the actual data in the table. For example. a simple three-column format
might appear as

c s s
1 n n .

The first line of this table contains a centered heading spanned across
all three columns (c s s). Each remaining line contains a left
adjusted item in the first column followed by two columns of numeric
data (1 n n). These specifications produce the following:
Spanned Heading
ltem-l
Item-2
ltem-3

34.22
12.65
23

9.1
.02
5.8

Total

69.87

14.92

Successive line formats separated by commas can also be given on the
same line. For example. the format for the preceding example could be

tb1

Reference

6-7

written:

c s s, 1 n n .
Spaces between the key letters are not required, but they can be helpful
visually when setting up or changing a table format. Each line in the
format section corresponds to a single line of data. However, if there
are more lines of data than there are format lines, the last format line
corresponds to all following data lines up to the table end ( . TE)
command or a table continue (. T&) command (see "Adding New tbl
Format Instructions in the Text").

5.3 Fine tuning your keyletter specification
To permit further refinement of your table formatting instructions,
keyletters can be followed by qualifiers that change the format and
placement of the column entries, or change the size and shape of the
columns.
These qualifiers can be in any order, they can be upper or lowercase,
and they need not be separated by spaces (except as indicated); for
example,

np12w(2.5i)fI 6
specifies a numeric column entry in 12-point type with a maximum
width of 2.5 inches, in italic font and separated by 6 ens from the next
column entry.

5.3.1 Drawing horizontal lines
A keyletter can be replaced by an underscore character U or equal
sign (=) to specify a single or double horizontal line in place of the
column entry:
1 1

If an adjacent column contains a horizontal line or if there are vertical
lines adjoining this column, the horizontal line is extended to meet
nearby lines. If any data entry is provided for this column, it is ignored
and a warning message is printed. (See Figure 6-7.)

5.3.2 Drawing vertical lines
A vertical bar ( I ) may be placed between keyletters to cause a vertical
line between the corresponding columns of the table (see Figure 6-1).
A vertical bar to the left of the first keyletter or to the right of the last

6-8

A/UX Text Processing Tools

one produces a line at the edge of the table. If two vertical bars appear
between key letters, a double vertical line is drawn; for example,

I 1 II 1 I
5.3.3 Column spacing
A number may follow the keyletter to indicate the amount of separation
between this column and the next column; for example,
n6 n
The number specifies the separation in ens. One en is about the width
of the letter "n." More precisely, an en is the number of points equal
to half the current type size. If the expand option is used, these
numbers are multiplied by a constant, making the table as wide as the
current line length. The default column separation number is 3. If the
separation is changed, the largest space commanded is assumed.

5.3.4 Vertical spacing
A keyletter followed by v and a number indicate the vertical line
spacing within a multiline table entry. The number may be plus or
minus (+ or -), in which case it is taken as an increment or decrement
from the current vertical spacing; for example,
cv+2
A column separation space value must be separated by blanks or some
other specification from a vertical spacing command. This command
has no effect unless the corresponding table entry is a block of text (see
"Text Blocks: Multiline Entries").

5.3.5 Vertical spanning
Vertically spanned items extending over several rows of the table are
normally centered in their vertical range. If a keyletter is followed by
t, any corresponding vertically spanned item will begin at the top line
of its range; for example,
It ct at

5.3.6 Column width
A keyletter followed by w and a value in parentheses specifies
maximum column width; for example,

tbl.

Reference

6-9

lw (2i)

specifies a 2-inch column.

If the largest element in the column is not as wide as the width value
given after the w, the column is assumed to be that wide. If the largest
element in the column is wider than the specified value, its width is
used. The width is also used as a default line length for text blocks (see
"Text Blocks: Multiline Entries").
Normal t ro f f formatter units can be used to scale the width value.
The default value is ens, but inches also may be used. If the width
specification is a unitless integer, the parentheses may be omitted. If
another width value is given in a column, the last one controls the
width.

5.3.7 Equal-width columns
A keyletter followed by e indicates equal-width columns. All columns
whose keyletters are followed by e or E are made the same width; for
example,

Ie ne

5.3.8 Staggered columns
A keyletter followed by u indicates that the corresponding entry is to
be moved up one-half line. This makes it easy to have a column of
differences between numbers in an adjoining column.

Note: Staggered columns do not work with the allbox
option.

5.3.9 Font changes
A keyletter followed by f and a string containing a font name (such as
R, I, or B) or font number (such as 1,2, or 3) indicates that the
corresponding column should be in a different font from the default
font; for example,

If2 IfB
specifies one column of italics and one column of boldface.
All font names are one or two letters. A one-letter font name should be
separated from whatever follows by a space or tab.

6-10

NUX Text Processing Tools

Note: troff font change commands given within the table
data override these specifications.

5.3.10 POint size changes
A keyletter followed by p and a number indicates the point size of the
corresponding table entries. If the number is preceded by a plus or
minus (+ or -) sign, the value is incremented or decremented from the
current point size; for example,
lp8
If both a point size and a column separation value are given, one or
more blanks must separate them.

5.3.11 Zero-width items
A keyletter followed by a data item is ignored in calculating column
widths. This may be useful in allowing a long heading to run across
adjacent columns where a spanned heading would be inappropriate.

5.3.12 Default column spacing
Column descriptors missing from the end of a format line are assumed
to be left adjusted. The longest line in the format section, however,
defines the number of columns in the table. Extra columns in the data
are ignored.

6. Refining your format
Table data is entered immediately following the format line. Each line
of the table is entered as one line of data. Very long input lines can be
broken up, however, by ending the first part of the input line with a
backslash (\) or by using text blocks (see' 'Text Blocks: Multiline
Entries"). When using the backslash, the line following it is combined
with the preceding line (the backs lash vanishes).

6.1 Tabs separate data in columns
Data for each column is separated by a tab or by whatever character
has been specified in the tab(x) global option.

6.2 Inserting troff commands in your table
t ro f f commands can be interspersed with table data to provide

further refinement and definition of the table output.

tbl Reference

6-11

An input line beginning with a dot and followed by anything but a
number is assumed to be a command to troff and is passed through
unchanged, retaining its position in the table. For example, an . s p
command can be used within a table to change the spacing between
rows.
Point size and font changes may also be made within the table data.
troff commands (such as \fI, \s+2, and so forth) entered within
the table override tbl column formatting instructions.

6.3 Text blocks: multiline entries
In order to include a block of text as a table entry, precede it by tab and
T {. Enter text on a new line, and terminate it with "T {"; for example,
previous text" IT {
block of
text
T}
where . . . I is a tab character or other character defined as a tab character
in the global specification of the table. The begin delimiter (T {) must
be followed by a new line, and the end delimiter (T }) must begin a
new line; however, additional columns of data may follow after a tab
on the same line. Text is pulled out from the table, processed
separately by the formatter, and replaced in the table as a solid block.
Note: Limits in the troff program will be exceeded if 30 or
more text blocks are used in a table. This produces diagnostic
messages such as "too many string/macro names"
or "too many number registers."
If no line length is specified in the block of text or in the table format,
the default is used:
lXc/(n+l)

where I is the current line length, c is the number of table columns
spanned by the text, and n is the total number of columns in the table.
Other parameters such as point size or font used in formatting the text
block are

6-12

AlUX Text ProceSSing Tools

• those defined for your whole document (including the effect of
the . TS macro)
• any table format specifications of size, spacing, font, and column
keyletters
• troff commands within the text block itself (commands within

the table data but not within the text block do not affect that
block)

. 6.4 More ways to draw lines
In addition to specifying lines using the keyletter system, tbl also
permits line specification within the data section.

6.4.1 Full width horizontal lines
If an input line contains only an underscore character U or equal sign
(=) on a line by itself, a single or double line is drawn that extends the
full width of the table; for example,

.TS
global options ;
column formatting instructions .
data
data

.TE

6.4.2 Single-column width lines
If an individual table entry contains an underscore character U or
equal sign (=), a single or double line is drawn that extends the full
width of the column. Such lines are extended to meet horizontal or
vertical lines adjoining this column.
To obtain these characters (_ and =) explicitly in a column, they should
be preceded by a \ & or followed by a space before the usual tab or
newline character.
An input table entry that contains only the string \_ is assumed to be a
single line as wide as the text in the column. It differs from the above
single-column line in that it is not extended to meet adjoining lines.

tbl.

Reference

6-13

6.4.3 Character repetition
An input table entry containing only the string \Rx, where x is any
character, is replaced by repetitions of that character as wide as the
data in the column. This sequence of characters is not extended to
meet adjoining columns.
6.4.4 Vertical spanning
An input table entry containing only the character string \ indicates
that the table entry immediately above spans downward over this row.
It is equivalent to the keyletter 'A'.
A

7. Multipage tables and variable format
7.1 Multipage tables with repeated headings
You can print tables on more than one page with tbl, and if you use
the rom and ms macros, you can produce multipage tables with repeated
headings. Begin your table with this macro:
.TS H
After you enter your heading text, input the macro . TH. Text that
precedes the . THis placed at the top of each page of the table. The
remaining lines of the table are placed on additional pages as required;
for example,
.TS H
global options ;
column formatting instructions .
heading text
.TH
data
.TE
If you use the rom macro package, the . TH macro can take the
argument N. This causes the table header to be printed only on the first
line on a page. This option is used when it is necessary to build long
tables from smaller. TS HI. TE segments; for example,

6-14

AlUX Text Processing Tools

.TS H
global options ;
column formatting instructions .
heading text
.TH
data
.TE
.TS H
global options ;
column formatting instructions .
heading text
.TH N
data
.TE
Note: This is not a feature of tbl but of rom and can be used
only with the rom macro package.
Although any number of lines may be present in a table, only the first
200 lines are used in setting up the table. A multipage table may be
arranged as several single-page tables if this proves to be a problem.

7.2 Adding new tbl. format instructions in the text
The table continue command ( . T &) resets column parameters. It is
used to specify tables with groups of rows containing identical formats.
Each group is different, but within a group, the format is the same.
Table specifications are split into groups (separated by . T&), and each
set of instructions specifies the format of each group. (See Figure 6-5.)
The . T & command is recognized only within the first 200 lines of a
table and does not change global options, the number of columns, the
spacing between columns, or the selection of equal-width columns.

An example of such table input is

tbl Reference

6-15

.TS
box expand;

c s s
1 1 1.

data
.T&
1 s s
c c c.
data
.T&
1 1 1.

data
.TE
Using this procedure, each data line can be located close to its
corresponding format line.

8. Restrictions
Input to tb1 is subject to the following restrictions:
• The tb1 program accepts up to 35 columns; the actual number
that can be processed may be smaller depending on the
availability of troff number registers.
• The keyletters n and a may not be used in the same column.
• Computation of column width is restricted to the first 200 lines of
data.
• Table continue commands ( . T &) apply only the first 200 lines of
a table.
• Staggered column entries and multipage tables do not work with
the global option a11box.
• When calculating column widths, all entries are assumed to be in
the font and point size in use when the . T S request was
encountered. However, font and point size specifications can be
changed within the data section (as in entry \s+3data\sO).
• When processing a file which contains tables and equations, tb1
should always be called before eqn.

6-16

NUX Text Processing Tools

• Number register names used by tbl must not be used within
tables. These include 2-digit numbers from 31 to 99 and strings
of the form 4x, 5x, #x,x+, X I, "'x, andx-, where x is any
lowercase letter. The names # # , # -, and #'" should also be
avoided. (When assigning eqn delimiters in a table, the symbols
## must never be used.)
• Multipage tables should not be boxed.
• No more than 30 text blocks can be used in a table. This number
may be smaller if the individual text blocks are long.
• Table width is defined in number register TW before the . TE
macro is invoked, and may be used to expand that macro.

9. Examples
Figures 6-1 through 6-10 are included to show tbl input and output
information and to illustrate the basic concepts of the tbl program.
Although each figure has a title naming certain options or features,
other uses of tbl can be learned from them as well. For instance,
Figure 6-5 shows the use of additional command lines and also
specifies bold type print in the format area. Studying these examples
will help you learn how to use the tbl program much more easily than
by simply reading the written explanations.

tbl Reference

6-17

Figure 6·1. Table using the expand option

Input:
.TS
expand box center tab(:)
c s
1 I 1

Menu
Monday:Fish
Tuesday: Tostada
Wednesday:Tuna salad
Thursday: Spaghetti
Friday:Chicken
.TE

Output:
Menu
Monday
Tuesday
Wednesday
Thursday
Friday

6-18

Fish
Tostada
Tuna salad
Spaghetti
Chicken

AlUX Text Processing Tools

Figure 6-2. Table using the allbox and center options

Input:
.TS
allbox center tab(:)
c s s
c c c
n n n .
Paradox common stock
Year:Price:Dividend
1971:41-54:$2.60
2:41-54:2.70
3:46-55:2.87
4:40-53:3.24
5:45-52:3.40
6:51-59: .95*
.TE
.ce
* (first quarter only)

Output:
Paradox common stock
Dividend
Year
Price
41-54
1971
$2.60
2.70
2
41-54
2.87
3 46-55
4
40-53
3.24
3.40
5 45-52
51-59
.95*
6
* (first quarter only)

tbl Reference

6-19

Figure 6-3. Table using the vertical bar keyletter feature

Input:
.TS
center box tab(:);
cB s s
cI I cI I cI
1

I 1 In.

Major New York bridges
Bridge:Designer:Length
Brooklyn:J. A. Roebling:1595
Williamsburg:L. L. Buck:1600
: :1380
Triborough:O. H. Ammann:
: : 383
Bronx Whitestone:O. H. Ammann:2300
Throgs Neck:O. H. Ammann:1800
.TE

Output:
Major New York bridges
Bridge
Designer
Brooklyn
J. A. Roebling
Williamsburg
L. L. Buck
Triborough
Bronx Whitestone
Throgs Neck

6-20

Length

1595
1600
1380

O. H. Ammann
O. H. Ammann
O.H.Ammann

383
2300
1800

AlUX Text Processing Tools

Figure 6-4. Table using horizontal lines in place of keyletters

Input:
.TS
center doublebox tab ( :)
L L L
L L
L L

L L
L L L

January: February:March
June:July:MONTHS
October:November:December
.TE

Output:
January
April
June
August
October

tbl Reference

February
May

July
September
November

March

I MONTHS
December

6-21

Figure 6·5. Table using additional command lines

Input:
.TS
center box tab(:) ;
cfB s s s .
Composition of foods
.T&
c I c s s
c I c s s
c I c c Ie.
Food:Percent by weight

"':

\"':Protein:Fat:Carbo\ '" : \ ~ : \ ~ : hydrate
.T&
1 I n I n In.
Halibut:18.4:5.2: ...
Lima beans:7.5:.8:22.0
Mushrooms:3.5:.4:6.0
.TE

Output:
Comp_osition of foods
Food
Halibut
Lima beans
Mushrooms

6-22

Percent by weight
CarboFat
Protein
hydrate
5.2
18.4
...
22.0
.8
7.5
6.0
3.5
.4

AlUX Text Processing Tools

Figure 6-6. Table using text blocks

Input:
.TS
center allbox tab(:) ;
cfI s s
clw(li) clw(1.3i) clw(1.3i)
III .

New York area rocks
Era:Formation:Age (years)
Precambrian:Reading:>l billion
Paleozoic:Manhattan:400 million
Mesozoic:T{
Newark Basin, incl. Lockatong
T} :200 million
Cenozoic:coastal Plain:T{
On Long Island 30,000 years;
Cretaceous sediments redeposited
by recent glaciation
T}
.TE

Output:
Era
Precambrian
Paleozoic
Mesozoic
Cenozoic

tbl Reference

New York area rocks
Age (years)
Formation
>1 billion
Reading
Manhattan
400 million
200 million
Newark Basin, incl.
Lockatong
On Long Island 30,000
Coastal Plain
years; Cretaceous
sediments redeposited
by recent glaciation

6-23

Figure 6-7. Table using eqn delimiters
Input:

.TS
center delim $$ tab ( :) box
cp12b I c I c
1 I c I c .
1:$ rho $:$ sigma $
$ omega sub 1 $:$ i over 2 $:$ x sub i

$ pi sub 2 $:$ i over -2 $:0
$ theta sup 1 = omega sub 3 $:$ i over 2 $:$ rho $
$ lambda sub 2:0 :$ x + y over 2 $
.TE
Output:

1
<01

i
"2""
i

aXi

9 1=<03

i
"2""

x+f

1t2

6-24

NUX Text Processing Tools

Figure 6-8. Table using horizontal lines in place of data

Input:
.TS
center tab(#) delim $$
c c c I c .
$P$#$Q$#$R$#$P - cap -

wig Q - cup - R )$

T#T#T#T
T#T#F#F
T#F#T#T
T#F#F#T
F#T#T#F
.TE
p

T
T
T
T
F

tbl. Reference

Q
T
T
F
F
T

P n(-Q uR)

T
F
T
F
T

T
F
T
T
F

6-25

Figure 6-9. Table showing the versatility of the tbl program
Input:

.TS
center tab ( : )
1 c c c 1
1 c c c 1
1
c I c I c I 1
1 c c c 1
1 c c c 1
1 c c c 1
c I 1
1
c I c
1 c c c 1
: \ (da : : \ (da

·· ..
.. ..

:lex: :yacc:

·· ..
.. ..

: \ (da : : \ (da

·· .. .

Input \ (->:yylex:\ (->:yyparse:\ (-> Output

·· ..
.. ..
. TE

Output:
lex

Input

6-26

yylex

yacc
~

yyparse

Output

AlUX Text Processing Tools

Figure 6-10. Table showing font changes

Input:
.TS
center box tab (:)
cB
I cB I cB
cfl I cf3 I cf2 .
Roman:Bold:ltalic

e
e
.TE

Output:
Roman
a
b
c
d
e

tbl Reference

Bold
a
b
c
d
e

Italic
a
b
c

6-27

Chapter 7
eqn Reference

Contents
1. eqn: a mathematics formatting program.

•

2. Using eqn
• • • • •
2.1 Command line syntax
2.2 Using eqn with other A/UX preprocessors
2.3 Greek letters and mathematical symbols •
2.4 Additional symbols • • • • • . • .
2.4.1 Using /usr/pub/eqnchar .
2.5 Command delimiters •
2.6 Displayed equations •
2.7 In-line equations

•

1
1
2
2
4
4
5
5
6

3. Specifying equations
3.1 How spaces are interpreted during input •
3.2 Special characters force output spacing
3.3 Using quotes
.••••
3.4 Combining items with braces • • • •
3.5 Equation labels

7
8
8
8
9
10

4. Entering equations
4.1 Subscripts and superscripts
4.2 Fractions
4.3 Square roots
4.4 Items with limits
4.5 Diacritical marks
4.6 Oversized brackets
4.7 Piling objects .
4.8 Matrixes

11
11
12
12
13
13
14
15
16

5. Precedence rules • .

6. Definitions

-i-

7. Equation alignment • • • •
7.1 Controlling local motions

• •

20
21

8. Changing the size and shape of fonts •
8.1 Local changes • . • . • •
8.2 Global changes
•••••

21
21
23

9. Debugging eqn • • • • •
9.1 Error conditions
9.2 The checkeq program •

23
23
24

•

Tables
Table 7-1. Standard mathematical characters

Table 7-2. Greek alphabet • • • •

Table 7-3. Additional character set

- ii -

Chapter 7
eqn Reference

1. eqn: a mathematics formatting program
The eqn program is a mathematical equation formatting preprocessor
for troff and nroff. It was designed to be easy to learn and use.
Its language has few rules, and even fewer exceptions, and can be
learned very quickly. It interfaces directly with troft, so
mathematical expressions can be embedded in the running text of a
manuscript, and the entire document can be produced in one process.
Typical mathematical expressions require point size and font changes,
positioning, line drawing, and other functions to print according to
mathematical conventions. In the eqn program these are done
automatically; eqn converts mathematical input into trotf
commands and the resulting output is passed directly to the formatter
for further processing.
This chapter shows you how to use eqn. Examples are provided to
illustrate its syntax and rules of grammar. Study these examples and in
a very short time you should be able to produce typeset-quality
mathematical text.

2. Using eqn
eqn needs no special keys to enter even the most complicated
equations. Subscripts and superscripts are printed automatically in the
appropriate size and font. Fraction bars are made the right length and
positioned at the correct height. Output may be produced either on a
typesetter, a laser printer, or on a terminal with forward and reverse
half-line motions.

2.1 Command line syntax
To produce typeset-quality mathematical text, use the following
command:
eqn file

I traff

eqn Reference

7-1

Any troff options (such as rom) are located following the troff
formatter part of the command:
eqn file I troff -rom
An nroff-compatible version of eqn (neqn(l)) can be used with
hardcopy terminals that have half-line forward and reverse capabilities.
The input language is identical, but some things will not look as good
because these terminals do not provide the same variety of characters,
sizes, and fonts. However, the output is usually adequate for
proofreading.
To print equations on one of these devices, use the command
neqn file I nroff
or
neqn file I nroff -Tx
where x is the terminal type being used.

2.2 Using eqn with other A/UX preprocessors
When eqn operates on the same file as the other A/UX preprocessors,
pic and tbl (see Chapter 8, "pic Reference" and Chapter 6, "tbl
Reference"), pic should be called first:
pic fik

I tbl I eqn I troff

If only eqn and tbl are present, tbl precedes eqn:

tblfile I eqn I troff

eqn produces a larger expansion of output than tbl, and it is faster
and more efficient to produce the table first and the equation last. The
order is optional, however, unless there are equations within tables, in
which case tbl must be called before eqn or the output will be
unreadable.

2.3 Greek letters and mathematical symbols
eqn knows the Greek alphabet and most mathematical symbols and
mathematical names. For example, the input

7-2

NUX Text Processing Tools

.EQ
size +2
{e sup {i delta t}}
.EN

produces the output
ei 01

Braces can also occur within braces if necessary. For example, the
statement
.EQ
size +4
{e sup {i pi sup {rho +1}}}
.EN

generates

e i 1tP+

Each string of characters (delimited by spaces, tildes, carets, or tabs) is
compared with a symbol table. If it finds the string contained there, it
substitutes the troff translation of that string. Digits, parentheses,
brackets, punctuation marks, and the following mathematical words are
converted to roman font:
sin
lim
1m

cos
log
and

tan

In
if

arc
exp
for

max
Re
det

min

Other strings are converted to italic font. In the previous example, pi
and rho become their Greek equivalents (n and p). Parentheses,
digits, and operators are also produced in roman font.
A common error is to type f (pi) without leaving spaces on both sides
of the pi. Without spaces, eqn does not recognize pi as a special
word, and it appears as f (Pi) in the output instead of f (n).
The only way eqn can deduce that some sequence of letters is special
is if that sequence is separated from the letters on either side of it. This
can be done by surrounding a special word by ordinary space, tab, or
newline characters. Special words can also be emphasized by
surrounding them with tildes or carets. The following:

eqn Reference

7-3

.EQ
x-=-2-pi-int-sin-(-omega-t-)
.EN
is much the same as the previous example, except tildes separate words
like sin, omega, and so forth, and also add an extra space in the
output per tilde. The output of this example is

x = 2 1t sin ( OJ t )
Tables 7-1 and 7-2 at the end of this chapter provide a complete list of
the mathematical characters recognized by eqn.

2.4 Additional symbols
Four-character troff names can also be used to specify any
characters eqn does not recognize; for example, \ (pI for the + sign
and \ (mi for the - sign. (See Chapter 3, "nroff /troff
Reference" for a complete list of t ro f f character codes.)
Additionally, the file /usr/pub/eqnchar contains nroff and
troff definitions of several more mathematical symbols. (See Table
7-3 at the end of this chapter.) These definitions must be enclosed
within eqn delimiters in order to be processed correctly.
For users who are experienced with troff motion commands and
string definitions, almost any mathematical character can be defined.
Studying the definitions contained in usr /pub/ eqnchar will give
you a good idea of how this is done (see eqncha r(5) in A/UX
Programmer's Reference).

Note: When you are making your own character definitions, it
is easier if you use a line gauge from a graphics supply store to
gauge the appropriate size changes and vertical and horizontal
troff motions.

2.4.1 Using /usr/pub/eqnchar
To process a document containing the extended mathematical set
(/usr/pub/eqnchar), you must include this file in your command:
eqn /usr/pub/eqnchar file I troff

7-4

A/UX Text Processing Tools

Or, if you have also included tables in your text:
tbl /usr /pub/ eqnchar file I eqn I troff

You may substitute neqn and/or nroff in both of these commands if
your output device requires it.

2.5 Command delimiters
Mathematical expressions are entered by beginning and ending each
equation with the delimiters . EQ and . EN as follows:
.EQ

equation-specifications
.EN

2.6 Displayed equations
A displayed equation is printed as a block, preceded and followed by
half a vertical space (one blank line). It is specified with the rom display
macro:
.DS
.EQ

equation-specifications
.EN
.DE
By default, a displayed equation using rom is left adjusted. Placement
options (centered, indented, or right) are provided, however, that
override these defaults. (See Chapter 4, "rom Reference," for a full
discussion of the display macros.)
For example, when using rom, the input
.DS I
.EQ
x = f
.EN
.DE

( y over 2 ) + y over 2

produces an indented equation

x =f(-r)+-!

eqn Reference

7-5

A centered equation can be produced with the following input:
.DS C
.EQ
x sub i

Y sub i

.EN

.DE

The resulting equation will be centered on the page:
Xi=Yi

If you are not using a macro package to format your document, you can
still manipulate the placement of equations within text. To obtain a
centered equation in a document without using ms or mm, enter the
following:
.ce
.EQ
x sub i

= Y sub i

.EN

2.7 In-line equations
An in-line equation is printed within the text of your document. Like a
displayed equation, it must be enclosed in delimiters, but instead of the
• EQ/ . EN sequence, you define a character to be the delimiter.
The most common character chosen to delimit in-line equations is the
dollar sign ($), which is defined at the beginning of the text file by
entering the following:
.EQ
delim$$
.EN

These characters are then recognized by eqn in the subsequent text as
delimiters and any text between them will be treated as an equation.
For example, the input
This is an example of an in-line equation
$ x sub y + Y = z $ using delimiters.

would send this as output:

7-6

A/UX Text Processing Tools

This is an example of an in-line
equation Xy +y =z using delimiters.
Producing something like y-ray is easy using the in-line equation,

$ gamma $-ray
eqn will try to keep the text betwccn the delimiters on one line, but if
the equation is very long, troff will break it based on the spacing of
characters, not mathematical logic. This can produce awkward and
inaccurate spacing, but you can prevent this by dividing the in-line
equation into sections:

$ x + Y

$ $

( c sub d ) $ $ + pi $

To tum off the delimiters so the selected character can be used as text,
enter the following into your file:
.EQ

delim off
.EN

Thereafter, eqn will no longer recognize the delimiter symbol.
The following should be observed when using the in-line equation
format:
• Do not use braces, tildes, carets, or double quotes as delimiters as
these have special significance to the . EQ and . EN macros .
• troff font changes must be closed before in-line equations are

encountered.

3. Specifying equations
An equation is specified by numeric items and mathematical operators.
Each of these components must be separated from the others according
to specific item separation conventions. For example, in the expression

~
which was produced with the notation

sqrt 5 sup 2
sqrt and sup serve as operators and the spaces between these
keywords and the arguments are item separators.

eqn Reference

7-7

3.1 How spaces are interpreted during input
Spaces and newline characters are used by eqn to separate pieces of
input; they do not create space in the output. For example, the input

.EQ
x

+ z + 1
.EN
produces the output

x=y+z+l
Each distinct entity within eqn must be delimited by blank spaces. If
items are not separated properly, eqn will interpret the expression
incorrectly.

3.2 Special characters force output spacing
Varying amounts of blank space can be forced into the output by
several characters:
• A tilde ( - ) gives a space equal to the normal word spacing in
text.
• A caret C) gives a half-space.
• A tab character spaces to the next tab stop (tab stops must be set
by troff commands).
Tildes, carets, and tabs also serve to delimit pieces of input. In these
cases, blank spaces are optional. For example, the input

.EQ
x - = - y - + - z
.EN
produces the output

x =y +z

3.3 Using quotes
Enclosing a string of characters in double quotes (n ... n) prevents eqn
from interpreting any special meaning the string might ordinarily have.
For example, to produce the expression

7-8

A/UX Text Processing Tools

sqrt~
1t
enter the following:
.EQ
"sqrt" 25 over pi
.EN

Omitting the quotes results in

-../25
1t

Quotes are used to force the printing of braces and certain eqn
keywords that wouldn't normally be printed. For example, the input
.EQ
"{ alpha is the name for "-alpha" }"
.EN

prints

{ alpha is the name for a}
The "" construction is often used as a place-holder (or null item) when
eqn requires something to satisfy its rules of grammar but when
nothing is actually wanted in the output.
For instance, eqn does not accept unmatched brackets, braces, or
parentheses. However, the input
.EQ
left ""
x over y
right }
.EN

permits you to obtain only a right brace:

3.4 Combining items with braces
Braces ({ }) are used to keep multiple objects together in unambiguous
groups. eqn interprets the items within a set of braces before applying

eqn Reference

7-9

the next mathematical function.
The end of a subscript or superscript is marked by a space, tilde, caret,
or tab. If the subscript or superscript specification requires spaces
within it, braces are used to mark the beginning and end. For example,
the input
.EQ
size +2
{e sup {i delta t}}
.EN

produces the output
ei Ot

Braces can also occur within braces if necessary. For example, the
statement
.EQ
size +4
{e sup {i pi sup {rho +l}}}
.EN

generates

e i 1tP+

A general rule is that a complicated string enclosed in braces can be
used in place of a single character (such as x). The eqn program
administers the appropriate formatting commands. In all cases,
complete pairs of braces must be used (unless the null item
specification is employed). Omitting one or adding an extra one
produces an error.

3.5 Equation labels
An equation label is specified as an argument to the equation start
delimiter ( . EQ):
.EQ 1.5e
a + b + e over abe
.EN

7-10

sqrt 25

NUX Text Processing Tools

The equation label is printed in the right margin:

e _1a+b+-:::-r:-:-="25
aue

1.5c

4. Entering equations
4.1 Subscripts and superscripts
Subscripts and superscripts are specified with the operators sub and
sup. The words sub and sup must be surrounded by spaces. For
example, this specification:
.EQ
x sup 2 + y sub k
.EN

produces the following expression:
X

+Yk

The eqn program makes the necessary point size changes and vertical
motion adjustments and automatically returns to the original base line.
Either a space or tilde marks the end of a subscript or superscript.
Multiple levels of subscripts or superscripts are permitted, such as
subscripted subscripts and superscripted superscripts. If the subscript
follows the superscript, the items are grouped to the right as in the
expression:

x Yz
produced with the input
.EQ
size +2
{x sup y sub z}
.EN

However, if the subscript precedes the superscript:
.EQ
x sub z sup y
.EN

the items are printed one above the other:

eqn Reference

7-11

xl
4.2 Fractions
Fractions are specified with the operator over. For example. the input

.EQ
a+b over c+d+e
.EN

produces

a+b
c+d+e 1
The division line is positioned and made the correct length
automaticall y.
When there is both a fraction and a superscript in the same expression.
eqn produces the superscript first. For example. the specification

.EQ
-b sup 2 over pi
.EN
produces

-b 2
1t

4.3 Sq uare roots
The square root symbol is produced by the operator sqrt. For
example. the input

.EQ
sqrt 25
.EN
draws the simple expression

ffi
With the more complicated

.EQ
x = {-b +- sqrt{b sup 2 -4ac}} over 2a
.EN

7-12

AlUX Text Processing Tools

eqn produces

x -b±~b2-4ac

2ll
4.4 Items with limits
Summations, integrals, and similar constructions are specified with the
operators from and to.
Either from or to can be omitted, but if both are present, they must
occur in that order. For example, the input
.EQ
sum from i=O to {i = inf} x sup i
.EN
produces

The second item (i = in f) is enclosed in braces because it contains
spaces. Braces are not necessary for the lower part (i=O), however,
because it contains no spaces.
Other useful keywords that can replace the sum in the above example:
prod
union
min
inter

int
max
lim

Because characters before the from can be anything, the from - to
construction can often be used in unexpected ways. The input
.EQ
lim from {n -> inf} x sub n =0
.EN
produces the output
limx,,=O

,,~

4.5 Diacritical marks
Diacritics are produced with the following keywords:

eqn Reference

7-13

x
x
x
x
x
x
x
x

dot
dotdot
hat
tilde
vec
dyad
bar
under

x
x
i

Y
~

An example of an expression using diacritical marks is
.EQ
x dot under + x hat + y dotdot
+ X hat + Y dotdot = z+Z bar
.EN

which will send as output

i:+i+)i+X +Y=z+Z

4.6 Oversized brackets
To produce large brackets [ ], braces { },parentheses ( ), vertical
bars I I , floors L J and ceilings 1 that surround information that
spans more than one line, use the keywords left and right:

.EQ
left { a over b + 1 right
= left
cover d right )
+ left
e right ]
.EN

This produces

{%+1 }=[ %]+[ e 1
and the input
.EQ
left floor x over y
right floor
<= left ceiling a over b -- right ceiling
.EN

produces

7-14

AlUX Text Processing Tools

The resulting brackets are made large enough to cover whatever they
enclose.
A right keyword cannot exist without a corresponding left. If the
expression requires that the left be omitted, use the paired double quote
null construction:

.EQ
left " " ... right )
.EN
The left " "means a left "nothing," which satisfies the rules
without hurting the output.

4.7 Piling objects
Large braces, brackets, parentheses, and vertical bars are often used
with another facility that makes vertical piles of objects. It is specified
by the operator pile. Elements of the pile (there can be any number)
are centered one above another, at the right height for most purposes.
The keyword above is used to separate the components; braces must
surround the entire list. Elements of a pile can be as complicated as
needed, even containing nested piles.
Three other forms of pile exist:
• lpile makes a left adjusted pile.
• rpile makes a right adjusted pile.
• cpile makes a centered pile, just like pile.

Vertical spacing between pieces is somewhat larger for Ipile,
rpile, and cpile than it is for ordinary piles. For example, to get

enter

1 if x>O
0 if x=O
-1 if xO above x=O above x / dev /null

This discards the output but prints the appropriate messages on your
terminal screen.

9.2 The checkeq program
The checkeq program checks for misplaced or missing delimiters.
You run it with the following command:
checkeq file

Output from checkeq is written to the standard output, or can be
redirected to a file as follows:
checkeq file > output file

7-24

NUX Text Processing Tools

Table 7·1. Standard mathematical characters

Input
> =
< =

Output

= =
! =
+ - >
< < <
> >

inf
partial
half
prime
approx
nothing
cdot
times
del
grad
dollar

"1=

±
~
~

«
»
00

::::

x
~

...

...
, ... ,

, ... ,

sum

int

J
n

prod
union
inter

eqn Reference

U
(l

7-25

Table 7-2. Greek alphabet

Input
alpha
beta
gamma
delta
epsilon
zeta
eta
theta
iota
kappa
lambda
mu
nu
xi
omicron
pi
rho
sigma
tau
upsilon
phi
chi
psi
omega

Output
ex
~
y

e
~

e
t

A11
V

~
0
1t

p
cr
't
U

X
'V
0)

Input
ALPHA
BETA
GAMMA
DELTA
EPSILON
ZETA
ETA
THETA
IOTA
KAPPA
LAMBDA
MU
NU
XI
OMICRON
PI
RHO
SIGMA
TAU
UPSILON
PHI
CHI
PSI
OMEGA

Output
ALPHA
BETA

r
b.
E
ZETA
ETA

IOTA
KAPPA
A
MU
NU
~

OMICRON
IT

RHO
L
TAU
Y

CHI
'l'

Note: As shown in Table 7-2, several uppercase Greek letters
are not provided in the eqn package. These uppercase Greek
letters may be produced using troff codes. See the
Reference tables in Chapter 3, "nroff/troff Reference."

7-26

AJUX Text Processing Tools

Table 7-3. Additional character set

Input
circle
ciplus
citimes
3quarter
quarter
<->
<=>
=del
hbar
ppd
prop
ang
angstrom
square
blot
bullet
empty
thf
-wig
>wig

eqn Reference

Output
0
El3
®
%
~
~

¢:::>

~
"Ii
~
ex:

A
0

••

0
"

::::::

Input
3dot
incl
langle
rangle
member
nomem
oppA
oppE
cup
cap
subset
!subset
supset
!supset
bigstar
star
degree
wig
=wig
, < - >, text

line/arrow

up, down, left, right,
height, width, from, to, by,
then, dotted, dashed, invis,
same, <-, ->, <->, text

spline

up, down, left, right,
height, width, from, to, by,
then, invis, same, <-, ->,
<->, text

move

up, down, left, right, to,
by, same, text

The keyword at places the geometrical center of an object in a
specified place.

8-6

NUX Text Processing Tools

An object can be made invisible with the keyword invisible (or
invis). This is particularly useful for positioning objects correctly
near text.
For lines, splines and arcs, height and width refer to arrowhead
size. The width of an arrowhead is the distance across its tail; the
height is the distance along the shaft. The arrowheads in this picture
are default size:

This was produced with the following code:

pic Reference

8-7

.PS

box invis height 3i wid 4i
A: circle at 0,1 "\f7/\f1 n
B: circle at -1.5,0 n\f7bin\f1 n
C: circle at -0.5,0 n\f7etc\f1 n
D: circle at 0.5,0 n\f7tmp\f1 n
E: circle at 1.5,0 n\f7usr\f1 n
F: circle at -1,-1 n\f7f1\f1 n
G: circle at 0,-1 n\f7f2\f1"
arrow from A.s to B.n
arrow from A.s to C.n
arrow from A.s to D.n
arrow from A.s to E.n
arrow from C.s to F.n
arrow from C.s to G.n
.PE
See "Blocks" for an explanation of the letters capitalized in this code.
Dimensions are divided by scale during output. pic works
internally in what it thinks are inches. Setting the variable scale to
some value causes all dimensions to be scaled down by that value; for
example,
scale = 2.54
causes dimensions to be interpreted as centimeters.

4.1.2 Object variables
A variable consists of a keyword, which mayor may not be followed
by a value. Keywords are used to redefine object dimensions globally.
Missing variables and values are filled in from defaults. Not all
variables apply to all primitives; those which don't are ignored.
The variables and their defaults are shown in the following table:

8-8

A/UX Text Processing Tools

Object
box

Variable
boxwid
boxht

Default
0.75 in.
0.50 in.

Description
box width
box height

circle

circlerad

0.25 in.

circle radius

ellipse

ellipsewid
ellipseht

0.75 in.
0.50 in.

ellipse width
ellipse height

line or
arrow

linewid
lineht

0.50 in.
0.50 in.

line or arrow width
line or arrow height

arc

arcrad

0.25 in.

arc radius

arrowhead

arrowht
arrowwid
arrowhead

0.10 in.
0.05 in.
2

arrowhead height
arrowhead width
arrowhead style (filled)

dash

dashwid

0.10 in.

width of dashes or dots

move

movewid
moveht

0.50 in.
0.50 in.

width of horizontal move
height of vertical move

These may be changed at any time, and the new values will remain in
force until changed again (see "Object Sizes: Changing the
Defaults").

5. Object sizes: changing the defaults
Figures are normally drawn at a fixed scale with objects of a standard
size. It is possible, however, to expand a figure to fit a particular width.
If the . P S line contains a number the drawing is forced to be that many
inches wide, with the height scaled proportionately. For example,
.PS 3.5i
causes the picture to be 3.5 inches wide.
The number given as a width in the . P S line overrides the dimensions
given in the picture; this can be used to force a picture to a particular
size even when coordinates have been given in inches. Experience
indicates that the easiest way to get a picture of the right size is to enter
its dimensions in inches, then if necessary add a width to the . P S line.

pic Reference

8-9

You can make any object any size you want. For example, using
object attributes for width and height, the input
/

box width 3i height O.li

draws a long, flat box 3 inches wide and 1/10 inch high:

Note: This specification changes the width and height of only
that particular occurrence of the object.
All positions and dimensions are assumed to be in inches; specifying
the" i" is optional. However, if the" i" is present, there should be
no spaces between it and the number it follows.
The default size of an object can be changed by assigning values to the
object variables. So if you want all your boxes to be long and skinny,
and relatively close together, enter
boxwid = O.li; boxht = Ii
movewid = O. 2i
box; move; box; move; box

This produces

In all cases, unless an explicit dimension for some object is specified,
you will get the default size. If you want an object to have the same
size as the previous one of that kind, use the keyword same. In the set
of boxes produced by this specification:
down; box ht O.2i wid 1.Si; move down O.lSi;
box same; move same; box same

8-10

AJUX Text Processing Tools

(

the dimensions set by the first box are used several times; similarly,
the amount of motion for the second move is the same as for the first
one.

6. Adding text to your picture
Text is normally an attribute of some primitive; by default it is placed
at the geometric center of an object. Each line of text is entered as a
separate quoted string. Quotes are mandatory, even if the text contains
no blanks. Each line is printed in the current point size and font,
centered horizontally, and separated vertically by the current t ro f f
line spacing value.
If there are multiple text items for some primitive, they are centered
vertically except as qualified. Positioning requests apply to each item
independently; for example,
.PS
box "this is" "a box"
.PE

creates a standard box and centers the two pieces of text in it:
this is
a box
Text items can contain troff commands for size and font changes,
local motions, and so on, but make sure that these are balanced so that
the entering state is restored before exiting from the string.
A text item is a quoted string optionally followed by a positioning
request:

pic Reference

8-11

" text"
"text"
" text"
" text"
"text"

center
ljust
rjust
above
below

The attribute 1 j us t positions the left end at the specified point, and
r just positions the right end at that position. above and below
center the text one half-line space in the given direction.
Text is most often an attribute of some other object, but self-standing
text can also be specified:

"this is some text" at 1,2 ljust
Text is centered on lines and arrows; if there is more than one line of
text, the lines are centered above and below:

belo~
above

belo~

above

---:........

top f}{

above
top f}{
below

These were produced with the following specifications:
.PS

arrow
arrow
arrow
arrow
arrow

"below"
"above"
"on top
"above"
"above"

below; move
above; move
of"; move
"below"; move
"on top of" "below"

.PE

7. Object positioning
A position is ultimately an x,y coordinate pair, and you may specify a
position in this way. But a position can be specified in other ways: you
may position an object in relation to a part of some other object with
the move and move to commands, or by using a label embedded in a
grouped object. These are discussed in "Using Coordinates."

8-12

NUX Text Processing Tools

7.1 Using coordinates
pic uses a standard Cartesian coordinate system, so any point or
object has an x and y position. The first object is placed with its start at
position 0,0 by default. The x,y position of a box, circle, or ellipse is its
geometrical center; the position of a line or motion is its beginning; the
position of an arc is the center of the corresponding circle.
Position modifiers such as from, to, by, and at are followed by an
x,y pair, and can be attached to boxes, circles, lines, motions, and so
forth, to specify or modify a position; for example,

................

····

...
. _-----------

...

is produced by the input

.PS

box dotted
line dashed to 2,0
.PE

You can also use up, down, right, and left with line and move:

.PS 2

box ht 0.2 wid 0.2 at 0,0 "1"
move to 0.5,0
box "2" same
move same
box "3" same
.PE

to draw three boxes, like this:

Note the use of same to repeat the previous dimensions instead of
reverting to the default values.
Attributes such as ht and wid and positions like at can be written in
any order:

pic Reference

8-13

box ht 0.2 wid 0.2 at 0,0
box at 0,0 wid 0.2 ht 0.2
box ht 0.2 at 0,0 wid 0.2

These are equivalent, although the last is harder to read and therefore
less desirable.
The from and to attributes are particularly useful with arcs, to specify
the endpoints. For example, these arcs:

were produced with the following specifications (respectively):
arc from O.Si,O to O,O.Si
arc from O,O.Si to O.Si,O

(

If the f rom attribute is omitted, the arc starts at the current position
and goes to the point indicated by to. The radius can be made large to

provide flat arcs:
arc -> cw from 0,0 to 2i,0 rad lSi

This produces

Notice that to put an arrowhead on an arc, you can use <-, ->, or <->
as an attribute.

7.2 Using corners
To cut down the need for explicit coordinates, most objects have
"comers" named by compass points:

8-14

AlUX Text Processing Tools

B. n w . - - - -B.n
- - - - - - - , B .ne

B.w

B.c

B.e

B.sw '-----""'='B,----------I B.se
.s
The primary compass points may also be written as . r, . b, . 1, and
. t, for right, bottom, left, and top. The box above was
produced with these specifications:
.PS 1.5
B: box "B.c"
" B.e" at B.e ljust
" B.ne" at B.ne ljust
" B.se" at B.se ljust
"B.s" at B.s below
"B.n" at B.n above
"B.sw " at B.sw rjust
"B.w " at B.w rjust
"B.nw " at B.nw rjust
.PE
Note the use of ljust, rjust, above, and below to alter the
default positioning of text, and of a blank: with some strings to help
space them away from a vertical line.
Lines and arrows have a start, an end, and a center in addition to
comers. (Arcs have only a center, a start, and an end.) There are many
ways to indicate the comers of an object Besides the compass points,
almost any sensible combination of left, right, top, bottom,
uppe r, and lowe r will work. Furthermore, if you don't like the "."
notation, as in:

last box.ne
you can instead say

upper right of last box
It is sometimes easiest to position objects by positioning some part of
one at some part of another, for example the northwest comer of one at

pic Reference

8-15

the southeast comer of another. The with attribute in pic permits
this kind of positioning; for example,
box ht O.7Si wid O.7Si
box ht O.Si wid O.Si with .sw at last box.se

produces

Notice that the comer after with is written. sw.
As another example, consider:
ellipse; ellipse with .nw at last ellipse.se

which produces

7.3 Object labels
Objects can be labeled or named for future reference; for example,
.PS

Boxl:
box

:# •.• other stuff . ..
move to Boxl
.PE

Place names have to begin with uppercase letters to distinguish them
from variables which begin with lowercase letters. The name refers to
the "center" of the object, which is the geometric center for most
objects. For lines and motions, it refers to the beginning point.

8-16

AlUX Text Processing Tools

Other combinations also work:

line
move
move
line

from Box1 to Box2
to Box1 up 0.1 right 0.2
to Box1 + 0.2,0.1
to Box1 - 0.5,0

The reserved name He re may be used to record the current position of
some object; for example,

Box1: Here
Labels are variables; they can be reset several times in a single picture,
so a line of the form

Box1: Box1 + 1i,li
is perfectly legal.
You can also refer to previously drawn objects of each type, using the
word last. For example, given the input

box "A"; circle "B"; box "e"
last box refers to box C, last circle refers to circle B, and
2nd last box refers to box A. Numbering of objects can also be
done from the beginning, so boxes A and C are 1st box and 2nd
box respectively.

7.4 Positioning with move
If you want to leave a space at some designated place, use move:

box; move; box; move; box
This produces

DDD

7.5 Positioning with variables

It's generally a bad idea to write everything in absolute coordinates if
you are likely to change things. pic variables let you set parameters
for your picture:

pic Reference

8-17

a = 0.5; b = 1
box wid a ht b
ellipse wid a/2 ht 1.S*b
move to Boxl - (a/2, b/2)
Expressions use the standard operators +, -, *, /, and %; pic uses
parentheses, ( ), for grouping.
Probably the most important variables are those that are predefined for
controlling the default sizes of objects. These may be set at any time in
any picture, and retain their values until reset.
You can use the height, width, radius, and x and y coordinates of any
object or comer in an expression:
Boxl. x

the x coordinate of Boxl

Boxl . ne . y

the y coordinate of the
northeast comer of Box 1

Boxl. wid

the width of Boxl

Boxl . ht

the height of Boxl

2nd last circle. rad

the radius of the 2nd last
circle

Any pair of expressions enclosed in parentheses defines a position;
furthermore such positions can be added or subtracted to yield new
positions. If (PI ,P2) are positions, then (PI.X ,P2.Y) refers to the
point.

8. Grouping objects
Objects are connected in the direction specified by the most recent up,
down, left, or right (either alone or as part of some object), with
the entry point of the second object attached to the exit point of the
first; for example,
arrow left ; box; arrow; circle; arrow

produces

8-18

AlUX Text Processing Tools

left indicates connection toward the left. This could also be written
as:
left; arrow; box; arrow; circle; arrow

Entry and exit points for boxes, circles, and ellipses are on opposite
sides and at the start and end of lines, motions, and arcs.
By default, arcs are drawn 90 degrees counterclockwise from the
current position. To change the direction to clockwise, use this
command:
arc cw

For example, this specification:
line; arc; arc cw; arrow

produces

_f
Lines and arrows are easily drawn by specifying amount of motion and
direction. Accordingly, the words up, down, left, and right and
an optional distance can be attached to line, arrow, and move. For
example,
.PS
line up li right 2i
arrow left 2i
move left O.li
line <-> down li "height"
.PE

draws

pic Reference

8-19

The notation <- > indicates a two-headed arrow; use - > for a head on
the end and <- for one on the start. Lines and arrows are really the
same thing; in fact, arrow is a synonym for" line ->".

If you don't put any distance after up, down, and so on, pic uses the
standard distance:
line
line
line
line

up right
down
down left
up

draws a parallelogram

If a set of commands is enclosed in braces ( ... }, the current position
and direction of motion when the group is finished will be exactly
where they were when entered. Nothing else is restored.

Note: There is also a more general way to group objects, using
brackets (see "Blocks").
Although objects are normally connected left to right, this can be
changed. If you specify a direction as a separate object, subsequent
objects will be joined in that direction. Thus:

8-20

A/UX Text Processing Tools

down; ellipse; arrow; circle

produces

and
left; box; arrow; ellipse; arrow; circle

produces

A line may actually be a path; that is, it may consist of segments
connected in a direction like this:

This line was produced by
line right Ii then down .5i left Ii\
then right Ii

The elements of a path, whether for line or spline, are specified as a
series of points, either in absolute terms or by up, down, and so forth.
If necessary to disambiguate, the word then can be used to separate
components, as in

pic Reference

8-21

line right then up then left then up
This produces

and is not the same as
line right up left up
which produces

8.1 Blocks
Any sequence of pic statements may be enclosed in brackets [ ...J to
form a block, which is then treated as a single object and manipulated
like an ordinary box. For example, the code
box "1"
[ box "2"; arrow "3" above; box "4" ] \
with .n at last box.s - (0,0.1)
"thing" at last [].s
produces the following picture:

8-22

AlUX Text Processing Tools

o
2

Ith:J

Notice that last-type constructs treat blocks as a unit and don't look
inside for objects: last box. s refers to box 1, not box 2 or 4. You
can use last [ ], and so on,just like last box.
Blocks have the same compass corners as boxes (determined by the
bounding box). You can position a block by placing either an absolute
coordinate (like 0 , 0) or an internal label (like A) at some external
point, as in
[ •.• ;

••• ;

.•.

]

with .'A at . . .

Blocks join with other objects at the center of the appropriate side.
Names of variables and places within a block are local to that block,
and thus do not affect variables and places of the same name outside.
You can get at the internal place names with constructs like this:
last [].A
or:
B.A
where
B

B
:

is a name attached to a block like so:
[

•..

;

... ;

]

When combined with define statements (see "Macros"), blocks
provide a reasonable simulation of a procedure mechanism.
Even though blocks may occur inside of other blocks, you can look
only one level deep with qualifiers such as B • A. The block A may be
further qualified so that specifications such as B • A. s w refer to the
southwest comer of the block named A which is inside block B.
For example, the object

pic Reference

8-23

r-------------,

I
I

is produced with these specifications:

lh
dh
dw

.5i
.02i
.li

Ptr:
boxht = h; boxwid
A: box
B: box
C: box
box wid 2*boxwid "
D: box

Block:
2*dw
boxht = 2*dw; boxwid
movewid = 2*dh
A: box; move
B: box; move
C: box; move
box invis " ... " wid 2*boxwid; move
D: box
with .t at Ptr.s - (O,h/2)
arrow from Ptr.A to Block.A.nw
arrow from Ptr.B to Block.B.nw
arrow from Ptr.C to Block.C.nw
arrow from Ptr.D to Block.D.nw
box dashed ht last [] .ht+dw wid last\
[] .wid+dw at last []

8-24

A/UX Text Processing Tools

8.2 The chop facility
Sometimes it is desirable to have a line intersect a circle at a point that
is not one of the eight compass points pic knows about. In such cases,
the proper visual effect can be obtained by using the attribute chop to
chop off part of the line:
circle "a"
circle "b" at
circle "c" at
line from 1st
line from 1st

1st circle - (O.75i,
1st circle + (O.75i,
circle to 2nd circle
circle to 3rd circle

Ii)
-Ii)
chop
chop

This produces

By default, the line is chopped by circlerad at each end. This can
be changed with the command:
line ... chop r
which chops both ends by r, and this specification:
line ... chop r1 chop r2
chops the beginning by r1 and the end by r2.
Another form of positioning refers to a point as a fraction of the way
between two other points:
fraction of the way between position1 and position2
fraction is any expression, and position1 and position2 are any
positions. You can abbreviate this:

pic Reference

8-25

fraction < positioni, position2 >
For example,

box
arrow right from 1/3 of the way\
between last box.ne and last box.se
arrow right from 2/3
produces

:
The distance given by fraction can be greater than 1 or less than O.

9. Macros
pic provides a rudimentary macro facility, the simple form of which is
identical to that in eqn:
de fine name X replacement-text X
This defines name to be the replacement-text; X is any character that
does not appear in the replacement. Any subsequent occurrence of
name will be replaced by replacement-text. Macros with arguments are
also available. The replacement text of a macro definition may contain
occurrences of $1 through $ 9; these will be replaced by the
corresponding actual arguments when the macro is invoked. The
invocation for a macro with arguments is

name (argi, arg2, ... )
Nonexistent arguments are replaced by null strings.
As an example, one might define a square:

define square X box ht $1 wid $1 $2 X
Then

square (Ii, "one" "inch")
calls for a 1 inch square with the obvious label, and

8-26

NUX Text Processing Tools

square (0. 5i)

calls for a square with no label:

1
inch

Coordinates like x,y may be enclosed in parentheses, as in (x, y) , so
they can be included in a macro argument.

10. Mathematical functions
pic provides a number of built-in arithmetic, trigonometric, and
random number functions. These are listed in the following table:

Function

Description

log (e)
sqrt (e)
int (e)
sin (e)
cos (e)
atan2 (eI,e2)
max (eI, e2)
min (eI, e2)
rand (e)

natural logarithm of expression e
square root of e
integral part of e
sine of e
cosine of e
arctangent of e Ile2
maximum of eland e 2
minimum of eland e 2
random number from 1 to e

The arguments to the trigonometric functions (sin, cos, atan2) are
assumed to be in radians. All other dimensions are assumed to be in
inches. Examples using these functions can be found in the next
section.

11. Loops and conditional statements
Newer versions of pic provide two very useful features: for loops
and conditionals with if. An example of the for loop is as follows:

pic Reference

8-27

.PS
for len=O to 2 by 0.1 do
X

line right len ; line up len
move left len ; move down len
move down 0.1
X

.PE

This will produce

(

The character X can be replaced by any other unique character; it
serves merely to delimit the statements that pic will loop through.
Also, the increment specifier by O. 1 may be omitted; if so, the
increment specifier defaults to 1.
You may execute pic commands conditionally by using the if
construction. The following example draws 15 boxes at random
locations; in addition, all boxes whose length exceeds the height are
dashed, while the rest are dotted:

8-28

NUX Text Processing Tools

.............................
...:.................. .
.
::
....
....
..
..
:: :::: rI - - - - - - - :
:. . -:- -:~
- - - -,
:

••••• I ................................. .

: ::

H"lTr"'!
~

.:.•• , .. :i

1
I

:::

I Ii

: ::

;:; .. ·~·jk:t~~~~~~~~~~:::: ~~::::: ~ -:-----:
:.:

: II·

-n.:. . . ::f~~;~~~~=~=~::~::~~~.;:;~~-~~~_r --~
:r·-:~t~r~~t:-;-;_~;_~_:;;;;;J~: -- ~ - ~

.: ••••••• :111: I I

L ______

This was specified as
.ps

for num

1 to 15 do

x = rand(50)/25
y = rand(50)/25
if ( x > y ) then
y

box dashed wid x ht y at x,y
y else Z

box dotted wid x ht y at x,y
Z

w
.PE

12. Expressions
Expressions in pic are evaluated in floating point. All numbers
representing dimensions are taken to be in inches.

pic Reference

8-29

expression:
e
e
e
e
e
-

+ e
- e
* e
/ e
% e (modulus)
e

(
I~

( e

variable
number

place
place
place
place

.x
.y
. ht
. wid

13. Examples
The figures in this section contain examples of complicated pic
specifications.

Figure 8-1. Space Pig

8-30

AJUX Text Processing Tools

Figure 8-2. Source code for "Space Pig"
.PS

.ps 100
A: circle radius 1 at 0,0
B: ellipse wid (0.75) height (0.50)\
with .n at (0,0.1)
c: circle radius (.075)\
with .e at B.c - (0.05,0)
D: circle radius (.075)\
with .w at B.c + (0.05,0)
line from (-.97,0.25) to (-.75,1.4)
line from (0.97,0.25) to (0.75,1.4)
line from (-.75,1.4) to (-.25,0.97)
line from (0.75,1.4) to (0.25,0.97)
define goggles\
@ [ up arc cw rad $1; line right $2;\
arc cw rad $1; \
arc cw rad $1; \
line left $2 ; \
arc cw rad $1 ] @
.ps 80
E: goggles(0.33, 0.93) with .s at B.n
.ps 40
F: goggles(0.26, 0.90) with .c at E.c
.ps 40
move to (-0.25,-0.675)
line right 0.5
.ps 10
.PE

pic Reference

8-31

Figure 8-3. Sine and cosine CUNes

(

8-32

AlUX Text Processing Tools

Figure 8-4. Source code for "Sine and cosine curves"
.PS
.ps -2
pi = atan2(0,-1)
for i = a to pi by 0.01 do
X

" " at i, sin (i)
" " at i, cos (i)

line from (0,-1) to (0,1)
line from (0,0) to (pi,O)
for i = a to pi by 0.05 do
y

line from (i, 0) to

(i, sin (i»

(0,. 03)

.ps +2
.PE

pic Reference

8-33

Figure 8-5. File system diagram

hashtab:

8-34

AlUX Text Processing Tools

Figure 8-6. Source code for "File system diagram"
.PS
boxht = .2i; boxwid = .3i
down; box; box; box; box ht 3*boxht n.n n." n."
L: box; box; box'invis wid 2*boxwid "hashtab:"\
with .e at 1st box .w
right
Start: box wid .5i\
with .sw at 1st box.ne + (.4i,.2i) " ... "
Nl: box wid .2i "nln; Dl: box wid .3i "dl"
N3: box wid .4i "n3"; D3: box wid .3i "d3"
box wid .4i "
"
N2: box wid .5i "n2"; D2: box wid .2i "d2"
arrow right from 2nd box
ndblock
spline -> right .2i from 3rd last
then to Nl.sw + (O.05i,O)
spline -> right .3i from 2nd last
then to Dl.sw + (O.05i,O)
arrow right from last box
ndblock
spline -> right .2i\
from 3rd last box\
to N2.sw-(O.05i, .2i)\
to N2.sw+(O.05i,O)
spline -> right .3i from 2nd last
to D2.sw-(O.05i, .2i)\
to D2.sw+(O.05i,O)
arrow right 2*linewid from L
ndblock
spline -> right .2i from 3rd last
to N3.sw + (O.05i,O)
spline -> right .3i from 2nd last
to D3.sw + (O.05i,O)

box\
box\

box\

box\
box\

.PE

pic Reference

8-35

Figure 8-7. Geometric shape

Figure 8-8. Source code for "geometric shape"
.PS

pi = 3.14159; n = 20; r = 1
s = 2*pi/n
for i = 1 to n-1 do
X

for j = 1+1 to n do
y

line from r*cos(s*i), r*sin(s*i)\
to r*cos (s*j), r*sin (s*j)
y
X

.PE

8-36

AlUX Text Processing Tools

Chapter 9
grap Reference

Contents
1. grap: a graph drawing program

2. Using grap.

3. Defining the graph format •

4. Specifying charts: default actions

5. Adjusting the frame

6. Adding text to a chart

7. Grids •

•

8. Using the shell

9. Macros
10. copy thru

11. Loops and conditionals

12. Plotting curves • • • •
12.1 Using polar coordinates
12.2 Equally scaled axes • •
12.3 Plotting curves from data points

14
17
23
25

13. Summary of grap syntax

Figures
Figure 9-1. A simple graph

Figure 9-2. A more complicated graph

-i-

Figure 9-3. The default graph

Figure 9-4. A better graph

Figure 9-5. A dotted frame

Figure 9-6. Adding grid lines •

Figure 9-7. Plotting a simple curve •

Figure 9-8. Shading part of a curve

Figure 9-9. Logarithmic and exponential
functions • • • • • • • • • •

Figure 9-10. Plotting a polar equation

Figure 9-11. A second polar equation

Figure 9-12. A grap circle

Figure 9-13. Equally scaled axes

Figure 9-14. Equally scaled axes without coord

Figure 9-15. Sample C program to generate data
points • • • • • • • • •

Figure 9-16. Plotting a curve from data points

- ii -

Chapter 9
qrap Reference

1. grap: a graph drawing program
grap is a language for describing graphs and charts that are included
in documents produced with troff. Figures 9-1 and 9-2 are simple
examples of the kind of output that you are able to produce using
grap.

Figure 9-1. A simple graph
sed

I
I

grap

I
I

p~c

Text
Processing
Programs

tbl
eqn
neqn
trot!
nroff

I
I
I
I

psd~t

I
I

50000

100000

Program size (bytes)
Figure 9-1 is a typical bar chart, depicting the relative sizes of some of
the A/UX text processing tools. Figure 9-2, on the other hand, is quite
a different kind of graph; it gives us a graph of the sine curve over one
cycle.

grap Reference

9-1

Figure 9-2. A more complicated graph

grap operates as a pic preprocessor, in the same way that pic
operates as a t ro f f preprocessor. Graphs are marked in the text by
enclosing their descriptions between. G1 and . G2 pairs. The grap
preprocessor translates these descriptions into the language understood
by pic, which must then be called to translate the grap output into
pure t ro f f commands.

This chapter is designed to acquaint you with grape The grap
keywords and commands are introduced largely through examples. A
complete reference list of grap syntax is given in the last section of
this chapter.

2. Using grap
grap is usually run with the command line
grap file I pic I troff -rom

If equations and tables are also present, you should run g rap and pic
before eqn and tbl.
grap file

I pic I tbl I eqn I troff -rom

There are two command-line arguments understood by grap:

-Ttype

9-2

Set the output device to type. Currently supported devices
are aps for the Autologic APS-5, and di10 for the
Imagen Imprint 10. The default device is apse In general,

A/UX Text Processing Tools

however, this argument can be omitted with no ill effects.
Do not include the file containing macro definitions,
/usr/1ib/dwb/grap. defines. By default, this file
is included whenever grap is called.

-1

3. Defining the graph format
A graph specification begins with a graph start command ( . G1) and
concludes with a graph end command (. G2). The. G1 and. G2 are
used by traff as command delimiters. The general format of grap
input is

.G1

chart-specifications
.G2

Individual commands must be separated by newlines or semicolons; a
long element may be continued by ending the line with a backslash (\).
Comments are introduced by a and terminated by a newline.
=11=

In addition to grap commands, the chart specification can also include
traff and pic commands. traff dot commands may be included
if they begin a new line; such commands are most useful for changing
point sizes in order to get thicker or thinner lines. Included pic
commands must be preceded by the keyword pic; this instructs grap
to ignore the rest of the line, passing it on to pic.

4. Specifying charts: default actions
The following table lists real and projected UNIX operating systembased hardware shipments for the years 1984 to 1990; as the table
heading indicates, dollar amounts are in billions of U.S. dollars and
units shipped are in thousands.

grap Reference

9-3

Year
1984
1985
1986
1987
1988
1989
1990

The UNIX market
Units shipped
Revenues
(billions)
(thousands)
127.1
5.3
161.3
6.5
205.0
7.9
265.0
9.5
340.0
11.3
414.0
13.9
485.0
16.8

The same data can be entered as a list of numbers using the simplest
grap specifications. For instance, the following input

.G1
1984 5.3
1985 6.5
1986 7.9
1987 9.5
1988 11.3
1989 13.9
1990 16.8
.G2

127.1
161.3
205.0
265.0
340.0
414.0
485.0

produces the graph in Figure 9-3.
This chart illustrates many of grap's default actions. First of all,
unless instructed otherwise, grap will plot the data in a frame that is
three inches wide and two inches tall. Also, grap automatically
supplies ticks indicating the ranges of the data points, drawing them
along the left and bottom sides. The ticks are arranged to leave a
margin of 7 percent on all sides of the graph. The default plotting tool
is the bullet. Finally, grap interprets the data in both the second and
third columns as belonging to the data in the first column, and (unless
told differently) interprets them in the same scale. So grap has plotted
the yearly system revenues in the same coordinate system as it used to
plot the number of units shipped.
Obviously, this chart could stand some improvement. One major
failing is the lack of text labeling the various axes and the data points.

9-4

NUX Text Processing Tools

Figure 9-3. The default graph

5004003002001000I

1984

1986

1988

1990

Also, the bullets look rather lonely plotting the data points. It would be
nice to do better, and grap provides numerous facilities to override
and supplement its default actions. All in all, the following chart
represents the original information much better:

Figure 9-4. A better graph
485.0

500

A/UX introduced:

400

300

12
Units Sold
(x 1000)

200

Revenues
(billion $)

•

100

2
O~~~~~~~~~~~~~r-~O

The UNIX Marketplace

grap Reference

9-5

The following sections provide the information necessary to turn
grap's default chart into this more elaborate chart.

5. Adjusting the frame
Every graph is surrounded by a frame (which may be invisible); this
determines the size of the graph. You can adjust the size of the frame
with the g rap command frame. For instance, the command
frame ht 3 wid 4
will set the height to three inches and the width to four inches. Because
grap ultimately translates its input into pic commands, the largest
graph is the largest possible pic drawing.
By default, the frame is drawn solid; this can be changed by adding an
attribute specifier to the frame command. For the moment, disregard
the second column of data. So you might have
.G1
frame
1984
1985
1986
1987
1988
1989
1990
.G2

9-6

dashed ht 2.5 wid 3.5
127.1
161.3
205.0
265.0
340.0
414.0
485.0

AlUX Text Processing Tools

Figure 9-5. A dotted frame

500-r---------------------------------,
I

I
I

400 -.JI
I

300-1I
I
I

I
I

200-1I
I

L-

r --------- T--------- 1 --------- 1 -

1984

1986

1988

1990

In addition to dashed, other available drawing attributes are dot ted,
invis, and solid.
You may also specify that only parts of the frame be drawn with a
specific attribute. For example, the following is very common:
frame ht 3 wid 4 top invis right invis

This will draw only the bottom and left sides.

6. Adding text to a chart
grap contains several ways to put text of various sorts into a chart.
You have already seen that grap automatically supplies ticks on the
bottom and left sides indicating the ranges of the data points. More
generally, text items can be placed in a chart with the plot command.
For example, the command
plot "A/UX introduced" rjust at 1987.5,300

will print the indicated text at the indicated point, right justified. The
default action is to center the text item at the specified point. Other

grap Reference

9-7

positional modifiers are ljust, above, and below. Strings in grap
are enclosed within double-quotes, as illustrated. Also, the word plot
is optional.
Labels can be added to any of the four sides of a chart using the
label command. For example,

label bottom "The 4gers' Season"
Multiple text strings are centered one above the others, as with pic. If
the default placement of the labels is not acceptable, the labels may be
shifted in any direction by adding a position modifier:

label bottom "The 4gers' Season" down .1
This will print the specified text, centered along the bottom of the chart,
bumped down one tenth of an inch. Instead of down, the text can also
be shifted up, left, or right.
Text items can contain troff commands for size and font changes,
local motions, and so on, but you should make sure that these are
balanced so that the entering state is restored before exiting from the
string. So, for example, you might have the following:

plot "\s12The \fB4gers'\fP Season\sO"

7. Grids
It is sometimes useful to add grid lines to a chart, to indicate that a
certain level has been achieved, to signal important events, or perhaps
just to make the chart easier to read. Grid lines are specified with the
command grid. For example,

9-8

NUX Text Processing Tools

.G1
frame ht 2.5 wid 3.5 top solid left solid
grid bottom dotted at 1987.5
plot "A/UX introduced" rjust at 1987.5,300
1984 127.1
1985 161.3
1986 205.0
1987 265.0
1988 340.0
1989 414.0
1990 485.0
.G2
will produce the graph in Figure 9-6.

Figure 9-6. Adding grid lines

500-

400-

300-

NUX introduced~

200-

8. Using the shell
There are three important ways in which grap can interact directly
with the NUX system. It can take input from files located in the NUX
filesystem, send output to the standard error file, and run arbitrary
NUX commands by passing instructions to the shell.

grap Reference

9-9

Instead of presenting your data to grap by including it in the chart
specification, you can tell g rap to get some data from a file. This is
done with the copy command. For example, if the data is stored in a
file named unix. da ta, you could simply write the following:

(

.Gl
copy "unix.data"
.G2
The result of this graph specification is to produce the default chart
given in Figure 9-3. Notice that you had to enclose the name of the file
in double quotes.
grap is also able to send information to the operating system. One
way to do this is by using the print command. The print
command sends its argument, either the value of an expression or a
string, to the standard error output file. Usually this is the user's
terminal screen. For instance, the command sequence

.Gl
x

= 5

(
'~

print x*7
.G2
will result in the value 35 being written on the user's screen. The
p r in t command is most useful for debugging purposes.

By far the most powerful form of interaction between grap and the

A/UX system is the sh command. The sh command passes its
arguments (presumably commands) to the A/UX shell; these
commands are executed, and control is then passed back to grap.
A typical use of the sh command is to produce the data that will
subsequently be plotted by grap using the copy command. For
example,

.Gl
sh @ awk -f /tmp/awkscript chap.l > out @
copy "out"
.G2
In this example, grap will run the awk program using the specified
script and redirect the output into a file; this file, out, is then copied in

9-10

AlUX Text Processing Tools

and grap continues processing the data it has just created.
Presumably, the awk script generates columns of numbers that grap
can understand. Note also that there is no reason that this grap input
could not occur in the file chap. 1 itself.

9. Macros
grap provides a rudimentary macro facility, the simple form of which
is identical to that in pic:
define name X replacement-text X
This defines name to be the replacement-text; X may be any character
that does not appear in the replacement. Any subsequent occurrence of
name will be replaced by replacement-text.
Macros with arguments are also available. The replacement text of a
macro definition may contain occurrences of the indicators $1 through
$ 9; these will be replaced by the corresponding actual arguments when
the macro is invoked. The invocation for a macro with arguments is

name (argl, arg2, ... )
Nonexistent arguments are replaced by null strings.

10. copy thru
grap contains a copy thru construction, identical to the one in
pic, that allows the graph data to be interpreted according to the
instructions defined earlier in a macro. A typical use of copy thru
is

.G1
define cprint @ circle rad $1 at $2,$3 @
copy "term. data" thru cprint
.G2
This will cause grap to open the file term. data in the current
directory and plot a circle of radius determined by the first field at a
location determined by the second and third fields.
The data provided to copy thru does not need to be taken from a
file, nor does the macro need to be predefined. See the entry for copy
in the section "Summary of grap Syntax" for a complete list of the
possible forms that a copy thru construction can take.

grap Reference

9-11

11. Loops and conditionals
Like pic, the grap program provides looping and conditional
constructions. Looping through a sequence of statements can be
achieved with the for command. The general form of a grap loop is
for var = start to end [by step] do
@ cmds @
If the optional step specification is omitted, the loop proceeds in
increments of 1; also, the character '@' may be replaced by any other
character that does not occur in the series of commands cmds. In fact,
the following form will also work, where the character '@' has been
replaced by matching braces:
for var = start to end [by step] do
{ cmds }

For instance, the curve corresponding to the equation

y =x 2
can be obtained very easily using the following grap instructions .

. Gl
frame ht 3 wid 3
draw solid
for i = -2 to 2 by 0.1 do
next at if

i*i

.G2

The resulting graph looks like this:

9-12

A/UX Text Processing Tools

(

Figure 9-7. Plotting a simple curve

-1

-2

The general form of the grap conditional statement is
if cond then

cmdsl

[else

cmds2 @]

If the condition cond is true, then the sequence of commands cmdsl is
executed. If the optional else clause is present and if the condition
evaluates false, then the sequence of commands cmds2 is executed;

otherwise it is ignored.
You can add a simple if-statement to the previous example to shade in
the positive side of the curve.

grap Reference

9-13

.G1
frame ht 3 wid 3
draw solid
for i = -2 to 2 by 0.1 do
next at i, i*i
if (i >= 0) then
@ line from O,i*i to i,i*i @
.G2
The resulting graph looks like this:
Figure 9-8. Shading part of a curve
4

o
-2

-1

12. Plotting curves
You saw above in the section "Loops and Conditionals" that the grap
language can be used to plot curves from equations as well as from

9-14

AlUX Text Processing Tools

discrete data points. In general, you can use this method to graph any
function y = f (x) where f (x) can be expressed using the operators and
functions built into grap. The built-in operators are

*
/

addition
subtraction
multiplication
division
equality

The built-in functions are
exp (expr)
log (expr)
sin (expr)
cos (expr)

atan2 (exprl,expr2)
sqrt (expr)
int (expr)
max (exprl,expr2)
min (exprl,expr2)
rand (expr)

10 to the power expr
logarithm base 10 of expression expr
sine of expression expr
cosine of expression expr
arctangent of exprl/expr2
square root of expression expr
integral part of expression expr
maximum of expr 1 and expr 2
minimum of exprl and expr2
a random number between 1 and expr

Consider for example the built-in logarithm function log. This
provides only the base-l0 logarithm, but you can define the natural
(base e) logarithm if you recall the following simple fact:
loge (x) = loge (10)

10glO(X)

Because loge (10) is an easily-determinable constant, you can construct
the following grap macro:

define In @ 2.30258

* log($l) @

Furthermore, the function y = eX is the inverse function of y = In(x),
so you can graph it by reflecting the graph of the natural logarithm
across the diagonal line y = x. So you have

grap Reference

9-15

.G1
define ln @ 2.30258
frame ht 4 wid 4
draw Nat solid
draw Ten dotted
draw Exp solid

log($l) @

for i = 0.5 to 5 by 0.1 do
next Nat at i, In(i)
next Ten at i, log (i)
next Exp at In(i), i
line dashed from 0,0 to 4,4
"$y-=-e sup x $" at 0.0, 2.00
"$y-=-ln (x) $" at 2.0, 1.0
"$y-=-log (x) . $" at 3.0, 0.65
"$y-=-x $" at 4.5, 4.5

.G2
This yields

9-16

A/UX Text Processing Tools

Figure 9·9. Logarithmic and exponential functions

y =x

y =e"

,, "

"
,,"

"
,""

"
""

, ""

= log(x) .. ............. .

........... ... ...

12.1 Using polar coordinates
Some curves are more easily described using polar coordinate
equations than using Cartesian rectangular coordinates. For example,
the polar equation of a circle with its center located at the origin is
simply r = a • for some constant a. whereas the rectangular equation is
the somewhat more complicated x 2 + y2 = a 2• Even though grap does
not contain primitives for handling polar equations, it is relatively
straightforward to graph some equations expressed in polar form.
r = f (9).

grap Reference

9-17

To see this, consider the following simple relationship between the
sides of a right triangle:
(x,y)

rsinCO)

rcosCO)

You notice the following two facts:

x = rcosCO)
y = rcosCO)

You can therefore graph the curve r = f (0) by plotting the sets of point

x ,Y which satisfy the equations:

=f CO) x cosCO)
y = f (0) x cosCO)

For example, suppose that you want to graph the Spiral of Archimedes,
r = O. The following grap input will do nicely:

.G1
frame ht 3.5 wid 2
label bot "Spiral of Archimedes" "$r-=-theta$"
pi = 3.14159
for i

= 0 to 3*pi/2 by 0.1 do

next at i*cos(i), i*sin(i)
.G2
This yields the graph:

9-18

AlUX Text Processing Tools

Figure 9-10. Plotting a polar equation
2

-2

-4

-3

o
-2
-1
Spiral of Archimedes
r =9

Similarly, you can give the following code to generate the graph of the
cardioid:

grap Reference

9-19

.Gl
frame invis ht 3.0 wid 3.5
grid bottom dotted at 0
grid left dotted at 0
ticks off
label bottom "Cardioid" "$r-=-l--- cos ( theta)
"X" at 1,0.25
"Y" at 0.25,1.5
pi = 3.14159
for i = 0 to 2*pi by 0.07 do
next at

(I-cos (i) ) *cos (i),

(I-cos (i) ) *sin (i)

.G2

This code yields

9-20

AlUX Text Processing Tools

Figure 9-11. A second polar equation
y

Cardioid
r = 1- cos(9)

As a final example of the power of this method, consider how easy it is
to graph a circle using polar coordinates. You noted that the polar
equation of a circle centered at the origin is just r = a. The necessary
transformations into x,y pairs are therefore

x =a xcos(9)
y = a x sin(9)

So, for a circle of radius 1:

grap Reference

9-21

.G1
frame invis ht 3 wid 3
pi = 3.14159
for i = 0 to 2*pi by 0.05 do
next at cos(i), sin(i)
next at 1,0 # close up graph
.G2
Figure 9-12. A grap circle

0.5-

-0.5-

-1-

I
-1

I
-0.5

0.5

I
1

The interested reader should attempt to recreate this graph without
using polar coordinates. (No fair using the pic built-in circle!)

9-22

A/UX Text Processing Tools

12.2 Equally scaled axes
You will notice that g rap automatically calculates the bounds of the
curve being graphed and scales the coordinate axes in such a way as to
fit the graph into the space available (either the size requested using the
frame command or the default size). This means that the axes are
almost never drawn according to the same scale. For graphs of discrete
data this is not generally a problem, but graphs of curves and functions
are often misleading unless drawn with axes scaled identically.
There is an easy way to get grap to produce equally scaled axes. The
frame and coord state{Ilents can be used to specify that the size and
coordinate ranges for both axes be identical. For instance, the
following grap instructions will ensure that the curve looks the way
you expect:
.G1
frame ht 3 wid 3
coord x 0,10 y 0,10
draw solid
for i from 0.1 to 10 by 0.05 do
next at i,

l/i

.G2

This yields

grap Reference

9-23

Figure 9-13. Equally scaled axes

10-rr----------------------------------,

You will notice that obtaining equally scaled axes via the coord
command demands that you have some previous idea of what the
bounds of the function are likely to be. If you genuinely have no firm
idea what the resulting graph is going to look like, you can still ensure
equally-scaled axes in the following way: while plotting the set of
points x,y over some interval, also plot the set of points y~ invisibly.
This has the effect of plotting the inverse function y = 1-1 (x), thereby
guaranteeing that the largest x value is the same as the largest y value.
To illustrate this second method of producing equal axes, suppose that
you want to graph the curve y = x 3• You can give the following code,
which does not use the coord command:

9-24

AlUX Text Processing Tools

.G1
frame ht 3 wid 3
draw Real solid
draw Hack invis
for i from 0 to 3 by 0.1 do
next Real at i, i*i*i
next Hack at i*i*i, i

.G2
This will produce the following graph:

Figure 9-14. Equally scaled axes without coord

20-

10-

12.3 Plotting curves from data points
Sometimes it is not possible to reduce an equation to the rectangular
form Y = f (x) or to the polar form r = f (9). In such a case, it is still

grap Reference

9-25

possible to obtain a graph of the function using grap, though not in the
easy way illustrated earlier.
Suppose you want to find a graph of the equation
x 8= (x 2+ y2)3.
One way to do this is to write a simple program to generate a set of
data points on the curve. Figure 9-15 illustrates a C language program
that will generate a set of points on the curve between 0 and 4.
Figure 9-15. Sample C program to generate data points
#include
#define STEP
0.01
1* step size between points *1
#define MARG
0.01
1* margin of closeness */
#define approx(a,b) ((a>=(1.0-MARG) *b)&& (a<=(1.0+MARG) *b»
main()
{

float x, y;
for ( x = 0.0 ; x <= 4.0 ; x += STEP)
for ( y = 0.0 ; y <= 4.0 ; y += STEP
if ( on_curve (x,y) )
printf("%4.3f %4.3f\n", x, y);
exit(O);

on_curve (fx, fy)
float fx, fy;
{

if ( approx( fx*fx*fx*fx*fx*fx*fx*fx ,
((fx*fx)+(fy*fy»
*((fx*fx)+(fy*fy»
*((fx*fx)+(fy*fy» ) )
return (1) ;
else
return(O);

When this program is compiled and run, it will generate a list of data
points. If the output of the command is redirected into the file
curve. data, the following grap commands will give you the graph
you want.

9-26

AlUX Text Processing Tools

.G1
frame ht 3 wid 3
coord x 0,8 y -4,4
draw Pos solid
draw Neg solid
copy "curve.data" thru @ next Pos at $1,$2
next Neg at $1,-$2 @
.G2
This yields

Figure 9-16. Plotting a curve from data points
4~--------------~--------------------~

-2

4-+--------~----~--~------~--------~

grap Reference

9-27

13. Summary of grap syntax
grap is a pic preprocessor designed for drawing charts and graphs
and including them in documents formatted with troff. The general
command line is
grap files I pic I ... I troff ...

Graph specifications are included between. G1 and. G2 pairs and may
include the following commands:
coord [dataset] x min, max y min, max [log x] [log y]
Set the range of the x and y coordinate axes to run from
min to max. This command overrides the default axis
scaling and may result in the loss of data points that do not
fit into the specified range. Addition of the optional log
indicator will result in logarithmic scaling of the specified
axis. The default dataset is the one currently active.
copy "file"
Include the file file at this point.
copy thru name
Pass the rest of the input for this graph (that is, until the
next. G2) through the macro name, breaking the line into
fields that are passed as arguments to the macro. Fields are
delimited by white space, except for white space enclosed
by string delimiters, " ... ". The macro name can be
replaced by an in-place macro.
copy thru name until "str"
As above, except that the copying ends when the first
occurrence of the string str is found at the beginning of an
input line.
copy "file" thru name until "str"
Copy the data from file file through macro name until the
first occurrence of the string str is encountered.
define name X anything X
Define a grap macro: replace all subsequent occurrences
of name by anything. If the string anything contains any
of the sequences $1, $ 2, ... , $ 9, they are replaced by the

9-28

AlUX Text Processing Tools

first, second, ... , ninth arguments enclosed in parentheses
following name. The file
/usr/lib/dwb/grap.defines contains several
macro definitions and it is included in all files processed by
grap if it exists (unless the -1 command line option is
specified) .
draw [dataset] attrib ["str"]
Set the attribute to be used in drawing the graph of data set
dataset to attrib. If the optional string str is added, this
string will appear at each point plotted.
for var

= start to end [by step]' do

@ cmds @
Run the specified list of commands cmds for all the values
between start and end, taken in steps of step. If the by
clause is omitted, steps of 1 are taken. The assignment
operator = can be replaced by the keyword from.

frame [attrib] ht h wid w [side attrib]
Set the frame surrounding the graph to the specified height
h and width w. The default size is 2 inches high and 3
inches wide. You may set the drawing mode attrib for the
entire frame or for each of the sides (top, bot, left,
and right) to anyone of the attributes dotted,
dashed, invis, or solid. The default attribute is
solid.
graph Name pos
Begin a new frame Name for subsequent plotting, placing
the frame at the specified pos. The position pos must be in
a form recognizable by pic, for instance,
graph New with .s at Old.n

The name of the graph Name must be capitalized, in
accordance with the input syntax for pic.
grid side attrib at [dataset] expr
Draw grid lines perpendicular to the specified side side at
the value of expression expr. The line is drawn with
attribute attrib, which is by default solid. There may be
more than one expression, and grid lines and labels of

grap Reference

9-29

incremental steps are available as with the ticks
command.
if cond then @ cmdsl @ [else @ cmds2 @]
Run the commands crr.dsl if the specified condition cond
is true. If the condition evaluates false, and if the optional
else clause is present, then run commands cmds2.
label side "str" [II str"] [pos expr]
Use string str as a label on the specified side side. The
default side is the bottom. There may be any number of
strings, which are centered one above the others. In
addition, a label specification may include an optional
position pos to shift the default position of the label. The
specifier pos may be up, down, left, or right, and
must be followed by an expression indicating the amount
of position shift in the specified direction.
1 ine from pt to pt [attrib]
Draw a line, using the specified attribute attrib, from the
first point pt to the second. The default attribute is sol id.
Also, the keyword line may be replaced by arrow.
new [dataset] attrib [II str"]
Set the attribute to be used in drawing the graph of the data
set dataset to attrib, and disconnect the subsequent data
points from any preceding ones. If the optional string str is
added, this string will appear at each point plotted.
next [dataset] at pt [attrib]
Plot the next data point for data set dataset at point pt,
connecting that point with previous points by a line of
attribute attrib.
pic anything
Pass the remainder of the input line to pic, removing any
leading white space. The input anything cannot contain
newlines.
plot "str" [loc] at pt
Place string str at point pt. The optional location loc can
be anyone of the modifiers rjust, 1 just, above, or

9-30

AlUX Text Processing Tools

(
I,~

below. Also, the keyword plot may be omitted
altogether.
point [dataset] expr, expr
Map the point determined by the values of the two listed
expressions to the specified dataset. The default data set is
the current.
print expr
print "str"
Print the value of expression expr or the string str on the
standard error file. This is most useful as a debugging tool.
sh @ anything @

Pass everything between the enclosing @, s to the NUX
shell. The character @ can be replaced by any other
character. Also, newlines may be included in the string
anything.
ticks side dir at [dataset] expr ["str"] [, expr "str"]
Draw ticks on the specified side side at expr, using the
optional string str as a label. More than one expression
and label can be listed, separated from the preceding ones
by a comma. Direction dir may be either in or out,
indicating the direction the ticks are drawn (the default
direction is out). The strings specified as labels may
contain format specifiers of the form %fn . m, which are
interpreted as with the C-Ianguage function printf. See
printf(3) for details.
ticks side dir from m to n [by step] ["str"]
Draw ticks on the specified side side beginning at value m
and continuing to value n in steps of size step, using the
optional string str as a label. The step size step may be
preceded by an optional + or - to obtain additive
increments or decrements, or by an optional * or / to
obtain multiplicative increments or decrements. If the step
specifier is omitted, steps of size 1 are used. If no ticks are
requested, they will be supplied automatically, although
this can be suppressed with the command ticks off. A
margin of 7% is left on each side of a graph; the margin

grap Reference

9-31

can be adjusted with the command
margin

expr

number-list
Unless copied through a macro (see copy thru), treat a
list of numbers as follows. A single column of numbers
(one number per line) is interpreted as a list of ordinates
(y-values) for the abscissae (x-values) 1,2,3, ... Multicolumned lists are treated as a single abscissa followed by
multiple ordinates; in other words, a line of the form:
xyl y2 y3 ...
will result in plotting the points (x,yl), (x,y2), (x,y3), and
soon.
var = expr
Set variable var to the value of expression expr.
. anything (at beginning of line)
Copy this line untouched. Hence, t ro f f commands may
be interspersed among grap commands.
:/I: anything

The symbol :/I: is a comment indicator; anything following
this symbol on a line will be ignored by grap. You can
also use the t ro f f comment indicator . \ " at the
beginning of a line to include comments in a graph
specification.

9-32

AlUX Text Processing Tools

Chapter 10
Other Text Processing Tools

Contents
1

1. Introduction
••••
2. Other text preprocessors
2.1 Preparing constant-width text • . •
2.2 Numbering lines
2.3 Translating characters
2.4 Single-spacing a document . • . •
2.5 Changing the format of a text file
2.6 Printing Greek characters
2.7 Creating underlines for your terminal .
2.8 Stripping out reverse line feeds •

.
.

•
•

•

1
1
2
3
3
4
4

3. Other macro packages . . • • • •
3.1 Typesetting viewgraphs and slides

•.•..•
4. Special tools for the manual pages
4.1 Creating a manual page • • •
4.2 Reading on-line manual entries •
4.3 Creating a permuted index

6
6
6
6

5. Checking your work before you format it
5.1 Checking your spelling
5.2 Checking your writing style. •
5.3 Checking your document's clarity .
5.4 Checking your eqn commands. .
5.5 Checking your mm commands
5.6 Checking your InS commands • .
5.7 Checking your cw commands

-i-

•

7
7
7
8
8
9
9
10

Chapter 10
Other Text Processing Tools

1. Introduction
The tools described here supplement the text processing programs
described in this book. This chapter is intended as a short reference to
these additional tools. For complete information on each command,
refer to the AIUX Command Reference.

2. Other text preprocessors
Preprocessors operate with text formatters to produce specialized
forms of output, such as tables, equations, and line drawings.
Preprocessor data is converted to troff (or nroff) commands, and
then this output is passed on to the formatter for further processing.
tbl, eqn, and pic are the most commonly used A/UX preprocessors.
The following is a brief description of some lesser-known A/UX tools.

2.1 Preparing constant-width text
Text typeset in constant-width (CW) font resembles the output of
terminals and line printers. All characters are the same width. CW
font is used most often to show examples of computer output.
CW font contains a nonstandard set of characters with character and
interword spacing different from that of standard t ro f f fonts, such as
Times Roman. Documents using the CW font must be preprocessed.
See cw(l) for more information.

2.2 Numbering lines
The nl program is a line-numbering filter. It reads lines from a named
file (or from standard input if no file is named) and reproduces the lines
on the standard output. Lines are numbered on the left side of the page.
nl processes your text in "logical pages." Line numbering is reset at
the start of each logical page. A logical page consists of a header, a
body, and a footer section. Different line numbering options are
available independently for each of these sections. For example, you

Other Text Processing Tools

10-1

may specify that you do not want header or footer lines numbered.
(The default is not to number either header or footer lines.)
To specify the start of each logical page section, use the following
default delimiters, which appear at the line preceding the start of the
section:
\ :\ :\ :

header

\: \:

body

footer

Thus, for general purposes \ and : are considered to be the delimiter
characters, as they are repeated and joined to form the actual
delimiters.
You may specify new delimiter characters by use of the -d flag option.
For example, in the command
nl -v5 -i5 -d!+ test.file

the delimiter characters are changed to ! +. The entire command
instructs nl to number test. file starting at line number 5 (-v5),
with an increment of 5 (- i 5). (The default is to begin numbering at
line 1 and to use an increment of 1.)
For a complete description of the available options, see nl(I).

2.3 Translating characters
The t r program translates characters in a file. It takes two string
arguments. Any characters found in the first string are replaced by the
equivalent characters in the second string.
For example, suppose you want to convert all uppercase characters in a
file to lowercase. You can do this with the command
tr "[A-Z]" "[a-z]" < upper.file > lower.file

where" [A - Z] " is the first string, " [a - z] " is the second string,
upper. file is the original file, and lower. file is the translated
file. The double quotes and brackets are necessary to distinguish
ranges from regular strings. If they are omitted, only the characters A,
-, and Z will be translated to lowercase.

10-2

AlUX Text Processing Tools

(
~

You can also use t r to delete character strings. For example, if you
want to remove all numeric characters from a file, you may use the
command
tr -d 0-9 < num.file > unnum.file
With the -d option, you specify only one string and t r deletes
members of it wherever they occur. Ranges do not need special
treatment with this option.
See tr(l) for more information.

2.4 Single-spacing a document
ssp removes extra blank lines from a file and causes all output to be
single-spaced. You may use it either directly on a file:
ssp file> out. file
or as a filter following text formatting:
troff -rom file I ssp> out.file
See ssp(l) for more information.

2.5 Changing the format of a text file
The newform program allows you to change the format of a text file.
You may change tab characters to spaces or spaces to tabs. You may
define a standard line length, and if your input exceeds that length, you
may designate that n characters be removed, from either the beginning
or the end of each line. If your input lines are shorter than the
designated line length, you may choose the number of characters to
append or prefix to each line. For example, given te st. f i le-a file
with lines consisting of leading digits, one or more tabs, and then
text-the command
newform -s -i -e -a test.file > out.file
converts it to a file (out pu t . file) with lines beginning with text ( s), all U\bs expanded to spaces ( - i), each line padded (or truncated)
with spaces to fit 72-column format (-e), and the leading digits (which
were stripped away with the -s option) appended after column 73 (a).
See newform(l) for more information.

Other Text Processing Tools

10-3

2.6 Printing Greek characters
greek is an nroff filter that permits you to produce an
approximation of the greek alphabet on output devices not normally
able to print nonstandard characters.

The file /usr/pub/ greek contains the default Greek characters
produced by nroff. The greek filter reinterprets this character set
(as well as the default reverse and half-line motions) to permit use on a
variety of terminals. The special characters are simulated by
overstriking.
Your own terminal type may be specified after the
Thus the command
nroff -rom test. file

-T

flag option.

I greek -Tterm

(where term specifies the output device) formats test. file and
filters the output through greek. (If no -T argument is given, greek
attempts to use the environment variable $TERM.)
greek recognizes only certain terminal types. To view the list of
recognized terminal types, see greek(l).

2.7 Creating underlines for your terminal
The ul program translates underscore characters to a sequence that
simulates underlining. The actual sequence depends on the options
supported by your terminal. Some terminals produce reverse video to
indicate underlining; others do actual underlining. If your terminal
cannot interpret underscores, ul behaves like cat(l) and simply
displays the file on your screen.
You may specify the terminal type after a -t. This is the most reliable
way to obtain underlining as such, if your terminal can do it. If no type
is specified, ul will try to determine itfrom the environment and may
consult / etc/termcap to learn how to underline.
Thus the command
nroff -rom test. file

I ul -t term

(where term is the terminal type) will format test. file and filter
the result through ul to produce underlining wherever test. file
had lines preceded by

10-4

AlUX Text Processing Tools

.ul
or had troff requests for italics.
See ul(l) for more information.

2.8 Stripping out reverse line feeds
The col program allows you to print files that contain reverse line
feeds and forward and reverse half-line feeds on output devices that
cannot handle reverse movements.
col filters out the reverse line feeds generated by the . rt (return)
nroff request, some eqn output, tbl output, and other multiplecolumn output. In addition to removing reverse line feeds, the col
program filters out other nonprinting characters. You can then print
your formatted file on simple printing devices.
To run colon a multiple-column nroff document, use the command
nroff -rom test.file I col> output. file
See col(l) for a complete description of the use of this command.

3. Other macro packages
The rom and ms macro packages permit you to produce a wide range of
text processed output. The following macros allow you to go a step
further in document preparation.

3.1 Typesetting viewgraphs and slides
You may use the mv macros to prepare typeset-quality viewgraphs and
slides. Viewgraphs can be prepared in a variety of dimensions, as well
as 35-mm slides and 2-by-2-inch "super slides." A few macros
perform most of the formatting tasks needed in making transparencies,
and you may use all of the facilities of nroff, troff, eqn, tbl, and
cw for the more difficult tasks. See mv(5) for a complete list of the
available macros.
To run your text files prepared with mv, use the mvt command:
mvt file> out.file
Options are provided to call tbl and eqn and the proper pipelines and
required arguments for troff are generated automatically.

Other Text Processing Tools

10-5

See romt(l) and mvt(l) in AIUX Command Reference and mv(5) in
AIUX Programmer's Reference for more information.

4. Special tools for the manual pages
The NUX manual pages found in the AIUX Command Reference,
AIUX Programmer's Reference, andAIUX System Administrator' s
Reference contain descriptions of all commands and maintenance
procedures contained in the A/UX system. The manual pages are
produced according to strict formatting conventions with the man
macros.

4.1 Creating a manual page
The man macros produce standardized manual entries. You use the
man macro package to create manual pages in the same way that you
use the rom macro package to produce text.
To produce your own manual pages, follow the instructions in man(5).

4.2 Reading on-line manual entries
The man command locates and prints a requested manual entry. The
manual page can be viewed on your terminal screen (the default) or can
be printed on your printer.
For example, to produce the manual page grep(l) for terminal
viewing, enter the following:
man 1 grep

The 1 is the section number of the manual. It alerts the system to
search through section 1. If the section number is not specified, the
entire manual set (sections 1 through 8) is searched.
See man(l) for more information.

4.3 Creating a permuted index
The permuted index in the AIUX Command Reference, AIUX System
Administrator's Reference, andAIUX Programmer's Reference is
produced with the ptx command. The permuted index presents a
sorted alphabetic listing of keywords contained in the command
descriptions.
It works in three stages:

10-6

NUX Text Processing Tools

It generates one line for each keyword in an input line, and then
rotates the keyword to the front of the line.

It alphabetically sorts the permuted file.

3. It rotates the sorted lines and places the keyword in the middle of
the line.
You can then scan the center column of the permuted index for the
keywords.
For flag options and formatting information, see ptx(1) and mptx(5).

5. Checking your work before you format it
The following tools check your work before you process it. With each
command, output either can be written to standard output (the default)
or redirected to a file.

5.1 Checking your spelling
The spell program checks the words in your document against an
on-line dictionary and then reports those words not found. You can
instruct spell to verify either American or British spelling. You can
also stipulate a file (with the + local. file flag option) of words not
in the on-line dictionary for spell to use as well. In this case,
+local. file must be sorted, with one word per line.
To run spell, type
spell test.file > spell.list

This checks the spelling of words in te st. file and puts dubious
ones in spell. list.

Note: Proper names and technical terms appear in the spell
output (unless you include them in your +local. file).
Often, you will have to edit these out of your spell. list
before using it to correct your files.
For complete instructions on using the spell program, see spell(l).

5.2 Checking your writing style
You can check certain aspects of your writing style with the style
program. It gives the use (by percentage) of various grammatical

Other Text Processing Tools

10-7

forms, and it reports on readability, sentence length and structure, word
length and usage, and types of verbs used.
Although such statistics may seem superficial, they can still be of use.
style is particularly useful for comparing two documents or seeing if
you are overusing a particular grammatical form.
To run style, enter the following:
style file

5.3 Checking your document's clarity
The diction program finds sentences in a document that are
overused or poorly constructed. It compares what is in your document
against a data base of bad phrases and reports any matches.
To run diction, enter the following:
diction < file

See dict ion(l) for additional information.

5.4 Checking your eqn commands
checkeq looks for missing or unbalanced eqn delimiters (usually
$ $) or . EQ and . EN pairs. It especially looks for mixtures of these,
which would confuse eqn; thus the output
$$ within .EQ . . . EN, line n

indicates that in-line delimiters were used within a displayed equation.
To run checkeq, type
checkeq file

Not all output lines flag errors directly. The diagnostic
$$ delims, line n

does not report an error. It states that in-line delimiters ($ $) were
turned on at line n. If the delimiters change, this will also be reported.
Then, if they are changed to another symbol or if they are left off for a
long time, this will be apparent from the output.
Note: Do not set delimiters to ## and then use eqn within
tables. tbl uses #'s internally and may not be able to function

10-8

AlUX Text Processing Tools

if eqn uses them as well.
If you need to use the dollar sign itself, you can use the following eqn
definition at the top of your file:
.EQ
define dol 'roman "$'"
delim $$
.EN

Because the single dollar sign appears in the file before the delimiters
were turned on, this usage will not cause an error to be reported by
checkeq. Then, to use this defined term, type
$dol$

to produce $. The dollar signs match, and no error is flagged.

Note: If you use the mm macros, you should use checkmm
instead of checkeq. The checkmm program incorporates all
the features of checkeq.

5.5 Checking your mm commands
checkmm checks for inconsistent use of the mm macros. It finds
unmatched pairs of macros, unmatched size and font changes, and
unbalanced . EQ . / . EN pairs. If you use checkmm, you do not have
to use checkeq as well.

To run checkmm, enter the following:
checkmm file

For more information on options and syntax, see mro(l).

5.6 Checking your ms commands
You can check your ms documents for formatting errors with the
checknr program. checknr examines your file and reports any
unrecognized macros or unbalanced macro constructions. For
example, it will find any . DS commands that are not terminated with
. DE, or it will verify that each. RS command has a corresponding
• RE command.

Other Text Processing Tools

10-9

To run checknr, enter the following:
checknr file

Any discrepancies are written to the standard output. Or, if you prefer,
you can direct the output from checknr to a file so you can examine
it later:
checknr file > output-file

For more detailed instructions on using this program, refer to
checknr(l) inAIUX Command Reference.

5.7 Checking your ow commands
You can use checkcw on files to be processed with cwo checkcw
finds unbalanced left and right delimiters, as well as . cw/. CN pairs.
See cw(!) in AIUX Command Reference for more information.

10-10

AlUX Text Processing Tools

Appendix A
Additional Reading

Document Formatting and Typesetting on the UNIX System
Narain Gehani
Silicon Press, 1986

Additional Reading

A-1

Appendix B
Glossary of Text Processing Terms

adjust: To add small amounts of space between words in a filled text
line so that the line of output text is the desired line length.

argument: Used in a command line and placed after the command to
specify what the command should act upon.

break: Printing of a partially filled output line.
comment: An informative remark embedded in text but not intended
for printing. You can include a comment at the end of a line by
prefacing it with \. You can include a comment in a file as a line by
itself by beginning the line with . \.

control lines: Sometimes called "dot commands," they are
interspersed with text lines and set parameters or otherwise control
subsequent processing. They begin with a period or an acute accent,
followed by a 1- or 2-character name that specify a basic request or the
substitution of a user-defined macro in place of the control line.

display: A block of text that is to be kept on one page. The relevant
text is enclosed within the . DS and . DE macros. By default, the text
lines are not filled or adjusted, but you can override this by providing
an argument to the . D S macro.

diversion: A mechanism provided by the traff formatter to store a
block of input text for a period of time in order to determine its size and
whether it will fit on the current page before actually printing it; for
example, footnotes or text between the macros . KS and . KE that is not
to be split across a page boundary (as for a figure or table.)
eqn: A mathematical equation formatting preprocessor for traff

Glossary of Text Processing Terms

8-1

that produces typeset-quality mathematical text. eqn converts
mathematical input into traff commands, and the resulting output is
passed directly to the formatter for further processing. Mathematical
expressions are entered by beginning and ending each with the
delimiters. EQ and . EN. In-line equations may be included in text if
they are enclosed in delimiters which are defined at the beginning of
the text file.
escape character: (\), followed by a command name anywhere in a
line. The escape character introduces sequences that cause the
following character to mean another character or signals the formatter
to treat the sequence as a command and not text. It should not be
confused with the control character ESC of the same name.
em: Used to specify a width approximately equal to the size of the
letter m in the current font and point size.
en: Half of an em.
field: A string of characters separated from other strings by blanks,
tabs, or other specific delimiters.
fill: To place as much text on a line as will fit, regardless of how the
text occurs in the input file.
floating keep: Begins with . KF and ends with . KE. If the number of
lines in a block of text exceeds the remaining lines on the page and it is
necessary to force a page break, the regular text material continues to
print until it reaches the end of the page, and the block of text is
printed. It differs from a static keep in that it waits for a natural page
break rather than forcing one.
font: A collection of letters and characters unified by a distinctive
pattern or "look." Times Roman, for example, is the default font for
traff.

footer: A line of text that is printed on the bottom of every page.

8-2

AlUX Text Processing Tools

(
~

formatter: A utility that processes text for output to a device. The
nroff and troff utilities, for example, are fonnatters that justify the

margins, center the titles, number the pages, and perform other
enhancements that improve the printed appearance of text files.

grap: A preprocessor for pic which penn its inclusion of graphs in a
document formatted with troff. Specifications for the graph are
enclosed within. Gl and . G2 pairs and are translated by grap into
pic code.
header: A line of text that is printed on the top of every page.

ligatures: Two or more characters or letters linked together. Two
ligatures are available in the t ro f f character set: fi and fl. They may
be input (even in the nroff formatter) by \ (fi and \ (fl,
respectively. Note that ligature mode is normally on in the troff
formatter; that is, ligatures are automatically produced.
leader: A single character, repeated as necessary, to visually tie one
item to another in a text line. For example, a heading and page number
in a table of contents are often connected with a line of dots. The
leader character is a period by default and may be set using the " .le"
troff request.
local motion: Vertical and horizontal motion contained within a line.
The function \ v, n' is used for vertical motion and \ h ' n' can be
used for horizontal motion. The distance n may be negative; the
positive directions are rightward and downward. To avoid unexpected
vertical dislocations, it is necessary that the net vertical local motion
(within a word in filled text and otherwise within a line) balance to
zero.
macros: A collection of instructions or requests invoked by a single,
simplified command. Text processing macros, for example, are
embedded in a file and usually take the form XX, where X is generally
a capital letter. Each macro is an abbreviation for a collection of
requests that would otherwise require repetition.

Glossary of Text Processing Terms

8-3

macro package: A collection of macros grouped into a useful unit.
neqn: An nroff preprocessor which formats mathematical symbols
and equations using standard keyboard symbols to approximate the
mathematical symbols requested as closely as possible.
nroff: A formatter which produces typewriter-quality output.
number registers: Where t ro f f keeps track of many of the
parameters governing the page layout. You can create a number
register with the command. nr or change existing parameters, such as,
. nr S i 8 to change the standard indent for displays.
output devices: Typically, a printer or display device, such as a digital
typesetter or phototypesetter, laser-driven printer, high-resolution video
display terminal, terminal screen, dot matrix printer, or daisy wheel
printer.
output translation: One character can be made a stand-in for another
character using the . t r request
page footer: Text printed at the bottom of each page.
page header: Text printed at the top of each page.
page offset: The distance betweeen the left margin and the left edge of
the paper. The default page offset for nroff/troff is one inch.

pic: A t ro f f preprocessor which produces simple line drawings in
a document The basic figures are arrow, box, circle, line, arc, ellipse
and text Descriptions are included between. sps and . PE pairs.
pica: A measurement (1/6 inch or 6 points) used for specifying line
lengths and page lengths.
point size: Used to specify size of type using printer's measurement of
a point equal to In2 of an inch. The default point size for t ro f f is
lO-point type.

8-4

A/UX Text Processing Tools

preprocessor: A utility such as tbl and eqn used to translate your
input into commands that troff can understand before piping the
output to that process. Also the part of a compiler that provides file
inclusion and macro substitution.
requests: Built-in commands recognized by the foqnatters.
static keep: A mechanism for preserving the integrity of a block of
text Begins with . KS and ends with . KE. If the number of lines
within these two macros exceeds the remaining lines on the page, a
page break is forced and the material in the block is printed on the next
page.
string: A named group of characters, not including a newline
character, that may be interpolated by name at any point
tab leader: A string of repeated characters between a tab stop and the
next tab or end of line. A column entry followed by \ a will repeat the
leader character to the next entry. The default leader character is a
period. A different character can be specified with the . 1 c instruction.
A text preprocessor to troff which formats tables. Table
specifications and text are placed between the commands . T S and
• TE. Columns can be centered, right adjusted, left adjusted, or aligned
by decimal points. Headings may be placed over single columns or
groups of columns. Any table or element can be enclosed in a box and
vertical and horizontal lines placed at will.
tb1:

text line: A line destined to be printed or displayed.
transparent throughput: An input line beginning with a \! is read in
copy mode and transparently output (without the initial \ !); the text
processor is otherwise unaware of the line's presence. This mechanism
may be used to pass control information to a post-processor or to
embed control lines in a macro created by a diversion.
trap: A mechanism used in writing macros to interrupt processing in
order to divert to another routine appropriate for the situation. Three

Glossary of Text Processing Terms

8-5

lUi-It)
- (/

types of trap mechanisms are available: page traps, diversion traps, and
input-line-count traps.

(
troff: A formatter which produces high-quality output on a high

resolution typesetter or laser printer.
unpaddable space: A space that cannot be expanded during
justification.
vertical spacing: The vertical distance from the base line of one line
of text to the base line of the next.
width function: The width function \ w' string' generates the numeric
width of string (in basic units). Size and font changes may be
embedded in string and will not affect the current environment.
word: A string of characters bounded at each end by one or more of
the following:
•
•
•
•

8-6

(

the space character
the tab character
the beginning of the input line
the end of the input line

AlUX Text Processing Tools

Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : No XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Create Date : 2011:07:27 17:45:37-08:00 Modify Date : 2011:07:27 20:21:30-07:00 Metadata Date : 2011:07:27 20:21:30-07:00 Producer : Adobe Acrobat 9.45 Paper Capture Plug-in Format : application/pdf Document ID : uuid:fb3ea77e-1b8c-4f9b-b816-1ade3d8206a3 Instance ID : uuid:416f6070-c0e7-432a-8eab-05d095330148 Page Layout : SinglePage Page Mode : UseNone Page Count : 474
EXIF Metadata provided by EXIF.tools

030 0761 A_AUX_Text_Processing_Tools_1990 A AUX Text Processing Tools 1990

030-0761-A_AUX_Text_Processing_Tools_1990 030-0761-A_AUX_Text_Processing_Tools_1990

Navigation menu

Versions of this User Manual:

Views

Navigation