Digital PDFs

AA-MFO6A-TE

1988

640 pages

Original

147MB

view download

OCR Version

89MB

view download

Document:	ULTRIX-32 Supplementary Documents General User
Order Number:	AA-MFO6A-TE
Revision:	0
Pages:	640
Original Filename:

OCR Text

ULTRIX-32 Supplementary Documents
General User
Order No. AA-MFOGA-TE

ULTRIX-32 Operating System, Version 3.0

Digital Equipment Corporation

The information in this document is subject to change without notice and
should not be construed as a commitment by Digital Equipment Corporation.
Digital Equipment Corporation assumes no responsibility for any errors that
may appear in this document.

The software described in this document is furnished under a license and may
be used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied by DIGITAL or its affiliated companies.

The following are trademarks of Digital Equipment Corporation:
DEC
DECUS
MASSBUS
PDP

ULTRIX-32
UNIBUS

ULTRIX

ULTRIX-11

VAX

VMS

dlilalilt[alI

UNIX is a trademark of AT&T Bell Laboratories.

Information herein is derived from copyrighted material as permitted under a
license agreement with AT&T Bell Laboratories.

This software and documentation is based in part on the Fourth Berkeley
Software Distribution under license from the Regents of the University of
California. We acknowledge the Electrical Engineering and Computer Science
Departments at the Berkeley Campus of the University of California for their
role in its development.

This software and documentation is based in part on the Fourth Berkeley Software Distribution under
license from The Regents of the University of California.

Digital Equipment Corporation acknowledges

the following individuals and institutions for their role in its development:

"The UNIX Time-Sharing System”:
reprinted by permission.

This is a revised version of an article that appeared in Communications of the

ACM, 17, No. 7 (July 1974), pp. 365-375.

That article was a revised version of a paper presnted at the

Fourth ACM Symposium on Operating Systems Principles, IBM Thomas J. Watson Research Center,
Yorktown Heights, New York, October 15-17, 1973.

Acknowledgements:

for their help and support,

R.H. Canaday, R. Morris, M.D. Mcllroy, and J.F. Ossanna.
”Advanced Editing on UNIX"” acknowledgement: Ted Dolotta for his ideas and assistance.

?An Introduction to the UNIX Shell” acknowledgements:

Dennis Ritchie, John Mashey and Joe Maran-

zano for their help and support.

"LEARN - Computer-Aided Instruction on UNIX” acknowledgements:

for their help and support, M.E.

Bittrich, J.L. Blue, S.I. Feldman, P.A. Fox, M.J. McAlpin, E.Z. Rothkopf, Don Jackowski, and Tom
Plum.

”A System for Typesetting Mathematics” acknowledgements: J.F. Ossanna, A.V. Aho, and S.C. Johnson,
for their ideas and assistance.
A TROFF Tutorial” acknowledgements:

J. F. Ossanna, Jim Blinn, Ted Dolotta, Doug Mcllroy, Mike

Lesk and Joel Sturman, for their help and support.

The document "The C Programming Language - Reference Manual” is reprinted, with minor changes,
from "The C Programming Language, by Brian W. Kernighan and Dennis M. Ritchie, Prentice-Hall,
Inc., 1978.

"Make - A Program for Maintaining Computer Programs” ackowledgements:

S.C.

Johnson, and H.

Gajewska, for their ideas and assistance.
"YACC:

Yet Another Compiler-Compiler” acknowledgements:

B.W. Kernighan, P.J. Plauger, S.I. Feld-

man, C. Imagna, M.E. Lesk, A. Snyder, C.B. Haley, D.M. Ritchie, M.O. Harris and Al Aho, for their

ideas and assistance.

"Lex - A Lexical Analyzer Generator” acknowledgements: S.C. Johnson, A.V. Aho, and Eric Schmidt, for

their help as originators of much of Lex, as well as debuggers of it.
The document "RATFOR - A Preprocessor for a Rational Fortran” is a revised and expanded version of
the one published in Software - Practice and Experience, October 1975.

the one in use on UNIX and GCOS at A T & T Bell Laboratories.

The Ratfor described here is

Acknowledgements: Dennis Ritchie,

and Stuart Feldman, for their ideas and assistance.
"The M4 Macro Processor” acknowledgements:

Rick Becker, John Chambers, Doug Mcllroy, and Jim

Weythman, for the help and support.
"BC - An Arbitrary Precision Desk-Calculator Language” acknowledgement:

The compiler is written in

YACQC; its original version was written by S.C. Johnson.
?A Dial-Up Network of UNIX TM Systems” acknowledgements:

G.L. Chesson, A.S.

Cohen, J. Lions,

and P.F. Long, for their suggestions and assistance.

Copyright © 1979, 1980 Regents of the University of California. Permission to copy these documents or
any portion thereof as necessary for licensed use of the software is granted to licenseesyof this software,

provided this copyright notice and statement of permission are included.
The document "Writing Tools - The STYLE and DICTION Programs” is copyrighted © 1979 by
T Bell Laboratories.

A T &

Holders of a UNIX TM/32V software license are permitted to copy this document,

or any portion of it, as necessary for licensed use of the software, provided this copyright notice and

statement of permission are included.

The document "The Programming Language EFL” is copyrighted © 1979 by A T & T Bell Laboratories.
EFL has been approved for general release, so that one may copy it subject only to the restriction of giving proper acknowledgement to A T & T Bell Laboratories.

The documents A Portable Fortran 77 Compiler” and "Fsck - The UNIX File System Check Program”

are modifications of earlier documents which are copyrighted © 1979 by A T & T Bell Laboratories.
Holders of a UNIX TM/32V software license are permitted to copy these documents, or any portion of

them, as necessary for licensed use of the software, provided this copyright notice and statement of per-

mission are included.

This manual reflects system enhancements made at Berkeley and sponsored in

part by NSF Grants MCS-7807291, MCS-8005144, and MCS-74-07644-A04; DOE Contract DE-AT0376SF00034 and Project Agreement DE-AS03-79ER10358; and by Defense Advanced Research Projects
Agency (DoD) ARPA Order No. 4031, monitored by Naval Electronics Systems Command under Contract No. N00039-80-K-0649.

"Ex Reference Manual” acknowledgements: Chuck Haley contributed greatly to the early development
of ex. Bruce Englar encouraged the redesign which led to ex version 1. Bill Joy wrote versions 1 and 2.0
through 2.7, and created the framework that users see in the present editor. Mark Horton added macros
and other features and made the editor work on a large number of terminals and UNIX systems.

”A Guide to the Dungeons of Doom” acknowledgements: Rogue was originally conceived by Glenn Wichman and Michael Toy. Ken Arnold and Michael Toy then smoothed out the user interface, and added
many new features. We would like to thank Bob Arnold, Michelle Busch, Andy Hatcher, Kipp Hickman,

Mark Horton, Daniel Jensen, Bill Joy, Joe Kalash, Steve Maurer, Marty McNary, Jan Miller, and Scott
Nelson for their ideas and assistance.

The document *The FRANZ LISP Manual” is copyrighted © 1980, 1981, 1983 by the Regents of the
University of California. (exceptions: Chapters 13, 14 (first half), 15 and 16 have separate copyrights, as
indicated.

These are reproduced by permission of the copyright holders.)

Permission to copy without

fee all or part of this material is granted provided that the copies are not made or distributed for direct

commercial advantage, and the copyright notice of the Regents, University of California, is given. All
rights reserved. Work reported herein was supported in part by the U.S. Department of Energy, Contract DE-AT03-76SF00034, Project Agreement DE-AS03-79ER10358, and the National Science Foundation under Grant No. MCS 7807291. MC68000 is a trademark of Motorola Semiconductor Products, Inc.
"The FRANZ LISP Manual” acknowledgements:

Richard Fateman, Mike Curry, John Breedlove, Jeff

Levinsky, Bill Rowan, Tom London, Keith Sklower, Kipp Hickman, Charles Koester, Mitch Marcus,
Don Cohen, John Foderaro, and Kevin Layer.

The document ”"Berkeley Pascal User’s Manual” is copyrighted © 1977, 1979, 1980, 1983 by W.N. Joy,
S.L. Graham, C.B. Haley, M.K. McKusick, P.B. Kessler. The financial support of the first and second

authors’ work by the National Science Foundation under grants MCS74-07644-A04, MCS78-07291, and
MCS80-05144, and the first author’s work by an IBM Graduate Fellowship are gratefully acknowledged.

"Introduction to the f77 I/O Library” acknowledgement: Peter J. Weinberger originally wrote the 1/0/
Library at A T & T Bell Laboratories.

"Writing Papers with NROFF Using -ME”, and ”-ME Reference Manual” acknowledgements:

Bob

Epstein, Bill Joy, Larry Rowe, Ricki Blau, Pamela Humphrey, and Jim Joyce, for their ideas and assistance. UNIX, NROFF, and TROFF are trademarks of A T & T Bell Laboratories.

"Refer - A Bibliography System” acknowledgements: Mike Lesk of A T & T Bell Laboratories wrote the
original refer software, including the indexing programs.

Al Stanberger of the Forestry Department
wrote the first version of addbib, then called bibin. Greg Shenaut of the Linguistics Department wrote
the original versions of sortbib and roffbib.

"Screen Updating and Cursor Movement Optimization: A Library Package” acknowledgements: For
their help and support, Bill Joy, Doug Merritt, Kurt Shoens, Ken Abrams, Alan Char, Mark Horton, and
Joe Kalash.

"Disc Quotas in a UNIX Environment” acknowledgements: Sam Leffler and Kirk McKusick, for their

work on the quota code.

The current disc quota system is loosely based on a very early scheme imple-

mented at the University of New South Wales and Syndey University.
The document, "Fsck - The UNIX File System Check Program”, is a revision by Marshall Kirk
McKusick; T.J. Kowalski wrote the original paper.

For their help and support, we thank Bill Joy, Sam

Leffler, Robert Elz, Dennis Ritchie, Robert Henry, Larry A. Wehr, and Rick B. Brandt.

Our sponsors

were the National Science Foundation under grant MCS80-05144, and the Defense Advance Research
Projects Agency (DoD) under Arpa Order No. 4031 monitored by Naval Electronic System Command

under Contract No. N00039-82-C-0235.
”A Fast File System for UNIX” acknowledgements: William N. Joy, Samuel J.

LefHler, Robert S. Fabry,

Marshall Kirk McKusick, Robert Elz, Michael Powell, Peter Kessler, Rober Henry, and Dennis Ritchie.
This work was done under grants from the National Science Foundation under grant MCS80-05144, and

the Defense Advance Research Projects Agency (DoD) under ARPA No. 4031 monitored by Naval Electronic System Command under Contract No. N00039-82-C-0235.
”4.2BSD Networking Implementation Notes” acknowledgements:

patterned after the Xerox PUP architecture [Boggs79].

The internal structure of the system is

The use of software interrupts for process invo-

cation is based on similar facilities found in the VMS operating system.

Many of the ideas are based on

Rob Gurwitz’s TCP/IP implementation for the 4.1BSD version of UNIX on the VAX [Gurwitz81]. Greg
Chesson explained his use of trailer encapsulations in Datakit, instigating their use in our system.

"SENDMAIL - An Internetwork Mail Router” acknowledgements:

For their ideas and assistance, Kurt

Shoens, Bill Joy, Mark Horton, Erick Schmidt, Kirk McKusick, Marvin Solomon, Mike Stonebraker, and
Bob Epstein.

A considerable part of this work was done while under the employ of the INGRES Project

at the University of California at Berkeley.

Vil

BEFORE YOU START

This is the first volume of ULTRIX-32 Supplementary Documents, a three volume set that
contains articles describing the ULTRIX-32 system. The authors are computer scientists and
program developers at Bell Laboratories and the University of California at Berkeley.

The

articles explain the software tools and utilities available on your ULTRIX-32 system.

They

constitute most of the lore that enriches this operating system; topics range from getting

started procedures to the details of screen updating and cursor movement facilities.
Each volume in this set contains several parts, and each part begins with an introduction.
Each introduction serves as a map that will help you find your way around in the documenta-

tion, allowing you to select articles that relate to your interest. Each introduction gives an
overview of the material covered in the part and a description of the articles included.

Most

readers will not need to read all articles in any part, since many articles cover parallel topics.
For example, Part 3 in this first volume contains articles describing several text editors.

should be able to choose one editor after reading the introduction;

You

then you can proceed to

the relevant article.

These articles provide authoritative and accurate information that is unavailable elsewhere.
However, you should be aware that some of the information in some articles is dated.

include those articles because many of the concepts they develop are still current and important.

At the end of each volume in this set, you will find a master index identifying topics for all
three volumes.

Topics in Volume I
This first volume contains articles written for general use.

You should find many of the arti-

cles helpful no matter how you plan to use your ULTRIX-32 system.

The two articles in Part

1 introduce the entire three-volume set; however, readers who are unfamiliar with operating

systems and programming and readers new to the ULTRIX-32 and UNIX systems should
begin with Part 2, Getting Started. The articles introduce basic concepts and demonstrate

simple procedures.

You will need to use a text editor if you plan to write (create or modify) files.

Part 3, Text

Editors, gives comprehensive information on five editors: ed, edit, vi, ex, and sed.
Articles

in Part 4,

ULTRIX-32 system:

Command

Interpreters,

introduce the two shells provided with the

the Bourne Shell and the C Shell.

Each shell serves as a set of handles

that gives the user access to the ULTRIX-32 utilities.
If you intend to use your ULTRIX-32 system to write and format any kind of document, you

will find the articles on Document Preparation in Part 5 essential.
formatting utilities.

Nroff and troff are text

In addition, the ULTRIX-32 software includes separate utilities that

cooperate with the formatters to help you typeset mathematical expressions, set up tables, and

create bibliographical references in your text.
Part 6 includes articles that tell about a variety of unsupported software.

Table of Contents

BEFORE YOU START
PART 1:

OVERVIEW

UNIX/32V - SUMMARY
WHAT’S NEW: HIGHLIGHTS OF THE UNIX/32V SYSTEM
.

e
e e e
1-4
.

Operating System .

User Access Control .

.. .. 1-3

SOFTWARE

. . .

Basic Software .

. . . . .

HARDWARE .

e e 1-4

..o

1-4

e 1-4

e 1-5

.00

0. [ 1-5

Status Inquiries .

Accounting

Backup and Maintenance
.

Communication .

File Manipulation .
Running of Programs

Terminal Handling

Manipulation of Directories and File Names

.o 1-5

. .
. .

. .
. S

. .

. . . . .

Computer-Aided Instruction

Languages .

The C Language.
Fortran .

Macroprocessing. .

Compiler-Compilers .

Other Algorithmic Languages.

Text Processing.

.«
.

s
e

e
e

e 1-6

e 1-7

e 1-9

e IR

.
e

... . ... 1-9
1-11
e

e
s

.. 1-6

... e

...

e 1-8

..
e

..o
.

Basic Program Development Tools . . .
UNIX/32V Programmer’s Manual. . . .
.

.
e

1-11

1-12

1-13

e
e

1-13

e
e

1-11

Document Preparation.

..o

1-13

Document Formatting .

..o

1-13

i e e e e e e e e

Information Handling.
Graphics .

. . . .e

e e e e e

Novelties, Games, and Things That Didn’t Fit Anywhere Else

e e

1-15
1-16

1-16

THE UNIX TIME-SHARING SYSTEM
INTRODUCTION .

1-19

HARDWARE AND SOFTWARE ENVIRONMENT . . . . . . . . . . . . . . .. . ...

1-20

THE FILE SYSTEM

1-20

e
e

1-20

.. e

.
.

Ordinary Files

Special Files .

Protection

I/O Calls .

Directories .

Removable File Systems

s
e

1-21

1-22

e
e

1-22
1-23

Table of Contents

THE UNIX TIME-SHARING SYSTEM (continued)
IMPLEMENTATION OF THE FILE SYSTEM.
PROCESSES AND IMAGES
Processes.

Pipes

THE SHELL .

....

. S

.. e

Implementation of the Shell.
Initialization .

Other Programs as Shell

Command Separators: Multitasking .

..,

The Shell as a Command: Command Files.

PART 2:

Standard I/O.

. oe,

Termination

Execution of Programs

TRAPS .

.
.

Process Synchronization.

Filters .

...

..o, e
e
e

...

GETTING STARTED

UNIX FOR BEGINNERS - SECOND EDITION
GETTING STARTED.

Logging In .

Typing Commands .

. .

Strange Terminal Behavior .
Mistakes in Typing .
Read-Ahead

Stopping a Program
Logging Out .
Mail .

L
.

...

Writing To Other Users.

On-Line Manual .

Printing Files.

.«

What’s in a Filename.

...

Using Files Instead of the Terminal .

The Shell

Shuffling Files About .

Pipes

...

Table of Contents

DOCUMENT PREPARATION.

2-12

Formatting Packages .

2-12

Supporting Tools .

L
e
e

2-13

Hints for Preparing Documents

2-13

PROGRAMMING . . . . . . . . . . . o, P

2-14

The Shell

...

2-14

Programming in C

Other Languages .

UNIX READING LIST

e
e e

Programming the Shell .

General

...

2-14

2-15

e
o

oL ..

Document Preparation

oo
e

2-16

Programming.

2-16

MAIL REFERENCE MANUAL
INTRODUCTION .

COMMON USAGE .

2-17

e
s s s e e

2-18

MAINTAINING FOLDERS

MORE ABOUT SENDING MAIL

Tilde Escapes

Special Recipients

Network Access.

Message Lists

. e

Custom Options

2-23

2-24

e
e

2-26

2-27

o
.

...

2-28

2-36
23T

s
e s e
e
.

2-28

2-33

SUMMARY OF COMMANDS, OPTIONS, AND ESCAPES.
CONCLUSION .

COMMAND LINE OPTIONS .
.

FORMAT OF MESSAGES

GLOSSARY.

List of Commands

2-38

.. L

2-39

2-41

BC - AN ARBITRARY PRECISION DESK-CALCULATOR LANGUAGE
INTRODUCTION .

SIMPLE COMPUTATIONS WITH INTEGERS
BASES .

...

2-43

...

s
s e
e e

2-44

2-45

FUNCTIONS .

SCALING.

o
e
e

SUBSCRIPTED VARIABLES

CONTROL STATEMENTS .

SOME DETAILS .

2-45

2-46

2-47

2-48

xii Table of Contents

BC - AN ARBITRARY PRECISION DESK-CALCULATOR LANGUAGE (continued)
APPENDIX .

e
s s e e s e

Notation .

Tokens.

... e

e
e

2-50

Comments

Identifiers.

.
s e e,

2-50

Keywords .

e
e e e
e,

2-50

Constants .

2-50

Expressions

Primitive Expressions

2-50

..o

2-51

..o .

2-51

. .

Function-Name

Length

Scale .

2-51

...

2-51

...

2-51

2-51
2-51

2-51

Unary Operators.

Parentheses

e
.

Constants

Sqrt.

Scale, Ibase and Obase.
Function Calls .

Array-Name.

Named Expressions.
Identifiers.

2-50

Exponentiation Operator.

..o

2-52

Multiplicative Operators .

..o

2-52

Additive Operators.

2-52

2-53

Assignment Operators .

2-53

Relations.

Storage Classes.
Statements.

2-53

2-54
2-54

Expression Statements.

..o

Compound Statements.

2-54

Quoted String Statements .

2-54

If Statements .

. e

2-54

While Statements .

2-54

For Statements

Break Statements .

2-54

Auto Statements.

2-55

Define Statements.

2-55

Return Statements.

2-55

Quit Statements.

2-55

... e
e e

2-54

Table of Contents

xiii

DC - AN INTERACTIVE DESK CALCULATOR
SYNOPTIC DESCRIPTION .

DETAILED DESCRIPTION .

o
.

Internal Representation of Numbers .

.
.
.

. . .
.
. . . . .
. . . . .

The Allocator. . . . . . . .
Internal Arithmetic. . . . .
Addition and Subtraction.
.

Multiplication

Division .

Remainder. . . . . . . . .
Square Root .

Exponentiation.

Output Commands .

Output Format and Base .

Internal Registers.

...

Stack Commands.

Subroutine Definitions and Calls

. e

Push-Down Registers and Arrays

2-57

2-59

2-61

2-62

2-63

...

e
e
.

2-62

2-61
2-61

2-61

..o

PART 3:

.00 P

Internal Registers Programming DC .

DESIGN CHOICES .

Miscellaneous Commands.

. . ... .
... 2-59
e
e
s e 2-59
e
e
e - 2-60
oo 2-60

Input Conversion and Base .
.

e s

2-62

2-63

TEXT EDITORS

EDIT: A TUTORIAL
INTRODUCTION .

SESSION 1.

e
e e
e . 3-5

Making Contact with UNIX.

Directly Linked Terminals .
Dial-Up Terminals.
Logging In

Asking for Edit.

. .

. . .

e
e 3-5

. .

Text Input Mode .

. .

..o 3-5

. .

Messages from Edit.

The “Command not found” Message .

Entering Text

3-3

A Summary .

.. ... e

.
s

e 3-5

oo 3-6

s 3-6

e 3-5
e

e 3-6

Writing TexttoDisk .

Signing Off.

e 3-8

Making Corrections.
.

e
.

e
e

...

e
e

.. e

e
e

e 3-7
e 3-7

e 3-8

xiv Table of Contents

EDIT: A TUTORIAL (continued)
SESSION 2.

3-9

Adding More Text tothe File .
Interrupt.

.. e

e 3-9

Lo 3-9

..., 3-9

Listing What’s in the Buffer.

Making Corrections.

Finding Things in the Buffer

The Current Line.

Numbering Lines .

Substitute Command .

...

3-10

...

3-11

...

3-12

3-13

3-14

Saving the Modified Text .

Another Way To List What’s in the Buffer.

SESSION 3.

..
.

Bringing Text into the Buffer .

Moving Text in the Buffer

...,

3-14

3-15
3-15

Copying Lines

Deleting Lines

...

3-14

A Word or Two of Caution

3-16

Undo to the Rescue.

3-16

Moving Around in the Buffer .

. .

‘Changing Lines.

SESSION 4.

...,

3-17

3-18

3-19

Making Commands Global

..o

3-19

3-20

Special Characters

...

3-20

...

3-21

Filenames and File Manipulation

...

3-21

...

3-21

..o,

3-22

...

3-22
3-22

.. e

directory

This is
that you are

Is > filelist

a list of your files will be placed in the file filelist

currently in:

(which will be created if it doesn’t already exist,

cd /usr/your-friend

(On some systems, cd is spelled chdir.) Now
when you use a filename in something like cat or

pr, it refers to the file in your friend's directory.
Changing directories doesa’t affect any permis-

sions associated with a file = if you couldn't
access a file from your own directory, changing
to another directory won't alter that fact.

or overwritten if it does). The symbol > means
**put the output on the following file, rather than

on the terminal.”” Nothing is produced on the
terminal.

cat fl f2 3 >temp

course, if you forget what directory you're in,
type

As another example, you could coms-

bine several files into one by capturing the output of cat in a file:

The symbol > > operates very much like >
does, except that it means ‘‘add to the end of.”

That is,

pwd

cat f1 2 3 > >temp

to find out.
It is usually convenient to arrange your own

means to concatenate f1, f2 and {3 to the end of

files so that all the files related to one thing are

whatever is already in temp, instead of overwrit-

in a directory separate. from other projects.

For

example, when you write your book, you might

ing the existing contents.

want to keep all the text in a directory called

book. So make one with

As with >, if temp

doesn’t exist, it will be created for you.
In a similar way, the symbol <

means to

take the input for a program from the following

file, instead of from the terminal.

Thus, you

could make up a script of commonly used editing
commands and put them into a file cailed seript.

Then you can run the script on a file by saying
then

start

typing chapters.

The

found in (presumably)
/usr/your-name/book
To remove the directory book, type

rm book/*®
rmdir book

book

ed file <script

now

As another example, you can use ed to prepare a

letter in file let, then send it to several people
with

mail adam eve mary joe <let

UNIX For Beginners

2-11

Pipes

The Shell

One of the novel coatributions of the UNIX
sysitem is the idea of a pipe. A pipe is simply a

the mysterious “‘sheil.”” whnich is in fact sh(l).

We have already menuoned once or twice

way to connec: the output of one program (o the

The shell is the program ihat interpre:s what you

input of another program. so the (wo run as a
sequence of processes - a pipeline.

after translating ®, etc., into lists of flenames,

For example,

type as commands and arguments.

[t aiso looks

and <, >. and | into changes of input and output streams.

prfgh

The shell has other capabilities t0o.

For

will print the files f, g, and h, beginning each on

example, you can run two programs with one

a new page. Suppose you want
together instead. You could say

command line by separating the commands with

them

run

a sermicolon:; the shell recognizes the semicolon

and breaks the line into wo commands. Thus

cat fg h >temp

date: who

pr <temp
PR temp

does both commands before ceturning with

but this is more work than necessary. Clearly
what we want i (0 take the output of cat and
connect it o the input of pr. So let us use a
pipe:

cacfg hlpe
The vertical bar | means to take the output from
cat, which would normally have gone to the ter-

You can also have more than one program
cunning simultaneously if vou wish. For example,
if you are doing something time-consuming, like
the editor script of an earlier section, and vyou
don't want to wait around for the results before
starting something eise, you can say
ed file <script &

minal, and put it into pr to be neatly formatted.
There are many other examples of pipes.
For example,

Is | pr =3
prints a list of your files in three columns. The
program we counts the number of lines, words
and characters in its input, and as we saw earlier,
who prints a list of currently-logged on people,

The ampersand at the end of a command line
says ‘°start this command running, then take
further commands f(rom the terminal immediately,’”” that is, don't wait for it 0 complete.
Thus the script will begin. but vou can do something else at the same time. Of course, (0 keep
the output from interfering with what you're
doing on the terminal. it would be better to say

one per line. Thus

ed file <script >script.@ut &

who | we

which

tells how many people are logged on.

prompt character.

And of

course

saves

the output

lines

in a file

called

script.out.

When you initiate 3 command with &. the
system replies with 2 number called the process

Is | we

number. which identifies the command in case

counts your files.

you later want to stop it. [f vou do, you can say

Any program that reads from the terminal
‘can read from a pipe instead; any program that
writes on the terminal can drive a pipe. You can

If you forget the process number. the command

have as many elements in a pipeline as you wish.

ps will tell you about everything vou nave run-

Many UNIX programs are written so that

they will take their input from one or more files
if file arguments are given:; if no arguments are
given they will read {rom the termiinal, and thus
can be used in pipelines. pr is one example:

pr =3 abe

prints files a, b and ¢ in order in three columns.
But in
[

]

catabecipr =3

pr prints the information coming down the pipeline, still in three columns.

kill process-number

ning. (If you are desperate, kill0 will kiil all
your processes.) And if you're curious about
other people,

ps a will

tell you about a#f pro-

grams that are currently running.

You can say

(command-1: command-2; command-3) &
1o start thres commands in the background. or
you can start a background pipeline with

command-1 | command-2 %
Just as you can tell the editor or some simi-

2-12

UNIX For Beginners

lar program to take its input from a file instead
of from the terminal, you can tell the shell to

read a file to get commands.

(Why not? The

shell, after all, is just a program, albeit a clever

one.) For instance, suppose you want to set tabs
on your terminal, and find out the date and
who's on

the

system every

time you

log

in.

Because nroff and troff are relatively hard to
learn to use effectively, several *‘packages’’ of
canned formatting requests are available to let
you specily paragraphs, running titles, footnotes,
multi-column output, and so on, with little effort
and

without

having

learn

nroff and

troff.

These packages take a modest effort to learn, but

Then you can put the three necessary commands

the rewards for using them are so great that it is

(tabs, date, who) into a file, let’s call it startup,

time well spent.

and then run it with

In this section, we will provide a hasty look
at the **manuscript’” package known as

sh startup

This says to run the shell with the file startup as
input. The effect is as if you had typed the contents of startup on the terminal.

and two upper-case letters, such as .TL, which is

used to introduce a title, or .PP to begin a new
paragraph.

If this is to be a regular thing, you can eliminate the need to type sh: simply type, once only,
the command

A document is typed so it looks something

like this:

.TL

chmod +x startup

title of document
AU

and thereafter you need only say

author name

startup

run

the

SH
sequence

commands.

section heading

The

chmod(l) command marks the file executable;
the

shell

recognizes

this

and

runs

paragraph ...

sequence of commands.
If you want

to the shell in the section on programming.

[1I. DOCUMENT PREPARATION
UNIX systems are used extensively for docu-

ment preparation.

another paragraph ...

startup to run automatically

every time you log in, create a file in your login
directory called .profile, and place in it the line
startup. When the shell first gains control when
you log in, it looks for the .profile file and does
whatever commands it finds in it. We'll get back

There are two major format-

ting programs, that is, programs that produce a

text with justified right margins, automatic page
numbering and titling, automatic
and the like.

—ms.

Formatting requests typically consist of a period

hyphenation,

nroff is designed to produce output

SH
another section heading
PP
etc.

The lines that begin with a period are the formatting requests. For example, .PP calls for
starting a new paragraph. The precise meaning
of .PP depends on what output device is being

used (typesetter or terminal, for instance), and
on what publication the document will appear in.

For

example,

—ms

normally

assumes

that a

paragraph is preceded by a space (one line in
nroff, "2 line in troff), and the first word is
indented. These rules can be changed if you
like,

but

they

are

changed

changing

the

on terminals and line-printers.
troff (pronounced ‘‘tee-roff’’) instead drives a photo-

interpretation of .PP, not by re-typing the docu-

typesetter, which produces very high quality out-

To actually produce a document in standard
format using —ms, use the command

put on photographic paper.

This paper was for-

matted with troff.

troff —ms files ...

Formatting Packages

for the typesetter, and

The basic idea of nroff and troff is that the
text to be formatted contains within it ‘‘format-

(ing commands’’ that indicate in detail how the

formatted text is to look.

ment.

For example, there

might be commands that specify how long lines
are, wnetwner to use
singie or Yl
doupie
spacing,
and
o o S
Rl Nl
| oA
IQQ

what running titles 1o use on each page.

nroff —ms files ...

for a terminal.

The —ms argument tells troff

and aroff to use the manuscript package of formatting requests.
T
There

are

cavusEa )
several

similar

packages;

chec

with a local expert to determine which ones are

in common use on your machine.

UNIX For Beginners

Supporting T ools

we counts the words, lines and characters in

[n addition to the basic formatters, thers is a
host of supporting programs that help with docu-

ment preparation. 1ne list in the next few paragraphs is far {rom complete, so browse through

a set of files. tr translates characters into other
characters; for example it will convert upper (o
lower case and vice versa. This translates upper
into lower:

the manual and check with people around you

tr A=Z a—z <input >output

for other possibilities.
eqn and neqn le¢ you integrate mathernatics

into the text of a document, in an easy-io-learn
language that closely resembles the way you
would speak it aloud.
For example, the egn
input
|

sum from (=0 tou x sub i " =" pi over 2

por

necessary to align complicated
¢columns with elements of varying widths.

refer prepares hibliographic citations from a

data base, in whatever style is defined by the formatting package. It looks after all the details of
aumbering refecences in sequence, flling in page
and volume numbers, getting the author’s initials
ang the journal aame right, and so on.

spell and typo detect possible spelling misspell works by comparing

in your document

dictionary,

printing those that are not in the dictionary.

It
knows enougi about English spelling to detect
plurals and the like, so it does a very good ob.

typo looks {or words which are ‘‘unusual’, and

Spelling mistakes tend to be more

unusual, and thus show up early when the maost

unusual words are printed first.
grep looks through a set of files for lines
that contain a particular text pattern (rather like
the editor’s context search does, but on a bunch

of files). For example,
grep 'ingd chap®
will find all lines that end with the letters ing in

the files chap®.
ice

put

(It is almost always a good prac-

single
-'.-‘.l

them to arbitrarcily long inputs.

quotes

awk provides the

ability to do both pattern matching and numesic

computations, and to conveniently procass feids
lines.

These

users.

and

programs

are

for

they

not

limited

are

Put them on your list of

things to learn about.

comiputations

takes in 2 document.

sed provides

many of the editing facilities of ed, dut can apply

document preparation.

The program tbl provides an analogous service for preparing tabular material; it does all the

prints those.

index (keyword-in-context listing).

advanced

”

words

sort sorts flles in a variety of ways: cref
makes cross-references: pex makes a permuted

within

sroduces the output

the

2-13

around

0 B oam om0 am wd a2 s ood

the

patiern
mnem
0D o emam

you're searching for, in case it contains characters like ® or 3 that have a special meaning to the

sheil.) grep is oftea useful for finding out in
whichi of a set of files the misspeiled words
detected by spell are actually located.

diff prints 2 list of the differences between
two files, so vou can compare wo versioas of
something automaticaily (which certainly beats
proofreading by hand).

Most of these programs are zither indepen-

dently documented (like eqn and tbl), or are
sufficiently simple that the description in the
UNIX Programmer's Manua( is adequate sxplanation.

Hints for Preparing Documents
Most documents go through several versions

(always more than you expected) before they are

finally

finished.

Accoedingly,

you

should

whatever possible (0 make the job of changing

them easy.

First, when you do the purely mechanical
tvpe so that subsegue:at
editing will be easy. Start sach sentence ona a
new line. Make lines short, and Sreak lines at
operations of typing,

natural places. such as after commas ind semicolons. rather than randomly.
change

documents

Since most people

rewriting

phrases

aind

adding, deleting and rearranging sentencss, these

precautions simplify any editing vou have 10 do
later.

Keep

the

individual

files of 2 document

down (o modest size, perhaps ten to fifteen
thousand characiers.
Larger fles edit more
slowly, and of course if you make a dumb mistake it's better 0 have clobbered a small file
than a big one. Split into files at natural boundaries in the document, {or the same reasons
that you suart eactl seatencs on a riew line.

The second aspect of making change 2asy (s
t0 not commit vourself to formatting decails (00

early.

One of the advantages of formatting oack-

ages like —ms is that they permit vou to delay
decisions to the last possible moment.
until

document

decided whether it will
printer.

printed.

1§

[ndaed.
not

aven

be typeset or sut on a iine

2-14

UNIX For Beginners

As a rule of thumb, for all but the most
trivial jobs, you should type a document in terms

commands (using the global commands of ed),
and write it into script.

of a set of requests like .PP, and then define

ed <script

them appropriately, either by using one of the

canned packages (the better way) or by defining
your own nroff and troff commands.

As long as

Now the command

will produce the same output as the laborious

hand typing.

Alternately (and more easily), you

you have entered the text in some systematic

can use the fact that the shell will perform loops,

way,

repeating a set of commands over and over again

can

always

cleaned

and

re-

formatted by a judicious combination of editing

for a set of arguments:

commands and request definitions.

for | in chap®
do

There will be no attempt made to teach any
of the programming languages available but a
few words of advice are in order. One of the
reasons why the UNIX system is a productive

programming

eavironment

that

there

already a rich set of tools available, and facilities

like pipes, 1/0 redirection, and the capabilities of
the shell often make it possible to do a job by
pasting

together programs that
instead of writing from scratch.

already

exist

This sets the shell variable { to each file name in
turn, then does the command.

You can type this

command at the terminal, or put it in a file for
later execution.

Programming the Shell
An option often overlooked by newcomers is
that the shell is itself a programming language,
with variables, control flow (if-else, while, for,

case), subroutines, and interrupt handling. Since

The Shell

The pipe mechanism lets you fabricate quite
complicated operations out of spare parts that
already exist. For example, the first draft of the

spell program was (roughly)
collect the files

tF .o

put each word on a new line

delete puncuation, .

sort

into dictionary order

unig

discard duplicates

comm

print-words in text

the UNIX Shell by S. R. Bourne.
Programming in C

If you are undertaking anything substantial,

C is the only reasonable choice of programming

this goes a long way for such a small effort.
special

programs

language: everything in the UNIX system is tuned

to it.

The system itself is written in C, as are

most of the programs that run on it.

The editor can be made to do things that
require

by ptecing together some of the building blocks
with shell command files.

ples and rules can be found in 4An /neroduction to

More pieces have been added subsequently, but

normally

there are many building-block programs, you can

sometimes avoid writing a new program merely

We will not go into any details here; exam-

cat ...

bug not in dictionary

would

ed $t <script
done

It is also a

easy language to use once you get started.

C is

introduced and fully described in The C Program-

other systems. For example, to list the first and
last lines of each of a set of files, such as a book,

Ritchie (Prentice-Hall, 1978).

you could laboriously type

of the manual describe the system interfaces,

Several sections

that is, how you do I/O and similar functions.

Read

e chapl.l

UNIX Programming for more complicated

things.

Most input and output in C is best handled

with the standard [/O library, which provides a

e chapl.2

set of [/O functions that exist in compatible
form on most machines that have C compilers.
In general, it's wisest to confine the system

etc.

But you can do the job much more easily.

One

way is (o type

interactions in a program to the facilities provided by this library.

C programs that don’t depend too much on

Is chap® > temp
to get the list of filenames into a file.

ming Language by B. W. Kernighan and D. M.

special features of UNIX (such as pipes) can be
Then edit

this file to make the necessary series of editing

moved

to other computers

pilers.

The list of such machines grows daily: in

addition

the

ornginal

that

PDP-11,

have
it

com-

currently

2-16

UNIX For Beginners

most formatting situations.

If this specific pack-

age isn't available on your system, something

similar probably is. The most likely alternative is
the PWB/UNIX macro package

--mm; see your

local guru if you use PWB/UNIX.

B. W. Kernighan and L. L. Cherry, ‘““A System
for Typesetting Mathematics,’’ Bell Laboratories
Computing Science Tech. Rep. 17.
M. E. Lesk, *“Tbl — A Program to Format
Tables,” Bell Laboratories CSTR 49, 1976.
J. F. QOssanna, Jr., “NROFF/TROFF User’s
Manual,” Bell Laboratories CSTR 54, 1976.
troff is the basic formatter used by —ms, eqn
and thl The reference manual is indispensable
if you are going to write or maintain these or
similar programs. But start with:

B. W. Kernighan, ‘A TROFF Tutorial,”” Bell
Laboratories, 1976. An attempt to unravel the
intricacies of troff.
Programming:

B. W. Kernighan and D. M. Ritchie, The C Programming Language, Prentice-Hall, 1978. Contains a tutorial introduction, complete discussions
of all language features, and the reference
manual.

B. W. Kernighan and D. M. Ritchie, ‘““UNIX Programming,”’ Bell Laboratories, 1978. Describes
how to interface with the system from C programs: /0 calls, signals, processes.
S.

R. Bourne, ‘‘An Introduction to the UNIX

Shell,”” Bell Laboratories, 1978. An introduction
and reference manual for the Version 7 shell.
Mandatory reading if you intend to make
effective use of the programming power of this
shell.

S. C. Johnson, “‘Yacc — Yet Another CompilerCompiler,” Bell Laboratories CSTR 32, 1978.
M. E. Lesk, ““Lex — A Lexical Analyzer Gen| erator,’”’ Bell Laboratories CSTR 39, 1975.

S. C. Johnson, ‘“‘Lint, a C Program Checker,”
Bell Laboratories CSTR 65, 1977.
S. 1. Feldman, “MAKE — A Program for Maintaining Computer Programs,’’ Bell Laboratories
CSTR 57, 1977.

J. F. Maranzano and S. R. Bourne, ‘““A Tutorial
Introduction to ADB,”" Bell Laboratories CSTR
62,

1977.

An introduction

to a powerful but

complex debugging tool.

S. 1. Feldman and P. J. Weinberger, ‘A Portable
Fortran 77 Compiler,’”’ Bell Laboratories,
A full Fortran 77 for UNIX systems.

1978.

Mail Reference Manual 2-17

MAIL REFERENCE MANUAL

Kurt Shoens

Revised by
Craig Leres
Version 2.18

1. Introduction

Mail provides a simple and friendly environment for sending and receiving mail. It
divides incoming mail into its constituent messages and allows the user to deal with them in
any order. In addition, it provides a set of ed-like commands for manipulating messages and
sending mail. Mail offers the user simple editing capabilities to ease the composition of outgoing messages, as well as providing the ability to define and send to names which address
groups of users. Finally, Mail is able to send and receive messages across such networks as
|
the ARPANET, UUCP, and Berkeley network.
This document describes how to use the Mail program to send and receive messages.
The reader is not assumed to be familiar with other message handling systems, but should be

familiar with the UNIX! shell, the text editor, and some of the common UNIX commands. “The
UNIX Programmer’s Manual,” “An Introduction to Csh,” and “Text Editing with Ex and Vi”
can be consulted for more information on these topics.

Here is how messages are handled: the mail system accepts incoming messages for you
from other people and collects them in a file, called your system mailbox. When you login,
the system notifies you if there are any messages waiting in your system mailbox. If you are a
csh user, you will be notified when new mail arrives if you inform the shell of the location of
your mailbox. On version 7 systems, your system mailbox is located in the directory
/usr/spool/mail in a file with your login name. If your login name is “sam,” then you can
make csh notify you of new mail by including the following line in your .cshrc file:
set mail=/usr/spool/mail/sam

When you read your mail using Mail, it reads your system mailbox and separates that file into
the individual messages that have been sent to you. You can then read, reply to, delete, or
save these messages. Each message is marked with its author and the date they sent it.

2-18

Mail Reference Manual

Common usage
The Mail command has two distinct usages, according to whether one wants to send or

receive mail.

Sending mail is simple:

to send a message to a user whose login name is, say,

“root,” use the shell command:

% Mail root

then type your message. When you reach the end of the message, type an EOT (control—d) at
the beginning of a line, which will cause Mail to echo “EOT” and return you to the Shell.
When the user you sent mail to next logs in, he will receive the message:
You have mail.
to alert him to the existence of your message.
If, while you are composing the message you decide that you do not wish to send it after
all, you can abort the letter with a RUBOUT. Typing a single RUBOUT causes Mail to print

(Interrupt -- one more to kill letter)
Typing a second RUBOUT causes Mail to save your partial letter on the file “dead.letter” in

your home directory and abort the letter.

way to undo the act, so be careful.

Once you have sent mail to someone, there is no

The message your recipient reads will consist of the message you typed, preceded by a
line telling who sent the message (your login name) and the date and time it was sent.
If you want to send the same message to several other people, you can list their login

names on the command line.

Thus,

% Mail sam bob john
Thuition fees are due next Friday.

Don’t forget!!

<Control—d>

EOT

%0
will send the reminder to sam, bob, and john.
If, when you log in, you see the message,

You have mail.
you can read the mail by typing simply:

% Mail
Mail will respond by typing its version number and date and then listing the messages you
have waiting. Then it will type a prompt and await your command. The messages are
assigned numbers starting with 1 — you refer to the messages with these numbers. Mail keeps
tack of which messages are new (have been sent since you last read your mail) and read (have

been read by you). New messages have an N next to them in the header listing and old, but
unread messages have a U next to them. Mail keeps track of new/old and read/unread messages by putting a header field called “Status” into your messages.
ply t.

To look at a specific message, use the type command, which may be abbreviated to simFor example, if you had the following messages:

N 1root

Wed Sep 21 09:21

N 2 sam

Tue Sep 20 22:55

"Tuition fees”

you could examine the first message by giving the command:
type 1

which might cause Mail to respond with, for example:
Mlessage

Mail Reference Manual 2-19

From root Wed Sep 21 09:21:45 1978
Subject: Tuition fees
Status: R

Tuition fees are due next Wednesday. Don’t forget!!

Many Mail commands that operate on messages take a message number as an argument like
the type command. For these commands, there is a notion of a current message. When you
enter the Mail program, the current message is initially the first one. Thus, you can often
omit the message number and use, for example,
t

to type the current message. As a further shorthand, you can type a message by simply giving
its message number.

Hence,

would type the first message.

Frequently, it is useful to read the messages in your mailbox in order, one after another.
You can read the next message in Mail by simply typing a newline. As a special case, you can
type a newline as your first command to Mail to type the first message.
If, after typing a message, you wish to immediately send a reply, you can do so with the

reply command. Reply, like type, takes a message number as an argument. Mail then
begins a message addressed to the user who sent you the message. You may then type in your
letter in reply, followed by a <control-d> at the beginning of a line, as before. Mail will type
EOT, then type the ampersand prompt to indicate its readiness to accept another command.
In our example, if, after typing the first message, you wished to reply to it, you might give the
command:
reply

Mail responds by typing:
To: root

Subject: Re: Tuition fees

and waiting for you to enter your letter.

You are now in the message collection mode

described at the beginning of this section and Mail will gather up your message up to a
control—d. Note that it copies the subject header from the original message. This is useful in
that correspondence about a particular matter will tend to retain the same subject heading,
making it easy to recognize. If there are other header fields in the message, the information
found will also be used. For example, if the letter had a “To:” header listing several recipients, Mail would arrange to send your replay to the same people as well. Similarly, if the
original message contained a “Cc:” (carbon copies to) field, Mail would send your reply to
those users, too. Mail is careful, though, not too send the message to you, even if you appear

in the “To:” or “Ce:” field, unless you ask to be included explicitly. See section 4 for more
details.

fter typing in your letter, the dialog with Mail might look like the following:
reply
To: root

Subject: Tuition fees
Thanks for the reminder
EOT
&

2-20 Mail Reference Manual

The reply command is especially useful for sustaining extended conversations over the
message system, with other “listening’ users receiving copies of the conversation.

The reply

command can be abbreviated to r.
Sometimes you will receive a message that has been sent to several people and wish to
reply only to the person who sent it.

Reply with a capital R replies to a message, but sends a

copy to the sender only.
If you wish, while reading your mail, to send a message to someone, but not as a reply to

one of your messages, you can send the message directly with the mail command, which takes
as arguments the names of the recipients you wish to send to. For example, to send a message
to “frank,” you would do:
mail frank
This is to confirm our meeting next Friday at 4.

EOT

&
The mail command can be abbreviated to m.

Normally, each message you receive is saved in the file mbox in your login directory at
the time you leave Mail.

Often, however, you will not want to save a particular message you

have received because it is only of passing interest.

To avoid saving a message in mbox you

can delete it using the delete command. In our example,

delete 1

will prevent Mail from saving message 1 (from root) in mbox. In addition to not saving
deleted messages, Mail will not let you type them, either. The effect is to make the message
disappear altogether, along with its number.

The delete command can be abbreviated to

simply d.
Many features of Mail can be tailored to your liking with the set command.

The set

command has two forms, depending on whether you are setting a binary option or a valued
option.

Binary options are either on or off.

For example, the “ask” option informs Mail that

each time you send a message, you want it to prompt you for a subject header, to be included
in the message.

To set the “ask” option, you would type

set ask
Another useful Mail option is “hold.” Unless told otherwise, Mail moves the messages
from your system mailbox to the file mbox in your home directory when you leave Mail.

you want Mail to keep your letters in the system mailbox instead, you can set the ‘“hold”

option.

Valued options are values which Mail uses to adapt to your tastes.

For example, the

“SHELL” option tells Mail which shell you like to use, and is specified by

set SHELL=/bin/csh
for example.

Note that no spaces are allowed in “SHELL=/bin/csh.” A complete list of the

Mail options appears in section 5.
Another important valued option is “crt.” If you use a fast video terminal, you will find
that when you print long messages, they fly by too quickly for you to read them.

With the

“crt” option, you can make Mail print any message larger than a given number of lines by

sending it through the paging program more.

For example, most CRT users should do:

set crt=24

to paginate messages that will not fit on their screens. More prints a screenful of information,
then types --MORE--.

Type a space to see the next screenful.

Mail Reference Manual 2-21

Another adaptation to user needs that Mail provides is that of aliases.

An alias is sim-

ply a name which stands for one or more real user names. Mail sent to an alias is really sent

to the list of real users associated with it. For example, an alias can be defined for the
members of a project, so that you can send mail to the whole project by sending mail to just a
single name.

The alias command in Mail defines an alias.

Suppose that the users in a pro-

ject are named Sam, Sally, Steve, and Susan. To define an alias called “project” for them, you
would use the Mail command:
alias project sam sally steve susan
The alias command can also be used to provide a convenient name for someone whose user
name Is inconvenient.

For example, if a user named “Bob Anderson” had the login name

“anderson,”” you might want to use:

alias bob anderson

so that you could send mail to the shorter name, “bob.”
While the alias and set commands allow you to customize Mail, they have the drawback that they must be retyped each time you enter Mail. To make them more convenient to

use, Mail always looks for two files when it is invoked.

It first reads a system wide file

“/usr/lib/Mail.rc,” then a user specific file, “.mailre,” which is found in the user’s home directory.

The system wide file is maintained by the system administrator and contains set com-

mands that are applicable to all users of the system. The “.mailrc” file is usually used by each

user to set options the way he likes and define individual aliases. For example, my .mailrc file
looks like this:

set ask nosave SHELL=/bin/csh
As you can see, it is possible to set many options in the same set command.

The “nosave”

option is described in section 5.

Mail aliasing is implemented at the system-wide level by the mail delivery system sendmail. These aliases are stored in the file /usr/lib/aliases and are accessible to all users of the
system. The lines in /usr/lib/aliases are of the form:

alias: name, name,, name,
where alias is the mailing list name and the name, are the members of the list. Long lists can
be continued onto the next line by starting the next line with a space or tab.

Remember that

you must execute the shell command newaliases after editing /usr/lib/aliases since the
delivery system uses an indexed file created by newaliases.
We have seen that Mail can be invoked with command line arguments which are people
to send the message to, or with no arguments to read mail.

Specifying the —f flag on the com-

mand line causes Mail to read messages from a file other than your system mailbox.

For

example, if you have a collection of messages in the file “letters” you can use Mail to read
them with:

% Mail —f letters
You can use all the Mail commands described in this document to examine, modify, or delete
messages from your “letters” file, which will be rewritten when you leave Mail with the quit

command described below.
Since mail that you read is saved in the file mbox in your home directory by default, you
can read mbox in your home directory by using simply

% Mail —f

Normally, messages that you examine using the type command are saved in the file
“mbox” in your home directory if you leave Mail with the quit command described below.
11

AECFTAR

you wish to retain a message in your system mailbox you can use the preserve command to

2-22 Mail Reference Manual

tell Mail to leave it there.

The preserve command accepts a list of message numbers, just

like type and may be abbreviated to pre.
Messages in your system mailbox that you do not examine are normally retained in your

system mailbox automatically.

If you wish to have such a message saved in mbox without

reading it, you may use the mbox command to have them so saved.

For example,

mbox 2

in our example would cause the second message (from sam) to be saved in mbox when the
quit command is executed.

Mbox is also the way to direct messages to your mbox file if you

have set the “hold” option described above.

Mbox can be abbreviated to mb.

When you have perused all the messages of interest, you can leave Mail with the quit
command, which saves the messages you have typed but not deleted in the file mbox in your
login directory.

Deleted messages are discarded irretrievably, and messages left untouched are

preserved in your system mailbox so that you will see them the next time you type:

% Mail
The quit command can be abbreviated to simply q.
If you wish for some reason to leave Mail quickly without altering either your system

mailbox or mbox, you can type the x command (short for exit), which will immediately
return you to the Shell without changing anything.

If, instead, you want to execute a Shell command without leaving Mail, you can type the

command preceded by an exclamation point, just as in the text editor. Thus, for instance:

ldate
will print the current date without leaving Mail.

Finally, the help command is available to print out a brief summary of the Mail commands, using only the single character command abbreviations.

Mail Reference Manual 2-23

3. Maintaining folders

Mail includes a simple facility for maintaining groups of messages together in folders.

This section describes this facility.

To use the folder facility, you must tell Mail where you wish to keep your folders. Each
folder of messages will be a single file. For convenience, all of your folders are kept in a single
directory of your choosing. To tell Mail where your folder directory is, put a line of the form
set folder=letters

in your .mailrc file. If, as in the example above, your folder directory does not begin with a

‘/ Mail will assume that your folder directory is to be found starting from your home direc-

tory. Thus, if your home directory is /usr/person the above example told Mail to find your
folder directory in /usr/person/letters.

Anywhere a file name is expected, you can use a folder name, preceded with ‘+.” For
example, to put a message into a folder with the save command, you can use:
save +classwork

to save the current message in the classwork folder. If the classwork folder does not yet exist,
it will be created. Note that messages which are saved with the save command are automati-

cally removed from your system mailbox.

In order to make a copy of a message in a folder without causing that message to be
removed from your system mailbox, use the copy command, which is identical in all other
respects to the save command. For example,
copy +classwork

copies the current message into the classwork folder and leaves a copy in your system mailbox.

The folder command can be used to direct Mail to the contents of a different folder.
For example,

folder +classwork

directs Mail to read the contents of the classwork folder. All of the commands that you can
use on your system mailbox are also applicable to folders, including type, delete, and reply.
To inquire which folder you are currently editing, use simply:
folder

To list your current set of folders, use the folders command.

To start Mail reading one of your folders, you can use the —f option described in section
2. For example:

% Mail —f +classwork

will cause Mail to read your classwork folder without looking at your system mailbox.

2-24

Mail Reference Manual

More about sending mail

4.1. Tilde escapes

While typing in a message to be sent to others, it is often useful to be able to invoke the

text editor on the partial message, print the message, execute a shell command, or do some
other auxiliary function. Mail provides these capabilities through tilde escapes, which consist

of a tilde (") at the beginning of a line, followed by a single character which indicates the function to be performed. For example, to print the text of the message so far, use:
~

which will print a line of dashes, the recipients of your message, and the text of the message

so far.

Since Mail requires two consecutive RUBOUT’s to abort a letter, you can use a single

RUBOUT to abort the output of "p or any other ~ escape without killing your letter.
If you are dissatisfied with the message as it stands, you can invoke the text editor on it

using the escape
L

which causes the message to be copied into a temporary file and an instance of the editor to
be spawned. After modifying the message to your satisfaction, write it out and quit the editor.
Mail will respond by typing

(continue)
after which you may continue typing text which will be appended to your message, or type
<control-d> to end the message.

A standard text editor is provided by Mail.

ride this default by setting the valued option “EDITOR” to something else.

You can over-

For example, you

might prefer:

set EDITOR=/usr/ucb/ex
Many systems offer a screen editor as an alternative to the standard text editor, such as
the vr editor from UC Berkeley.

To use the screen, or visual editor, on your current message,

you can use the escape,
for

\Y%

“v works like “e, except that the screen editor is invoked instead.
defined by Mail.

A default screen editor is

If it does not suit you, you can set the valued option “VISUAL” to the path

name of a different editor.

It is often useful to be able to include the contents of some file in your message; the
escape

“r filename

is provided for this purpose, and causes the named file to be appended to your current mes-

sage. Mail complains if the file doesn’t exist or can’t be read.

If the read is successful, the

number of lines and characters appended to your message is printed, after which you may

continue appending text.

The filename may contain shell metacharacters like * and ?

which

are expanded according to the conventions of your shell.
As a special case of “r, the escape
d
reads in the file “dead.letter” in your home directory.

This is often useful since Mail copies

the text of your message there when you abort a message with RUBOUT.
To save the current text of your message on a file you may use the
"w filename

escape. Mail will print out the number of lines and characters written to the file, after which

Mail Reference Manual 2-25

you may continue appending text to your message. Shell metacharacters may be used in the
filename, as in “r and are expanded with the conventions of your shell.
If you are sending mail from within Mail’s command mode you can read a message sent
to you into the message you are constructing with the escape:
m 4

which will read message 4 into the current message, shifted right by one tab stop. You can
name any non-deleted message, or list of messages.

Messages can also be forwarded without

shifting by a tab stop with “f. This is the usual way to forward a message.
If, in the process of composing a message, you decide to add additional people to the list
of message recipients, you can do so with the escape
"t namel name?2 ...

You may name as few or many additional recipients as you wish. Note that the users originally on the recipient list will still receive the message; you cannot remove someone from the
recipient list with “t.

If you wish, you can associate a subject with your message by using the escape
“s Arbitrary string of text

which replaces any previous subject with “Arbitrary string of text.” The subject, if given, is
sent near the top of the message prefixed with “Subject:” You can see what the message will
look like by using “p.

For political reasons, one occasionally prefers to list certain people as recipients of car-

bon copies of a message rather than direct recipients. The escape
“¢c namel name2 ...

adds the named people to the “Cec:” list, similar to "t. Again, you can execute "p to see what
the message will look like.

The recipients of the message together constitute the “To:” field, the subject the “Subject:” field, and the carbon copies the “Cc:” field. If you wish to edit these in ways impossible
with the “t, s, and “c escapes, you can use the escape
“h

which prints “To:” followed by the current list of recipients and leaves the cursor (or print-

head) at the end of the line. If you type in ordinary characters, they are appended to the end
of the current list of recipients. You can also use your erase character to erase back into the
list of recipients, or your kill character to erase them altogether. Thus, for example, if your
erase and kill characters are the standard # and @ symbols,
»
“h

To: root kurt####bill

would change the initial recipients “root kurt” to “root bill.” When you type a newline, Mail
advances to the ‘“Subject:” field, where the same rules apply. Another newline brings you to
the “Cc:” field, which may be edited in the same fashion. Another newline leaves you appending text to the end of your message. You can use “p to print the current text of the header
fields and the body of the message.
To effect a temporary escape to the shell, the escape

“lcommand

is used, which executes command and returns you to mailing mode without altering the text of
your message. If you wish, instead, to filter the body of your message through a shell command, then you can use
“lcommand

2-26

Mail Reference Manual

which pipes your message through the command and uses the output as the new text of your
message. If the command produces no output, Mail assumes that something is amiss and
retains the old version of your message.

A frequently-used filter is the command fmt,

designed to format outgoing mail.

To effect a temporary escape to Mail command mode instead, you can use the
“Mail command

escape.

This is especially useful for retyping the message you are replying to, using, for exam-

ple:
~it

It is also useful for setting options and modifying aliases.
If you wish (for some reason) to send a message that contains a line beginning with a
tilde, you must double it.

Thus, for example,

““This line begins with a tilde.
sends the line
“This line begins with a tilde.
Finally, the escape
~9

prints out a brief summary of the available tilde escapes.

On some terminals (particularly ones with no lower case) tilde’s are difficult to type.
Mail allows you to change the escape character with the “escape” option.

For example, I set

set escape=|]

and use a right bracket instead of a tilde.
bracket, I double it, just as for .

If I ever need to send a line beginning with right

Changing the escape character removes the special meaning

of ~.

4.2,

Network access

This section describes how to send mail to people on other machines.
ing to a plain login name sends mail to that person on your machine.

Recall that send-

If your machine is

directly (or sometimes, even, indirectly) connected to the Arpanet, you can send messages to
people on the Arpanet using a name of the form
name@host

where name is the login name of the person you're trying to reach and host is the name of the
machine where he logs in on the Arpanet.

If your recipient logs in on a machine connected to yours by UUCP (the Bell Laboratories supplied network that communicates over telephone lines), sending mail to him is a bit
more complicated.

You must know the list of machines through which your message must

travel to arrive at his site.

So, if his machine is directly connected to yours, you can send mail

to him using the syntax:
hostlname

where, again, host is the name of his machine and name is his login name. If your message
must go through an intermediate machine first, you must use the syntax:
intermediate!host!name

and so on. It is actually a feature of UUCP that the map of all the systems in the network is
not known anywhere (except where people decide to write it down for convenience).
Talk to
4

A BNS

E-S ¥4

your system administrator about the machines connected to your site.

Mail Reference Manual

2-27

If you want to send a message to a recipient on the Berkeley network (Berknet), you use
the syntax:
host:name

where host is his machine name and name is his login name.

Unlike UUCP, you need not

know the names of the intermediate machines.
When you use the reply command to respond to a letter, there is a problem of figuring
out the names of the users in the “To:” and “Cec:” lists relative to the current machine. If the

original letter was sent to you by someone on the local machine, then this problem does not
exist, but if the message came from a remote machine, the problem must be dealt with. Mail
uses a heuristic to build the correct name for each user relative to the local machine.

So,

when you reply to remote mail, the names in the “To:” and “Cec:” lists may change some|
what.
4.3. Special recipients
- As described previously, you can send mail to either user names or alias names.

It is

also possible to send messages directly to files or to programs, using special conventions. If a
recipient name has a ‘/’ in it or begins with a ‘+’, it is assumed to be the path name of a file
into which to send the message.

If the file already exists, the message is appended to the end

of the file. If you want to name a file in your current directory (ie, one for which a ‘/” would
not usually be needed) you can precede the name with ‘./” So, to send mail to the file “memo”
in the current directory, you can give the command:

% Mail ./memo
If the name begins with a ‘+,” it is expanded into the full path name of the folder name in

your folder directory. This ability to send mail to files can be used for a variety of purposes,
such as maintaining a journal and keeping a record of mail sent to a certain group of users.
The second example can be done automatically by including the full pathname of the record
file in the alias command for the group.

the command:

Using our previous alias example, you might give

alias project sam sally steve susan /usr/project/mail record
Then, all mail sent to "project” would be saved on the file ‘“/usr/project/mail record” as well
as being sent to the members of the project. This file can be examined using Mail —f.
It is sometimes useful to send mail directly to a program, for example one might write a
project billboard program and want to access it using Mail. To send messages to the billboard

program, one can send mail to the special name billboard’ for example. Mail treats recipient
names that begin with a I as a program to send the mail to. An alias can be set up to reference a ‘I prefaced name if desired. Caveats: the shell treats ¢ specially, so it must be quoted
on the command line. Also, the \ program’ must be presented as a single argument to mail.
The safest course is to surround the entire name with double quotes.

usage in the alias command.
would need to say:

alias rmsgs | rmsgs -s”

This also applies to

For example, if we wanted to alias ‘rmsgs’ to ‘rmsgs —s’ we

2-28 Mail Reference Manual

5. Additional features

This section describes some additional commands of use for reading your mail, setting
options, and handling lists of messages.

5.1. Message lists

Several Mail commands accept a list of messages as an argument. Along with type and
delete, described in section 2, there is the from command, which prints the message headers
associated with the message list passed to it. The from command is particularly useful in
conjunction with some of the message list features described below.
A message list consists of a list of message numbers, ranges, and names, separated by

spaces or tabs.

Message numbers may be either decimal numbers, which directly specify mes-

sages, or one of the special characters “{”
last relevant message, respectively.

€¢

“.”

or “$” to specify the first relevant, current, or

Relevant here means, for most commands “not deleted”

and “deleted” for the undelete command.
A range of messages consists of two message numbers (of the form described
in the previous paragraph) separated by a dash. Thus, to print the first four messages, use
type 1—4

and to print all the messages from the current message to the last message, use

type .—$
A name is a user name. The user names given in the message list are collected together
and each message selected by other means is checked to make sure it was sent by one of the
named users.

If the message consists entirely of user names, then every message sent by one

those users that is relevant (in the sense described earlier) is selected.

Thus, to print every

message sent to you by “root,” do
type root

As a shorthand notation, you can specify simply

€% 99

to get every relevant (same sense)

message. Thus,

type *

prints all undeleted messages,
delete *

deletes all undeleted messages, and
undelete *

‘undeletes all deleted messages.

You can search for the presence of a word in subject lines with /. For example, to print
the headers of all messages that contain the word “PASCAL,” do:

from /pascal

Note that subject searching ignores upper/lower case differences.
5.2.

List of commands

This section describes all the Mail commands available when receiving mail.
!

Used to preface a command to be executed by the shell.

—

The — command goes to the previous message and prints it.

The — command may be

given a decimal number n as an argument, in which case the nth previous message 1is

gone to and printed.

Mail Reference Manual

2-29

Like print, but also print out ignored header fields.

directory

names

separated by :. For example,

PATH=:/usr/fred/bin:/bin:/usr/bin
specifies

that

the

current

directory

(the

null

string

before

/usr/fred/bin, /bin and /usr/bin are to be searched in that order.

the

first

:),

In this way

individual users can have their own ‘private’ commands that are accessible
independently of the current directory.

If the command name contains a / then

this directory search is not used; a single attempt is made to execute the command.

$PS1

The primary shell prompt string, by default, ‘$ .

$PS2

The shell prompt when further input is needed, by default, ‘> .

$IFS

The set of characters used by blank interpretation (see section 3.4).

2.5 The test command
The test command, although not part of the shell, is intended for use by shell programs.

For

example,
test f file
returns zero exit status if file exists and non-zero exit status otherwise.

ates a predicate and returns the result as its exit status.

In general test evalu-

Some of the more frequently used

test arguments are given here, see test (1) for a complete specification.

test s

true if the argument s is not the null string

test —f file true if file exists

test —r file true if file is readable
test —-w file true if file is writable

test—d file true if file is a directory

2.6 Control flow - while
The actions of the for loop and the case branch are determined by data available to the
shell.

A while or until loop and an if then else branch are also provided whose actions are

determined by the exit status returned by commands. A while loop has the general form
while command-list,
do command-list,

done
The value tested by the while command is the exit status of the last simple command follow-

ing while.

Each time round the loop command-list, is executed; if a zero exit status is

returned then command-list, is executed; otherwise, the loop terminates.

For example,

while test $1

do ...
shift
P

Uuoiice

is equivalent to

for 1

do .

done
shift is a shell command that renames the positional parameters $2, $3, ... as $1, $2, ... and

loses $1.

An Introduction to the UNIX Shell 4-13

Another kind of use for the while/until loop is to wait until some external event occurs and
then run some commands.

In an until loop the termination condition is reversed.

ple’

For exam-

‘
until test f file

do sleep 300; done
commands

will loop until file exists. Each time round the loop it waits for 5 minutes before trying again.
(Presumably another process will eventually create the file.)
2.7 Control flow - if
Also available is a general conditional branch of the form,
if command-list

then command-list

else command-list

fi
that tests the value returned by the last simple command following if.
The if command may be used in conjunction with the test command to test for the existence
of a file as in
if test -f file

then process file

else

do something else

An example of the use of if, case and for constructions is given in section 2.10.
A multiple test if command of the form
if ...

‘then ...
else if ...

then ...
else

if...
fi

may be written using an extension of the if notation as,
if ...

then ...

elif
then ...

elif
fi

The following example is the touch command which changes the ‘last modified’ time for a list
of files.

The command may be used in conjunction with make (1) to force recompilation of a

list of files.

4-14 An Introduction to the UNIX Shell
flag="

for 1

do case $i in

~C)

flag=N ;;

*)1f test -f $1

then In $i junk$$; rm junk$$
elif test $flag

then echo file \’$i\' does not exist
else

>$i1

fi
esac

done
The -¢ flag is used in this command to force subsequent files to be created if they do not
already exist. Otherwise, if the file does not exist, an error message is printed. The shell variable flag is set to some non-null string if the —¢ argument is encountered. The commands
In..;rm...

make a link to the file and then remove it thus causing the last modified date to be updated.
The sequence

if command1
then command2
fi

may be written

commandl && command?2
Conversely,

commandl || command?
executes command?2 only if commandl fails. In each case the value returned is that of the last
simple command executed.
|
2.8 Command grouping
Commands may be grouped in two ways,

{ command-list ; }
and
( command-list )

In the first command-list is simply executed.
-

separate process.

The second form executes command-list as a

For example,

(cd x; rm junk )

executes rm junk in the directory x without changing the current directory of the invoking
shell
WIALAN

KK,

The commands

cd x; rm junk

have the same effect but leave the invoking shell in the directory x.

An Introduction to the UNIX Shell 4-15

2.9 Debugging shell procedures

The shell provides two tracing mechanisms to help when debugging shell procedures.

The

first is invoked within the procedure as
set —v

(v for verbose) and causes lines of the procedure to be printed as they are read. It is useful to
help isolate syntax errors. It may be invoked without modifying the procedure by saying
sh —v proc ...

where proc is the name of the shell procedure. This flag may be used in conjunction with the
-n flag which prevents execution of subsequent commands. (Note that saying set -n at a terminal will render the terminal useless until an end-of-file is typed.)
The command
set —x

will produce an execution trace. Following parameter substitution each command is printed
as it is executed. (Try these at the terminal to see what effect they have.) Both flags may be
turned off by saying
set —

and the current setting of the shell flags is available as $-.
2.10 The man command

The following is the man command which is used to print sections of the UNIX manual. It is
called, for example, as
man sh

man -t ed

man 2 fork

In the first the manual section for sh is printed. Since no section is specified, section 1 is
used. The second example will typeset (-t option) the manual section for ed. The last prints
the fork manual page from section 2.

4-16 An Introduction to the UNIX Shell

cd /usr/man
: “‘colon is the comment command’
: “"default is nroff ($N), section 1 ($s)’
N=n s=1
for 1

do case $1 In
[1-9]*) s=$1 ;;

-t)

N=t ;;

N=n ;;

_x)

echo unknown flag \'$i\ ;;

x)if test
- man$s/$i.$s

then ${N}roff man0/${N}aa man$s/$i.$s
else

: ‘look through all manual sections’
found=no

foryin123456789

do if test f man$j/$i.$;
then man §j $i

found=yes
fi

done
case $found in
no) echo “$i: manual page not found’
esac

esac

done
Figure 1. A version of the man command

An Introduction to the UNIX Shell

4-17

3.0 Keyword parameters
Shell variables may be given values by assignment or when a shell procedure is invoked.

argument to a shell procedure of the form name=value that precedes the command name

causes value to be assigned to name before execution of the procedure begins.
name in the invoking shell is not affected.

The value of

For example,

user=fred command
will execute command with user set to fred.

The -k flag causes arguments of the form

name=value to be interpreted in this way anywhere in the argument list.

sometimes called keyword parameters.

Such names are

If any arguments remain they are available as posi-

tional parameters $1, $2, ....
The set command may also be used to set positional parameters from within a procedure.

For

example,
set
— *

will set $1 to the first file name in the current directory, $2 to the next, and so on. Note that
the first argument, —, ensures correct treatment when the first file name begins with a —
3.1 Parameter transmission

When a shell procedure is invoked both positional and keyword parameters may be supplied
with the call.

Keyword parameters are also made available implicitly to a shell procedure by

specifying in advance that such parameters are to be exported. For example,

export user box
marks the variables user and box for export.

When a shell procedure is invoked copies are

made of all exportable variables for use within the invoked procedure.

Modification of such

variables within the procedure does not affect the values in the invoking shell. It is generally
true of a shell procedure that it may not modify the state of its caller without explicit request
on the part of the caller.

(Shared file descriptors are an exception to this rule.)

Names whose value is intended to remain constant may be declared readonly.

The form of

this command is the same as that of the export command,

readonly name ...
Subsequent attempts to set readonly variables are illegal.
3.2 Parameter substitution
If a shell parameter is not set then the null string is substituted for it.

For example, if the

variable d is not set

echo $d
or

echo ${d}
will echo nothing. A default string may be given as in

echo ${d-}
which will echo the value of the variable d if it is set and ‘. otherwise.
evaluated using the usual quoting conventions so that

echo ${d-"*"}
will echo * if the variable d is not set.

Similarly

The default string is

4-18 An Introduction to the UNIX Shell

echo ${d-$1}

will echo the value of d if it is set and the value (if any) of $1 otherwise. A variable may be
assigned a default value using the notation
echo ${d=.}
which substitutes the same string as

echo ${d-}
and if d were not previously set then it will be set to the string ‘..
not available for positional parameters.)

(The notation ${...=...} is

If there is no sensible default then the notation

echo ${d?7message}
will echo the value of the variable d if it has one, otherwise message is printed by the shell

and execution of the shell procedure is abandoned. If message is absent then a standard message is printed. A shell procedure that requires some parameters to be set might start as follows.

: ${user?} ${acct?} ${bin?}

Colon (:) is a command that is built in to the shell and does nothing once its arguments have
been evaluated. If any of the variables user, acct or bin are not set then the shell will abandon execution of the procedure.

3.3 Command substitution
The standard output from a command can be substituted in a similar way to parameters. The
command pwd prints on its standard output the name of the current directory. For example,
if the current directory is /usr/fred/bin then the command
d="pwd’
is equivalent to

d=/usr/fred/bin
The entire string between grave accents ('...) is taken as the command to be executed and is

replaced with the output from the command. The command is written using the usual quot-

ing conventions except that a * must be escaped using a\. For example,
Is “‘echo ”$1TM
is equivalent to
Is $1

Command substitution occurs in all contexts where parameter substitution occurs (including
here documents) and the treatment of the resulting text is the same in both cases. This
mechanism allows string processing commands to be used within shell procedures. An example of such a command is basename which removes a specified suffix from a string. For exam-

ple,
basename main.c .c

will print the string main.
mand.

Its use is illustrated by the following fragment from a cc com-

An Introduction to the UNIX Shell 4-19

case $A in

*,¢c)

B='basename $A .c

esac

that sets B to the part of $A with the suffix .c stripped.
Here are some composite examples.

foriin ls—t; do...
The variable i is set to the names of files in time order, most recent first.

set ‘date’; echo $6 $2 $3, $4
will print, e.g.,

1977 Nov 1, 23:59:59

3.4 Evaluation and quoting
The shell is a macro processor that provides parameter substitution, command substitution
and file name generation for the arguments to commands.

This section discusses the order in

which these evaluations occur and the effects of the various quoting mechanisms.
Commands are parsed initially according to the grammar given in appendix A.

Before a com-

mand is executed the following substitutions occur.
parameter substitution, e.g. $user
command substitution, e.g. ‘pwd’

Only one evaluation occurs so that if, for example, the value of the variable X is
the string $y then
echo $X
will echo $y.
blank interpretation
Following the above substitutions the resulting characters are broken into non-

blank words (blank interpretation).
the string $IFS.

For this purpose ‘blanks’ are the characters of

By default, this string consists of blank, tab and newline.

null string is not regarded as a word unless it is quoted.

The

For example,

echo ”
will pass on the null string as the first argument to echo, whereas
echo $null
will call echo with no arguments if the variable null is not set or set to the null
string.

file name generation
Each word is then scanned for the file pattern characters %, ? and [...] and an
alphabetical list of file names is generated to replace the word.

Each such file

name is a separate argument.

The evaluations just described also occur in the list of words associated with a for loop.

Only

substitution occurs in the word used for a case branch.
As well as the quoting mechanisms described earlier using \and "...” a third quoting mechan1sm is provided using double quotes.

Within double quotes parameter and command substitu-

tion occurs but file name generation and the interpretation of blanks does not.

The following

characters have a special meaning within double quotes and may be quoted using \.

4-20 An Introduction to the UNIX Shell

parameter substitution
command substitution
ends the quoted string

quotes the special characters $ ~” \

For example,
echo ”$x”

will pass the value of the variable x as a single argument to echo.

Similarly,

echo "$*”

will pass the positional parameters as a single argument and is equivalent to
echo "$1 $2 ...
The notation $ @ is the same as $* except when it is quoted.
echo "$@”

will pass the positional parameters, unevaluated, to echo and is equivalent to
echo ”$1” 7§27 ...

The following table gives, for each quoting mechanism, the shell metacharacters that are
evaluated.
metacharacter
’

)

”

terminator

interpreted

not interpreted
Figure 2. Quoting mechanisms

In cases where more than one evaluation of a string is required the built-in command eval

may be used. For example, if the variable X has the value $y, and if y has the value pqr then
eval echo $X
will echo the string pgr.

In general the eval command evaluates its arguments (as do all commands) and treats the
result as input to the shell.

The input is read and the resulting command(s) executed.

For

example,
/

wg=eval who|grep

$wg fred
1s equivalent to
whogrep fred

In this example, eval is required since there is no interpretation of metacharacters, such as |,
following substitution.

An Introduction to the UNIX Shell 4-21
3.5 Error handling

The treatment of errors detected by the shell depends on the type of error and on whether the
shell is being used interactively. An interactive shell is one whose input and output are con-

nected to a terminal (as determined by gtty (2)).
interactive.

A shell invoked with the -i flag is also

Execution of a command (see also 3.7) may fail for any of the following reasons.
.

Input output redirection may fail.

created.
o
®

For example, if a file does not exist or cannot be

The command itself does not exist or cannot be executed.
The command terminates abnormally, for example, with a "bus error” or “memory
See Figure 2 below for a complete list of UNIX signals.

fault”.
.

The command terminates normally but returns a non-zero exit status.

In all of these cases the shell will go on to execute the next command. Except for the last case

an error message will be printed by the shell.

All remaining errors cause the shell to exit from
An interactive shell will return to read another command from the
Such errors include the following.

a command procedure.

terminal.

Syntax errors.

A signal such as interrupt.

Failure of any of the built-in commands such as c¢d.

e.g., if ... then ... done

The shell waits for the current command, if any, to finish
execution and then either exits or returns to the terminal.

The shell flag -e causes the shell to terminate if any error is detected.

hangup

interrupt

quit

illegal instruction

trace trap

IOT instruction

EMT instruction

floating point exception

kill (cannot be caught or ignored)

10*

bus error

11*

segmentation violation

12*

bad argument to system call

write on a pipe with no one to read it

alarm clock

software termination (from kill (1))

Figure 3. UNIX signals
Those signals marked with an asterisk produce a core dump if not caught.
itself ignores quit which is the only external signal that can cause a dump.

list of potential interest to shell
IJ S

VNS AR

However, the shell

The signals in this

roal1, 9

2
14 and 1K
2, 3,
14 and 15.

3.6 Fault handling

Shell procedures normally terminate when an interrupt is received from the terminal.

trap command is used if some cleaning up is required, such as removing temporary files.

example,

The
For

trap ‘rm /tmp/ps$$; exit” 2
sets a trap for signal 2 (terminal interrupt), and if this signal is received will execute the

4-22

An Introduction to the UNIX Shell

commands

rm /tmp/ps$$; exit
exit is another built-in command that terminates execution of a shell procedure.

The exit is

required; otherwise, after the trap has been taken, the shell will resume executing the pro-

cedure at the place where it was interrupted.
UNIX signals can be handled in one of three ways.
signal is never sent to the process.

They can be ignored, in which case the

They can be caught, in which case the process must decide

what action to take when the signal is received.

Lastly, they can be left to cause termination

of the process without it having to take any further action.

If a signal is being ignored on

entry to the shell procedure, for example, by invoking it in the background (see 3.7) then trap
commands (and the signal) are ignored.
The use of trap is illustrated by this modified version of the touch command (Figure 4).

The

cleanup action is to remove the file junk$$.
flag=

trap rm —f junk$$; exit” 1 2 3 15
for 1

do case $i in

~C)

flag=N ;;

*)1f test
£ $i

then In $i junk$$; rm junk$$

elif test $flag

then echo file \"$i\ does not exist
else

>$i

fi
esac

done

Figure 4. The touch command
The trap command appears before the creation of the temporary file; otherwise it would be

possible for the process to die without removing the file.

Since there is no signal 0 in UNIX it is used by the shell to indicate the commands to be executed on exit from the shell procedure.
A procedure may, itself, elect to ignore signals by specifying the null string as the argument to
trap.

The following fragment is taken from the nohup command.

trap “ 12315
which causes hangup, interrupt, quit and kill to be ignored both by the procedure and by
invoked commands.
Traps may be reset by saying

The procedure scan (Figure 5) is an example of the use of trap where there is no exit in the
trap command.

scan takes each directory in the current directory, prompts with its name,

and then executes commands typed at the terminal until an end of file or an interrupt is
received.

Interrupts are ignored while executing the requested commands but cause termina-

tion when scan is waiting for input.

An Introduction to the UNIX Shell 4-23

d="pwd
for 1 in *

do if test
—-d $d/$i
then cd $d/$i
while echo ”$1:”
trap exit 2
read x

do trap : 2; eval $x; done
fi

done
Figure 5. The scan command
read x is a built-in command that reads one line from the standard input and places the result
in the variable x.

It returns a non-zero exit status if either an end-of-file is read or an inter-

rupt is received.

3.7 Command execution
To run a command (other than a built-in) the shell first creates a new process using the sys-

tem call fork. The execution environment for the command includes input, output and the
states of signals, and is established in the child process before the command is executed. The
built-in command exec is used in the rare cases when no fork is required and simply replaces
the shell with a new command. For example, a simple version of the nohup command looks
like

trap “ 12315
exec $x

The trap turns off the signals specified so that they are ignored by subsequently created commands and exec replaces the shell by the command specified.

Most forms of input output redirection have already been described.
only subject to parameter and command substitution.

In the following word is

No file name generation or blank

interpretation takes place so that, for example,

echo ... >*.c

will write its output into a file whose name is *.c.

Input output specifications are evaluated

left to right as they appear in the command.

> word

The standard output (file descriptor 1) is sent to the file word which is created if
it does not already exist.

>> word

The standard output is sent to file word.

If the file exists then output is

appended (by seeking to the end); otherwise the file is created.
< word

The standard input (file descriptor 0) is taken from the file word.

<< word

The standard input is taken from the lines of shell input that follow up to but

not including a line consisting only of word.
tation of the document occurs.

If word is quoted then no interpre-

If word is not quoted then parameter and com-

mand substitution occur and \ is used to quote the characters \ $ * and the first
character of word. In the latter case\newline is ignored (c.f. quoted strings).>& digit

The file descriptor digit is duplicated using the system call dup (2) and the
result is used as the standard output.

<& digit

The standard input is duplicated from file descriptor digit.

<&-—

The standard input is closed.

4-24 An Introduction to the UNIX Shell
>&-

The standard output is closed.

Any of the above may be preceded by a digit in which case the file descriptor created is that
specified by the digit instead of the default 0 or 1.

For example,

.. 2>file
runs a command with message output (file descriptor 2) directed to file.

. 2>&1
runs a command with its standard output and message output merged. (Strictly speaking file
descriptor 2 is created by duplicating file descriptor 1 but the effect is usually to merge the
two streams.)

The environment for a command run in the background such as

list *.c | lpr &
is modified in two ways.

file /dev/null.

Firstly, the default standard input for such a command is the empty
This prevents two processes (the shell and the command), which are running

in parallel, from trying to read the same input.

Chaos would ensue if this were not the case.

For example,

ed file &
would allow both the editor and the shell to read from the same input at the same time.
The other modification to the environment of a background commandis to turn off the QUIT

and INTERRUPT signals so that they are ignored by the command. This allows these signals
to be used at the terminal without causing background commands to terminate.

For this reason the UNIX convention for a signal is that if it is set to 1 (ignored) then it is never changed

even for a short time.

Note that the shell command trap has no effect for an ignored signal.

3.8 Invoking the shell
The following flags are interpreted by the shell when it is invoked.

If the first character of

argument zero 1s a minus, then commands are read from the file .profile.

-¢ string
If the —c flag is present then commands are read from string.

—s

If the —s flag is present or if no arguments remain then commands are read from the
standard input.

-4

Shell output is written to file descriptor 2.

If the 4 flag is present or if the shell input and output are attached to a terminal (as
told by gtty) then this shell is interactive. In this case TERMINATE is ignored (so that

kill O does not kill an interactive shell) and INTERRUPT is caught and ignored (so
In all cases QUIT is ignored by the shell.

that wait is interruptable).
Acknowledgements

The design of the shell is based in part on the original UNIX shell? and the PWB/UNIX

shell,* some features having been taken from both. Similarities also exist with the command
interpreters of the Cambridge Multiple Access System® and of CTSS.6

n|
I would like to thank Dennis Ritchie and John Masheyfor many discussionsduring the a
design

of the shell.

I am also grateful to the members of the Computing Science Research Center

and to Joe Maranzano for their comments on drafts of this document.

References
1.

B. W. Kernighan, UNIX

for Beginners, 1978.

An Introduction to the UNIX Shell 4-25
K. Thompson and D. M. Ritchie, UNIX Programmer’s Manual, Bell Laboratories, 1978.
Seventh Edition.

K. Thompson, “The UNIX Command Language,” in Structured Programming—Infotech
State of the Art Report, pp. 375-384, Infotech International Ltd., Nicholson House,
Maidenhead, Berkshire, England, March 1975.
J. R. Mashey, PWB/UNIX Shell Tutorial, September 30, 1977.
D. F. Hartley (Ed.), The Cambridge Multiple Access System — Users Reference
Manual, University Mathematical Laboratory, Cambridge, England, 1968.

P. A. Crisman (Ed.), The Compatible Time-Sharing System, M.L'T. Press, Cambridge,
Mass., 1965.

4-26

An Introduction to the UNIX Shell

Appendix A - Grammar
item:

word
input-output
name = value

simple-command: item
simple-command item
command. simple-command

( command-list )

{ command-list }
for name do command-list done

for name in word ... do command-list done
while command-list do command-list done
until command-list do command-list done
case word in case-part ... esac

if command-list then command-list else-part fi

pipeline:

command

pipeline | command
andor:

pipeline
andor && pipeline

andor || pipeline
command-list:

andor

command-list ;
command-list &

command-list ; andor
command-list & andor

input-output:

> file

< file
>> word
<< word

file:

word
& digit
& -

case-part: pattern ) command-list 3
pattern:

word

pattern | word
else-part: elif command-list then command-list else-part

else command-list
empty

empty

word.

name:

digit:

a sequence of non-blank characters

a sequence of letters, digits or underscores starting with a letter

0123456789

An Introduction to the UNIX Shell 4-27

Appendix B - Meta-characters and Reserved Words
a) syntactic

pipe symbol

‘andf’ symbol

‘orf’ symbol

;

command separator

case delimiter

background commands

()

command grouping

input redirection

input from a here document

output creation

output append

b) patterns
%

match any character(s) including none

match any single character

[...]

match any of the enclosed characters

c) substitution

${...} substitute shell variable
“

substitute command output

d) quoting

quote the next character

quote the enclosed characters except for ’

”...”

quote the enclosed characters except for § ° \”

e) reserved words
if then else elif fi
case in esac

for while until do done

{

Introduction to the C Shell 4-29

An introduction to the C shell
William Joy

Computer Science Division

Department of Electrical Engineering and Computer Science
University of California, Berkeley
Berkeley, California 94720

Introduction

A shell is a command language interpreter. Csh is the name of one particular command
interpreter on UNIX. The primary purpose of csh is to translate command lines typed at a
terminal into system actions, such as invocation of other programs. Csh is a user program
just like any you might write. Hopefully, csh will be a very useful program for you in
interacting with the UNIX system.

In addition to this document, you will want to refer to a copy of the UNIX programmer’s
manual. The csh documentation in the manual provides a full description of all features of
the shell and is a final reference for questions about the shell.
Many words in this document are shown in italics. These are important words; names of
commands, and words which have special meaning in discussing the shell and UNIX. Many of
the words are defined in a glossary at the end of this document. If you don’t know what is
meant by a word, you should look for it in the glossary.
Acknowledgements

Numerous people have provided good input about previous versions of csh and aided in
its debugging and in the debugging of its documentation. I would especially like to thank
Michael Ubell who made the crucial observation that history commands could be done well
over the word structure of input text, and implemented a prototype history mechanism in an
older version of the shell. Eric Allman has also provided a large number of useful comments
on the shell, helping to unify those concepts which are present and to identify and eliminate
useless and marginally useful features. Mike O’Brien suggested the pathname hashing
mechanism which speeds command execution. Jim Kulp added the job control and directory
stack primitives and added their documentation to this introduction.

4-30

Introduction to the C Shell

Terminal usage of the shell

1.1.

The basic notion of commands

A shell in UNIX acts mostly as a medium through which other programs are invoked.
While it has a set of builtin functions which it performs directly, most commands cause exe-

cution of programs that are, in fact, external to the shell. The shell is thus distinguished from
the command interpreters of other systems both by the fact that it is just a user program, and

by the fact that it is used almost exclusively as a mechanism for invoking other programs.

Commands in the UNIX system consist of a list of strings or words interpreted as a com-

mand name followed by arguments. Thus the command

mail bill

consists of two words. The first word mail names the command to be executed, in this case
the mail program which sends messages to other users. The shell uses the name of the com-

mand in attempting to execute it for you. It will look in a number of directories for a file
with the name mail which is expected to contain the mail program.

The rest of the words of the command are given as arguments to the command itself
In this case we specified also the argument bill which is interpreted by

when it is executed.

the mail program to be the name of a user to whom mail is to be sent.

In normal terminal

usage we might use the mail command as follows.

% mail bill
I have a question about the csh documentation.

My document seems to be missing page 5.
Does a page five exist?
Bill

EOT

%
Here we typed a message to send to bill and ended this message with a 1D which sent
an end-of-file to the mail program. (Here and throughout this document, the notation “tx” is

to be read “control-x” and represents the striking of the x key while the control key is held
down.) The mail program then echoed the characters ‘EOT’ and transmitted our message.
The characters ‘% ’ were printed before and after the mail command by the shell to indicate

that input was needed.

After typing the ‘% ’ prompt the shell was reading command input from our terminal.
We typed a complete command ‘mail bill’. The shell then executed the mail program with
argument bill and went dormant waiting for it to complete. The mail program then read
input from our terminal until we signalled an end-of-file via typing a 1D after which the shell
noticed that mail had completed and signaled us that it was ready to read from the terminal

again by printing another ‘% ’ prompt.
This is the essential pattern of all interaction with UNIX through the shell. A complete
command is typed at the terminal, the shell executes the command and when this execution
completes, it prompts for a new command.

If you run the editor for an hour, the shell will

patiently wait for you to finish editing and obediently prompt you again whenever you finish

editing.
An example of a useful command you can execute now is the tset command, which sets
the default erase and kill characters on your terminal — the erase character erases the last

character you typed and the kill character erases the entire line you have entered so far.

default, the erase character is ‘#’ and the kill character is ‘@.

Most people who use CRT

displays prefer to use the backspace (TH) character as their erase character since it is then
easler to see what you have typed so far. You can make this be true by typing

Introduction to the C Shell 4-31
tset —e

which tells the program tset to set the erase character, and its default setting for this character is a backspace.

1.2. Flag arguments

A useful notion in UNIX is that of a flag argument. While many arguments to commands
specify file names or user names some arguments rather specify an optional capability of the
command which you wish to invoke. By convention, such arguments begin with the character
‘~’> (hyphen). Thus the command
Is

will produce a list of the files in the current working directory. The option —s is the size
option, and
ls —s

causes Is to also give, for each file the size of the file in blocks of 512 characters. The manual

section for each command in the UNIX reference manual gives the available options for each
command. The Is command has a large number of useful and interesting options. Most other
commands have either no options or only one or two options. It is hard to remember options
of commands which are not used very frequently, so most UNIX utilities perform only one or
two functions rather than having a large number of hard to remember options.
1.3. Output to files

Commands that normally read input or write output on the terminal can also be exe-

cuted with this input and/or output done to a file.

Thus suppose we wish to save the current date in a file called ‘now’. The command
date

will print the current date on our terminal. This is because our terminal is the default standard output for the date command and the date command prints the date on its standard
output. The shell lets us redirect the standard output of a command through a notation
using the metacharacter ‘>’ and the name of the file where output is to be placed. Thus the
command
date > now

runs the date command such that its standard output is the file ‘now’ rather than the terminal. Thus this command places the current date and time into the file ‘now’. It is important
to know that the date command was unaware that its output was going to a file rather than to
the terminal. The shell performed this redirection before the command began executing.
One other thing to note here is that the file ‘now’ need not have existed before the date
command was executed; the shell would have created the file if it did not exist. And if the file
did exist? If it had existed previously these previous contents would have been discarded! A
shell option noclobber exists to prevent this from happening accidentally; it is discussed in
section 2.2.

The system normally keeps files which you create with >’ and all other files. Thus the

default is for files to be permanent. If you wish to create a file which will be removed
automatically, you can begin its name with a ‘#’ character, this ‘scratch’ character denotes the
fact that the file will be a scratch file.* The system will remove such files after a couple of
*Note that if your erase character is a ‘#’, you will have to precede the ‘#’ with a ‘X. The fact that the ‘#’
character is the old (pre-crT) standard erase character means that it seldom appears in a file name, and allows this convention to be used for scratch files. If you are using a CRT, your erase character should be a
fH, as we demonstrated in section 1.1 how this could be set up.

4-32

Introduction to the C Shell

days, or sooner if file space becomes very tight.

Thus, in running the date command above,

we don’t really want to save the output forever, so we would more likely do

date > #now

1.4. Metacharacters in the shell
The shell has a large number of special characters (like ‘>’) which indicate special functions.

We say that these notations have syntactic and semantic meaning to the shell.

In gen-

eral, most characters which are neither letters nor digits have special meaning to the shell.

We shall shortly learn a means of quotation which allows us to use metacharacters without
the shell treating them in any special way.
Metacharacters normally have effect only when the shell is reading our input.

We need

not worry about placing shell metacharacters in a letter we are sending via mail, or when we
are typing in text or data to some other program.

Note that the shell is only reading input

when it has prompted with ‘% .
1.5.

Input from files; pipelines

We learned above how to redirect the standard output of a command to a file.

It is also

possible to redirect the standard input of a command from a file. This is not often necessary
since most commands will read from a file whose name is given as an argument.

We can give

the command
sort < data
to run the sort command with standard input, where the command normally reads its input,
from the file ‘data’.

We would more likely say

sort data
letting the sort command open the file ‘data’ for input itself since this is less to type.

We should note that if we just typed
sort

then the sort program would sort lines from its standard input. Since we did not redirect the
standard input, it would sort lines as we typed them on the terminal until we typed a 1D to
indicate an end-of-file.

A most useful capability is the ability to combine the standard output of one command
with the standard input of another, i.e. to run the commands in a sequence known as a pipeline. For instance the command
Is —s

normally produces a list of the files in our directory with the size of each in blocks of 512
characters.

If we are interested in learning which of our files is largest we may wish to have

this sorted by size rather than by name, which is the default way in which Is sorts.

We could

look at the many options of Is to see if there was an option to do this but would eventually

discover that there is not.

Instead we can use a couple of simple options of the sort com-

mand, combining it with Is to get what we want.
The —n option of sort specifies a numeric sort rather than an alphabetic sort.

Thus

Is —s |sort —n
specifies that the output of the Is command run with the option —s is to be piped to the command sort run with the numeric sort option.
size, but with the smallest first.

This would give us a sorted list of our files by

We could then use the —r reverse sort option and the head

command in combination with the previous command doin
-

Introduction to the C Shell 4-33

ls —s | sort —n —r |head =5

Here we have taken a list of our files sorted alphabetically, each with the size in blocks. We
have run this to the standard input of the sori command asking it to sort numerically in
reverse order (largest first). This output has then been run into the command head which
gives us the first few lines. In this case we have asked head for the first 5 lines. Thus this
command gives us the names and sizes of our 5 largest files.

The notation introduced above is called the pipe mechanism. Commands separated by
‘I’ characters are connected together by the shell and the standard output of each is run into
the standard input of the next. The leftmost command in a pipeline will normally take its
standard input from the terminal and the rightmost will place its standard output on the terminal. Other examples of pipelines will be given later when we discuss the history mechanism; one important use of pipes which is illustrated there is in the routing of information to
the line printer.
1.6. Filenames

Many commands to be executed will need the names of files as arguments. UNIX pathnames consist of a number of components separated by ‘/’. Each component except the last
names a directory in which the next component resides, in effect specifying the path of direc-

tories to follow to reach the file. Thus the pathname
/etc/motd

specifies a file in the directory ‘etc’ which is a subdirectory of the root directory ‘’.. Within

this directory the file named is ‘motd’ which stands for ‘message of the day’. A pathname

that begins with a slash is said to be an absolute pathname since it is specified from the abso-

lute top of the entire directory hierarchy of the system (the root). Pathnames which do not
begin with ¢/’ are interpreted as starting in the current working directory, which is, by default,
your home directory and can be changed dynamically by the cd change directory command.
Such pathnames are said to be relative to the working directory since they are found by starting in the working directory and descending to lower levels of directories for each component
of the pathname. If the pathname contains no slashes at all then the file is contained in the
working directory itself and the pathname is merely the name of the file in this directory.
Absolute pathnames have no relation to the working directory.

Most filenames consist of a number of alphanumeric characters and ‘.’s (periods). In
fact, all printing characters except ¢/’ (slash) may appear in filenames. It is inconvenient to
have most non-alphabetic characters in filenames because many of these have special meaning

to the shell.

The character ‘.’ (period) is not a shell-metacharacter and is often used to

separate the extension of a file name from the base of the name. Thus
prog.c prog.o prog.errs prog.output

are four related files. They share a base portion of a name (a base portion being that part of
the name that is left when a trailing ‘.’ and following characters which are not .’ are stripped
off). The file ‘prog.c’ might be the source for a C program, the file ‘prog.o’ the corresponding
object file, the file ‘prog.errs’ the errors resulting from a compilation of the program and the
file ‘prog.output’ the output of a run of the program.

If we wished to refer to all four of these files in a command, we could use the notation
prog.*

This word is expanded by the shell, before the command to which it is an argument is executed, into a list of names which begin with ‘prog.’. The character ‘*’ here matches any

sequence (including the empty sequence) of characters in a file name. The names which
match are alphabetically sorted and placed in the argument list of the command. Thus the
command

4-34

Introduction to the C Shell

echo prog.*
will echo the names
prog.c prog.errs prog.o prog.output

Note that the names are in sorted order here, and a different order than we listed them above.
The echo command receives four words as arguments, even though we only typed one word as

as argument directly.

The four words were generated by filename expansion of the one input

word.
Other notations for filename expansion are also available.
any single character in a filename.

The character

“)’

matches

Thus

echo ? 77 777
will echo a line of filenames; first those with one character names, then those with two charac-

ter names, and finally those with three character names.

The names of each length will be

independently sorted.
Another mechanism consists of a sequence of characters between ‘[’ and ¢]’.
metasequence matches any single character from the enclosed set.

This

Thus

prog.[co]

will match
prog.c prog.o

in the example above.

We can also place two characters around a

‘=’

in this notation to

denote a range. Thus
chap.[1-5]
might match files

chap.1 chap.2 chap.3 chap.4 chap.5
if they existed.

This is shorthand for

chap.[12345]

and otherwise equivalent.
An important point to note is that if a list of argument words to a command (an argument list) contains filename expansion syntax, and if this filename expansion syntax fails to
match any existing file names, then the shell considers this to be an error and prints a diag-

nostic

No match.

and does not execute the command.
Another very important point is that files with the character ‘.’ at the beginning are
€9

treated specially.

Neither “*’ or ‘?° or the ‘[’ ‘" mechanism will match it.

This prevents

accidental matching of the filenames ‘.’ and ‘..’ in the working directory which have special
meaning to the system, as well as other files such as .cshrc¢ which are not normally visible.

will discuss the special role of the file .cshrc later.

Another filename expansion mechanism gives access to the pathname of the home directory of other users.

users’ login name.

This notation consists of the character ‘” (tilde) followed by another

For instance the word “bill’ would map to the pathname ‘/usr/bill’ if the

home directory for ‘bill’ was ‘/usr/bill’.

Since, on large systems, users may have login direc-

tories scattered over many different disk volumes with different prefix directory names, this

notation provides a reliable way of accessing the files of other users.

Introduction to the C Shell 4-35

A special case of this notation consists of a

£~

alone, e.g. “/mbox’.

This notation is

expanded by the shell into the file ‘mbox’ in your home directory, i.e. into ‘/usr/bill/mbox’ for
me on Ernie Co-vax, the UCB Computer Science Department VAX machine, where this document was prepared.

This can be very useful if you have used cd to change to another direc-

tory and have found a file you wish to copy using c¢p. If I give the command

cp thatfile ~

the shell will expand this command to

cp thatfile /usr/bill

since my home directory is /usr/bill.
There also exists a mechanism using the characters ‘{’ and ‘}’ for abbreviating a set of
words which have common parts but cannot be abbreviated by the above mechanisms because
they are not files, are the names of files which do not yet exist, are not thus conveniently
described.

This mechanism will be described much later, in section 4.2, as it is used less fre-

quently.
1.7.

Quotation

We have already seen a number of metacharacters used by the shell.

These metacharac-

ters pose a problem in that we cannot use them directly as parts of words.

Thus the com-

mand
echo *

will not echo the character ‘*’.

It will either echo an sorted list of filenames in the current

working directory, or print the message ‘No match’ if there are no files in the working directory.

The recommended mechanism for placing characters which are neither numbers, digits,

‘/’, ¢ or ‘=’ in an argument word to a command is to enclose it with single quotation characters 7, i.e.
echo TM
There is one special character ‘I’ which is used by the history mechanism of the shell and
which cannot be escaped by placing it within ‘” characters.

It and the character ” itself can

be preceded by a single ‘\_ to prevent their special meaning.

Thus

echo \'\!
prints

!
These two mechanisms suffice to place any printing character into a word which is an argument to a shell command.

They can be combined, as in

echo \"*
which prints
VNN

since the first ‘\ escaped the first “’ and the “*’ was enclosed between “ characters.
1.8.

Terminating commands

When you are executing a command and the shell is waiting for it to complete there are
several ways to force it to stop. For instance if you type the command

the system will print a copy of a list of all users of the system on your terminal. This is likely

4-36

Introduction to the C Shell

to continue for several minutes unless you stop it.

You can send an INTERRUPT signal to the

cat command by typing the DEL or RUBOUT key on your terminal.* Since cat does not take
any precautions to avoid or otherwise handle this signal the INTERRUPT will cause it to terminate.

The shell notices that cat has terminated and prompts you again with ‘% ’.

If you

hit INTERRUPT again, the shell will just repeat its prompt since it handles INTERRUPT signals

and chooses to continue to execute commands rather than terminating like cat did, which
would have the effect of logging you out.
Another way in which many programs terminate is when they get an end-of-file from

their standard input.

Thus the mail program in the first example above was terminated when

we typed a 1D which generates an end-of-file from the standard input.

The shell also ter-

minates when it gets an end-of-file printing ‘logout’; UNIX then logs you off the system.

Since

this means that typing too many 1D’s can accidentally log us off, the shell has a mechanism
for preventing this.

This ignoreeof option will be discussed in section 2.2.

If a command has its standard input redirected from a file, then it will normally terminate when it reaches the end of this file.

Thus if we execute

mail bill < prepared.text

the mail command will terminate without our typing a 1D. This is because it read to the
end-of-file of our file ‘prepared.text’ in which we placed a message for ‘bill’ with an editor program.

We could also have done

cat prepared.text | mail bill
since the cat command would then have written the text through the pipe to the standard
input of the mail command.

When the cat command completed it would have terminated,

closing down the pipeline and the mail command would have received an end-of-file from it

and terminated.

Using a pipe here is more complicated than redirecting input so we would

more likely use the first form.

These commands could also have been stopped by sending an

INTERRUPT.

Another possibility for stopping a command is to suspend its execution temporarily, with

the possibility of continuing execution later.

aTZ.

This is done by sending a STOP signal via typing

This signal causes all commands running on the terminal (usually one but more if a

pipeline is executing) to become suspended.

The shell notices that the command(s) have been

suspended, types ‘Stopped’ and then prompts for a new command.

The previously executing

command has been suspended, but otherwise unaffected by the STOP signal.
mands can be executed while the original command remains suspended.
mand can be continued using the fg command with no arguments.

Any other com-

The suspended com-

The shell will then retype

the command to remind you which command is being continued, and cause the command to
resume execution.

Unless any input files in use by the suspended command have been

changed in the meantime, the suspension has no effect whatsoever on the execution of the
command.

This feature can be very useful during editing, when you need to look at another

file before continuing. An example of command suspension follows.

*Many users use stty(1) to change the interrupt character to1C.

Introduction to the C Shell 4-37

% mail harold
1?omeone just copied a big file into my directory and its name is
Z

Stopped

% ls
funnyfile
prog.c

prog.o

% jobs
+ Stopped

[1]

mail harold

% fg
mail harold
funnyfile. Do you know who did it?
EOT

In this example someone was sending a message to Harold and forgot the name of the file he

wanted to mention. The mail command was suspended by typing 1Z. When the shell noticed
that the mail program was suspended, it typed ‘Stopped’ and prompted for a new command.
Then the s command was typed to find out the name of the file.

The jobs command was run

to find out which command was suspended. At this time the f¢g command was typed to continue execution of the mail program.

Input to the mail program was then continued and

ended with a TD which indicated the end of the message at which time the mail program
typed EOT. The jobs command will show which commands are suspended. The 1Z should
only be typed at the beginning of a line since everything typed on the current line is discarded
when a signal is sent from the keyboard.

This also happens on INTERRUPT, and QUIT signals.

More information on suspending jobs and controlling them is given in section 2.6.
If you write or run programs which are not fully debugged then it may be necessary to

stop them somewhat ungracefully.

This can be done by sending them a QUIT signal, sent by

typing aT\: This will usually provoke the shell to produce a message like:
Quit (Core dumped)
indicating that a file ‘core’ has been created containing information about the program ‘a.out’s
state when it terminated due to the QUIT signal.

You can examine this file yourself, or for-

ward information to the maintainer of the program telling him/her where the core file is.
If you run background commands (as explained in section 2.6) then these commands will
ignore INTERRUPT and QUIT signals at the terminal.

mand.

To stop them you must use the kill com-

See section 2.6 for an example.

If you want to examine the output of a command without having it move off the screen

as the output of the

cat /etc/passwd
command will, you can use the command

more /etc/passwd
The more program pauses after each complete screenful and types ‘——More——" at which
point you can hit a space to get another screenful, a return to get another line, or a ‘q’ to end
the more program.

You can also use more as a filter, i.e.

cat /etc/passwd | more
works just like the more simple more command above.

For stopping output of commands not involving more you can use the 1S key to stop the
typeout. The typeout will resume when you hit 1Q or any other key, but 1Q is normally used
because it only restarts the output and does not become input to the program which is

4-38

Introduction to the C Shell

running.

This works well on low-speed terminals, but at 9600 baud it is hard to type #S and

1Q fast enough to paginate the output nicely, and a program like more is usually used.

An additional possibility is to use the 1O flush output character; when this character is

typed, all output from the current command is thrown away (quickly) until the next input
read occurs or until the next shell prompt. This can be used to allow a command to complete
without having to suffer through the output on a slow terminal; 10 is a toggle, so flushing can

be turned off by typing 1O again while output is being flushed.
1.9. What now?
We have so far seen a number of mechanisms of the shell and learned a lot about the
way in which it operates.

The remaining sections will go yet further into the internals of the

shell, but you will surely want to try using the shell before you go any further.

To try it you

can log in to UNIX and type the following command to the system:

chsh myname /bin/csh
Here ‘myname’ should be replaced by the name you typed to the system prompt of ‘login:’ to

get onto the system.

Thus I would use ‘chsh bill /bin/csh’.

once; it takes effect at next login.

You only have to do this

You are now ready to try using csh.

Before you do the ‘chsh’ command, the shell you are using when you log into the system

is ‘/bin/sh’.

In fact, much of the above discussion is applicable to ‘/bin/sh’. The next section

will introduce many features particular to csh so you should change your shell to c¢sh before

you begin reading it.

Introduction to the C Shell 4-39

2. Details on the shell for terminal users
2.1. Shell startup and termination

When you login, the shell is started by the system in your home directory and begins by
reading commands from a file .cshrc in this directory.

your terminal session will read from this file.
usefully placed there.

All shells which you may start during

We will later see what kinds of commands are

For now we need not have this file and the shell does not complain

about its absence.

A login shell, executed after you login to the system, will, after it reads commands from
.cshrc, read commands from a file .login also
in your home directory. This file contains commands which you wish to do each time you login to the UNIX system.

My .login file looks

something like:
set ignoreeof

set mail=(/usr/spool/mail/bill)
echo "${prompt}users” ; users
alias ts \

‘set noglob ; eval ‘tset —s —m dialup:c100rvdpna —m plugboard:?hp2621nl **;

ts; stty intr1 C kill U crt
set time=15 history=10
msgs —f

if (—e $mail) then

echo "${prompt }mail”
mail

endif
This file contains several commands to be executed by UNIX each time I login.
is a set

command which is interpreted directly by the shell.

ignoreeof which causes the shell to not log me off if I hit
mand to log off of the system.
incoming mail to me.

The first

It sets the shell variable

Rather, I use the logout com-

By setting the mail variable, I ask the shell to watch for

Every 5 minutes the shell looks for this file and tells me if more mail

has arrived there. An alternative to this is to put the command

biff y

in place of this set; this will cause me to be notified immediately when mail arrives, and to be
shown the first few lines of the new message.
Next I set the shell variable ‘time’ to ‘15’ causing the shell to automatically print out
statistics lines for commands which execute for at least 15 seconds of CPU time.

The variable

‘history’ is set to 10 indicating that I want the shell to remember the last 10 commands I type
in its history list, (described later).

I create an alias “ts” which executes a tset (1) command setting up the modes of the terminal.

The parameters to tset indicate the kinds of terminal which I usually use when not on

a hardwired port.

I then execute “ts” and also use the stty command to change the interrupt

character to 1T C and the line kill character to 1 U.
I then run the ‘msgs’ program, which provides me with any system messages which I

have not seen before; the ‘—f” option here prevents it from telling me anything if there are no

‘new messages. Finally, if my mailbox file exists, then I run the ‘mail’ program to process my
mail.

When the ‘mail’ and ‘msgs’ programs finish, the shell will finish processing my .login file

and begin reading commands from the terminal, prompting for each with ‘% ’. When I log off
(by giving the logout command) the shell will print ‘logout’ and execute commands from the
file ‘logout’ if it exists in my home directory. After that the shell will terminate and UNIX will
log me off the system.

If the system is not going down, I will receive a new login message.

any case, after the ‘logout’ message the shell is committed to terminating and will take no

4-40 Introduction to the C Shell
further input from my terminal.
2.2.

Shell variables

The shell maintains a set of variables. We saw above the variables history and time
which had values ‘10’ and ‘15’. In fact, each shell variable has as value an array of zero or
more strings. Shell variables may be assigned values by the set command. It has several
forms, the most useful of which was given above and is
set name=value

Shell variables may be used to store values which are to be used in commands later
through a substitution mechanism. The shell variables most commonly referenced are, however, those which the shell itself refers to. By changing the values of these variables one can
directly affect the behavior of the shell.

One of the most important variables is the variable path. This variable contains a
sequence of directory names where the shell searches for commands. The set command with
no arguments shows the value of all variables currently defined (we usually say set) in the
shell. The default value for path will be shown by set to be
% set
argv

cwd
home
path

/usr/bill
/usr/bill
(. /usr/ucb /bin /usr/bin)

prompt

shell

/bin/csh

status

term

c100rv4pna

user

bill

This output indicates that the variable path points to the current directory ‘.’ and then

‘/usr/uch’, ‘/bin’ and ‘/usr/bin’. Commands which you may write might be in ‘.’ (usually one of
your directories). Commands developed at Berkeley, live in ‘/usr/ucb’ while commands
developed at Bell Laboratories live in ‘/bin’ and ‘/usr/bin’.

A number of locally developed programs on the system live in the directory ‘/usr/local’.
If we wish that all shells which we invoke to have access to these new programs we can place
the command

set path=(. /usr/ucb /bin /usr/bin /usr/local)
in our file .cshrc in our home directory. Try doing this and then logging out and back in and
do
set

again to see that the value assigned to path has changed.
One thing you should be aware of is that the shell examines each directory which you
insert into your path and determines which commands are contained there. Except for the
current directory ‘., which the shell treats specially, this means that if commands are added to
a directory in your search path after you have started the shell, they will not necessarily be
found by the shell. If you wish to use a command which has been added in this way, you
should give the command
rehash

to the shell, which will cause it to recompute its internal table of command locations, so that
it will find the newly added command. Since the shell has to look in the current directory ‘.’

Introduction to the C Shell 4-41

on each command, placing it at the end of the path specification usually works equivalently
and reduces overhead.
Other useful built in variables are the variable home which shows your home directory,
cwd which contains your current working directory, the variable ignoreeof which can be set in
your .login file to tell the shell not to exit when it receives an end-of-file from a terminal (as

described above).

The variable ‘ignoreeof’ is one of several variables which the shell does not

care about the value of, only whether they are set or unset. Thus to set this variable you simply do

set ignoreeof

and to unset it do
unset ignoreeof

These give the variable ‘ignoreeof’ no value, but none is desired or required.
Finally, some other built-in shell variables of use are the variables noclobber and mail.
The metasyntax
> filename

which redirects the standard output of a command will overwrite and destroy the previous
contents of the named file.

In this way you may accidentally overwrite a file which is valu-

able. If you would prefer that the shell not overwrite files in this way you can
set noclobber
in your .login file. Then trying to do

date > now

would cause a diagnostic if ‘now’ existed already. You could type
date >! now
if you really wanted to overwrite the contents of ‘now’.

The ‘>!" is a special metasyntax indi-

cating that clobbering the file is ok.t
2.3. The shell’s history list
The shell can maintain a history list into which it places the words of previous commands.

It is possible to use a notation to reuse commands or words from commands in form-

ing new commands.

This mechanism can be used to repeat previous commands or to correct

minor typing mistakes in commands.
The following figure gives
mechanism of the shell.

a sample session

involving typical usage of the history

In this example we have a very simple C program which has a bug

(or two) in it in the file ‘bug.c’, which we ‘cat’ out on our terminal.

We then try to run the C

compiler on it, referring to the file again as ‘!$’, meaning the last argument to the previous

command.

Here the ‘!’ is the history mechanism invocation metacharacter, and the ‘$’ stands

for the last argument, by analogy to ‘¢’ in the editor which stands for the end of the line. The

shell echoed the command, as it would have been typed without use of the history mechanism,
and then executed it.

The compilation yielded error diagnostics so we now run the editor on

the file we were trying to compile, fix the bug, and run the C compiler again, this time referring to this command simply as ‘I¢’, which repeats the last command which started with the
letter ‘c’.

If there were other commands starting with ‘c’ done recently we could have said ‘!cc’

or even ‘lcc:p’ which would have printed the last command starting with ‘cc’ without executing
it.
TThe space between the ‘" and the word ‘now’ is critical here, as ‘‘'now’ would be an invocation of the historv mechanism, and have a totally different effect.

Introduction to the C Shell

% cat bug.c
main()

{

printf("hello);

)

% cc'$

cc bug.c

"bug.c”, line 4. newline in string or char constant
"bug.c”, line 5: syntax error

% ed !$
ed bug.c
29

4s/);/”&/p
printf("hello”);
W

30
q

% lc

cc bug.c

% a.out
hello% le

ed bug.c
30

4s/lo/1o\\n/p
printf("hello.n”);
w

32
q

% lc —o bug

cc bug.c —o bug

% size a.out bug
a.out: 2784+364+1028 = 4176b = 0x1050b

bug: 2784+364+1028 = 4176b = 0x1050b

% ls —11*
Is =1 a.out bug
—rwxr-xr-x 1 bill

3932 Dec 19 09:41 a.out

-rwxr-xr—x 1 bill

3932 Dec 19 09:42 bug

% bug
hello

% num bug.c | spp
spp: Command not found.

% 1 spptssp

num bug.c | ssp
main()
(

printf(”hello\'n”);

}

% ! llpr
i

4-42

num bug.c |ssp | lpr
%

Introduction to the C Shell 4-43
After this recompilation, we ran the resulting ‘a.out’ file, and then noting that there still

was a bug, ran the editor again.

After fixing the program we ran the C compiler again, but

tacked onto the command an extra ‘—o bug’ telling the compiler to place the resultant binary
in the file ‘bug’ rather than ‘a.out’.

In general, the history mechanisms may be used anywhere

in the formation of new commands and other characters may be placed before and after the

- substituted commands.

We then ran the ‘size’ command to see how large the binary program images we have
created were, and then an ‘Is =1’ command with the same argument list, denoting the argument list ‘*’. Finally we ran the program ‘bug’ to see that its output is indeed correct.

To make a numbered listing of the program we ran the ‘num’ command on the file
‘bug.c’.

In order to compress out blank lines in the output of ‘num’ we ran the output through

the filter ‘ssp’, but misspelled it as spp.

To correct this we used a shell substitute, placing the

old text and new text between ‘1’ characters. This is similar to the substitute command in the
editor.

Finally, we repeated the same command with ‘", but sent its output to the line

printer.

There are other mechanisms available for repeating commands.

The history command

prints out a number of previous commands with numbers by which they can be referenced.
There is a way to refer to a previous command by searching for a string which appeared in it,

and there are other, less useful, ways to select arguments to include in a new command.

complete description of all these mechanisms is given in the C shell manual pages in the UNIX
Programmers Manual.

2.4. Aliases

The shell has an alias mechanism which can be used to make transformations on input
commands.

This mechanism can be used to simplify the commands you type, to supply

default arguments to commands, or to perform transformations on commands and their arguments.

The alias facility is similar to a macro facility.

Some of the features obtained by alias-

ing can be obtained also using shell command files, but these take place in another instance of
the shell and cannot directly affect the current shells environment or involve commands such
as cd which must be done in the current shell.
As an example, suppose that there is a new version of the mail program on the system

called ‘newmail’ you wish to use, rather than the standard mail program which is called ‘mail’.
If you place the shell command

alias mail newmail
in your .cshrc file, the shell will transform an input line of the form
mail bill

into a call on ‘newmail’.

More generally, suppose we wish the command ‘ls’ to always show

sizes of files, that is to always do ‘—s’. We can do
alias Is Is —s
or even

alias dir Is —

creating a new command syntax ‘dir’ which does an ‘lIs —s’. If we say
dir “bill

then the shell will translate this to

Is —s /mnt/bill
hus the alias mechanism can beused to provide short names for commands, to provide

default arguments, and to definenew short commandsin terms
of other commands. It is also

4-44

Introduction to the C Shell

possible to define aliases which contain multiple commands or pipelines, showing where the
arguments to the original command are to be substituted using the facilities of the history

mechanism.

Thus the definition

alias c¢d “cd \!* ; 1s~
would do an Is command after each change directory cd command. We enclosed the entire
alias definition in *” characters to prevent most substitutions from occurring and the character
;’ from being recognized as a metacharacter. The ‘!’ here is escaped with a ‘X to prevent it
from being interpreted when the alias command is typed in. The ‘X*’ here substitutes the
entire argument list to the pre-aliasing ¢d command, without giving an error if there were no
arguments. The ‘;’ separating commands is used here to indicate that one command is to be
done and then the next. Similarly the definition

alias whois “grep \! T /etc/passwd’
defines a command which looks up its first argument in the password file.
Warning: The shell currently reads the .cshre file each time it starts up. If you place a
large number of commands there, shells will tend to start slowly. A mechanism for saving the
shell environment after reading the .cshre file and quickly restoring it is under development,

but for now you should try to limit the number of aliases you have to a reasonable number...

10 or 15 is reasonable, 50 or 60 will cause a noticeable delay in starting up shells, and make

the system seem sluggish when you execute commands from within the editor and other programs.

2.5.

More redirection; >> and >&

There are a few more notations useful to the terminal user which have not been intro-

duced yet.

In addition to the standard output, commands also have a diagnostic output which is
normally directed to the terminal even when the standard output is redirected to a file or a
pipe. It is occasionally desirable to direct the diagnostic output along with the standard output. For instance if you want to redirect the output of a long running command into a file
and wish to have a record of any error diagnostic it produces you can do

command >& file
The “>&’ here tells the shell to route both the diagnostic output and the standard output into
‘file’.

Similarly you can give the command

command | & lpr
to route both standard and diagnostic output through the pipe to the line printer daemon

[pr.it

‘
Finally, it is possible to use the form

command >> file

to place output at the end of an existing file.t
#A command form
command >&! file
exists, and is used when noclobber is set and file already exists.

TIf noclobber is set, then an error will result if file does not exist, otherwise the shell will create file if it
doesn’t exist. A form
command >>! file

makes it not be an error for file to not exist when noclobber is set.

Introduction to the C Shell 4-45

2.6. Jobs; Background, Foreground, or Suspended
When one or more commands are typed together as a pipeline or as a sequence of commands separated by semicolons, a single job is created by the shell consisting of these commands together as a unit.

jobs.

Single commands without pipes or semicolons create the simplest

Usually, every line typed to the shell creates a job.

Some lines that create jobs (one per

line) are

sort < data

Is —s | sort —n| head =5
mail harold

If the metacharacter ‘&’ is typed at the end of the commands, then the job is started as

a background job. This means that the shell does not wait for it to complete but immediately
prompts and is ready for another command.

The job runs in the background at the same

time that normal jobs, called foreground jobs, continue to be read and executed by the shell
one at a time.

Thus

du > usage &
would run the du program, which reports on the disk usage of your working directory (as well

as any directories below it), put the output into the file ‘usage’ and return immediately with a
prompt for the next command without out waiting for du to finish.

The du program would

continue executing in the background until it finished, even though you can type and execute
more commands in the mean time.

When a background job terminates, a message is typed by

the shell just before the next prompt telling you that the job has completed.

In the following

example the du job finishes sometime during the execution of the mail command and its completion is reported just before the prompt after the mail job is finished.

% du > usage &
[1] 503

% mail bill
How do you know when a background job is finished?
EOT
[1] — Done

|
du > usage

%
If the job did not terminate normally the ‘Done’ message might say something else like

‘Killed’.

If you want the terminations of background jobs to be reported at the time they

occur (possibly interrupting the output of other foreground jobs), you can set the notify variable.

In the previous example this would mean that the ‘Done’ message might have come

right in the middle of the message to Bill.

Background jobs are unaffected by any signals

from the keyboard like the STOP, INTERRUPT, or QUIT signals mentioned earlier.

Jobs are recorded in a table inside the shell until they terminate.

In this table, the shell

remembers the command names, arguments and the process numbers of all commands in the

job as well as the working directory where the job was started.

Each job in the table is either

running in the foreground with the shell waiting for it to terminate, running in the back-

ground, or suspended. Only one job can be running in the foreground at one time, but several

jobs can be suspended or running in the background at once.

As each job is started, it is

assigned a small identifying number called the job number which can be used later to refer to
the job in the commands described below.

Job numbers remain the same until the job ter-

minates and then are re-used.

When a job is started in the backgound using ‘&’, its number, as well as the process
b/

numbers of all its (top level) commands, is typed by the shell before prompting you for

another command. For example,

4-46

Introduction to the C Shell

% 1s —s |sort —n > usage &
[2] 2034 2035

%
runs the ‘Is’ program with the ‘—s’ options, pipes this output into the ‘sort’ program with the
‘—n’ option which puts its output into the file ‘usage’.

Since the ‘&’ was at the end of the line,

these two programs were started together as a background job.

After starting the job, the

shell prints the job number in brackets (2 in this case) followed by the process number of each
program started in the job.

Then the shell immediates prompts for a new command, leaving

the job running simultaneously.
As mentioned in section 1.8, foreground jobs become suspended by typing 1Z which

sends a STOP signal to the currently running foreground job.
suspended by using the stop

command described below.

A background job can become
When jobs are suspended they

merely stop any further progress until started again, either in the foreground or the back-

gound.

The shell notices when a job becomes stopped and reports this fact, much like it

reports the termination of background jobs.

For foreground jobs this looks like

% du > usage

Stopped
%
‘Stopped’ message is typed by the shell when it notices that the du program stopped.

For

background jobs, using the stop command, it is

% sort usage &
[1] 2345

% stop %1
[1] + Stopped (signal)

sort usage

Suspending foreground jobs can be very useful when you need to temporarily change what you
are doing (execute other commands) and then return to the suspended job.

Also, foreground

jobs can be suspended and then continued as background jobs using the bg command, allowing you to continue other work and stop waiting for the foreground job to finish.

Thus

% du > usage

17
Stopped

% bg
[1] du > usage &

%
starts ‘du’ in the foreground, stops it before it finishes, then continues it in the background
allowing more foreground commands to be executed.

This is especially helpful when a fore-

ground job ends up taking longer than you expected and you wish you had started it in the

backgound in the beginning.
All job control commands can take an argument that identifies a particular job.

All job

name arguments begin with the character ‘%’, since some of the job control commands also
accept process numbers (printed by the ps command.) The default job (when no argument is

given) is called the current job and is identified by a ‘4’ in the output of the jobs command,

which shows you which jobs you have.

When only one job is stopped or running in the back-

ground (the usual case) it is always the current job thus no argument is needed.

If a job is

stopped while running in the foreground it becomes the current job and the existing current
job becomes the previous job — identified by a ‘=’ in the output of jobs. When the current

job terminates, the previous job becomes the current job.

When given, the argument is either

‘% —’ (indicating the previous job); ‘% #’, where # is the job number; ‘% pref’ where pref is

Introduction to the C Shell 4-47

some unique prefix of the command name and arguments of one of the jobs; or ‘%
?’ followed
by some string found in only one of the jobs.
The jobs command types the table of jobs, giving the job number, commands and status
(‘Stopped’ or ‘Running’) of each backgound or suspended job. With the ‘—1’ option the process numbers are also typed.

% du > usage &
[1] 3398

% 1s —s | sort —n > myfile &

[2] 3405

% mail bill
17
Stopped

% jobs
[1] Running

[2]

Running

[3] s Stopped

% fg %ls
Is —s | sort —n > myfile

du > usage

Is —s | sort —n > myfile
mail bill

% more myfile
The fg command runs a suspended or background job in the foreground.

It is used to

restart a previously suspended job or change a background job to run in the foreground
(allowing signals or input from the terminal). In the above example we used fg to change the
‘Is’ job from the background to the foreground since we wanted to wait for it to finish before
looking at its output file. The bg command runs a suspended job in the background. It is
usually used after stopping the currently running foreground job with the STOP signal. The
combination of the STOP signal and the bg command changes a foreground job into a background job. The stop command suspends a background job.
The kill command terminates a background or suspended job immediately. In addition
to jobs, it may be given process numbers as arguments, as printed by ps. Thus, in the example
above, the running du command could have been terminated by the command
% kill %1
[1] Terminated

du > usage

The notify command (not the variable mentioned earlier) indicates that the termination
of a specific job should be reported at the time it finishes instead of waiting for the next
prompt.

If a job running in the background tries to read input from the terminal it is automatically stopped. When such a job is then run in the foreground, input can be given to the job.
If desired, the job can be run in the background again until it requests input again. This is
illustrated in the following sequence where the ‘s’ command in the text editor might take a
long time.

% ed bigfile
120000

1,$s/thisword/thatword/
17
Stopped

% bg
[1] ed bigfile &

. .. some foreground commands
[1] Stopped (tty input)

ed bigfile

4-48

Introduction to the C Shell

% fg

ed bigfile
W

120000
q

So after the ‘s’ command was issued, the ‘ed’ job was stopped with {Z and then put in the
background using bg. Some time later when the ‘s’ command was finished, ed tried to read
another command and was stopped because jobs in the backgound cannot read from the terminal. The f¢ command returned the ‘ed’ job to the foreground where it could once again
accept commands from the terminal.

The command
stty tostop

causes all background jobs run on your terminal to stop when they are about to write output

to the terminal.

This prevents messages from background jobs from interrupting foreground
job output and allows you to run a job in the background without losing terminal output. It

also can be used for interactive programs that sometimes have long periods without interac-

tion.

Thus each time it outputs a prompt for more input it will stop before the prompt. It
can then be run in the foreground using fg, more input can be given and, if necessary stopped
and returned to the background. This stty command might be a good thing to put in your
login file if you do not like output from background jobs interrupting your work.

It also can

reduce the need for redirecting the output of background jobs if the output is not very big:

% stty tostop
% wc hugefile &
[1] 10387

% ed text
. . . some time later
q

[1] Stopped (tty output)

wc hugefile

% fg wc
wc hugefile
13371

30123

302577

% stty —tostop
Thus after some time the ‘we¢’ command, which counts the lines, words and characters in a
When it tried to write this to the terminal it stopped. By restart-

file, had one line of output.

ing it in the foreground we allowed it to write on the terminal exactly when we were ready to

look at its output.

Programs which attempt to change the mode of the terminal will also
block, whether or not tostop is set, when they are not in the foreground, as it would be very

unpleasant to have a background job change the state of the terminal.

Since the jobs command only prints jobs started in the currently executing shell, it
knows nothing about background jobs started in other login sessions or within shell files.

The
ps can be used in this case to find out about background jobs not started in the current shell.
2.7. Working Directories

As mentioned in section 1.6, the shell is always in a particular working directory. The
‘change directory’ command chdir (its short form ¢d may also be used) changes the working
directory of the shell, that is, changes the directory you are located in.
It is useful to make a directory for each project you wish to work on and to place all files

related to that project in that directory.

The ‘make directory’ command, mkdir, creates a new
The pwd (‘print working directory’) command reports the absolute pathname of
the working directory of the shell, that is, the directory you are located in. Thus in the

directory.

Introduction to the C Shell 4-49

example below:

% pwd
fusr/bill
% mkdir newpaper
% chdir newpaper
% pwd
/usr/bill/newpaper
%

the user has created and moved to the directory newpaper. where, for example, he might
place a group of related files.
No matter where you have moved to in a directory hierarchy, you can return to your
‘home’ login directory by doing just
cd

with no arguments.

The name ‘..’ always means the directory above the current one in the

hierarchy, thus

cd ..
changes the shell’s working directory to the one directly above the current one.

The name .’

can be used in any pathname, thus,

cd ../programs
means change to the directory ‘programs’ contained in the directory above the current one.

you have several directories for different projects under, say, your home directory, this shorthand notation permits you to switch easily between them.
The shell always remembers the pathname of its current working directory in the vari-

able cwd.

The shell can also be requested to remember the previous directory when you

change to a new working directory. If the ‘push directory’ command pushd is used in place of
the ¢d command, the shell saves the name of the current working directory on a directory
stack before changing to the new one.

You can see this list at any time by typing the ‘direc-

tories’ command dirs.

% pushd newpaper/references
“/newpaper/references ~

% pushd /usr/lib/tmac
/usr/lib/tmac ”/newpaper/references -

% dirs
/usr/lib/tmac ~/newpaper/references ~
% popd
“/newpaper/references ~
% popd
%
The list is printed in a horizontal line, reading left to right, with a tilde (7) as shorthand for

your home directory—in this case ‘/usr/bill’. The directory stack is printed whenever there is
more than one entry on it and it changes.

Itis also printed by a dirs command.

Dirs is usu-

ally faster and more informative than pwd since it shows the current working directory as well

as any other directories remembered in the stack.
The pushd command with no argument alternates the current directory with the first

directory in the list. The ‘pop directory’ popd command without an argument returns you to

the directory you were in prior to the current one, discarding the previous current directory
from the stack (forgetting it).
vad

VRAS AN

\ o

bt
o

Typing popd
22y

several times in a series takes you backward
N e

- .

(€

[SA VS A

VIR
AR WINS

through the dlrectorles you had been in (changed to) by pushd command.

There are other

4-50 Introduction to the C Shell

options to pushd and popd to manipulate the contents of the directory stack and to change to
directories not at the top of the stack; see the csh manual page for details.
Since the shell remembers the working directory in which each job was started, it warns
you when you might be confused by restarting a job in the foreground which has a different
working directory than the current working directory of the shell.

Thus if you start a back-

ground job, then change the shell’s working directory and then cause the background job to
run in the foreground, the shell warns you that the working directory of the currently running

foreground job is different from that of the shell.

% dirs —1

/mnt/bill
% cd myproject
% dirs
“/myproject

% ed prog.c
1143

17
Stopped

% cd ..
% ls
myproject

textfile

% fg
ed prog.c (wd: “/myproject)
This way the shell warns you when there is an implied change of working directory, even
though

no c¢d command was issued. In the above example the ‘ed’ job was still in
‘/mnt/bill/project’ even though the shell had changed to ‘/mnt/bill’. A similar warning is given
when such a foreground job terminates or is suspended (using the STOP signal) since the
return to the shell again implies a change of working directory.

% fg
ed prog.c (wd: “/myproject)
. . . after some editing
q

(wd now: ")
%
These messages are sometimes confusing if you use programs that change their own working

directories, since the shell only remembers which directory a job is started in, and assumes it
stays there.

The ‘—1’ option of jobs will type the working directory of suspended or back-

ground jobs when it is different from the current working directory of the shell.

2.8. Useful built-in commands
We now give a few of the useful built-in commands of the shell describing how they are
used.

The alias command described above is used to assign new aliases and to show the existing aliases.

With no arguments it prints the current aliases.

It may also be given only one

argument such as

alias lIs
to show the current alias for, e.g., ‘Is’.
The echo command prints its arguments.

It is often used in shell scripts or as an

interactive command to see what filename expansions will produce.

Introduction to the C Shell 4-51

The history command will show the contents of the history list.

The numbers given

with the history events can be used to reference previous events which are difficult to refer-

ence using the contextual mechanisms introduced above.

There is also a shell variable called

prompt. By placing a ‘I’ character in its value the shell will there substitute the number of the

current command in the history list.
history substitution.

You can use this number to refer to this command in a

Thus you could

set prompt="\! % ~
Note that the ‘I’ character had to be escaped here even within ¢” characters.
The limit command is used to restrict use of resources.

With no arguments it prints the

current limitations:

cputime
filesize

unlimited
unlimited

datasize

5616 kbytes

stacksize

512 kbytes

coredumpsize

unlimited

Limits can be set, e.g.:
limit coredumpsize 128k

Most reasonable units abbreviations will work; see the csh manual page for more details.
The logout command can be used to terminate a login shell which has ignoreeof set.
The rehash command causes the shell to recompute a table of where commands are

located.

This is necessary if you add a command to a directory in the current shell’s search

path and wish the shell to find it, since otherwise the hashing algorithm may tell the shell that
the command wasn’t in that directory when the hash table was computed.
The repeat command can be used to repeat a command several times.

copies of the file one in the file five you could do

Thus to make 5

repeat 5 cat one >> five
The setenv command can be used to set variables in the environment.

Thus

setenv TERM adm3a

will set the value of the environment variable TERM to ‘adm3a’.
exists which will print out the environment.

A user program printenv

It might then show:

% printenv
HOME=/usr/bill

SHELL=/bin/csh
PATH-=:/usr/uchb:/bin:/usr/bin:/usr/local
TERM=adm3a

USER=hbill
%
The source command can be used to force the current shell to read commands from a
file.

Thus

source .cshre

can be used after editing in a change to the .cshrc file which you wish to take effect before the
next time you login.

The time command can be used to cause a command to be timed no matter how much
CPU time it takes.

Thus

4-52 Introduction to the C Shell

% time cp /etc/rc /usr/bill/rc
0.0u 0.1s 0:01 8% 2+1k 3+2io 1pf+0w
% time wc /etc/rc /usr/bill/rc

52
52

178
178

1347 /etc/rc
1347 /usr/bill/rc

104

356

2694 total

0.1u 0.1s 0:00 13% 3+3k 5+3io 7Tpf+0w
%

indicates that the ¢p command used a negligible amount of user time (u) and about 1/10th of

a system time (s); the elapsed time was 1 second (0:01), there was an average memory usage of
2k bytes of program space and 1k bytes of data space over the cpu time involved (2+1k); the

program did three disk reads and two disk writes (3+2i0), and took one page fault and was
not swapped (1pf+0w).

The word count command wc on the other hand used 0.1 seconds of

user time and 0.1 seconds of system time in less than a second of elapsed time.

The percen-

tage ‘13%’ indicates that over the period when it was active the command ‘wc¢’ used an average of 13 percent of the available CPU cycles of the machine.
The unalias and unset commands can be used to remove aliases and variable definitions
from the shell, and unsetenv removes variables from the environment.
2.9. What else?

This concludes the basic discussion of the shell for terminal users.

There are more

features of the shell to be discussed here, and all features of the shell are discussed in its

manual pages.

One useful feature which is discussed later is the foreach built-in command

which can be used to run the same command sequence with a number of different arguments.
If you intend to use UNIX a lot you you should look through the rest of this document

and the shell manual pages to become familiar with the other facilities which are available to
youl.

Introduction to the C Shell

4-53

3. Shell control structures and command scripts
3.1. Introduction
It is possible to place commands in files and to cause shells to be invoked to read and

execute commands from these files, which are called shell scripts.

We here detail those

features of the shell useful to the writers of such scripts.

3..2. Make
It is important to first note what shell scripts are not useful for.

There is a program

called make which is very useful for maintaining a group of related files or performing sets of
operations on related files.

For instance a large program consisting of one or more files can

have its dependencies described in a makefile which contains definitions of the commands

used to create these different files when changes occur.

Definitions of the means for printing

listings, cleaning up the directory in which the files reside, and installing the resultant pro-

grams are easily, and most appropriately placed in this makefile. This format is superior and
preferable to maintaining a group of shell procedures to maintain these files.

Similarly when working on a document a makefile may be created which defines how

different versions of the document are to be created and which options of nroff or troff are
appropriate.

3.3. Invocation and the argv variable
A csh command script may be interpreted by saying

% csh script ...
where script is the name of the file containing a group of csh commands and ‘...’ is replaced

by a sequence of arguments.

The shell places these arguments in the variable argv and then

begins to read commands from the script.

These parameters are then available through the

same mechanisms which are used to reference any other shell variables.
If you make the file ‘script’ executable by doing

chmod 755 script

and place a shell comment at the beginning of the shell script (i.e. begin the file with a ‘#’
character) then a ‘/bin/csh’ will automatically be invoked to execute ‘script’ when you type
script

If the file does not begin with a ‘#’ then the standard shell ‘/bin/sh’ will be used to execute it.
This allows you to convert your older shell scripts to use csh at your convenience.

3.4. Variable substitution
After each input line is broken into words and history substitutions are done on it, the
input line is parsed into distinct commands.

Before each command is executed a mechanism

know as variable substitution is done on these words.

Keyed by the character ‘$’ this substi-

tution replaces the names of variables by their values. Thus

when placed in a command script would cause the current value of the variable argv to be
echoed to the output of the shell script. It is an error for argv to be unset at this point.
A number of notations are provided for accessing components and attributes of variables.

The notation

$7name

expands to ‘1’ if name is set or to ‘0’ if name is not set. It is the fundamental mechanism used
for checking whether particular variables have been assigned values.

All other forms of

4-54 Introduction to the C Shell
reference to undefined variables cause errors.
The notation

$#name

expands to the number of elements in the variable name. Thus
% set argv=(a b ¢)
% echo $?argv
1

% echo $#argv
3

% unset argv

% echo $?argv
0

% echo $argv
Undefined variable: argv.
%

It is also possible to access the components of a variable which has several values. Thus
$argv[1]

gives the first component of argv or in the example above ‘a’. Similarly
$argv[$Hargv]

would give ‘c’, and
$argv[1—2]

would give ‘a b’. Other notations useful in shell scripts are
$n

where n is an integer as a shorthand for
$argv[n]

the nth parameter and
g

which is a shorthand for
$argv
The form

$&
expands to the process number of the current shell. Since this process number is unique in
the system it can be used in generation of unique temporary file names. The form
$<

is quite special and is replaced by the next line of input read from the shell’s st anaara imput
(not the script it is reading). This is useful for writing shell scripts that are interactive, reading commands from the terminal, or even writing a shell script that acts as a filter, reading

RPN

.S4

lines from its input file. Thus the sequence

echo ’yes or no?\c’
set a=($<)

would write out the prompt ‘yes or no?’ without a newline and then read the answer into the
variable ‘a’. In this case ‘$#a’ would be ‘0’ if either a blank line or end-of-file (1D) was typed.

Introduction to the C Shell 4-55

One minor difference between ‘$n’ and ‘$argv[n]” should be noted here. The form
‘$argv[n]’ will yield an error if n is not in the range ‘1—$#argv’ while ‘$n’ will never yield an
out of range subscript error. This is for compatibility with the way older shells handled
parameters.

Another important point is that it is never an error to give a subrange of the form ‘n—’
if there are less than n components of the given variable then no words are substituted. A
range of the form ‘m—n’ likewise returns an empty vector without giving an error when m
exceeds the number of elements of the given variable, provided the subscript n is in range.
3.5. Expressions

In order for interesting shell scripts to be constructed it must be possible to evaluate
expressions in the shell based on the values of variables. In fact, all the arithmetic operations
of the language C are available in the shell with the same precedence that they have in C. In

particular, the operations ‘==’ and ‘!=" compare strings and the operators ‘&&’ and il imple-

ment the boolean and/or operations. The special operators ‘="" and ‘! are similar to ‘==’ and
‘I=> except that the string on the right side can have pattern matching characters (like *, 7 or

[1) and the test is whether the string on the left matches the pattern on the right.
The shell also allows file enquiries of the form
—? filename

where ‘?’ is replace by a number of single characters. For instance the expression primitive
—e filename

tell whether the file ‘filename’ exists. Other primitives test for read, write and execute access
to the file, whether it is a directory, or has non-zero length.
It is possible to test whether a command terminates normally, by a primitive of the form
‘{ command }’ which returns true, i.e. ‘1’ if the command succeeds exiting normally with exit
status 0, or ‘0’ if the command terminates abnormally or with exit status non-zero. If more
detailed information about the execution status of a command is required, it can be executed
and the variable ‘$status’ examined in the next command. Since ‘$status’ is set by every command, it is very transient. It can be saved if it is inconvenient to use it only in the single
immediately following command.

For a full list of expression components available see the manual section for the shell.
3.6. Sample shell script

A sample shell script which makes use of the expression mechanism of the shell and
some of its control structure follows:

4-56 Introduction to the C Shell

% cat copyc
#

# Copyc copies those C programs in the specified list
# to the directory “/backup if they differ from the files
# already in “/backup
H#
set noglob

foreach i ($argv)

if ($1!” *.c) continue # not a .c file so do nothing

if (! —r “/backup/$i:t) then
echo $i:t not in backup... not cpxXed
continue

endif

cmp —s $i “/backup/$i:t # to set $status
if ($status != 0) then

echo new backup of $i

cp $i “/backup/$i:t
endif
end
This script makes use of the foreach command, which causes the shell to execute the
commands between the foreach and the matching end for each of the values given between ‘(’

and ‘)’ with the named variable, in this case ‘i’ set to successive values in the list. Within this
loop we may use the command break to stop executing the loop and continue to prematurely
terminate one iteration and begin the next.

After the foreach loop the iteration variable (i in

this case) has the value at the last iteration.

We set the variable noglob here to prevent filename expansion of the members of argv.

This is a good idea, in general, if the arguments to a shell script are filenames which have
already been expanded or if the arguments may contain filename expansion metacharacters.
It is also possible to quote each use of a ‘$’ variable expansion, but this is harder and less reli-

able.

,
The other control construct used here is a statement of the form
if ( expression ) then

command
endif
The placement of the keywords here is not flexible due to the current implementation of the

shell.T
TThe following two formats are not currently acceptable to the shell:
if ( expression )

# Won’t work!

then

command
endif
and
if
(
AL

eAyr
'@
)

WVERAS /AL LUULIIAIIQAAIIA

.l.l.\all..l

Introduction to the C Shell 4-57

The shell does have another form of the if statement of the form
if ( expression ) command

which can be written

if ( expression ) \
command
Here we have escaped the newline for the sake of appearance.

The command must not

involve ‘I’, ‘&’ or ‘;’ and must not be another control command. The second form requires the
final ‘\ to immediately precede the end-of-line.
The more general if statements above also admit a sequence of else—if pairs followed by
a single else and an endif, e.g.:
if ( expression ) then

commands

else if (expression ) then
commands

else
commands
endif

Another important mechanism used in shell scripts is the ¢’ modifier. We can use the
modifier “:r’ here to extract a root of a filename or ‘e’ to extract the extension. Thus if the
variable ¢ has the value ‘/mnt/foo.bar’ then
’

% echo $i $i:r $ice
/mnt/foo.bar /mnt/foo bar
%

shows how the “r’ modifier strips off the trailing ‘.bar’ and the the ‘¢’ modifier leaves only the

‘bar’. Other modifiers will take off the last component of a pathname leaving the head :h’ or
all but the last component of a pathname leaving the tail ‘t’.

These modifiers are fully

described in the csh manual pages in the programmers manual. It is also possible to use the
command

substitution

mechanism

described

the

major

modifications on strings to then reenter the shells environment.

section

perform

Since each usage of this

mechanism involves the creation of a new process, it is much more expensive
to use than the

‘> modification mechanism.## Finally, we note that the character ‘#’ lexically introduces a
shell comment in shell scripts (but not from the terminal).

All subsequent characters on the

input line after a ‘#’ are discarded by the shell. This character can be quoted using ‘’ or ‘\ to
place it in an argument word.

3.7. Other control structures

The shell also has control structures while and switch similar to those of C. These take
the

forms
E-% -3

#1It is also important to note that the current implementation of the shell limits the number of ‘:” modifiers
on a ‘$ substitution to 1. Thus

% echo $i $i:h:t

/a/b/c /a/b:t
%

does not do what one would expect.

4-58 Introduction to the C Shell

while ( expression )
commands
end

and

switch ( word )
case strl:

commands
breaksw

case strn:

commands
breaksw
default:
commands
breaksw
endsw

For details see the manual section for csh. C programmers should note that we use breaksw to
exit from a switch while break exits a while or foreach loop.

A common mistake to make in

csh scripts is to use break rather than breaksw in switches.
Finally, csh allows a goto statement, with labels looking like they do in C, i.e.:

loop:

commands
goto loop

3.8. Supplying input to commands
Commands run from shell scripts receive by default the standard input of the shell
which is running the script.

This is different from previous shells running under UNIX.

allows shell scripts to fully participate in pipelines, but mandates extra notation for commands which are to take inline data.

Thus we need a metanotation for supplying inline data to commands in shell scripts. As
an example, consider this script which runs the editor to delete leading blanks from the lines
in each argument file

% cat deblank
# deblank —— remove leading blanks
foreach i ($argv)

ed — $i << 'EOF’

1,8s/1 1%//
W

"‘EOF’

end
%
The notation ‘<< "EOF” means that the standard input for the ed command is to come from

the text in the shell script file up to the next line consisting of exactly “EOF”.

The fact that

the ‘EOF’ is enclosed in ‘” characters, i.e. quoted, causes the shell to not perform wvariable

Introduction to the C Shell 4-59

substitution on the intervening lines. In general, if any part of the word following the ‘<<’
which the shell uses to terminate the text to be given to the command is quoted then these
substitutions will not be performed. In this case since we used the form ‘1,$’ in our editor
script we needed to insure that this ‘$’ was not variable substituted. We could also have

insured this by preceding the ‘$’ here with a ‘\’, i.e.:

L\$s/A[ 1*//
but quoting the ‘EOF’ terminator is a more reliable way of achieving the same thing.
3.9.#Catching interrupts

If our shell script creates temporary files, we may wish to catch interruptions of the shell
script so that we can clean up these files. We can then do
onintr label

where label is a label in our program. If an interrupt is received the shell will do a ‘goto label’
and we can remcve the temporary files and then do an exit command (which is built in to the
shell) to exit from the shell script. If we wish to exit with a non-zero status we can do
exit(1)

e.g. to exit with status ‘1’.

3.10. What else?

There are other features of the shell useful to writers of shell procedures. The verbose
and echo options and the related —v and —x command line options can be used to help trace
the actions of the shell. The —n option causes the shell only to read commands and not to
execute them and may sometimes be of use.

One other thing to note is that csh will not execute shell scripts which do not begin with
the character ‘#’, that is shell scripts that do not begin with a comment. Similarly, the
‘/bin/sh’ on your system may well defer to ‘csh’ to interpret shell scripts which begin with ‘#’.
This allows shell scripts for both shells to live in harmony.

There is also another quotation mechanism using
which allows only some of the
expansion mechanisms we have so far discussed to occur on the quoted string and serves to
€9y

make this string into a single word as ” does.

4-60

Introduction to the C Shell

4. Other, less commonly used, shell features
4.1.

Loops at the terminal; variables as vectors

It is occasionally useful to use the foreach control structure at the terminal to aid in performing a number of similar commands.

For instance, there were at one point three shells in

use on the Cory UNIX system at Cory Hall, ‘/bin/sh’, ‘/bin/nsh’, and ‘/bin/csh’.

To count the

number of persons using each shell one could have issued the commands

% grep —c csh$ /etc/passwd
27

% grep —c nsh$ /etc/passwd
128

% grep —c —v sh$ /etc/passwd
430

%
Since these commands are very similar we can use foreach to do this more easily.

% foreach i ("sh$” ‘csh$” "—v sh$)
? grep —c $i /etc/passwd
? end
27

128
430

%
Note here that the shell prompts for input with ‘? * when reading the body of the loop.
Very useful with loops are variables which contain lists of filenames or other words.

You

can, for example, do

% set a=(ls’)
% echo $a
csh.n csh.rm

% s
csh.n
csh.rm

% echo $#a
2

%
The set command here gave the variable a a list of all the filenames in the current directory

as value.

We can then iterate over these names to perform any chosen function.

The output of a command within © characters is converted by the shell to a list of
words.

You can also place the *’ quoted string within “”’ characters to take each (non-empty)

line as a component of the variable; preventing the lines from being split into words at blanks

and tabs.

A modifier “:x’ exists which can be used later to expand each component of the vari-

able into another variable splitting it into separate words at embedded blanks and tabs.
4.2.

Braces { ... }| in argument expansion

Another form of filename expansion, alluded to before involves the characters ‘{’ and ‘} .
These characters specify that the contained strings, separated by ‘,” are to be consecutively

substituted into the containing characters and the results expanded left to right. Thus

A{strl,str2,..strn}B
expands to

Introduction to the C Shell 4-61

Astr1B Astr2B ... AstrnB

This expansion occurs before the other filename expansions, and may be applied recursively
(i.e. nested). The results of each expanded string are sorted separately, left to right order
being preserved. The resulting filenames are not required to exist if no other expansion
mechanisms are used. This means that this mechanism can be used to generate arguments
which are not filenames, but which have common parts.
A typical use of this would be

mkdir ~/{hdrs,retrofit,csh}

to make subdirectories ‘hdrs’, ‘retrofit’ and ‘csh’ in your home directory. This mechanism is
most useful when the common prefix is longer than in this example, i.e.

chown root /usr/{ucb/{ex,edit},lib/{ex?.?* how ex}}
4.3. Command substitution

A command enclosed in ¢’ characters is replaced, just before filenames are expanded, by
the output from that command. Thus it is possible to do
set pwd="pwd"

to save the current directory in the variable pwd or to do
ex grep —1 TRACE *.c’

to run the editor ex supplying as arguments those files whose names end in ‘.c’ which have the
string “TRACE’ in them.*

4.4. Other details not covered here

In particular circumstances it may be necessary to know the exact nature and order of
different substitutions performed by the shell. The exact meaning of certain combinations of
quotations is also occasionally important. These are detailed fully in its manual section.
The shell has a number of command line option flags mostly of use in writing UNIX programs, and debugging shell scripts. See the shells manual section for a list of these options.

*Command expansion also occurs in input redirected with ‘<<’ and within “’ quotations. Refer to the shell
manual section for full details.

4-62

Introduction to the C Shell

Appendix — Special characters
The following table lists the special characters of csh and the UNIX system, giving for each the

section(s) in which it is discussed.
expressions.

A number of these characters also have special meaning in

See the csh manual section for a complete list.

Syntactic metacharacters
:

2.4

separates commands to be executed sequentially

1.5

separates commands in a pipeline

()

2.23.6

2.5

brackets expressions and variable values

follows commands to be executed without waiting for completion

Filename metacharacters

1.6
]

{}

separates C()mponenfs of a file’s pathname

1.6

expansion character matching any single character

1.6

expansion character matching any sequence of characters

1.6

expansion sequence matching any single character from a set

1.6

used at the beginning of a filename to indicate home directories

4.2

used to specify groups of arguments with common parts

Quotation metacharacters

1.7

’

1.7

prevents meta-meaning of following single character
prevents meta-meaning of a group of characters

4.3

like ’, but allows variable and command expansion

Input/output metacharacters
<

1.5

indicates redirected input

1.3

indicates redirected output

Expansion/substitution metacharacters
$

3.4

2.3

indicates variable substitution
indicates history substitution

3.6

precedes substitution modifiers

2.3

used in special forms of history substitution

)

4.3

indicates command substitution

Other metacharacters

1.3,3.6

—

1.2

prefixes option (flag) arguments to commands

begins scratch file names; indicates shell comments

2.6

prefixes job name specifications

Introduction to the C Shell 4-63
Glossary

This glossary lists the most important terms introduced in the introduction to the shell
and gives references to sections of the shell document for further information about them.
References of the form ‘pr (1)’ indicate that the command pr is in the UNIX programmer’s

manual in section 1. You can get an online copy of its manual page by doing
man 1 pr

References of the form (2.5) indicate that more information can be found in section 2.5 of this
manual.

Your current directory has the name ‘.’ as well as the name printed by the
command pwd; see also dirs. The current directory ‘.’ is usually the first component of the search path contained in the variable path, thus commands
which are in ‘" are found first (2.2). The character ‘.’ is also used in separating components of filenames (1.6). The character ‘.’ at the beginning of a
component of a pathname is treated specially and not matched by the
filename expansion metacharacters ‘?’, ‘*’, and ‘[’ ‘]’ pairs (1.6).
Each directory has a file ‘..” in it which is a reference to its parent directory.

After changing into the directory with chdir, i.e.

~ chdir paper
you can return to the parent directory by doing
chdir ..

The current directory is printed by pwd (2.7).
a.out

Compilers which create executable images create them, by default, in the file

a.out. for historical reasons (2.3).

absolute pathname

A pathname which begins with a ‘/’ is absolute since it specifies the path of
directories from the beginning of the entire directory system — called the root
directory. Pathnames which are not absolute are called relative (see
definition of relative pathname) (1.6).

alias

An alias specifies a shorter or different name for a UNIX command, or a
transformation on a command to be performed in the shell. The shell has a
command alias which establishes aliases and can print their current values.
The command unalias is used to remove aliases (2.4).

argument

Commands in UNIX receive a list of argument words. Thus the command
echoabc

consists of the command name ‘echo’ and three argument words ‘a’, ‘b’ and
‘’. The set of arguments after the command name is said to be the argument list of the command (1.1).

argv

The list of arguments to a command written in the shell language (a shell
script or shell procedure) is stored in a variable called argv within the shell.
This name is taken from the conventional name in the C programming
language (3.4).

background
base

Commands started without waiting for them to complete are called background commands (2.6).

A filename is sometimes thought of as consisting of a base part, before any ‘.’
character, and an extension — the part after the ‘.’. See filename and exten¢

sion (1.6)

4-64 Introduction to the C Shell

bg
bin

The bg command causes a suspended job to continue execution in the background (2.6).

A directory containing binaries of programs and shell scripts to be executed is

typically called a bin directory. The standard system bin directories are
‘/bin’ containing the most heavily used commands and ‘/usr/bin’ which contains most other user programs.

Programs developed at UC Berkeley live in

‘/usr/ucb’, while locally written programs live in ‘/usr/local’. Games are kept
in the directory ‘/usr/games’. You can place binaries in any directory. If you
wish to execute them often, the name of the directories should be a component of the variable path.

break

Break is a builtin command used to exit from loops within the control struc-

ture of the shell (3.7).

breaksw

The breaksw builtin command is used to exit from a switch control structure,
like a break exits from loops (3.7).

builtin

A command executed directly by the shell is called a builtin command. Most
commands in UNIX are not built into the shell, but rather exist as files in bin

directories.

These commands are accessible because the directories in which
they reside are named in the path variable.
case

A case command is used as a label in a switch statement in the shell’s control
structure, similar to that of the language C.

Details are given in the shell

documentation ‘csh(1)’ (3.7).
cat

The cat program catenates a list of specified files on the standard output.

It
is usually used to look at the contents of a single file on the terminal, to ‘cat a

file’ (1.8, 2.3).

The c¢d command is used to change the working directory. With no arguments, cd changes your working directory to be your home directory (2.4,
2.7).

chdir

The chdir command is a synonym for c¢d. Cd is usually used because it is
easier to type.

chsh

The chsh command is used to change the shell which you use on UNIX.

By
default, you use an different version of the shell which resides in ‘/bin/sh’.
You can change your shell to ‘/bin/csh’ by doing

chsh your-login-name /bin/csh
Thus I would do

chsh bill /bin/csh

It is only necessary to do this once. The next time you log in to UNIX after

doing this command, you will be using csh rather than the shell in ‘/bin/sh’
(1.9).
cmp

Cmp is a program which compares files.
to see if two files are identical (3.6).

It is usually used on binary files, or

For comparing text files the program

diff, described in ‘diff (1)’ is used.
a WS Rl A

command

RS W

Aaa

A function performed by the system, either by the shell (a builtin command)

or by a program residing in a file in a directory within the UNIX system, is
called a command (1.1).
command name

When a command is issued, it consists of a command name, which is the first

word of the command, followed by arguments.

The convention on UNIX is

that the first word of a command names the function to be performed (1.1).

Introduction to the C Shell 4-65

command substitution

The replacement of a command enclosed in ©’ characters by the text output
by that command is called command substitution (4.3).
€89

component

A part of a pathname between ‘/’ characters is called a component of that
pathname. A variable which has multiple strings as value is said to have
several components; each string is a component of the variable.

continue

A builtin command which causes execution of the enclosing foreach or while
loop to cycle prematurely. Similar to the continue command in the programming language C (3.6).

control-

Certain special characters, called control characters, are produced by holding
down the CONTROL key on your terminal and simultaneously pressing another
character, much like the SHIFT key is used to produce upper case characters.
Thus control-c¢ is produced by holding down the CONTROL key while pressing
the ‘¢’ key. Usually UNIX prints an up-arrow (f) followed by the corresponding letter when you type a control character (e.g. ‘)C’ for control-c (1.8).

core dump

When a program terminates abnormally, the system places an image of its
current state in a file named ‘core’. This core dump can be examined with
the system debugger ‘adb(1)’ or ‘sdb(1)’ in order to determine what went
wrong with the program (1.8). If the shell produces a message of the form
[llegal instruction (core dumped)

(where °‘Illegal instruction’ is only one of several possible messages), you
should report this to the author of the program or a system administrator,
saving the ‘core’ file.
cp

The cp (copy) program is used to copy the contents of one file into another
file. It is one of the most commonly used UNIX commands (1.6).

csh

The name of the shell program that this document describes.

.cshre

The file .cshrc in your home directory is read by each shell as it begins execution. It is usually used to change the setting of the variable path and to set
alias parameters which are to take effect globally (2.1).

cwd

The cwd variable in the shell holds the absolute pathname of the current

working directory. It is changed by the shell whenever your current working
directory changes and should not be changed otherwise (2.2).
date

The date command prints the current date and time (1.3).

debugging

Debugging is the process of correcting mistakes in programs and shell scripts.
The shell has several options and variables which may be used to aid in shell
debugging (4.4).

default:

The label default: is used within shell switch statements, as it is in the C
language to label the code to be executed if none of the case labels matches
the value switched on (3.7).

DELETE

The DELETE or RUBOUT key on the terminal normally causes an interrupt to

be sent to the current job.

Many users change the interrupt character to be

fC.

detached

A command that continues running in the background after you logout is said
to be detached.

diagnostic

An error message produced by a program is often referred to as a diagnostic.
Most error messages are not written to the standard output, since that is
often directed away from the terminal (1.3, 1.5). Error messsages are instead
written to the diagnostic output which may be directed away from the terminal, but usually is not. Thus diagnostics will usually appear on the terminal
(2.5).

4-66

Introduction to the C Shell

directory

A structure which contains files.

At any time you are in one particular direc-

tory whose names can be printed by the command pwd.

The chdir command

will change you to another directory, and make the files in that directory

visible. The directory in which you are when you first login is your home
directory (1.1, 2.7).

directory stack The shell saves the names of previous working directories in the directory
stack when you change your current working directory via the pushd com-

mand.

The directory stack can be printed by using the dirs command, which

includes your current working directory as the first directory name on the left

(2.7).

dirs

The dirs command prints the shell’s directory stack (2.7).

The du command is a program (described in ‘du(1)’) which prints the number

of disk blocks is all directories below and including your current working
directory (2.6).

echo

The echo command prints its arguments (1.6, 3.6).

else

The else command is part of the ‘if-then-else-endif’ control command con-

struct (3.6).

endif

If an if statement is ended with the word then, all lines following the if up to

a line starting with the word endif or else

are executed if the condition

between parentheses after the if is true (3.6).
EOF

An end-of-file is generated by the terminal by a control-d, and whenever a
command reads to the end of a file which it has been given as input.

Com-

mands receiving input from a pipe receive an end-of-file when the command

sending them input completes.
an end-of-file.

Most commands terminate when they receive

The shell has an option to ignore end-of-file from a terminal

input which may help you keep from logging out accidentally by typing too
many control-d’s (1.1, 1.8, 3.8).
escape

A character ¢\’ used to prevent the special meaning of a metacharacter is said
to escape the character from its special meaning.

Thus

echo \*
will echo the character ‘*’ while just
echo *
will echo the names of the file in the current directory.
escapes ‘*’ (1.7).

In this example, x

There is also a non-printing character called escape, usually

labelled ESC or ALTMODE on terminal keyboards.

Some older UNIX systems

use this character to indicate that output is to be suspended.

Most systems

use control-s to stop the output and control-q to start it.

/etc/passwd

This file contains information about the accounts currently on the system.

consists of a line for each account with fields separated by ‘.’ characters (1.8).
You can look at this file by saying

cat /etc/passwd
The commands finger and grep are often used to search for information in

this file.
exit

See ‘finger(1)’, ‘passwd(5)’, and ‘grep(1)’ for more details.

The exit command is used to force termination of a shell script, and is built
into the shell (3.9).

exit status

A command which discovers a problem may reflect this back to the command

(such as a shell) which invoked (executed) it.

It does this by returning a

non-zero number as its exit status, a status of zero being considered ‘normal

Introduction to the C Shell 4-67

termination’. The exit command can be used to force a shell command script
to give a non-zero exit status (3.6).
expansion

The replacement of strings in the shell input which contain metacharacters by

other strings is referred to as the process of expansion. Thus the replacement of the word ‘*’ by a sorted list of files in the current directory is a
‘filename expansion’. Similarly the replacement of the characters ‘!’ by the
text of the last command is a ‘history expansion’. FExpansions are also
referred to as substitutions (1.6, 3.4, 4.2).
expressions

Expressions are used in the shell to control the conditional structures used in
the writing of shell scripts and in calculating values for these scripts. The
operators available in shell expressions are those of the language C (3.5).

extension

Filenames often consist of a base name and an extension separated by the
character ‘.”. By convention, groups of related files often share the same root
name. Thus if ‘prog.c’ were a C program, then the object file for this program
would be stored in ‘prog.o’. Similarly a paper written with the ‘—me’ nroff
macro package might be stored in ‘paper.me’ while a formatted version of this
paper might be kept in ‘paper.out’ and a list of spelling errors in ‘paper.errs’
(1.6).

The job control command fg is used to run a background or suspended job

filename

Each file in UNIX has a name consisting of up to 14 characters and not including the character ‘/> which is used in pathname building. Most filenames do
not begin with the character ‘.’, and contain only letters and digits with
perhaps a ‘.’ separating the base portion of the filename from an extension

in the foreground (1.8, 2.6).

(1.6).
filename expansion

Filename expansion uses the metacharacters ‘*’, ‘?” and ‘[’ and ‘]’ to provide
a convenient mechanism for naming files. Using filename expansion it is
easy to name all the files in the current directory, or all files which have a
common root name. Other filename expansion mechanisms use the metacharacter ~ and allow files in other users’ directories to be named easily (1.6,
4.2).
flag

Many UNIX commands accept arguments which are not the names of files or
other users but are used to modify the action of the commands. These are
referred to as flag options, and by convention consist of one or more letters
preceded by the character ‘=’ (1.2). Thus the Is (list files) command has an
option ‘—s’ to list the sizes of files. This is specified
Is —s

foreach

The foreach command is used in shell scripts and at the terminal to specify

repetition of a sequence of commands while the value of a certain shell variable ranges through a specified list (3.6, 4.1).
foreground

When commands are executing in the normal way such that the shell is waiting for them to finish before prompting for another command they are said to
be foreground jobs or running in the foreground. This is as opposed to
background. Foreground jobs can be stopped by signals from the terminal

caused by typing different control characters at the keyboard (1.8, 2.6).
The shell has a command goto used in shell scripts to transfer control to a
given label (3.7).

The grep command searches through a list of argument files for a specified
string. Thus

4-68

Introduction to the C Shell

grep bill /etc/passwd
will print each line in the file /etc/passwd which contains the string ‘bill’.
Actually, grep scans for regular expressions in the sense of the editors ‘ed(1)’

and ‘ex(1)’.
head

Grep stands for ‘globally find regular expression and print’ (2.4).

The head command prints the first few lines of one or more files.

If you have

a bunch of files containing text which you are wondering about it is sometimes useful to run head with these files as arguments.

This will usually

show enough of what is in these files to let you decide which you are
interested in (1.5).

Head 1is also used to describe the part of a pathname before and including

the last ‘/’ character.

The tail of a pathname is the part after the last ‘/’.

The “h’ and “t’ modifiers allow the head or tail of a pathname stored in a
shell variable to be used (3.6).
history

The

history

mechanism

of the

shell

allows

commands

repeated, possibly after modification to correct typing mistakes or to change
the meaning of the command.

The shell has a history list where these com-

mands are kept, and a history variable which controls how large this list is

(2.3).
home directory
Each user has a home directory, which is given in your entry in the password

file, /etc/passwd. This is the directory which you are placed in when you first
login.

The c¢d or chdir command with no arguments takes you back to this

directory, whose name is recorded in the shell variable home.
access the home directories

You can also

of other users in forming filenames using a

filename expansion notation and the character < (1.6).
if

A conditional command within the shell, the if command is used in shell com-

mand scripts to make decisions about what course of action to take next (3.6).
ignoreeof

Normally, your shell will exit, printing ‘logout’ if you type a control-d at a
prompt of ‘% ’.

This is the way you usually log off the system.

You can set

the ignoreeof variable if you wish in your .login file and then use the command logout to logout.

This is useful if you sometimes accidentally type too

many control-d characters, logging yourself off (2.2).

input

Many commands on UNIX take information from the terminal or from files

which they then act on.

This information is called input.

Commands nor-

mally read for input from their standard input which is, by default, the terminal.

This standard input

can be redirected from a file using a shell

metanotation with the character ‘<’.

file specified as argument.

Many commands will also read from a

Commands placed in pipelines will read from the

output of the previous command in the pipeline.

The leftmost command in a

pipeline reads from the terminal if you neither redirect its input nor give it a
filename to use as standard input.

Special mechanisms exist for supplying

input to commands in shell scripts (1.5, 3.8).
Nv\n] 4+ A
MO
Ln
P Vot o Wa'
An uwcliu,po is a osignai
to a program
thatt is gen
erated b

4—4— "AN
o~ hTTnf\TTm
1trin
g he
RUBOUT

or DELETE key (although users can and often do change the interrupt charac-

ter, usually to fC).

It causes most programs to stop execution.

Certain pro-

grams, such as the shell and the editors, handle an interrupt in special ways,

usually by stopping what they are doing and prompting for another command.
While the shell is executing another command and waiting for it to finish, the
shell does not listen to interrupts. The shell often wakes up when you hit
interrupt because many commands die when they receive an interrupt (1.8,

3.9).

Introduction to the C Shell

job

4-69

One or more commands typed on the same input line separated by ¢ or
characters are run together and are called a job.

6,9

Simple commands run by

themselves without any ¢ or ¢’ characters are the simplest jobs. Jobs are
classified as foreground, background, or suspended (2.6).

job control

The builtin functions that control the execution of jobs are called job control

commands. These are bg, fg, stop, kill (2.6).

job number

When each job is started it is assigned a small number called a job number

which is printed next to the job in the output of the jobs command.

This

number, preceded by a ‘%’ character, can be used as an argument to job control commands to indicate a specific job (2.6).

jobs

The jobs command prints a table showing jobs that are either running in the

kill

A command which sends a signal to a job causing it to terminate (2.6).

Jlogin

The file .login in your home directory is read by the shell each time you login

background or are suspended (2.6).

to UNIX and the commands there are executed.

There are a number of com-

mands which are usefully placed here, especially set commands to the shell
b 1L

itself

(2.1).

The shell that is started on your terminal when you login is called your login
shell.

It is different from other shells which you may run (e.g. on shell

scripts) in that it reads the .login file before reading commands from the terminal and it reads the .logout file after you logout (2.1).
logout

The logout command causes a login shell to exit.

Normally, a login shell will

exit when you hit control-d generating an end-of-file,

but if you have set

ignoreeof in you .login file then this will not work and you must use logout to
log off the UNIX system (2.8).

Jogout

When you log off of UNIX the shell will execute commands from the file
dogout in your home directory after it prints ‘logout’.

lpr

The command [pr is the line printer daemon.

spooled and printed on the UNIX line printer.
filenames as arguments to be printed.

The standard input of Ipr

You can also give [pr a list of

It is most common to use lpr as the

last component of a pipeline (2.3).
Is

The [s

(list files) command is one of the most commonly used UNIX com-

mands.

With no argument filenames it prints the names of the files in the

current directory.

It has a number of useful flag arguments, and can also be

given the names of directories as arguments, in which case it lists the names
of the files in these directories (1.2).
The mail program is used to send and receive messages from other UNIX users
(1.1, 2.1).

The make command is used to maintain one or more related files and to

organize functions to be performed on these files. In many ways make

easier to use, and more helpful than shell command scripts (3.2).
AABLA
AR/ A B A

'T‘}\o file containino com
manfl
CRLANAND

manual

The manual often referred to is the ‘UNIX programmer’s manual’.

ARAT

UVJALUCALEARLLX &

LUririil

(\7‘ 144] WIVT
\JL

COEATUA

Frvie
s

Iuv

(3.2).
\v

It contains

a number of sections and a description of each UNIX program.

An online ver-

sion of the manual is accessible through the man command.

Its documenta-

tion can be obtained online via
man man

metacharact

Many characters which are neither letters nor digits have special meaning

4-70 Introduction to the C Shell

either to the shell or to UNIX. These characters are called metacharacters. If
it is necessary to place these characters in arguments to commands without
them having their special meaning then they must be quoted. An example of
a metacharacter is the character ‘>’ which is used to indicate placement of
output into a file. For the purposes of the history mechanism, most
unquoted metacharacters form separate words (1.4). The appendix to this
user’s manual lists the metacharacters in groups by their function.
mkdir

The mkdir command is used to create a new directory.

modifier

Substitutions with the history mechanism, keyed by the character ‘I’ or of
variables using the metacharacter ‘$’, are often subjected to modifications,
indicated by placing the character ‘.’ after the substitution and following this
with the modifier itself. The command substitution mechanism can also be
‘used to perform modification in a similar way, but this notation is less clear
(3.6).

noclobber

The program more writes a file on your terminal allowing you to control how
much text is displayed at a time. More can move through the file screenful
by screenful, line by line, search forward for a string, or start again at the
beginning of the file. It is generally the easiest way of viewing a file (1.8).
The shell has a variable noclobber which may be set in the file .login to
prevent accidental destruction of files by the ‘>’ output redirection metasyntax of the shell (2.2, 2.5).

noglob

The shell variable noglob is set to suppress the filename expansion of arguments containing the metacharacters 7, “*’, ‘?’, ‘[” and ‘]’ (3.6).

notify

The notify command tells the shell to report on the termination of a specific
background job at the exact time it occurs as opposed to waiting until just
before the next prompt to report the termination. The notify variable, if set,
causes the shell to always report the termination of background jobs exactly
when they occur (2.6).

onintr

The onintr command is built into the shell and is used to control the action
of a shell command script when an interrupt signal is received (3.9).

output

Many commands in UNIX result in some lines of text which are called their
output. This output is usually placed on what is known as the standard output which is normally connected to the user’s terminal. The shell has a syntax using the metacharacter ‘>’ for redirecting the standard output of a com-

mand to a file (1.3). Using the pipe mechanism and the metacharacter I it is

also possible for the standard output of one command to become the standard input of another command (1.5). Certain commands such as the line
printer daemon p do not place their results on the standard output but
rather in more useful places such as on the line printer (2.3). Similarly the
write command places its output on another user’s terminal rather than its
standard output (2.3). Commands also have a diagnostic output where they
write their error messages. Normally these go to the terminal even if the
standard output has been sent to a file or another command, but it is possible to direct error diagnostics along with standard output using a special
metanotation (2.5).
pushd

The pushd command, which means ‘push directory’, changes the shell’s working directory and also remembers the current working directory before the
change is made, allowing you to return to the same directory via the popd
command later without retyping its name (2.7).

path

The shell has a variable path which gives the names of the directories in
which it searches for the commands which it is given. It always checks first to
see if the command it is given is built into the shell. If it is, then it need not

Introduction to the C Shell 4-71

search for the command as it can do it internally. If the command is not
builtin, then the shell searches for a file with the name given in each of the
directories in the path variable, left to right. Since the normal definition of
the path variable is

path (. /usr/ucb /bin /usr/bin)
the shell normally looks in the current directory, and then in the standard
system directories ‘/usr/ucb’, ‘/bin’ and ‘/usr/bin’ for the named command
(2.2). If the command cannot be found the shell will print an error diagnostic. Scripts of shell commands will be executed using another shell to interpret them if they have ‘execute’ permission set. This is normally true because
a command of the form
chmod 755 script

was executed to turn this execute permission on (3.3). If you add new commands to a directory in the path, you should issue the command rehash
(2.2).

pathname

A list of names, separated by ¢/’ characters, forms a pathname. Each component, between successive ¢/’ characters, names a directory in which the next
component file resides. Pathnames which begin with the character /° are
interpreted relative to the root directory in the filesystem. Other pathnames
are interpreted relative to the current directory as reported by pwd. The last
component of a pathname may name a directory, but usually names a file.

pipeline

A group of commands which are connected together, the standard output of

each connected to the standard input of the next, is called a pipeline. The
pipe mechanism used to connect these commands is indicated by the shell

metacharacter ¥ (1.5, 2.3).

popd

port

The popd command changes the shell’s working directory to the directory

you most recently left using the pushd command. It returns to the directory
without having to type its name, forgetting the name of the current working
directory before doing so (2.7).
The part of a computer system to which each terminal is connected is called a
port. Usually the system has a fixed number of ports, some of which are connected to telephone lines for dial-up access, and some of which are permanently wired directly to specific terminals.

The pr command is used to prepare listings of the contents of files with

headers giving the name of the file and the date and time at which the file
was last modified (2.3).
printenv

The printenv command is used to print the current setting of variables in the
environment (2.8).

process

An instance of a running program is called a process (2.6). UNIX assigns each
process a unique number when it is started — called the process number.
Process numbers can be used to stop individual processes using the kill or

stop commands when the processes are part of a detached background job.
program

Usually synonymous with command; a binary file or shell command script
which performs a useful function is often called a program.

programmer’s manuals manual’u>(750u+1n) .br
Also referred to as the manual. See the glossary entry for ‘manual’.
prompt

Many programs will print a prompt on the terminal when they expect input.
Thus the editor ‘ex(1)’ will print a ’ when it expects input. The shell
prompts for input with ‘% ’ and occasionally with ‘? ’ when reading commands from the terminal (1.1). The shell has a variable prompt which may

4-72 Introduction to the C Shell

be set to a different value to change the shell’s main prompt.

This is mostly

used when debugging the shell (2.8).
ps

The ps command is used to show the processes you are currently running.

Each process is shown with its unique process number, an indication of the
terminal name it is attached to, an indication of the state of the process
(whether it is running, stopped, awaiting some event (sleeping), and whether
it is swapped out), and the amount of CPU time it has used so far.

The com-

mand is identified by printing some of the words used when it was invoked
(2.6).

Shells, such as the csh you use to run the ps command, are not nor-

mally shown in the output.

pwd

The pwd command prints the full pathname of the current working direc-

tory. The dirs builtin command is usually a better and faster choice.
quit

The quit signal, generated by a control-x is used to terminate programs which
are behaving unreasonably. It normally produces a core image file (1.8).

quotation

The process by which metacharacters are prevented their special meaning,

usually by using the character ¢ in pairs, or by using the character ‘X, is
referred to as quotation (1‘7).
redirection

The routing of input or output from or to a file is known as redirection of
input or output (1.3).

rehash

The rehash command tells the shell to rebuild its internal table of which

commands are found in which directories in your path.

This is necessary

when a new program is installed in one of these directories (2.8).
relative pathname

A pathname which does not begin with a ‘/’ is called a relative pathname
since it is interpreted relative to the current working directory. The first
component of such a pathname refers to some file or directory in the working

directory, and subsequent components between ‘/° characters refer to direcPathnames that are not relative are

tories below the working directory.
called absolute pathnames (1.6).
repeat

The repeat command iterates another command a specified number of times.

root

The directory that is at the top of the entire directory structure is called the
root directory since it is the ‘root’ of the entire tree structure of directories.

The name used in pathnames to indicate the root is ‘/’. Pathnames starting
with ¢/’ are said to be absolute since they start at the root directory. Root is
also used as the part of a pathname that is left after removing the extension.
See filename for a further explanation (1.6).
RUBOUT

The RUBOUT or DELETE key sends an interrupt to the current job.

Most

interactive commands return to their command level upon receipt of an interrupt, while non-interactive commands usually terminate, returning control to

the shell. Users often change interrupt to be generated by {{C rather than
DELETE by using the stty command.
scratch file

Files whose names begin with a ‘#’ are referred to as scratch files, since they

are automatically removed by the system after a couple of days of non-use, or
more frequently if disk space becomes tight (1.3).
script

Sequences of shell commands placed in a file are called shell command
scripts. It is often possible to perform simple tasks using these scripts
without writing a program in a language such as C, by using the shell to selectively run other programs (3.3, 3.10).

set

The builtin set command is used to assign new values to shell variables and

to show the values of the current variables. Many shell variables have special
meaning to the shell itself. Thus by using the set command the behavior of

Introduction to the C Shell 4-73

the shell can be affected (2.1).

Variables in the environment ‘environ(5)’ can be changed by using the setenv
builtin command (2.8). The printenv command can be used to print the

setenv

value of the variables in the environment.
shell

A shell is a command language interpreter.

It is possible to write and run

your own shell, as shells are no different than any other programs as far as

the system is concerned. This manual deals with the details of one particular
shell, called csh.

shell script

See script (3.3, 3.10).

signal

A signal in UNIX is a short message that is sent to a running program which
causes something to happen to that process. Signals are sent either by typing
special control characters on the keyboard or by using the kill or stop commands (1.8, 2.6).

sort

The sort program sorts a sequence of lines in ways that can be controlled by
argument flags (1.5).

source

The source command causes the shell to read commands from a specified file.
It is most useful for reading files such as .cshrc after changing them (2.8).

special character

See metacharacters and the appendix to this manual.
standard

We refer often to the standard input and standard output of commands.
See input and output (1.3, 3.8).

status

A command normally returns a status when it finishes. By convention a
status of zero indicates that the command succeeded. Commands may return
non-zero status to indicate that some abnormal event has occurred. The shell
variable status is set to the status returned by the last command. It is most
useful in shell commmand scripts (3.6).

stop

The stop command causes a background job to become suspended (2.6).

string

A sequential group of characters taken together is called a string.
can contain any printable characters (2.2).

stty

The stty program changes certain parameters inside UNIX which determine

Strings

how your terminal is handled. See ‘stty(1)’ for a complete description (2.6).
substitution

The shell implements a number of substitutions where sequences indicated
by metacharacters are replaced by other sequences. Notable examples of this

are history substitution keyed by the metacharacter ‘I’ and variable substitution indicated by ‘$’. We also refer to substitutions as expansions (3.4).

suspended

A job becomes suspended after a STOP signal is sent to it, either by typing a
control-z at the terminal (for foreground jobs) or by using the stop command
(for background jobs). When suspended, a job temporarily stops running
until it is restarted by either the fg or bg command (2.6).

switch

The switch command of the shell allows the shell to select one of a number of

sequences of commands based on an argument string.
switch statement in the language C (3.7).

It is similar to the

termination

When a command which is being executed finishes we say it undergoes termination or terminates. Commands normally terminate when they read an
end-of-file from their standard input. It is also possible to terminate commands by sending them an interrupt or quit signal (1.8). The kill program
terminates specified jobs (2.6).

then

The then command is part of the shell’s ‘if-then-else-endif’ control construct
used in command scripts (3.6).

4-74 Introduction to the C Shell
time

The time command can be used to measure the amount of CPU and real time

consumed by a specified command as well as the amount of disk i/0, memory
utilized, and number of page faults and swaps taken by the command (2.1,
2.8).
tset

The tset program is used to set standard erase and kill characters and to tell
the system what kind of terminal you are using.
dogin file (2.1).

tty

It is often invoked in a

The word tty is a historical abbreviation for ‘teletype’ which is frequently
used in UNIX to indicate the port to which a given terminal is connected. The

tty command will print the name of the tty or port to which your terminal is
presently connected.
unalias
UNIX

The unalias command removes aliases (2.8).

UNIX is an operating system on which csh runs.

UNIX provides facilities

which allow csh to invoke other programs such as editors and text formatters
which you may wish to use.
unset

The unset command removes the definitions of shell variables (2.2, 2.8).

variable expansion

See variables and expansion (2.2, 3.4).
variables

Variables in csh hold one or more strings as value. The most common use of
variables is in controlling the behavior of the shell. See path, noclobber, and
ignoreeof for examples.

Variables such as argv are also used in writing shell

programs (shell command scripts) (2.2).
verbose

The verbose shell variable can be set to cause commands to be echoed after
they are history expanded.

This is often useful in debugging shell scripts.

The verbose variable is set by the shell’s —v command line option (3.10).
WwC

The we program calculates the number of characters, words, and lines in the

files whose names are given as arguments (2.6).
while

The while builtin control construct is used in shell command scripts (3.7).

word

A sequence of characters which forms an argument to a command is called a

word. Many characters which are neither letters, digits, ‘=’, ‘.” nor ¢/’ form
words all by themselves even if they are not surrounded by blanks. Any
sequence of characters may be made into a word by surrounding it with
characters except for the characters ” and ‘!’ which require special treatment
(1.1). This process of placing special characters in words without their special
meaning is called quoting.

working directory

At any given time you are in one particular directory, called your working
directory.

This directory’s name is printed by the pwd command and the

files listed by Is are the ones in this directory. You can change working directories using chdir.

write

The write command is used to communicate with other users who are logged
in to UNIX.

Introduction 5-1

PART 5:

DOCUMENT PREPARATION

This part includes articles on the features and utilities of the ULTRIX-32 system that will
help you to prepare written information for publication. Seven of the articles deal with nroff

and troff, the text formatters that convert unformatted text into a formal document ready for
output on a printer or typesetter. Nroff produces output printable on a typewriter-like terminal, line printer, or terminal screen.

Troff prepares output for a phototypesetter.

Five other

articles explain the uses of egn, tbl, and refer. These are utilities that cooperate with the text
processors to produce mathematical equations, tables, and bibliographical references in the

text formatted by nroff or troff. An additional article describes the style and diction programs,
tools that provide criteria for evaluating written material.

Nroff and Troff
Formatting a document on the ULTRIX-32 system is a two-stage process.

In stage one, you

create or change a file using vi or one of the other editors. This file should contain the text to

be processed and commands to the text formatter.

The commands tell the formatter how to

treat the text, for example how wide to make the margins, when to start a new paragraph, and
when to leave the right margin unjustified.

In stage two, you give a command to the shell tel-

ling nroff or troff to process the text in the file you created. Nroff and troff are compatible, so

that one text file can generally serve as a source for both line printer output and typesetter
output.

The text processors allow you to define exactly how you want your text to look.

However,

developing a format that is consistent throughout a document involves repeating many details

(consider page headers and multicolumn formats, for example).

ULTRIX-32 includes two

macro packages (-ms and -me) that specify many details and simplify the specification of

other details for you.

These macro packages serve to reduce your direct contact with nroff

and troff, making the text formatting process easier.

The articles by Lesk, “Typing Docu-

ments on the UNIX System: Using the -ms Macros with TROFF and NROFF,” and Tuthill,
“A Revised Version of -ms,” tell what there is to know about using -ms.
ing Documents with -ms,” also by Lesk, gives comprehensive examples.

The topics include:

(Cover sheet format such as author, title, abstract

Page headings

Multicolumn format

Section headings

Paragraph control

Italics

Footnotes

Specifying dates

“A Guide to Prepar-

5-2 Introduction

(Changing default values

Using accent marks

Automatic footnote numbering

The Lesk article is readable and arranged in a tutorial format.

The Tuthill article is a brief

supplement.

“Writing Papers with NROFF Using -ME,” by Allman, covers many of the same topics.
article is also tutorial.

This

It provides good explanations and examples.

The “ME Reference Manual,” also by Allman, lists all features of the -me macro package.

Read it if you want greater flexibility than is allowed by the procedures shown in the first Allman article.

The “NROFF/TROFF User’s Manual,” by Ossanna, is appropriate for users already familiar
with the macro packages who want to develop their own nroff or troff macros or macro packages.

The first part of this article lists the command line options for the text formatters, all

nroff and troff commands, escape sequences, and predefined registers.

The second part

defines in detail the rules that govern use of the text formatters. A set of examples completes
the article.
“A TROFF Tutorial,” by Kernighan, concentrates on features of troff that are specific to
typesetting such as:
e

Point sizes

Font changes

Special characters

Horizontal and vertical motions

The information in this article is appropriate for users who want more flexibility in typesetter

control than they can get with the -ms and -me macro packages.

Preprocessors
Three preprocessor utilities expand the text formatting capabilities of the ULTRIX-32 sys|

tem:

eqn lets you typeset mathematical expressions.

tbl helps you to format tables easily.
refer helps you to create bibliographical references.
These utilities process notation for mathematical expressions, tables, and bibliographical

descriptions, turning them into sequences of commands for nroff or troff.
This part includes two articles on egn by Kernighan and Cherry.

Mathematics” outlines the design goals and capabilities of eqn.

“A System for Typesetting

The second article, “Typeset-

ting Mathematics - User’s Guide,” shows how to make egn produce:
e

Kquations

Special symbols
e

Greek letters

Subscripts and superscripts

Braces

Piles

Matrices

Local motions

Read this second article for practical information on using eqn.

Read the first eqgn article, “A

System for Typesetting Mathematics,” if you want to know more about the background of
eqn.

Introduction

5-3

eqn.

“TBL - A Program to Format Tables,” by Lesk, serves as a reference and a tutorial.

part of the article lists rules for using tbl to create tables.

The first

The remainder of the article con-

sists of examples showing sequences of commands supplied to tbl and the resulting tables.
Three of the articles in this part deal with utilities related to bibliographies and indexing.
Using refer to make bibliographical references in a text requires three steps:
1

You must build a data base that describes the items that can be referenced.

Each

entry in the data base identifies the publication by several categories such as:
e

Author

Title

Issuer (publisher)

(City where published

Date of publication

Enter this information by running the addbib utility.

Note that you can list the

entire data base, sorted by author and date, by running the sortbib and roffbib utilities.

As you write a new text to be processed by nroff or troff, you can create a standard

bibliographical reference to an item contained in the data base by specifying one or
two key fields of the data base item.
3

Run the refer and nroff or troff utilities to process the text.

Tuthill’s article, “Refer - A Bibilography System,” is the most readable and useful of the three

articles on refer.

The Lesk articles, “Some Applications of Inverted Indexes on the UNIX System” and
“Updating Publication Lists,” deal with indexing and bibliographical referencing.
ples that relate to refer may be useful, if you read the Tuthill article first.

of indexing are hard to follow.

The exam-

The explanations

If you must use the searching and indexing utilities, you may

want help from someone who uses this software to supplement the Lesk articles.

Style and Diction
The style and diction programs can help you evaluate and refine writing skills.

be evaluated can be in a file on the system.

The texts to

The article entitled “Writing Tools - The Style

and Diction Programs,” by Cherry and Vesterman, explains the yardsticks that style uses to
measure:

Readability levels
e

Sentence structure

Word usage (by parts of speech)

Sentence openers

The article also shows how to use the diction program to identify phrases that are frequently
misused or WOI’dy

You can use the BL[JLULIL prograim together with
a
diction to find substitutes
T

SRR

:4
s+ 1.

D ks

for the objectionable phrases.

Summary
The articles on -ms and -me (choose one) will help you to get started using nroff and troff.
Eqgn, tbl, and refer work with nroff and troff to simplify typesetting mathematical expressions,

formatting tables, and making bibliographical references.
LN

VoS

RS a

-5 QW §

help you to evaluate what you write.

The style and diction programs will

Typing Documents on the UNIX System

5-5

Typing Documents on the UNIX System:

Using the —ms Macros with Troff and Nroff
M. E. Lesk
Bell Laboratories
Murray Hill, New Jersey 07974

Introduction.

This memorandum describes a package of commands to produce papers

using the troff and nroff formatting programs on the UNIX system. As with other roff -derived
programs, text is prepared interspersed with formatting commands. However, this package,
which itself is written in troff commands, provides higher-level commands than those pro-

vided with the basic troff program.
Appendix A.

The commands available in this package are listed in

Text. Type normally, except that instead of indenting for paragraphs, place a line reading “.PP” before each paragraph. This will produce indenting and extra space.
Alternatively, the command .LP that was used here will produce a left-aligned (block) paragraph. The paragraph spacing can be changed: see below under “Registers.”
Beginning.

For a document with a paper-type cover sheet, the input should start as fol-

lows:

|
[optional overall format .RP — see below]
TL

Title of document (one or more lines)
AU

Author(s) (may also be several lines)

Author’s institution(s)

Abstract; to be placed on the cover sheet of a paper.

Line length is 5/6 of normal; use .1l here to change.
AE (abstract end)
text ... (begins with .PP, which see)
To omit some of the standard headings (e.g. no abstract, or no author’s institution) just omit

the corresponding fields and command lines. The word ABSTRACT can be suppressed by writing “.AB no” for “.AB”. Several interspersed .AU and .Al lines can be used for multiple

authors.

The headings are not compulsory: beginning with a .PP command is perfectly OK
Warning: You can’t just begin a document with a line of text. Some —ms command must precede any text input. When in doubt,
use .LP to get proper initialization, although any of the commands .PP, .LP, .TL, .SH, .NH is
good enough. Figure 1 shows the legal arrangement of commands at the start of a document.
and will just start printing an ordinary paragraph.

Cover Sheets and First Pages.

The first line of a document signals the general format

of the first page. In particular, if it is ”.RP” a cover sheet with title and abstract is prepared.
The default format is useful for scanning drafts.
UNIX is a Trademark of Bell Laboratories

5-6 Typing Documents on the UNIX System
In general —ms is arranged so that only one form of a document need be stored, containing all information;

the first command gives the format, and unnecessary items for that for-

mat are ignored.

Warning: don’t put extraneous material between the .TL and .AE commands. Processing of the titling items is special, and other data placed in them may not behave as you
expect. Don’t forget that some —ms command must precede any input text.
Page headings.

The —ms macros, by default, will print a page heading containing a

page number (if greater than 1).

date is used.

A default page footer is provided only in nroff, where the

The user can make minor adjustments to the page headings/footings by

redefining the strings LH, CH, and RH which are the left, center and right portions of the

page headings, respectively; and the strings LF, CF, and RF, which are the left, center and
right portions of the page footer.

For more complex formats, the user can redefine the macros

PT and BT, which are invoked respectively at the top and bottom of each page.

The margins

(taken from registers HM and FM for the top and bottom margin respectively) are normally 1

inch; the page header/footer are in the middle of that space.

The user who redefines these

macros should be careful not to change parameters such as point size or font without resetting

them to default values.

Multi-column formats.

If you place

the command “.2C” in your document, the

Care and Feeding of Department

Heads

document will be printed in double column
format

beginning

that

point.

Alternatively,

This

.SH

feature is not too useful in computer termi-

Care and Feeding of Directors

nal output, but is often desirable on the

typesetter.

The

command

“.1C”

will

back to one-column format and also skip to
a new page.

The “.2C” command is actu-

ally a special case of the command

will

makes

multiple

columns

with

the

columns as will fit across the page are used.
Thus triple, quadruple, ... column pages can

printed.

Whenever

the

heading

with

number

Every section heading, of either type,

specified column and gutter width; as many

the

Care and Feeding of Directors

MC [column width [gutter Width]]
which

added:

number

should be followed by a paragraph beginning with .PP or .LLP, indicating the end of

the heading.

Headings may contain more

than one line of text.
The

.NH

command

complex

numbering

also

supports

columns is changed (except going from full

width to some larger number of columns) a

numerical argument is given, it is taken to

special

produce

heading, there are two commands.

If you

type

sub-section

number

as in this example:

Erie-Lackawanna

type section heading here

NH 2

may be several lines

Morris and Essex Division

you will get automatically numbered section
headings

(1,

...),

boldface.

For

example,
.NH

Care and Feeding of Department Heads
produces

generated.

Larger

level numbers indicate deeper sub-sections,

.NH

If a

be a ‘“level”” number and an appropriate

new page is started.

Headings.

schemes.

Gladstone Branch
.NH 3

Montclair Branch
NH 2
Boonton Line
generates:

Typing Documents on the UNIX System

(in character positions) and will remain in

2. Erie-Lackawanna

effect until the next .PP or .LP.

2.1. Morris and Essex Division

“NH

0”

will

.NH 0

the

And so forth.
.LP

produces this:

first:

Notice the longer label, requiring
larger

indenting for these

graphs.

1. Penn Central

paragraphs.

(Paragraphs

with hanging numbers, e.g. references.) The
sequence

second:
It

para-

And so forth.

also

possible

produce

multiple

nested indents; the command .RS indicates
that the next .IP starts from the current

1P [1]

Text for first paragraph, typed
normally for as long as you would
like on as many lines as needed.

IP [2]
Text for second paragraph, ...
produces

indentation level.

and

.RE commands.

example
IP 1.

Bell Laboratories

RS
JP 1.1

Text for second paragraph, ...

Murray Hill

A series of indented paragraphs may be fol-

JP 1.2

lowed by an ordinary paragraph beginning

Holmdel

with .PP or .LP, depending on whether you

P 1.3

wish indenting or not.

Whippany

The command .LP

was used here.

JP 1.3.1

More sophisticated uses of .IP are also

Madison

possible. If the label is omitted, for example, a plain block indent is produced.

RE
JP 1.4

Chester

This material will

just be turned into a

will produce

This material will just be turned into

a block indent suitable for quotations

will result in
1.

Bell Laboratories
1.1

Murray Hill

1.2

Holmdel

1.3

Whippany

or such matter.

If a non-standard amount of indenting is
required, it may be specified after the label

.RS command

the .RE command as “move left”.

as many lines as needed.

such matter.

The

should be thought of as “move right” and

Text for first paragraph, typed nor-

block indent suitable for quotations or

Each .RE will eat up one

level of indenting so you should balance .RS

mally for as long as you would like on
[2]

and

IP second:

reset the

Penn Central

[1]

label

indenting for these paragraphs.

numbering of level 1 to one, as here:

Indented

the

For example,

Notice the longer label, requiring larger

2.2. Boonton Line
explicit

fields:

IP first: 9

2.1.2. Montclair Branch

additional

indenting length.

Gladstone Branch

Thus, the

general form of the .IP command contains
two

2.1.1.

5-7

1.3.1 Madison
1.4

Chester

As an

5-8 Typing Documents on the UNIX System
All of these variations on .LP leave the

FE (footnote end) will be collected, remem-

right

bered, and finally placed at the bottom of

margin

untouched.

Sometimes,

for

purposes such as setting off a quotation, a

the current page*.

paragraph indented on both right and left

are 11/12th the length of normal text, but

is required.

this can be changed using the FL register

(see below).

A single paragraph like this is

obtained
QP.

preceding

Displays

it with

More complicated material

(several

paragraphs)

should

get

italics

and

Tables.

prepare

displays of lines, such as tables, in which
the lines should not be re-arranged, enclose

them in the commands .DS and .DE

bracketed with .QS and .QE.
Emphasis.

By default, footnotes

(on

the

typesetter) or underlining (on the terminal)

table lines, like the
examples here, are placed

say

between .DS and .DE

.DE

as much text as you want

can be typed here

By default, lines between .DS and .DE are

as was done for these three words.

The .R

command restores the mnormal (usually
Roman) font. If only one word is to be italicized, it may be just given on the line with
the .I command,
J word

indented and left-adjusted.

You can also

center

left

retain

the

lines bracketed by .DS L and .DE are left-

adjusted,

not

arranged.

A plain .DS is equivalent to .DS

indented,

and

not

re-

I, which indents and left-adjusts. Thus,

Text to be set in boldface

goes here

these lines were preceded

by .DS C and followed by
a .DE command;
whereas

these lines were preceded

by .DS L and followed by

and also will be underlined on the terminal
As with .I, a single word

can be placed in boldface by placing it on
the same line as the .B command.
A few size changes can be specified

similarly with the commands .LG (make
larger), .SM (make smaller), and .NL
(return to normal size).

The size change is

two points; the commands may be repeated
for increased effect (here one .NL canceled two
.SM commands).

a .DE command.

Note that .DS C centers each line; there is a
variant .DS B that makes the display into a
left-adjusted block of text, and then centers

that entire block.

italicizing is required on the typesetter, the

command

Normally a display is

kept together, on one page.

across page boundaries, use .CD, .LD, or
D in place of the commands .DS C, .DS L,

or .DS I respectively. An extra argument to
the .DS I or .DS command is taken as an
Note: it is tempting to

assume that .DS R will right adjust lines,
but it doesn’t work.
Boxing words or lines.

To draw rec-

tangular boxes around words the command

.UL word

will underline a word.

If you wish to

have a long display which may be split

amount to indent.

If actual underlining as opposed to

There is no way to

underline multiple words on the typesetter.
Footnotes.

margin.

mands are centered (and not re-arranged);

and in this case no .R is needed to restore
Boldface can be produced by

11111

Lines bracketed by .DS C and .DE com-

the previous font.

or line printer.

lines,

Material placed between

.BX word

Typing Documents on the UNIX System

will print
as shown. The boxes will
not be neat on a terminal, and this should

ment

.SG

not be used as a substitute for italics.

natures.

Longer pieces of text may be boxed by

released paper format.

typing

can

the

altered

registers

change

They should be changed

nr PS 9

as has been done here.

Keeping blocks together.
together

with .nr commands, as with

keep

Certain

—ms

default settings.

text...

The .SG command is ignored in

Registers.
used

.B1

used

identification line, and placed after the sig-

enclosing them with .B1 and .B2:

5-9

If you wish

a table or other block of lines
on

page,

release” commands.

there

are

“keep

If a block of lines pre-

ceded by .KS and followed by .KE does not
fit on the remainder of the current page, it

will begin on a new page.

Lines bracketed

by .DS and .DE commands are automati-

to make the default point size 9 point.

the effect is needed immediately, the nor-

mal troff command should be used in addition to changing the number register.
Register

Defines

point size

line spacing

Takes

Default

effect
next para.
next para.

10
12 pts

LL
LT

line length
title length

next para.
next para.

be kept together is preceded by .KF instead

next para.

0.3 VS

para. indent

next para.

5 ens

of .KS and does not fit on the current page,

FL
CW
GW

footnote length
column width
intercolumn gap

next F'S
next 2C
next 2C

11/12 LL
7/15 LL
1/15 LL

cally kept together this way.

There is also

a “keep floating” command: if the block to

it will be moved down through the text

until the top of the next page.

Thus, no

large blank space will be introduced in the
document.

page offset

26/27\”

top margin

1\”’

Nroff/Troff commands.

Among the

useful commands from the basic formatting
programs are the following. They all work
with both typesetter and computer terminal
output:

Dbottom margin

1\”

You may also alter the strings LH, CH, and

RH which are the left, center, and right
headings respectively; and similarly LLF, CF,

and RF which are strings in the page footer.
The page number on output is taken from
register PN, to permit changing its output

.bp - begin new page.

style.

.br - “break”, stop running text

.na - don’t adjust right margins.

default,

documents

pro-

and

can

in ”.RP” format places the specified date on
the cover sheet and nowhere else.
this line before the title.

Place

You can obtain a sig-

nature line by placing the command .SG in

The authors’ names will be
An argu-

To simplify typing certain

accent marks are defined.

They precede

the letter over which the mark is to appear.
Here are the strings:

.ND May 8, 1945

output in place of the .SG line.

foreign words, strings representing common

at the bottom of each page. The command

the document.

macros

Accents.

duced on computer terminals have the date
at the bottom of each page; documents produced on the typesetter don’t. To force the
date, say ‘“.DA”. To force no date, say
“ND”. To lie about the date, say “.DA
July 4, 1776 which puts the specified date

Signature line.

the

redefined, as explained earlier.

.Sp n - insert n blank lines.

For more complicated headers and

footers

from line to line.

Date.

para. spacing

6\ >
6\

Input

Output

Input

Output

\* ‘e
\*'e
\*:u

e
e
!

\¥"a
\*Ce
\*,c

a
e
,C

\""e

Use.

After

your

document

prepared and stored on a file, you can print
it on a terminal with the command*
* If .2C was used, pipe the nroff output through
col;

make

/usr/bin/col.”

the

first

line

the

input

“.pi

5-10 Typing Documents on the UNIX System

References

nroff —ms file

and you can print it on the typesetter with
the command

[1]

B. W. Kernighan and L. L. Cherry,
Typesetting

Mathematics

—

troff —ms file

Computing Science Report no. 17.

(many options are possible).

In each case,

M. E. Lesk, Tbl — A Program to For-

if your document is stored in several files,

mat

just list all the filenames where we have

puting Science Report no. 45.

used “file”. If equations or tables are used,
eqn and/or tbl must be invoked as prepro-

Bell Laboratories, 1976.

CeSsors.

References

and

further

study.

you have to do Greek or mathematics, see
eqn

[1] for equation setting.

To aid egn

users, —ms provides definitions of .EQ and
.EN

which normally center the

and set it off slightly.
is taken to be

equation

An argument on .EQ

an equation number and

placed in the right margin near the equa-

tion.

In addition, there are three special

arguments to EQ: the letters C, I, and L
indicate centered

left

adjusted

(default), indented, and

equations,

respectively.

there is both a format argument and an

equation number, give the format argument
first, as in

EQ L (1.3a)
for

left-adjusted

equation

numbered

(1.3a).

Similarly, the macros .T'S and .TE are
defined to separate tables (see
text with a little space.

[2]) from

A very long table

with a heading may be broken across pages
by beginning it with . TS H instead of .TS,

and placing the line ."TH in the table data
after the heading.

If the table has no head-

ing repeated from page to page, just use the

ordinary .T'S and .TE macros.
To learn more about troff see [3] for a

general introduction, and [4] for the full
details

(experts

only).

Information

related UNIX commands is in [5].

For jobs

that do not seem well-adapted to —ms, consider other macro packages.

It is often far

easler to write a specific macro packages for

such tasks as imitating particular journals

than to try to adapt —ms.
Acknowledgment.

|
Many thanks are

due to Brian Kernighan for his help in the

design and implementation of this package,
and

for

manual.

his

Users

Guide (2nd edition), Bell Laboratories

assistance

preparing

this

Tables, Bell Laboratories Com-

B. W.

Kernighan, A

Troff Tutorial,

J. F. Ossanna, Nroff /Troff Reference
Manual, Bell Laboratories Computing

Science Report no. 51.
K.

Thompson

UNIX

and

Programmer’s

Laboratories, 1978.

Ritchie,

Manual,

Bell

Typing Documents on the UNIX System

5-11

Appendix A
List of Commands

Return to single column format.

Increase type size.

Start double column format.

Left aligned block paragraph.

Begin abstract.

End abstract.

Specify author’s institution.

Specify author.

Change or cancel date.

Begin boldface.

Specify numbered heading.

Provide the date on each page.

Return to normal type size.

End display.

Begin paragraph.

Start display (also CD, LD, ID).

End equation.

Return to regular font (usually Roman).

Begin equation.

End one level of relative indenting.

End footnote.

Use released paper format.

Begin footnote.

Relative indent increased one level.

SG
I

Begin italics.

Insert signature line.
Specify section heading.

Begin indented paragraph.

Change to smaller type size.
Specify title.

Underline one word.

SM
KE

Release keep.

Begin floating keep.

Start keep.

Independent use of these

names in one’s own macros may produce incorrect output.

Note that no lower case letters are

usedin any —ms internal name.

|
Number registers used in —ms

OdJ

H#HT

’

)

Eb5

String registers used in —ms

Typing Documents on the UNIX System

Order of Commands in Input

NH, SH

PP, LP

text ...
e

5-12

Figure 1

A Guide to -ms

5-13

Commands for a TM
.TM 1978-5b3 39999 99999-11
ND April 1, 1976
TJL
The Role of the Allen Wrench in Modern

A Guide to Preparing
Documents with —ms

Electronics
AU "MH 2G-111" 2345

M. E. Lesk

Bell Laboratories

August 1978

This guide gives some simple examples of document preparation on Bell Labs computers,
emphasizing the use of the -—ms macro package. It enormously abbreviates information in
1.
Typing Documents on UNIX and GCOS, by
M. E. Lesk;
2.
Typesetting Mathematics — User's Guide,
by B. W. Kernighan and L. L. Cherry; and
3.
Tbl — A Program to Format Tables, by M.
E. Lesk.
These memos are all included in the UNIX
Programmer’s Manual, Volume 2. The new
user should also have 4 Tutorial Introduction to
the UNIX Text Editor, by B. W. Kernighan.
For more detailed information, read Advanced
Editing on UNIX and A Troff Tutorial, by B. W,

J. Q. Pencilpusher
AU "MH 1K-222" 5432
X. Y. Hardwired
Al
MH
OK
Tools
Design
AB
This abstract should be.short enough to
fit on a single page cover sheet.
)
It must attract the reader into sending for

the compiete memorandum.

AE
LS 10212567
NH
Introduction.

PP
Now the first paragraph of actual text ..

Last line of text.
SG MH-1234-JQP/XYH-unix
NH

References ...

Commands not needed in a particular format are ignored.

Kernighan, and (for experts) Nroff/Troff Reference Manual by J. F. Ossanna.

Information on

related commands is found (for UNIX users) in
UNIX for Beginners by B. W. Kernighan and
the UNIX Programmer’s Manual by K. Thompson and D. M. Ritchie.

2
3
4
5
6
7
8

Throughout the examples, input is shown in

this Helvetica sans serif font
while the resuiting output is shown in

this Times Roman font.

UNIX Document no. 1111

This informanion is for empiovees of Bell Laborarones.

Tite-The Role of the Allen Wrench
in Modern Electronics

Contents
ATM ... .
Areleased paper .............
An internal memo, and headings ...
Lists, displays, and footnotes . . . ..
Indents, keeps, and double column .
Equations and registers . ........
Tablesand usage .............

Cover Sheet for TM

Bell Laboratories

(GEl 13.9-3)

Date-April 1, 1976

TTM- 1978-5b3

Other Keywords- Tools
Design

Author

Location

J. Q. Pencilpusher
X.Y. Hardwired

MH 2G-111 2345 Filing Case- 999992
MH 1K-222 5432

Ext.

Charging Case- 99999

ABSTRACT

This abstract should be short enough to
fit on a single page cover sheet. It must
attract the reader into sending for the complete memorandum.

Pages Text

No. Figures

E-1932-U (6-73)

Other

No. Tables

Totai
6

No. Refs.

SEE REVERSE SIDE FOR DISTRIBUTION LIST

5-14 A Guide to -ms

An Internal Memorandum

A Released Paper with Mathematics
EQ
delim $$
EN
RP

AM
ND January 24, 1956

TJLU
The 19568 Consent Decree
AU
Able, Baker &

... (as for a TTMM)

Charley, Attys.
PP

L£8102125867
NH

Plaintiff, United States of America, having filed
its complaint herein on January 14, 1949; the

introduction

PP
The solution to the torque handle equation
EQ (1)
sumfromQtoinfF(xsubi) =G (x)
EN
is found with the transformation $ x = rho over
theta $ where S rho = G prime (x) $ and $thetas

defendants having appeared and filed their
answer to such complaint denying the

substantive allegations thereof; and the parties,

by their attorneys, ...

is dqrived Bell Laboratories

Subject: The 1956 Consent Decree date:

January 24, 1956

from: Able, Baker &

Charley, Attys.

The Role of the Allen Wrench
in Modern Electronics

Plaintiff, United States of America, having filed its com-

plaint herein on January 14, 1949 the defendants having
appeared and filed their answer (o such compliaint denying
the substantive allegations thereof: and the parties. by their
attorneys, having severaily consented to the entry of this

J. Q. Pencilpusher

X. Y. Hardwired

Final Judgment. without (riai or adjudication of any issues
of fact or law herein and without this Final Judgment con-

Beil Laboratories
Murray Hill, New Jersey 07974

stituting any evidence or admission by any party in respect
of any such issues;

Now, therefore before anv testimony has been taken
herein, and without trial or adjudication of any issue of fact
or law herein, and upon the consent of ail parties hereto. it
is hereby

ABSTRACT
This abstract should be short enough 0 fit on a
sirigie psge cover sheet.
It must actract the
reader into sending {or the compilete memorandum.

Ordered, adjudged and decreed as foilows:

[Sherman Act]
This Court has jurisdiction of the subject matter herein

and of all the parties hereto.
upon

which

and

commerce

relief may

The complaint states a claim

granted

against

each

of the

defendants under Sections |. 2 and 5 of the Act of
Congress of July 2, 1890, =nutled "*An act to protect trade

April 1, 1976

against

unlawful

restraints

and

monopo-

lies,”” commonly known as the Sherman Act, as amended.

1. [Definitions]
For the purposes of this Final Judgment:

(a)

**Western’" shail mean the defendant Western Elec-

teic Company, [ncorporated.

The Role of the Allen Wrench
in Modern Electronics
J. Q. Pencilpusher

Other formats possible (specify before .TL) are: MR
(**‘memo for record’’). .MF (“*memo for fiile’"). EG
(‘“*engineer’s notes’’) and .TR (Computing Science
Tech. Report).

X. Y. Hardwired
Bell Laboratories
Murray Hill, New Jersey 07974

Headings
1. {ntroduction
The solution to the torque handle equation

2 F(x,)=Gix)

(1)

i$ found with the transformation x -%- where p=G
' (x) and
9 is derived from well-known principles.

introduction.

Appendix |

text text text

Appendix |

Introduction
text text text

lext

ext text

A Guide to -ms

Multiple Indents

A Simple List
JP 1.

J. Pencilpusher and X. Hardwired,
A

A New Kind of Set Screw,
R

(1976), 23-255.

AP 2.

H. Nails and R. lrons,
R

Fasteners for Printed Circuit Boards,

(1974), 23-24.
LP (terminates list)

line.

J. Pencilpusher and X. Hardwired, 4 New Kind
of Set Screw, Proc. IEEE 75 (1976), 23-255.
H. Nails and R. Irons, Fasteners for Printed Circuit Boards, Proc. ASME 23 (1974), 23-24.

Displays
text text text text text text
DS
and now
for something
completely different
DE
text text text text text text

hoboken harrison newark roseville avenue grove
street east orange brick church orange highland avenue mountain station south orange maplewood
millburn short hills summit new providernce

and now

for something

completely different

murray hill berkeley heights gillette stirling millington lyons basking ridge bernardsville far hills
peapack gladstone

Options: .DS

level item, but somewhat longer.
RE
P 2.
Return to previous value of the
indenting at this point.
AP 3.
Another

Proc. ASME
B 23

This is ordinary text to point out
the margins of the page.
AP 1.
First level item
RS

P a)
Second level.
AP b)
Continued here with another second

Proc. |IEEE
B 78

5-15

L: left-adjust; .DS C: line-by-line

center; .DS B: make block, then center.

This is ordinary text to point out the margins of the
page.

First level item
a)
Second level.
b) Continued here with another second level

Return to previous value of the indenting at this
point.
Another line.

item, but somewhat longer.

Keeps
Lines bracketed by the following commands are kept
together, and will appear entirely on one page:
KF
may float
KS
not moved
KE
in text
KE
through text

Double Column
JL
The Declaration of independence
.2C
PP
When in the course of human events, it becomes
necessary for one people to dissolve the

political bonds which have connected them with
another, and to assume among the powers of the

earth the separate and equal station to which
the laws of Nature and of Nature's God entitle

Footnotes

them, a decent respect to the opinions of

The Declaration of Independence

Among the most important occupants

of the workbench are the long-nosed pliers.
Without these basic tools®
FS

* As first shown by Tiger & Leopard
(1975).

few assemblies could be completed. They may
lack the popular appeal of the sledgehammer

Among the most important occupants of the workbench are the long-nosed pliers. Without these basic
tools® few assembiies could be completed. They
may lack the popular appeal of the sledgehammer
* Ag first shown by Tiger & Leopard (1975).

When in the course of

human

events,

be-

comes necessary for one
peopie

dissolve

political
bonds
have
connected

the

which
them

they

should declare the

causes which impel them
to the separation.
We

hold

these

truths

sume among the powers

to be self-evident, that
all
men
are
created
equal, that they are endowed by their creator

of the earth the separate

with

and
equal
station
(o
which the laws of Nature

rights, that among these

with another, and to as-

and of Nature's God entitle
them,
a
decent
respect to the opinions

of mankind requires that

certain

unalienable

are life, liberty, and the
pursuit
of
happiness.
That
to secure
these
rights, governments are
instituted

among

men,

5-16 A Guide to -ms

Tables

Equations
TS

A displayed equation is marked
with an equation number at the right margin

(® indicates a tab)

alibox;

by adding an argument to the EQ line:
EQ (1.3)

CsSSs

AT&T Common Stock |

g fi ‘;

Yeur| Price ;: Dividend

AT&T Common Stock

1971 '“"f"

A displayed equation is marked with an equation

1971

number at the right margin by adding an argument

X Sup 2overasup 2 "="sqrt {pzsup 2 +qz+r}

Year @ Price ® Dividend

to the EQ line:

-‘S-; =\ pzidqs
r

(1.3

a
1 4

A(lD)
.
.
.

b -+ o
¢

2.837

2241-5402.70

4140-33

329

4®40-5303.24

A A LIEEALY

5D45-5203.40

* (first quarter only)

.
|18
AQBD]
Ly

(2.2a)

* (first quarter only)
The meunings of the key-letters describing the alignment ol each entry are:
c

center

numerical

rright-adjust

subcolumn

f
left-adjust
S
spanned
The global table options are center, expand, box.
doublebox, allbox, tab (x) and linesize (n).

TS
(with delim SS on. see panel 3)
doublebox, center:

ccC

EN
EQ

Name @ Definition

I 1.

lineup =" {left ( {partial V] over |partial x} right )
} sup 2 + { left { {partial V} over |partial y} right
) ) sup 2 ~""""" lambda -> inf

Fly)
= |V

av]
[av]’
“ox | "oy

(with delim SS on, see panel 3).

See also the equations in the second table, panel 8.

Some Registers You Can Change
Line length
nr LL 7i

Paragraph spacing

Title length
ar LT 7i

Page offset
.nr PO 0.5

Point size
.nrPSH

Page heading
.ds CH Appendix

Vertical spacing

nr VS 11

Column width
nr CW 3j
Intercolumn spacing
.nr GW 5§
Margins = head and foot
.nr HM .75i

..SP

Gamma
@ SGAMMA (z) = int sub O sup inf \

t sup {z-1] e sup -t dts

Sine®Ssin (x) = 1 over 2i (e sup ix - e sup -ix )3
Error @S roman erf (z) = 2 over sqrt pi \
int sub O sup z e sup {-t sup 2} dts
Bessel®S Jsub 0 (2) = 1 over pi \
int sub O sup pi cos ( Z sin theta ) d theta S

A ==co

Sadots, $bdotdotS, $ xitilde times y vecS:

.nr FM .75i

6051-59®.95°

F hat (chi) " mark = ~|del V|sup 2

Paragraph indent
.ar Pl 2n

2.70

3146-33

a, b, Exv.

SZ'EO

1(2.2a)

bold V bar sub nu~="left [ pile (a above b above
¢ ) right] + left [ matrix { col { A(11) above .
above . | col {. above . above .} col {. above .
above A(33) |} right ] cdot left [ pile { alpha
above beta above gamma } right
]
-

D41-54 DS2.60

3P46-5502.87

2(41-34 |

.ar PD 0

(center)

~.ds RH 7-25-76

(right)
.ds LH Private

(left)
Page footer
.ds CF Draft
ds LF
ds RE

. .
similar

Page numbers
nr% 3

Zeta @S zeta (s) =\
sum from k=1 to inf k sup -s ~"( Re’s > 1)S
TE
Name

Definition

Gamma

I‘(:)-fo t:=le
=" dr

Sine

sin(x)-«%;(e"’-e"")

Error

erf(:)--}..;‘!:):e"zdr

Bessel

JO('—)"}{fo cos(zsind)d@

Zeta

{(s)=3
k=

(Res>1)

{ |

Usage

“

Documents with just text:
troff -ms files
With equations only:

eqn files| troff -ms

With tables only:

tbl files | troff -ms

With both tables and equuations:

tbl files{egn!troff -ms

The above generates STARE output on GCOS: replace
-8t with —=ph for tvpesetter output.

A Revised Version of -ms 5-17

A Revised Version of -ms
Bill Tuthull
Computing Services
University of California
Berkeley, CA 94720

The -ms macros have been slightly revised and rearranged. Because of the rearrangement, the new macros can be read by the computer in about half the time required by the
previous version of -ms. This means that output will begin to appear between ten seconds and
several minutes more quickly, depending on the system load. On long files, however, the savings in total time are not substantial. The old version of -ms is still available as-mos.

Several bugs in -ms have been fixed, including a bad problem with the .1C macro, minor

difficulties with boxed text, a break induced by .EQ before initialization, the failure to set tab
stops in displays, and several bothersome errors in the refer macros. Macros used only at
Bell Laboratories have been removed. There are a few extensions to previous -ms macros, and
a number of new macros, but all the documented -ms macros still work exactly as they did
before, and have the same names as before. Output produced with -ms should look like output produced with—mos.

One important new feature is automatically numbered footnotes. Footnote numbers are
printed by means of a pre-defined string (\**), which you invoke separately from .FS and .FE.

Each time it is used, this string increases the footnote number by one, whether or not you use

FS and .FE in your text. Footnote numbers will be superscripted on the phototypesetter and
on daisy-wheel terminals, but on low-resolution devices (such as the lpr and a crt), they will
be bracketed. If you use )Y** to indicate numbered footnotes, then the .FS macro will
automatically include the footnote number at the bottom of the page. This footnote, for
example, was produced as follows:!

This footnote, for example, was produced as follows:
\**
FS

If you are using }** to number footnotes, but want a particular footnote to be marked with an
asterisk or a dagger, then give that mark as the first argument to .FS: T

then give that mark as the first argument to .FS: \(dg
FS

\(dg

Footnote numbering will be temporarily suspended, because the \** string is not used.
Instead of a dagger, you could use an asterisk * or double dagger i, represented as \(dd.
I If you never use the “\**” string, no footnote numbers will appear anywhere in the text, including down
here. The output footnotes will look exactly like footnotes produced with -mos.
t In the footnote, the dagger will appear where the footnote number would otherwise appear, as on the
left.

5-18 A Revised Version of -ms
Another new feature is a macro for printing theses according to Berkeley standards.
This macro is called .'TM, which stands for thesis mode.

(It is much like the .th macro in

‘me.) It will put page numbers in the upper right-hand corner; number the first page; suppress

the date; and doublespace everything except quotes, displays, and keeps.
each file making up your thesis.

Use it at the top of

Calling .TM defines the .CT macro for chapter titles, which

skips to a new page and moves the pagenumber to the center footer.

The .P1 (P one) macro

can be used even without thesis mode to print the header on page 1, which is suppressed
except in thesis mode.

If you want roman numeral page numbering, use an ‘“.af PN i”

request.

There is a new macro especially for bibliography entries, called .XP, which stands for

exdented paragraph.

It will exdent the first line of the paragraph by\n(PI units, usually 5n

(the same as the indent for the first line of a .PP).

Most bibliographies are printed this way.

Here are some examples of exdented paragraphs:
Lumley, Lyle S., Sex in Crustaceans: Shell Fish Habits, Harbinger Press, Tampa Bay and

San Diego, October 1979.

243 pages.

The pioneering work in this field.

Leffadinger, Harry A., “Mollusk Mating Season: 52 Weeks, or All Year?” in Acta Biologica,
vol. 42, no. 11, November 1980.

A provocative thesis, but the conclusions are wrong.

Of course, you will have to take care of italicizing the book title and journal, and quoting the
title of the journal article.

Indentation or exdentation can be changed by setting the value of

number register PI.
If you need to produce endnotes rather than footnotes, put the references in a file of

their own.

This is similar to what you would do if you were typing the paper on a conven-

tional typewriter.

Note that you can use automatic footnote numbering without actually hav-

ing .FS and .FE pairs in your text.

If you place footnotes in a separate file, you can use .IP

macros with \** as a hanging tag; this will give you numbers at the left-hand margin.

With

some styles of endnotes, you would want to use .PP rather then .IP macros, and specify \'*

before the reference begins.
There are four new macros to help produce a table of contents.

Table of contents

entries must be enclosed in . XS and .XE pairs, with optional . XA macros for additional
entries; arguments to .XS and .XA specify the page number, to be printed at the right.
final .PX macro prints out the table of contents.

Here is a sample of typical input and output

text:

Introduction

XA 1
Chapter 1: Review of the Literature
XA 23
Chapter 2: Experimental Evidence
XE
PX
Table of Contents
INEPOAUCTION

ot
e et e e e abe s e e eesaaasbateeeeesessareseeesenaneeas

Chapter 1: Review of the Literature ......ccccoeiieeiiiiiiiiiieieeeeeeeeeee
et eeeeeeeeeeeeeene

Chapter 2: Experimental Evidence ....couoviivviieiiiiiiiiiieeeeeeeeeeeeeeee
et eeveeeesee e

The .XS and .XE pairs may also be used in the text, after a section header for instance, in

which case page numbers are supplied automatically.

However, most documents that require

a table of contents are too long to produce in one run, which is necessary if this method is to
work.

It is recommended that you do a table of contents after finishing your document.

print out the table of contents, use the .PX macro; if you forget it, nothing will happen.

A Revised Version of -ms

5-19

As an aid in producing text that will format correctly with both nroff and troff, there
are some new string definitions that define quotation marks and dashes for each of these two
formatting programs. The \* string will yield two hyphens in nroff, but in troff it will pro-

duce an em dash— like this one. The \*Q and \*U strings will produce “ and ” in troff, but ”
in nroff.

(In typesetting, the double quote is traditionally considered bad form.)

There are now a large number of optional foreign accent marks defined by the-ms mac-

ros. All the accent marks available in—mos are present, and they all work just as they always

did. However, there are better definitions available by placing .AM at the beginning of your
document. Unlike the—mos accent marks, the accent strings should come after the letter
being accented. Here is a list of the diacritical marks, with examples of what they look like.
name of accent

acute accent

input

e\*’

output

e’

grave accent

e\*'

e’

circumflex
cedilla

question
exclamation

o\*~
c\*,
n\*.

\*?
\*!

o
c,
n”

umlaut
digraph s
hacek

u\*:
\*8
c\rv

u”

macron
underdot
o-slash
angstrom

a\*
s\*.
o\*/
a\o

a
S
0
a
knit

tilde

yogh

kni\*3t

Thorn
thorn

\*(Th
\*(th

Eth

\*(D-

eth

\*(d-

hooked o
ae ligature
AE ligature

\*q
\*(ae
\*(Ae

oe ligature

\*(oe

OE ligature

\*(Oe

If you want to use these new diacritical marks, don’t forget the .AM at the top of your file.
Without it, some will not print at all, and others will be placed on the wrong letter.
It is also possible to produce custom headers and footers that are different on even and
odd pages. The .OH and .EH macros define odd and even headers, while .OF and .EF define
odd and even footers. Arguments to these four macros are specified as with .tl. This document was produced with:

.OH '\\fIThe -mx Macros”“Page %\\fP’
EH "\fIPage

%”“The -mx Macros\fP’

Note that it would be a error to have an apostrophe in the header text; if you need one, you
will have to use a different delimiter around the left, center, and right portions of the title.
You can use any character as a delimiter, provided it doesn’t appear elsewhere in the argument to .OH, .EH, .OF, or EF.

The—ms macros work in conjunction with the tbl, eqn, and refer preprocessors. Macros to deal with these items are read in only as needed, as are the thesis macros (. TM), the
special accent mark definitions (.AM), table of contents macros (.XS and .XE), and macros to

5-20 A Revised Version of -ms

format the optional cover page. The code for the ms package lives in /usr/lib/tmac/tmac.s,
and sourced files reside in the directory /usr/ucb/lib/ms.

Writing Papers with -me 5-21

WRITING PAPERS WITH NROFF USING —ME
Eric P. Allman
Electronics Research Laboratory

University of California, Berkeley
Berkeley, California 94720

This document describes the text processing facilities available on the UNIXt operating
system via NROFFT and the —me macro package. It is assumed that the reader already is gen-

erally familiar with the UNIX operating system and a text editor such as ex. This is intended
to be a casual introduction, and as such not all material is covered.

In particular, many varia-

tions and additional features of the —me macro package are not explained.

For a complete

discussion of this and other issues, see The —me Reference Manual and The NROFF/TROFF
Reference Manual.

NROFF, a computer program that runs on the UNIX operating system, reads an input file
prepared by the user and outputs a formatted paper suitable for publication or framing.

The

input consists of text, or words to be printed, and requests, which give instructions to the
NROFF program telling how to format the printed copy.

Section 1 describes the basics of text processing.

Section 3 introduces displays.

Section 2 describes the basic requests.

Annotations, such as footnotes, are handled
in section 4.

more complex requests which are not discussed in section 2 are covered in section 5.

section 6 discusses things you will need to know if you want to typeset documents.

The

Finally,

If you are

a novice, you probably won’t want to read beyond section 4 until you have tried some of the

basic features out.
When you have your raw text ready, call the NROFF formatter by typing as a request to
the UNIX shell:
nroff —me —Ttype files

where type describes the type of terminal you are outputting to.

Common values are dte for

a DTC 300s (daisy-wheel type) printer and lpr for the line printer.

If the —T flag is omitted,

a “lowest common denominator” terminal is assumed; this is good for previewing output on
most terminals.

A complete description of options to the NROFF command can be found in

The NROFF/TROFF Reference Manual.
The word argument is used in this manual to mean a word or number which appears on

the same line as a request which modifies the meaning of that request.
request

For example, the

.Sp

spaces one line, but
Sp 4

spaces four lines.

The number 4 is an argument to the .sp request which says to space four

5-22 Writing Papers with -me

lines instead of one.

Arguments are separated from the request and from each other by

spaces.

Basics of Text Processing

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

For example, the input:

Now is the time
for all good men

to come to the aid
of their party.
Four score and seven
years ago,...

will be read, packed onto output lines, and justified to produce:
Now is the time for all good men to come to the aid of their party.

Four score

and seven years ago,...
Sometimes you may want to start a new output line even though the line you are on is not
yet full; for example,
at the end of a paragraph.
starts a new output line.

To do this you can cause a break, which

Some requests cause a break automatically, as do blank input

lines and input lines beginning with a space.

Not all input lines are text to be formatted.
which describe how to format the text.

Some of the input lines are requests

Requests always have a period or an apostrophe

(““"”) as the first character of the input line.

The text formatter also does more complex things, such as automatically numbering
pages, skipping over page folds, putting footnotes in the correct place, and so forth.
I can offer you a few hints for preparing text for input to NROFF.

input lines short.

First, keep the

Short input lines are easier to edit, and NROFF will pack words onto

longer lines for you anyhow.

In keeping with this, it is helpful to begin a new line after

every period, comma, or phrase, since common corrections are to add or delete sentences or

phrases.

Second, do not put spaces at the end of lines, since this can sometimes confuse

the NROFF processor.

Third, do not hyphenate words at the end of lines (except words

that should have hyphens in them, such as “mother-in-law”); NROFF is smart enough to

hyphenate words for you as needed, but is not smart enough to take hyphens out and join
a word back together. Also, words such as “mother-in-law” should not be broken over a
line, since then you will get a space where not wanted, such as “mother- in-law”.
2.

Basic Requests
2.1. Paragraphs

Paragraphs are begun by using the .pp request. For example, the input:
Now is the time for all good men
to come to the aid of their party.
Four score and seven years ago,...

produces a blank line followed by an indented first line. The result is:

TUNIX, NROFF, and TROFF are Trademarks of Bell Laboratories

Writing Papers with -me 5-23

Now 1is the time for all good men to come to the aid of their party. Four

score and seven years ago,...

Notice that the sentences of the paragraphs must not begin with a space, since

blank lines and lines begining with spaces cause a break. For example, if I had typed:
-pPp

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

The output would be:

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

A new line begins after the word “men” because the second line began with a space
character.

There are many fancier types of paragraphs, which will be described later.
2.2. Headers and Footers

Arbitrary headers and footers can be put at the top and bottom of every page.

Two requests of the form .he title and .fo title define the titles to put at the head and
the foot of every page, respectively. The titles are called three-part titles, that is, there
is a left-justified part, a centered part, and a right-justified part. To separate these
three parts the first character of title (whatever it may be) is used as a delimiter. Any
character may be used, but backslash and double quote marks should be avoided. The
percent sign is replaced by the current page number whenever found in the title. For
example, the input:
.he

//%//

fo “Jane Jones”"My Book”

results in the page number centered at the top of each page, “Jane Jones” in the lower
left corner, and “My Book” in the lower right corner.

2.3. Double Spacin‘g‘
NROFF will double space output text automatically if you use the request .Is 2, as
is done in this section. You can revert to single spaced mode by typing .Is 1.
2.4. Page Layout

A number of requests allow you to change the way the printed copy looks, sometimes called the layout of the output page. Most of these requests adjust the placing of
“white space” (blank lines or spaces). In these explanations, characters in italics should

be replaced with values you wish to use; bold characters represent characters which
should actually be typed.

The .bp request starts a new page.

The request .sp N leaves N lines of blank space. N can be omitted (meaning skip
a single line) or can be of the form Ni (for N inches) or Ne¢ (for N centimeters). For
example, the input:
.sp 1.51

My thoughts on the subject
.Sp

leaves one and a half inches of space, followed by the line “My thoughts on the

5-24 Writing Papers with -me

subject”, followed by a single blank line.
The .in +N request changes the amount of white space on the left of the page
The argument N can be of the form +N (meaning leave N spaces more

(the indent).

than you are already leaving), —N (meaning leave less than you do now), or just N
(meaning leave exactly N spaces). N can be of the form Ni or Ne also. For example,

the input:

initial text

in 5
some text

in +1i
more text

an —2¢
final text

produces “some text” indented exactly five spaces from the left margin, “more text”
indented five spaces plus one inch from the left margin (fifteen spaces on a pica type-

writer), and “final text” indented five spaces plus one inch minus two centimeters from
the margin. That is, the output is:
initial text
some text
more text

final text

The .ti +N (temporary indent) request is used like .in +N when the indent
should apply to one line only, after which it should revert to the previous indent. For
example, the input:

an 1i
i 0

Ware, James R. The Best of Confucius,
Halcyon House, 1950.
An excellent book containing translations of

most of Confucius” most delightful sayings.
A definite must for anyone interested in the early foundations

of Chinese philosophy.
produces:

Ware, James R.

The Best of Confucius, Halcyon House, 1950. An excellent book containing translations of most of Confucius’ most delightful sayings. A
definite must for anyone interested in the early foundations of Chinese

philosophy.

Text lines can be centered by using the .ce request.

tered (horizontally) on the page.

The line after the .ce is cen-

To center more than one line, use .ce

the number of lines to center), followed by the N lines.
lines but don’t want to count them, type:

N (where N is
If you want to center many

.ce 1000

lines to center
.ce 0

The .ce O request tells NROFF to center zero more lines, in other words, stop centering.

All of these requests cause a break; that is, they always start a new line.
want to start a new line without performing any other action, use .br.

If you

Writing Papers with -me

5-25

2.5. Underlining

Text can be underlined using the .ul request. The .ul request causes the next
input line to be underlined when output. You can underline multiple lines by stating a
count of input lines to underline, followed by those lines (as with the .ce request). For
example, the input:
.l 2

Notice that these two input lines

are underlined.

will underline those eight words in NROFF. (In TROFF they will be set in italics.)
3. Displays

Displays are sections of text to be set off from the body of the paper. Major quotes,
tables, and figures are types of displays, as are all the examples used in this document. All
displays except centered blocks are output single spaced.
3.1. Major Quotes

Major quotes are quotes which are several lines long, and hence are set in from
the rest of the text without quote marks around them. These can be generated using
the commmands .(q and .)q to surround the quote. For example, the input:
As Weizenbaum points out:

It is said that to explain is to explain away.
This maxim is nowhere so well fulfilled

as in the areas of computer programming,...

)q
generates as output:

As Weizenbaum points out:
It is said that to explain is to explain away. This maxim is nowhere so well fulfilled as
in the areas of computer programming,...

3.2. Lists

A list is an indented, single spaced, unfilled display.

Lists should be used when

the material to be printed should not be filled and justified like normal text, such as
columns of figures or the examples used in this paper. Lists are surrounded by the
requests .(1 and .)l. For example, type:
Alternatives to avoid deadlock are:
1
Lock in a specified order

Detect deadlock and back out one process
Lock all resources needed before proceeding
Il

will produce:
Alternatives to avoid deadlock are:

Lock in a specified order

Detect deadlock and back out one process

Lock all resources needed before proceeding

5-26 Writing Papers with -me

3.3. Keeps

A keep is a display of lines which are kept on a single page if possible. An example of where you would use a keep might be a diagram. Keeps differ from lists in that
lists may be broken over a page boundary whereas keeps will not.
Blocks are the basic kind of keep.

the request .)b.

They begin with the request .(b and end with
If there is not room on the current page for everything in the block, a

new page is begun.

of the page.

keeps.

This has the unpleasant effect of leaving blank space at the bottom
When this is not appropriate, you can use the alternative, called floating

Floating keeps move relative to the text. Hence, they are good for things which
will be referred to by name, such as “See figure 3”. A floating keep will appear at the
bottom of the current page if it will fit; otherwise, it will appear at the top of the next
page. Floating keeps begin with the line .(z and end with the line .)z. For an example

of a floating keep, see figure 1. The .hl request is used to draw a horizontal line so that
the figure stands out from the text.

3.4. Fancier Displays
Keeps and lists are normally collected in nofill mode, so that they are good for
If you want a display in fill mode (for text), type .(1 F (Throughout

tables and such.

this section, comments applied to .(1 also apply to .(b and .(z).
will be indented from both margins.

For example, the input:

(AF
And now boys and girls,

a newer, bigger, better toy than ever before!

Be the first on your block to have your own computer!
Yes kids, you too can have one of these modern

data processing devices.
You too can produce beautifully formatted papers
without even batting an eye!

will be output as:

hl
Text of keep to be floated.
.Sp
.Ce

Figure 1. Example of a Floating Keep.

Y
Figure 1.

Example of a Floating Keep.

This kind of display

Writing Papers with -me 5-27

And now boys and girls, a newer, bigger, better toy than ever before! Be the
first on your block to have your own computer! Yes kids, you too can have one
of these modern data processing devices. You too can produce beautifully formatted papers without even batting an eye!

Lists and blocks are also normally indented (floating keeps are normally left
justified). To get a left-justified list, type .(1 L. To get a list centered line-for-line,
type .(1 C. For example, to get a filled, left justified list, enter:
(ALF

text of block
Il
The input:

first line of unfilled display
more lines

produces the indented text:
first line of unfilled display
more lines

Typing the character L after the .(l request produces the left justified result:
first line of unfilled display
more lines

Using C instead of L produces the line-at-a-time centered output:
first line of unfilled display
more lines

Sometimes it may be that you want to center several lines as a group, rather than
centering them one line at a time. To do this use centered blocks, which are surrounded by the requests .(c and .)e. All the lines are centered as a unit, such that the
longest line is centered and the rest are lined up around that line. Notice that lines do
not move relative to each other using centered blocks, whereas they do using the C
argument to keeps.

Centered blocks are not keeps, and may be used in conjunction with keeps.
example, to center a group of lines as a unit and keep them on one page, use:

For

Ab L
c

first line of unfilled display
more lines

If the block requests (.(b and .)b) had been omitted the result would have been the
same, but with no guarantee that the lines of the centered block would have all been on
one page. Note the use of the L argument to .(b; this causes the centered block to
center within the entire line rather than within the line minus the indent. Also, the
center requests must be nested inside the keep requests.

5-28 Writing Papers with -me

4. Annotations

There are a number of requests to save text for later printing.
at the bottom of the current page.

Footnotes are printed

Delayed text is intended to be a variant form of foot-

note; the text is printed only when explicitly called for, such as at the end of each chapter.
Indexes are a type of delayed text having a tag (usually the page number) attached to each

entry after a row of dots. Indexes are also saved until called for explicitly.
4.1.

Footnotes

Footnotes begin with the request .(f and end with the request .)f.

The current

footnote number is maintained automatically, and can be used by typing \**, to pro-

duce a footnote number'.
note.

The number is automatically incremented after every foot-

For example, the input:

(q
A man who is not upright

and at the same time is presumptuous;
one who is not diligent and at the same time is ignorant;
one who is untruthful and at the same time is incompetent;

such men I do not count among acquaintances.\**
Af

\**James R. Ware,
.ul
The Best of Confucius,
Halcyon House, 1950.

Page 77.
Of

)q
generates the result:
A man who is not upright and at the same time is presumptuous; one who is not dili-

gent and at the same time is ignorant; one who is untruthful and at the same time is in-

competent; such men I do not count among acquaintances.”
It is important that the footnote appears inside the quote, so that you can be sure that

the footnote will appear on the same page as the quote.
4.2.

Delayed Text
Delayed text is very similar to a footnote except that it is printed when called for

explicitly.

This allows a list of references to appear (for example) at the end of each

chapter, as is the convention in some disciplines.

Use \*# on delayed text instead of \**

as on footnotes.
If you are using delayed text as your standard reference mechanism, you can still
use footnotes, except that you may want to reference them with special characters*
rather than numbers.
4.3.

Indexes
An “index” (actually more like a table of contents, since the entries are not sorted

alphabetically) resembles delayed text, in that it is saved until called for.

However,

each entry has the page number (or some other tag) appended to the last line of the
'Like this.

‘James R. Ware, The Best of Confucius, Halcyon House, 1950. Page 77.
*Such as an asterisk.

Writing Papers with -me

5-29

index entry after a row of dots.
Index entries begin with the request .(x and end with .)x.

The .)x request may

have a argument, which is the value to print as the “page number”.

current page number.

It defaults to the

If the page number given is an underscore (“ ”’) no page number

or line of dots is printed at all. To get the line of dots without a page number, type .)x
”” which specifies an explicitly null page number.
The .xp request prints the index.
For example, the input:

Sealing wax
)X

Cabbages and kings

A(x

Why the sea is boiling hot
Jx 2.5a

Ax
Whether pigs have wings
Jx

Ax
This is a terribly long index entry, such as might be used
for a list of illustrations, tables, or figures; I expect it to

take at least two lines.

)X
XP

generates:

SEALINE WAX ..uviiiiiiiiiiiiniiiniiecieicteintereeeeesrreseseeeesesessasessseessssessssssstossssesstessseesssasesssessnns

Cabbages and kings
Why the sea is BoIling Mot .......coivviiiiiiiireeiirr
ettt ste e se s

2.5a

Whether pigs have WINES .....cccciviiiiiiiiiiiiieeecirecnieecnee
e esseressssecesseesessessssssesssssesns
This is a terribly long index entry, such as might be used for a list of illustra-

tions, tables, or figures; I expect it to take at least two lines.

......ccceeeuvunn.....

The .(x request may have a single character argument, specifying the “name” of

the index; the normal index is x.

Thus, several “indicies” may be maintained simul-

taneously (such as a list of tables, table of contents, etc.).
Notice that the index must be printed at the end of the paper, rather than at the

beginning where it will probably appear (as a table of contents); the pages may have to
be physically rearranged after printing.
5. Fancier Features
A large number of fancier requests exist, notably requests to provide other sorts of
paragraphs, numbered sections of the form 1.2.3 (such as used in this document), and
multicolumn output.

5.1. More Paragraphs
Paragraphs generally start with a blank line and with the first line indented.

It is

possible to get left-justified block-style paragraphs by using .lp instead of .pp, as
demonstrated by the next paragraph.

5-30 Writing Papers with -me

Sometimes you want to use paragraphs that have the body indented, and the first line
exdented (opposite of indented) with a label.

This can be done with the Ap request.

word specified on the same line as .ip is printed in the margin, and the body is lined up
at a prespecified position (normally five spaces).

For example, the input:

ip one

This is the first paragraph.

Notice how the first line
of the resulting paragraph lines up

with the other lines in the paragraph.
Ap two

And here we are at the second paragraph already.
You may notice that the argument to .ip
appears

in the margin.

Ip
We can continue text...
produces as output:
one

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

two

And here we are at the second paragraph already.
ment to .Ip appears in the margin.

You may notice that the argu-

We can continue text without starting a new indented paragraph by using the .lp

request.

If you have spaces in the label of a .ip request, you must use an “unpaddable
space” instead of a regular space. This is typed as a backslash character (“\”) followed

by a space. For example, to print the label “Part 1”, enter:

ip "Part\1”
If a label of an indented paragraph (that is, the argument to .ip) is longer than
the space allocated for the label, .ip will begin a new line after the label. For example,

the input:

1p longlabel

This paragraph had a long label.

The first character of text on the first line
will not line up with the text on second and subsequent lines,

although they will line up with each other.
will produce:

longlabel
This paragraph had a long label. The first character of text on the first line will
not line up with the text on second and subsequent lines, although they will line
up with each other.

It is possible to change the size of the label by using a second argument which is

the size of the label.
ing:

For example, the above example could be done correctly by say-

.1p longlabel 10

which will make the paragraph indent 10 spaces for this paragraph only.

many paragraphs to indent all the same amount, use the number register ii.

ple, to leave one inch of space for the label, type:

If you have
For exam-

Writing Papers with -me 5-31

ar il 1i

somewhere before the first call to .ip. Refer to the reference manual for more information.

If .ip is used with no argument at all no hanging tag will be printed. For example,
the input:

ip [a]

This is the first paragraph of the example.

We have seen this sort of example before.
Ap

This paragraph is lined up with the previous paragraph,
but it has no tag in the margin.
produces as output:

[a]

This is the first paragraph of the example.

We have seen this sort of example

before.

This paragraph is lined up with the previous paragraph, but it has no tag in the
margin.

A special case of .ip is .np, which automatically numbers paragraphs sequentially
from 1. The numbering is reset at the next .pp, .Ip, or .sh (to be described in the next
section) request. For example, the input:
.np

This is the first point.
.np

This is the second point.
Points are just regular paragraphs

which are given sequence numbers automatically
by the .np request.
.Pp

This paragraph will reset numbering by .np.
.np

For example,

we have reverted to numbering from one now.
generates:

(1)

This is the first point.

(2)

This is the second point. Points are just regular paragraphs which are given
sequence numbers automatically by the .np request.
This paragraph will reset numbering by .np.

(1)

For example, we have reverted to numbering from one now.

5.2. Section Headings

Section numbers (such as the ones used in this document) can be automatically
generated using the .sh request. You must tell .sh the depth of the section number
and a section title. The depth specifies how many numbers are to appear (separated by
decimal points) in the section number. For example, the section number 4.2.5 has a
depth of three.

Section numbers are incremented in a fairly intuitive fashion. If you add a
number (increase the depth), the new number starts out at one. If you subtract section

numbers (or keep the same number) the final number is incremented. For example, the
input:

5-32 Writing Papers with -me

.sh 1 ”The Preprocessor”
.sh 2 ”Basic Concepts”

.sh 2 ”Control Inputs”
.sh 3

.sh 3

.sh 1 ”Code Generation”
.sh 3
produces as output the result:
1. The Preprocessor

1.1. Basic Concepts
1.2. Control Inputs
1.2.1.
1.2.2.

2. Code Generation
2.1.1.

You can specify the section number to begin by placing the section number after

the section title, using spaces instead of dots. For example, the request:
.sh 3 "Another section” 7 3 4
will begin the section numbered 7.3.4; all subsequent .sh requests will number relative
to this number.
There are more complex features which will cause each section to be indented pro-

portionally to the depth of the section. For example, if you enter:
anr si N

each section will be indented by an amount N. N must have a scaling factor attached,
that is, it must be of the form Nx, where x is a character telling what units N is in.

Common values for x are i for inches, ¢ for centimeters, and n for ens (the width of a
single character). For example, to indent each section one-half inch, type:
ar si 0.51

After this, sections will be indented by one-half inch per level of depth in the section
number.

For example, this document was produced using the request

.nr si 3n

at the beginning of the input file, giving three spaces of indent per section depth.

Section headers without automatically generated numbers can be done using:
.uh "Title”

which will do a section heading, but will put no number on the section.

5.3. Parts of the Basic Paper
There are some requests which assist in setting up papers. The .tp request initializes for a title page.

There are no headers or footers on a title page, and unlike other

pages you can space down and leave blank space at the top. For example, a typical title
page might appear as:

Writing Papers with -me 5-33

.Sp 2i

(1C
THE GROWTH OF TOENAILS
IN UPPER PRIMATES
Sp

by
.Sp

Frank N. Furter

Il
.bp

The request .th sets up the environment of the NROFF processor to do a thesis,

using the rules established at Berkeley.

It defines the correct headers and footers (a

page number in the upper right hand corner only), sets the margins correctly, and double spaces.
The .+¢ T request can be used to start chapters.

Each chapter is automatically

numbered from one, and a heading is printed at the top of each chapter with the

chapter number and the chapter name T.

For example, to begin a chapter called “Con-

clusions”, use the request:

.+c¢ "CONCLUSIONS”
which will produce, on a new page, the lines
CHAPTER 5

CONCLUSIONS

with appropriate spacing for a thesis. Also, the header is moved to the foot of the page
on the first page of a chapter. Although the .+c¢ request was not designed to work only
with the .th request, it is tuned for the format acceptable for a PhD thesis at Berkeley.
If the title parameter T is omitted from the .+¢ request, the result is a chapter

with no heading.

This can also be used at the beginning of a paper; for example, .+¢

was used to generate page one of this document.
Although papers traditionally have the abstract, table of contents, and so forth at

the front of the paper, it is more convenient to format and print them last when using
NROFF.

This is so that index entries can be collected and then printed for the table of

contents (or whatever). At the end of the paper, issue the .++ P request, which begins
the preliminary part of the paper.

After issuing this request, the .+c¢ request will begin

a preliminary section of the paper.

Most notably, this prints the page number restarted

from one in lower case Roman numbers.

.+¢ may be used repeatedly to begin different

parts of the front material for example, the abstract, the table of contents, acknowledgments, list of illustrations, etc.

The request .++ B may also be used to begin the

bibliographic section at the end of the paper.
outlined in figure 2.

For example, the paper might appear as

(In this figure, comments begin with the sequence \”.)

5.4. Equations and Tables
Two special UNIX programs exist to format special types of material.
neqn set equations for the phototypesetter and NROFF respectively.
print extremely pretty tables in a variety of formats.

Eqn and

Tbl arranges to

This document will only describe

the embellishments to the standard features; consult the reference manuals for those
processors for a description of their use.

The eqn and neqn programs are described fully in the document Typesetting
Mathematics

—

Users’

Guide

Brian

Kernighan

and

Lorinda

Cherry.

5-34 Writing Papers with -me

.th

\” set for thesis mode

‘

\’ define footer for each page
V' begin title page
\" center a large block

fo "DRAFT”
Ap

(1C

THE GROWTH OF TOENAILS

IN UPPER PRIMATES
.Sp

by
.Sp

Frank Furter

\” end centered part
b/

+c¢ INTRODUCTION
Ax t
Introduction

\" begin chapter named "INTRODUCTION”

\’ make an entry into index ‘t’

V" end of index entry

)
text of chapter one

+c¢ "NEXT CHAPTER”
(x t

\” begin another chapter
\” enter into index ‘t’ again

Next Chapter

)X
text of chapter two

+c¢ CONCLUSIONS
Ax t
Conclusions

)X
text of chapter three

\” begin bibliographic information

4+ B

.+c¢ BIBLIOGRAPHY

\” begin another ‘chapter’

Ax t

Bibliography
)X

text of bibliography

\r begin preliminary material

4+ P

.+c "TABLE OF CONTENTS”
Xpt

.+c PREFACE

\” print index ‘t’ collected above
\” begin another preliminary section

text of preface

Figure 2.

Outline of a Sample Paper

Equations are centered, and are kept on one page.

They are introduced by the .EQ

request and terminated by the .EN request.
The .EQ request may take an equation number as an optional argument, which is
printed vertically centered on the right hand side of the equation.

becomes too long it should be split between two lines. To do this, type:

If the equation

Writing Papers with -me 5-35

EQ (eq 34)
text of equation 34

EN C
EQ
continuation of equation 34
.EN
The C on the .EN request specifies that the equation will be continued.
The tbl program produces tables.

It is fully described (including numerous exam-

ples) in the document Tbl — A Program to Format Tables by M. E. Lesk. Tables begin
with the .T'S request and end with the .TE request.
gle page.

Tables are normally kept on a sin-

If you have a table which is too big to fit on a single page, so that you know it

will extend to several pages, begin the table with the request .TS H and put the
request .TH after the part of the table which you want duplicated at the top of every

page that the table is printed on.

For example, a table definition for a long table might

look like:

TS H
cCsS
nnn.

THE TABLE TITLE
.TH

text of the table
TE

5.5. Two Column Output
You can get two column output automatically by using the request .2¢.

This

causes everything after it to be output in two-column form. The request .be will start a
new column; it differs from .bp in that .bp may leave a totally blank column when it
starts a new page.

To revert to single column output, use .1c.

5.6. Defining Macros
A macro is a collection of requests and text which may be used by stating a simple
request.

Macros begin with the line .de xx (where xx is the name of the macro to be

defined) and end with the line consisting of two dots.

After defining the macro, stating

the line .xx is the same as stating all the other lines.

For example, to define a macro

that spaces 3 lines and then centers the next input line, enter:

.de SS
.Sp 3
.ce

and use it by typing:
SS
Title Line

(beginning of text)
Macro names may be one or two characters.

In order to avoid conflicts with

names in —me, always use upper case letters as names.

TS, TH, TE, EQ, and EN.

The only names to avoid are

5.7. Annotations Inside Keeps
Sometimes you may want to put a footnote or index entry inside a keep.

For

example, if you want to maintain a “list of figures” you will want to do something like:

5-36 Writing Papers with -me

c
text of figure
e
.Cée

Figure 5.

Ax f
Figure 5

)X
)z

which you may hope will give you a figure with a label and an entry in the index f
(presumably a list of figures index).

Unfortunately, the index entry is read and inter-

preted when the keep is read, not when it is printed, so the page number in the index is

likely to be wrong. The solution is to use the magic string \! at the beginning of all the
lines dealing with the index.

In other words, you should use:

c
Text of figure

Je
.ce

Figure 5.

\l.(x f
\!Figure 5
\!)x
)Z

which will defer the processing of the index until the figure is output. This will guarantee that the page number in the index is correct.

The same comments apply to blocks

(with .(b and .)b) as well.
6. TROFF and the Photosetter

With a little care, you can prepare documents that will print nicely on either a regular terminal or when phototypeset using the TROFF formatting program.
6.1. Fonts
A font is a style of type.

There are three fonts that are available simultaneously,

Times Roman, Times Italic, and Times Bold, plus the special math font.
font is Roman.

The normal

Text which would be underlined in NROFF with the .ul request is set in

italics in TROFF.
There are ways of switching between fonts.

Roman, italic, and bold fonts respectively.

The requests .r, .i, and .b switch to

You can set a single word in some font by

typing (for example):
.1 word

which will set word in italics but does not affect the surrounding text.

In NROFF, italic

and bold text is underlined.
Notice that if you are setting more than one word in whatever font, you must sur-

round that word with double quote marks (‘”’) so that it will appear to the NROFF pro-

cessor as a single word. The quote marks will not appear in the formatted text. If you
do want a quote mark to appear, you should quote the entire string (even if a single
word), and use two quote marks where you want one to appear.
want to produce the text:

For example, if you

Writing Papers with -me 5-37

"Master Control”
in italics, you must type:

i ”””Master Control\!”””
The\| produces a very narrow space so that the

(‘1”

does not overlap the quote sign in

TROFF, like this:

"Master Control”

There are also several “pseudo-fonts” available. The input:
(b
.u underlined
.bi ”bold italics”

.bx "words in a box”
)b
generates

underlined
bold italics

[words in a box !
In NROFF these all just underline the text.

Notice that pseudo font requests set only

the single parameter in the pseudo font; ordinary font requests will begin setting all

text in the special font if you do not provide a parameter. No more than one word
should appear with these three font requests in the middle of lines. This is because of
the way TROFF justifies text. For example, if you were to issue the requests:
.bi ”some bold italics”

and

.bx "words in a box”

in the middle of a line TROFF would produce smme bl widloss and \words in 2 box.,
which I think you will agree does not look good.
The second parameter of all font requests is set in the original font. For example,
the font request:

.b bold face

generates “bold” in bold font, but sets “face” in the font of the surrounding text,
resulting in:

boldface.

To set the two words bold and face both in bold face, type:
.b ”bold face”

You can mix fonts in a word by using the special sequence \¢ at the end of a line
to indicate ‘“continue text processing’; this allows input lines to be joined together
without a space inbetween them. For example, the input:

.u under \¢
.1 1talics

generates underitalics, but if we had typed:
.u under
.1 italics

the result would have been under italics as two words.

5-38 Writing Papers with -me

6.2. Point Sizes

The phototypesetter supports different sizes of type, measured in points.

default point size is 10 points for most text, 8 points for footnotes.

The

To change the

pointsize, type:
sz +N

where N is the size wanted in points. The vertical spacing (distance between the bottom of most letters (the baseline) between adjacent lines) is set to be proportional to
the type size.

Warning: changing point sizes on the phototypesetter is a slow mechanical operation.

Size changes should be considered carefully.

6.3. Quotes
It is conventional when using the typesetter to use pairs of grave and acute

accents to generate double quotes, rather than the double quote character (‘”’). This is
because it looks better to use grave and acute accents; for example, compare "quote” to
“quote”.

In order to make quotes compatible between the typesetter and terminals, you

may use the sequences \*(lg and \*(rq to stand for the left and right quote respectively. These both appear as ” on most terminals, but are typeset as “ and ” respec-

tively. For example, use:

\*(1gSome things aren’t true
even if they did happen.\*(rq
to generate the result:

“Some things aren’t true even if they did happen.”
As a shorthand, the special font request:
.q "quoted text”

will generate “quoted text”.

Notice that you must surround the material to be quoted

with double quote marks if it is more than one word.

Acknowledgments

I would like to thank Bob Epstein, Bill Joy, and Larry Rowe for having the courage to

use the —me macros to produce non-trivial papers during the development stages; Ricki Blau,
Pamela Humphrey, and Jim Joyce for their help with the documentation phase; and the
plethora of people who have contributed ideas and have given support for the project.

-me Reference Manual

5-39

—ME REFERENCE MANUAL
Release 1.1/25

Eric P. Allman
Electronics Research Laboratory

University of California, Berkeley
Berkeley, California 94720

This document describes in extremely terse form the features of the —me macro package

for

version

seven

NROFF/TROFF.

Some

familiarity

assumed

with

those

programs,

specifically, the reader should understand breaks, fonts, pointsizes, the use and definition of

number registers and strings, how to define macros, and scaling factors for ens, points, v’s

(vertical line spaces), etc.

For a more casual introduction to text processing using NROFF, refer to the document
Writing Papers with NROFF using —me.
There are a number of macro parameters that may be adjusted.
font number only.

Fonts may be set to a

In NROFF font 8 is underlined, and is set in bold font in

font 3, bold in TROFF, is not underlined in NROFF).

surrounding text is used instead.
are simulated by the macros.

TROFF (although

Font 0 is no font change; the font of the

Notice that fonts 0 and 8 are “pseudo-fonts”; that is, they

This means that although it is legal to set a font register to zero

or eight, it is not legal to use the escape character form, such as:

\f8
All distances are in basic units, so it is nearly always necessary to use a scaling factor.
For example, the request to set the paragraph indent to eight one-en spaces is:
.nr pi 8n

and not
.nr pi 8

which would set the paragraph indent to eight basic units, or about 0.02 inch.

Default param-

eter values are given in brackets in the remainder of this document.
Registers and strings of the form $x may be used in expressions but should not be
changed.

Macros of the form $x perform some function (as described) and may be redefined

to change this function.

This may be a sensitive operation; look at the body of the original

macro before changing it.
All names in —me follow a rigid naming convention.

The user may define number regis-

ters, strings, and macros, provided that s/he uses single character upper case names or double
character names consisting of letters and digits, with at least one upper case letter.
should special characters be used in user-defined names.

In no case
|

On daisy wheel type printers in twelve pitch, the —rx1 flag can be stated to make lines
default to one eighth inch (the normal spacing for a newline in twelve-pitch). This is normally
too small for easy readability, so the default is to space one sixth inch.

TNROFF and TROFF are Trademarks of Bell Laboratories.

5-40 -me Reference Manual

1. Paragraphing

These macros are used to begin paragraphs.

The standard paragraph macro is .pp; the

others are all variants to be used for special purposes.
The first call to one of the paragraphing macros defined in this section or the .sh macro

(defined in the next session) initializes the macro processor.

After initialization it is not pos-

sible to use any of the following requests: .s¢, .lo, .th, or .ac.

Also, the effects of changing

parameters which will have a global effect on the format of the page (notably page length and
header and footer margins) are not well defined and should be avoided.

Begin left-justified paragraph.

Centering and underlining are turned
off if they were on, the font is set to \n(pf [1] the type size is set to
\n(pp [10p], and a \n(ps space is inserted before the paragraph [0.35v
in TROFF, 1v or 0.5v in NROFF depending on device resolution].

The

indent is reset to \n($i [0] plus \n(po [0] unless the paragraph is
inside a display.

(see .ba).

At least the first two lines of the para-

graph are kept together on a page.

pPp

Like .lp, except that it puts \n(pi [6n] units of indent.

This is the

standard paragraph macro.

ip T I

Indented paragraph with hanging tag. The body of the following para-

graph is indented I spaces (or \n(ii [5n] spaces if I is not specified)
more than a non-indented paragraph (such as with .pp) is.
T is exdented (opposite of indented).

The title

The result is a paragraph with

an even left edge and T printed in the margin. Any spaces in T must
be unpaddable.
new line.

If T will not fit in the space provided, .ip will start a
|

A variant of .ip which numbers paragraphs.

Numbering is reset after

a .Ip, .pp, or .sh. The current paragraph number is in \n($p.
2.

Section Headings

Numbered sections are similiar to paragraphs except that a section number is automatically generated for each one.

The section numbers are of the form 1.2.3.

The depth of the

section is the count of numbers (separated by decimal points) in the section number.
Unnumbered section headings are similar, except that no number is attached to the
heading.

Ssh+NTabcdef

Beginnumbered section of depth N. If N is missing the current depth

(maintained in the number register \n($0) is used. The values of the
individual parts of the section number are maintained in \n($1
through \n($6. There is a \n(ss [1v] space before the section.
printed as a section title in font \n(sf [8] and size \n(sp [10p].

T is
The

“name” of the section may be accessed via \¥*($n. If \n(si is non-zero,
the base indent is set to \n(si times the section depth, and the section
title is exdented. (See .ba.) Also, an additional indent of \n(so [0] is
added to the section title (but not to the body of the section).

The

font is then set to the paragraph font, so that more information may

occur on the line with the section number and title.

.sh insures that

there is enough room to print the section head plus the beginning of a

paragraph (about 3 lines total).

If a through f are specified, the sec-

tion number is set to that number rather than incremented automati-

cally. If any of a through f are a hyphen that number is not reset. If
T is a single underscore (* ”’) then the section depth and numbering is
reset, but the base indent is not reset and nothing is printed out. This

-me Reference Manual 5-41

is useful to automatically coordinate section numbers with chapter

numbers.
Ssx +N

Go to section depth N [—1], but do not print the number and title,
and do not increment the section number at level N.

This has the

effect of starting a new paragraph at level .
auh T

Unnumbered section heading.

The title T is printed with the same

rules for spacing, font, etc., as for .sh.

SpTBN

Print section heading.

May be redefined to get fancier headings.

T is

the title passed on the .sh or .uh line; B is the section number for this

section, and N is the depth of this section.

These parameters are not

always present; in particular, .sh passes all three, .uh passes only the
first, and .sx passes three, but the first two are null strings.

Care

should be taken if this macro is redefined; it is quite complex and sub-

tle.
S0 TBN

‘

This macro is called automatically after every call to .$p.

It is nor-

mally undefined, but may be used to automatically put every section
title into the table of contents or for some similiar function.

7T is the

section title for the section title which was just printed, B is the section number, and N is the section depth.

$1 - .66

Traps called just before printing that depth section.

May be defined

to (for example) give variable spacing before sections.

These macros

are called from .$p, so if you redefine that macro you may lose this
feature.

3. Headers and Footers
Headers and footers are put at the top and bottom of every page automatically.

are set in font \n(tf [3] and size \n(tp [10p].
page.

They

Each of the definitions apply as of the next

Three-part titles must be quoted if there are two blanks adjacent anywhere in the title

or more than eight blanks total.

The spacing of headers and footers are controlled by three number registers. \n(hm [4v]
is the distance from the top of the page to the top of the header, \n(fm [3v] is the distance
from the bottom of the page to the bottom of the footer, \n(tm [7v] is the distance from the
top of the page to the top of the text, and \n(bm [6v] is the distance from the bottom of the
page to the bottom of the text (nominal).

The macros .m1, .m2, .m3, and .m4 are also sup-

plied for compatibility with ROFF documents.

Je U'm’r’

Define three-part header, to be printed on the top of every page.

o U'm’r’

Define footer, to be printed at the bottom of every page.

eh I'm’r

Define header, to be printed at the top of every even-numbered page.

.oh I'm’r’

Define header, to be printed at the top of every odd-numbered page.

ef'l'm’r’

Define footer, to be printed at the bottom of every even-numbered
page.

of I'm’r’

Define footer, to be printed at the bottom of every odd-numbered
page.

Suppress headers and footers on the next page.

ml +N

Set the space between the top of the page and the header [4v].

m2 +N

Set the space between the header and the first line of text [2v].

5-42 -me Reference Manual

m3 +N

Set the space between the bottom of the text and the footer [2v].

.m4 +N

Set the space between the footer and the bottom of the page [4v].

.ep

End this page, but do not begin the next page. Useful for forcing out
footnotes, but other than that hardly every used. Must be followed by
a .bp or the end of input.

Called at every page to print the header.

May be redefined to provide

fancy (e.g., multi-line) headers, but doing so loses the function of the

.he, .fo, .eh, .oh, .ef, and .of requests, as well as the chapter-style
title feature of .+c.

Print footer; same comments apply as in .$h.

A normally undefined macro which is called at the top of each page
(after outputing the header, initial saved floating keeps, etc.); in other
words, this macro is called immediately before printing text on a page.
It can be used for column headings and the like.

4. Displays
All displays except centered blocks and block quotes are preceeded and followed by an

extra \n(bs [same as \n(ps] space. Quote spacing is stored in a separate register; centered
blocks have no default initial or trailing space.

The vertical spacing of all displays except

quotes and centered blocks is stored in register \n($R instead of \n($r.
dmf

Begin list.

Lists are single spaced, unfilled text.

If f is F, the list will

be filled. If m [I] is I the list is indented by \n(bi [4n]; if M the list is
indented to the left margin; if L. the list is left justified with respect to

the text (different from M only if the base indent (stored in \n($i and
set with .ba) is not zero); and if C the list is centered on a line-by-line

basis.

The list is set in font \n(df [0].

Must be matched by a .)l.

This macro is almost like .(b except that no attempt is made to keep

the display on one page.

End list.

Begin major quote.

These are single spaced, filled, moved in from the

text on both sides by \n(qi [4n], preceeded and followed by \n(gs
[same as \n(bs] space, and are set in point size \n(qp [one point
smaller than surrounding text].

End major quote.

b mf

Begin block. Blocks are a form of keep, where the text of a keep is
kept together on one page if possible (keeps are useful for tables and
figures which should not be broken over a page). If the block will not
fit on the current page a new page is begun, unless that would leave

more than \n(bt [0] white space at the bottom of the text. If\n(bt is
zero, the threshold feature is turned off.

is F, when they are filled.

Blocks are not filled unless f

The block will be left-justified if m is L,

indented by \n(bi [4n] if m is I or absent, centered (line-for-line) if m
is C, and left justified to the margin (not to the base indent) if m is

M. The block is set in font \n(df [0].
)b

End block.

(zmf

Begin floating keep. Like .(b except that the keep is floated to the
bottom of the page or the top of the next page. Therefore, its position
relative to the text changes. The floating keep is preceeded and followed by \n(zs [1v] space. Also, it defaults to mode M.

-me Reference Manual 5-43

End floating keep.

Begin centered block.

The next keep is centered as a block, rather

than on a line-by-line basis as with .(b C.

This call may be nested

inside keeps.
Je

End centered block.

5. Annotations
Ad

Begin delayed text.

Everything in the next keep is saved for output

later with .pd, in a manner similar to footnotes.

Jd n

End delayed text. The delayed text number register \n($d and the
associated string \*# are incremented if \*# has been referenced.

.pd

Print delayed text.

Everything diverted via .(d is printed and trun-

cated. This might be used at the end of each chapter.

Begin footnote.

The text of the footnote is floated to the bottom of

the page and set in font \n(ff [1] and size \n(fp [8p].

Each entry is
preceeded by \n(fs [0.2v] space, is indented \n(fi [3n] on the first line,

and is indented \n(fu [0] from the right margin.
underneath two columned output.

Footnotes line up

If the text of the footnote will not

all fit on one page it will be carried over to the next page.

Jf n

End footnote. The number register \n($f and the associated string \**
are incremented if they have been referenced.
The macro to output the footnote seperator.

This macro may be

redefined

types

give

other

size

lines

other

separators.

Currently it draws a 1.51 line.

AX x

Begin index entry.

Index entries are saved in the index x [x] until

called up with .xp. Each entry is preceeded by a \n(xs [0.2v] space.
Each entry is “undented” by \n(xu [0.5i]; this register tells how far
the page number extends into the right margin.

P A
JX

End index entry.

The index entry is finished with a row of dots with

A [null] right justified on the last line (such as for an author’s name),

followed by P [\n%].

If A is specified, P must be specified; \n% can

be used to print the current page number.

If P is an underscore, no

page number and no row of dots are printed.
XP X

Print index x [X].

The index is formated in the font, size, and so forth

in effect at the time it is printed, rather than at the time it is col-

lected.
6. Columned Output

2¢c +S N

Enter two-column mode.

The column separation is set to +S [4n, 0.51

in ACM mode] (saved in \n($s).

The column width, calculated to fill

the single column line length with both columns, is stored in \n($l.
The current column is in \n($c. You can test register \n($m [1] to
see if you are in single column or double column mode.

Actually, the

request enters N [2] columned output.
dc¢

Revert to single-column mode.

.bc

Begin column.

This is like .bp except that it begins a new column on

a new page only if necessary, rather than forcing a whole new page if
there is another column left on the current page.

5-44 -me Reference Manual

7. Fonts and Sizes
.Sz +P

The pointsize is set to P [10p], and the line spacing is set proportion-

ally. The ratio of line spacing to pointsize is stored in \n($r. The
ratio used internally by displays and annotations is stored in \n($R
(although this is not used by .sz).
T WX

Set W in roman font, appending X in the previous font.

To append

different font requests, use X = \e. If no parameters, change to roman
font.

i WX

Set W in italics, appending X in the previous font.

If no parameters,

change to italic font. Underlines in NROFF.

b WX

Set W in bold font and append X in the previous font.
ters, switch to bold font.

b W X

If no parame-

In NROFF, underlines.

Set W in bold font and append X in the previous font.
ters, switch to bold font.

If no parame-

.rb differs from .b in that .rb does not

underline in NROFF.
awx

Underline

W and append X. This is a true underlining, as opposed to

the .ul request, which changes to “underline font” (usually italics in
TROFF).

It won’t work right if W is spread or broken (including

hyphenated).

q WX

In other words, it is safe in nofill mode only.

Quote W and append X.

In NROFF this just surrounds W with double

quote marks (‘”’), but in TROFF uses directed quotes.

bi WX

Set W in bold italics and append X.
overstrikes once.

Actually, sets

W in italic and

Underlines in NROFF.

It won’t work right if W is

spread or broken (including hyphenated).

In other words, it is safe in

nofill mode only.
Jox WX

Underlines in NROFF.

It won’t

work right if W is spread or broken (including hyphenated).

Sets W in a box, with X appended.

In other

words, it is safe in nofill mode only.
8. Roff Support

Ax +N

Indent, no break.

bl N

Leave N contiguous white space, on the next page if not enough room

on this page.

Equivalent to in N.

Equivalent to a .sp N inside a block.

.pa +N

Equivalent to .bp.

8 o)

Set page number in roman numerals. Equivalent to .af % 1.

.ar

Set page number in arabic.

Number lines in margin from one on each page.

n2 N

Number lines from N, stop if N = 0.

Leave the next output page blank, except for headers and footers.

Equivalent to .af % 1.

This is used to leave space for a full-page diagram which is produced

externally and pasted in later.

To get a partial-page paste-in display,

say .sv N, where N is the amount of space to leave; this space will be

output immediately if there is room, and will otherwise be output at
the top of the next page.

However, be warned: if N is greater than the

amount of available space on an empty page, no space will ever be output.

-me Reference Manual 5-45

9. Preprocessor Support

EQmT

The equation is centered if m is C or omitted,

Begin equation.

indented \n(bi [4n] if m is I, and left justified if m is L. T is a title
printed on the right margin next to the equation. See Typesetting
Mathematics — User’s Guide by Brian W. Kernighan and Lorinda L.
Cherry.

EN ¢

End equation. If ¢ is C the equation must be continued by immedi-

ately following with another .EQ, the text of which can be centered
along with this one. Otherwise, the equation is printed, always on one
page, with \n(es [0.5v in TROFF, 1v in NROFF] space above and below
it.

TS h

Table start. Tables are single spaced and kept on one page if possible.

JTH

With .TS H, ends the header portion of the table.

Table end. Note that this table does not float, in fact, it i1s not even

If you have a large table which will not fit on one page, use h = H and
follow the header part (to be printed on every page of the table) with
a .TH. See Tbl — A Program to Format Tables by M. E. Lesk.

guaranteed to stay on one page if you use requests such as .sp intermixed with the text of the table. If you want it to float (or if you use

requests inside the table), surround the entire table (including the .TS
and .TE requests) with the requests .(z and .)z.

10. Miscellaneous

Reset tabs. Set to every 0.5i in TROFF and every 0.81 in NROFF.

.ba +N

Set the base indent to +N [0] (saved in \n($i). All paragraphs, sec-

tions, and displays come out indented by this amount.
footnotes are unaffected.

Titles and

The .sh request performs a .ba request if

\n(si [0] is not zero, and sets the base indent to \n(si®\n($0.

x1 +N

Set the line length to N [6.0i]. This differs from .1l because it only
affects the current environment.

1 +N

Set line length in all environments to N [6.0i]. This should not be

.hl

output. The current line length is stored in \n($L
Draws a horizontal line the length of the page. This is useful inside

This macro loads another set of macros (in /usr/lib/me/local.me)

used after output has begun, and particularly not in two-columned

floating keeps to differentiate between the text and the figure.

which is intended to be a set of locally defined macros. These macros
should all be of the form .*X, where X is any letter (upper or lower
case) or digit.

11.

Standard Papers

Begin title page.

Spacing at the top of the page can occur, and

headers and footers are supressed. Also, the page number is not incremented for this page.

.th

Set thesis mode. This defines the modes acceptable for a doctoral

dissertation at Berkeley. It double spaces, defines the header to be a
single page number, and changes the margins to be 1.5 inch on the left
and one inch on the top. .++ and .+c¢ should be used with it. This
macro must be stated before initialization, that is, before the first call

5-46 -me Reference Manual

of a paragraphing macro or .sh.
A+ mH

This request defines the section of the paper which we are entering.
The section type is defined by m.

C means that we are entering the

chapter portion of the paper, A means that we are entering the appendix portion of the paper,

P means that the material following should

be the preliminary portion (abstract, table of contents, etc.) portion of

the paper, AB means that we are entering the abstract (numbered
independently from 1 in Arabic numerals), and B means that we are

entering the bibliographic portion at the end of the paper.

Also, the

variants RC and RA are allowed, which specify renumbering of pages
from one at the beginning of each chapter or appendix, respectively.
The H parameter defines the new header.

the entire header must be quoted.

If there are any spaces in it,

If you want the header to have the

chapter number in it, Use the string \\\\n(ch. For example, to number
appendixes A.1 etc, type .++ RA “\\\\n(ch.%".
Each section
(chapter, appendix, etc.) should be preceeded by the .+e¢ request.

should be mentioned that it is easier when using TROFF to put the
front material at the end of the paper, so that the table of contents

can be collected and output; this material can then be physically
moved to the beginning of the paper.

Ac T

Begin chapter with title T.

\n(ch.

The chapter number is maintained in

This register is incremented every time .+c is called with a

parameter.

The title and chapter number are printed by .$¢.

header is moved to the footer on the first page of each chapter.

The

If T is

omitted, .$¢ is not called; this is useful for doing your own “title page”
at the beginning of papers without a title page proper.

.$c calls .$C

as a hook so that chapter titles can be inserted into a table of contents
automatically. The footnote numbering is reset to one.

$e T

Print chapter

number

(from

\n(ch)

and

This

macro

can

redefined to your liking.

It is defined by default to be acceptable for a

PhD thesis at Berkeley.

This macro calls $C, which can be defined to

make index entries, or whatever.

SCKNT

This macro is called by .$c.

It is normally undefined, but can be used

to automatically insert index entries, or whatever.

K is a keyword,

either “Chapter” or “Appendix” (depending on the .++ mode); N is
the chapter or appendix number, and T is the chapter or appendix

title.
ac AN

This macro

(short for .acm)

sets up the NROFF environment for

photo-ready papers as used by the ACM.
and has no headers or footers.

This format is 25% larger,

The author’s name A is printed at the

bottom of the page (but off the part which will be printed in the
conference proceedings), together with the current page number and
the total number of pages N.

Additionally, this macro loads the file

/usr/lib/me/acm.me, which may later be augmented with other macros useful for printing papers for ACM conferences.

It should be

noted that this macro will not work correctly in TROFF, since it sets

the page length wider than the physical width of the phototypesetter
roll.

-me Reference Manual 5-47

12. Predefined Strings

Footnote number, actually \*[\n($f\*].

This macro is incremented

after each call to .)f.

Delayed text number. Actually [\n($d].
Superscript.

This string gives upward movement and a change to a

smaller point size if possible, otherwise it gives the left bracket character (‘[’). Extra space is left above the line to allow room for the super-

script.

Unsuperscript.

Inverse to \¥[.

For example, to produce a superscript

you might type x\¥[2\*], which will produce x.
Subscript.

Defaults to ‘<’ if half-carriage motion not possible.

Extra

space is left below the line to allow for the subscript.

\¥>

Inverse to \*<.

\(dw

The day of the week, as a word.

V¥(mo

The month, as a word.

\*(td

Today’s date, directly printable. The date is of the form April 8, 1984.

Other forms of the date can be used by using \n(dy (the day of the

month; for example, 8), \*(mo (as noted above) or \n(mo (the same,
but as an ordinal number; for example, April is 4), and \n(yr (the last
two digits of the current year).

\*(1q

Left quote marks.

V¥ (rq

Right quote.

\*.....

% em dash in TROFF; two hyphens in NROFF.

13.

Double quote in NROFF.

Special Characters and Marks

There are a number of special characters and diacritical marks (such as accents) avail-

able through —me.

To reference these characters, you must call the macro .sc to define the

characters before using them.
Define special characters and diacritical marks, as described in the

remainder of this section.

This macro must be stated before initializa-

tion.

The special characters available are listed below.

Tilde

Caret

Cedilla
Czech

Circle
There exists

For all

Example

a\*’
e\*"

\*\*»
\*,
\*y

n\*"
e\*”
c\¥,
eVtv

\*:

\*(ge
\*(qa

s O

(Grave accent
Umlat

Usage

\**
\*

u\*:

A\*o

l>0m<‘0 M®> =

Acute accent

Name

5-48 -me Reference Manual

Acknowledgments
I would like to thank Bob Epstein, Bill Joy, and Larry Rowe for having the courage to

Nroff/Troff Users Manual 5-49

NROFF/TROFF User’s Manual
Joseph F. Ossanna

Bell Laboratories

Murray Hill, New Jersey 07974

Introduction

NROFF and TROFF are text processors under the PDP-11 UNIX Time-Sharing System! that format text

for typewriter-like terminals and for a Graphic Systems phototypesetter, respectively. They accept lines
of text interspersed with lines of format control information and format the text into a printable,
paginated document having a user-designed style. NROFF and TROFF offer unusual freedom in document styling, including: arbitrary style headers and footers; arbitrary style footnotes; multiple automatic
sequence numbering for paragraphs, sections, etc; multiple column output; dynamic font and point-size
control; arbitrary horizontal and vertical local motions at any point; and a family of automatic overstriking, bracket construction, and line drawing functions.

NROFF -and TROFF are highly compatible with each other and it is almost always possible to prepare
input acceptable to both. Conditional input is provided that enables the user to embed input expressly

destined for either program. NROFF can prepare output directly for a variety of terminal types and is

capable of utilizing the full resolution of each terminal.
Usage

The general form of invoking NROFF (or TROFF) at UNIX command level is

nroff options files

(or troff options files)

where oprions represents any of a number of option arguments and files represents the list of files containing the document to be formatted. An argument consisting of a single minus (=) is taken to be a
file name corresponding to the standard input. If no file names are given input is taken from the standard input. The options, which may appear in any order so long as they appear before the files, are:
Option

= g list

Effect

Print only pages whose page numbers appear in lisz, which consists of commaseparated numbers and number ranges. A number range has the form N—M and
means pages N through M; a initial —/N means from the beginning to page N, and
a final

—=nN

—g N

N— means from N to the end.

‘Number first generated page N.

Stop every N pages. NROFF will halt prior to every N pages (default N=1) to

allow paper loading or changing, and will resume upon receipt of a newline.
TROFF will stop the phototypesetter every N pages, produce a trailer to allow
changing cassettes, and will resume after the phototypesetter START button is
pressed.

—~mname Prepends the macro file /usr/lib/tmac.name to the input files.
—ralN

Read standard input after the input files are exhausted.

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

5-50

Nroff/Troff Users Manual

NROFF Only
—Tname

Specifies the name of the output terminal type.

Currently defined names are 37

for the (defauit) Model 37 Teletype?®, tn300 for the GE TermiNet 300 (or any terminal without half-line capabilities), 300S for the DASI-300S, 300 for the DASI-

300, and 450 for the DASI-450 (Diablo Hyterm).
-

Produce equally-spaced words in adjusted lines, using full terminal resolution.

TROFF Only
-t

Direct output to the standard output instead of the phototypesetter.

el {

Refrain from feeding out paper and stopping phototypesetter at the end of the run.

. |

Wait until phototypesetter is available, if currently busy.

-=b

TROFF will report whether the phototypesetter is busy or available.
cessing is done.

No text pro-

Send a printable (ASCII) approximation of the results to the standard output.

-pN

Print all characters in point size N while retaining all prescribed spacings and
motions, to reduce phototypesetter eiasped time.

-g

Prepare output for the Murray Hill Computation Center phototypesetter and direct
it to the standard output.

Each option is invoked as a separate argument; for example,

nroff —04,8—10 =T300S —mabc filel file2
requests formatting of pages 4, 8, 9, and 10 of a document contained in the files named file] and file2,
specifies the output terminal as a DASI-300S, and invokes the macro package abc.
Various pre- and post-processors are available for use with NROFF and TROFF.

These include the

equation preprocessors NEQN and EQN? (for NROFF and TROFF respectively), and the tableconstruction preprocesser TBL3. A reverse-line postprocessor COL4 is available for multiple-column

NROFF output on terminals without reverse-line ability; COL expects the Model 37 Teletype escape

sequences that NROFF produces by default. TK* is a 37 Teletype simulator postprocessor for printing
NROFF output on a Tektronix 4014, TCAT? is phototypesetter-simulator postprocessor for TROFF that
produces an approximation of phototypesetter output on . Tektronix 4014.

For example, in

thl files | eqn | troff =t options | tcat

the first | indicates the piping of TBL’s output to EQN’s input; the second the piping of EQN’s output to

TROFF’s input; and the third indicates the piping of TROFF's output to TCAT.

send TROFF (=—g) output to the Murray Hill Computation Center.

GCAT* can be used to

The remainder of this manual consists of: a Summary and Index; a Reference Manual keyed to the
index; and a set of Tutorial Examples. Another tutorial is [5].

Joseph F. Ossanna
References

[1]

K. Thompson, D. M. Ritchie, UNIX Programmer’s Manual, Sixth Edition (May 1975).

(2]

B. W. Kernighan, L. L. Cherry, Typesetting Mathematics — User's Guide (Second Edition), Bell Laboratories
internal memorandum.

[3]

M. E. Lesk, TB{ — A4 Program to Formar Tables, Bell Laboratories internal memorandum.

[4]

Internal on-line documentation, on UNIX.

(S]

B. W. Kernighan, 4 TROFF Tutorial, Beil Laboratories internal memorandum.

Nroff/Troff Users Manual 5-51

SUMMARY AND INDEX

Request
Form

Initial
Value®

If No
Argument

Notes# Explanation

1. General Explanation

.ps =N
ss N
cs FNM
bd FN
bdS FN
gt F
fp N F

10 point
12/36em
off
off
off
Roman
R,I,B,S

previous
ignored

Mmoo temim

2. Font and Character Size Control

Point size; also \s+ V.t
Space-character size set to N/36em.t

Constant character space (width) mode (font F).t
Embolden font F by N—1 units.t
Embolden Special Font when current font is F.f

\f.N.
Change to font F = x, xx, or 1-4. Also \fx, \f(xx,
Font named F mounted on physical position 1 < N<4.

3. Page Control
pl =N
bp =N
pn =N

1lin
Nem|

11in

Nem]

ignored

Page length.

Bty

Eject current page; next page number N.

Next page number N.
Page offset.

.po =N

0; 26/27 in

.ne N

D,v

mnk R

none

gt =N

none

N1V
internal
internal

D
D,y

Need N vertical space ( V' = vertical spacing).

Mark current vertical place in register R.
Return (upward only) to marked vertical place.

4. Text Filling, Adjusting, and Centering
br

Break.

i
.nf

fill
fill

B.E
B.,E

No filling or adjusting of output lines.

.ad ¢
.na

adj,both
adjust

adjust

Adjust output lines with mode c.
No output line adjusting.

ce N

off

Na=|

E
B,E

Fill output lines.

Center following N input text lines.

5. Vertical Spacing
Vertical base line spacing (V).
Output N—1 Vs after each text output line.
Space vertical distance N in either direction.

v§ N

1/6in;12pts previous

ds N
Sp N

Na=]
-

Sv N

.08

Output saved vertical distance.

space

Turn no-space mode on.

Restore spacing; turn no-space mode off.

Ne=lV
Ne=] V

Save vertical distance N.

Line Length and Indenting

Al =N
dn =N
obd

e AS
o dV

6.5in
N
()
-

E.m

Line length.

B,E.m

Indent.

ignored

B.Em

T o

i€mpora U 1

7. Macros, Strings, Diversion, and Position Traps
de xyy

Jyy=

Define or redefine macro xx; end at call of yy.

Am XX yy

yy==,,

Append to a macro.

.ds xx string -

ignored

a8 Xx string -

ignored

Define a string xx containing string.
Append string to string xx.

*Values separated by ";" are for NROFF and TROFF respectively.

#Notes are explained at the end of this Summary and Index
tNo effect in NROFF.

tThe use of ° ° " as controi character (instead of ".") suppresses the break function.

5-52 Nroff/Troff Users Manual

Request

Initial

Form

Value

If No
Argument

JIm XX

ignored

Remove request, macro, or string.

I XX Py

ignored

Rename request, macro, or string xx to yy.

di xx

end

Divert output to macro xx.

.da xx

end

Divert and append to xx.

wh Vxx

Set location trap; negative is w.r.t. page bottom.

Notes

Explanation

.ch x N

Change trap location.

dt N xx
dt NV xx

off
off

D.v
E

Set a diversion trap.

.em xx

none

End macro is xx.

Set an input-line count trap.

Number Registers

nr R=NM

Define and set number register R; auto-increment by M.

.af R ¢

arabic

I R

Assign format to register R (c=1,1i, I, a, A).
Remove register R.

Tabs, Leaders, and Fields

ta Nt ...
(s

0.8: 0.5in
none

none

E,m

Tab settings; lef? type, unless t=R (right), C(centered).

none

Tab repetition character.

Jdec

none

Leader repetition character.

feabd

off

Set field delimiter a and pad character b.

10.

Input and Output Conventions and Character Translations

&C C
.80

Set escape character.

Turn off escape character mechanism.

Jdg N

-;on

Ligature mode on if N>0.

aul N
cu N

off
off

Ne=
Ne=

E
E

Continuous underline in NROFF; like ul in TROFF.

uf F

Italic

[talic

Underline font set to F (to be switched to by ul).

.ce ¢

Set control character to c.

Yy &-Y- 4

Underline (italicize in TROFF) N input lines.

.c2 ¢

’

Set nobreak control character to ¢

tr abed

none

Translate a to b, etc. on output.

11.

Local Horizontal and Vertical Motions, and the Width Function

12.

Overstrike, Bracket, Line-drawing, and Zero-width Functions

13.

Hyphenation.

.nh

hyphenate

hy N

hyphenate

Hyphenate; N = mode.

e ¢

Hyphenation indicator character c.

ignored

Exception words.

Three part title.
Page number character.

w wordl ...

14.

tl “left’ center’ right’

Jt =N

6.5in

off
previous

E.m

Length of title.

Output Line Numbering.

am =NMS ]
-

.an N

16.

Three Part Titles.

.pc ¢
15.

No hyphenation.

off
N |

E
E

Number mode on or off, set parameters.
Do not number next N lines.

Conditional Acceptance of Input

if ¢ anything

If condition ¢ true, accept anything as input,

for multi-line use \{anvthing\).

Nroff/Troff Users Manual 5-53

If No

Initial
Value

Request

Form

Notes

Explanation

Argument

Af 'c anything

Af N anything

If condition c false, accept anything.

Af ' N anything
Af “stringl’string2’ anything
Af ! stringl’ string2’ anything
de ¢ anything
-

.el anything

If expression N > 0, accept anything.
If expression N < 0, accept anything.
If stringl identical to string2, accept anything.
If stringl not identical to string2, accept anything.
If portion of if-else; all above forms (like if).
Else portion of if-else.

Environment switched (push down).

17. Environment Switching.
.ev N

N=()

18. Insertions from the Standard Input
.rd prompt

prompt =BEL -

Read insertion.

Exit from NROFF/TROFF.

19. Input/Output File Switching
.S0 filename

.nx filename

end-of-file

.pl program

Switch source file (push down).
Next file.
Pipe output to program (NROFF only).

20. Miscellaneous

mechN

off

E.m

Set margin character ¢ and separation .

Lm string

newline

yy=.,

.pm ¢

all

Print string on terminal (UNIX standard message output).
Ignore till call of yy.
Print macro names and sizes;

if ¢ present, print only total of sizes.
Flush output buffer.

Ag yy

21. Output and Error Messages

NotesB

Request normally causes a break.

Mode or relevant parameters associated with current diversion level.

E
O

Relevant parameters are a part of the current environment.
Must stay in effect until logical output.
P
Mode must be still or again in effect at the time of physical output.
v,p.m,u Default scale indicator; if not specified, scale indicators are ignored.
Alphabetical Request and Section Number Cross Reference

cc 10

nh 13

nml$

nn 1§

pm 20

mc 20

8§

$§

tm 20

eo 10

he 13

nx 19

ev 17

hw 13

ex 18

hy 13

5-54 Nroff/Troff Users Manual

Escape Sequences for Characters, Indicators, and Functions

Section

Escape

Reference

Sequence

Meaning

\ (to prevent or delay the interpretation of \)

" (acute accent); equivalent to \(aa
" (grave accent); equivalent to \(ga

10.1
SR e SN € SR
[

[

— Minus sign in the current font

Period (dot) (see de)

el
el
[
L3
[
9

\ -

\(space)
\0

10.6

10.7
7.3

Printable version of the current escape character.

\&
\!
\n

\SN

Unpaddable space-size space character

Digit width space

1/6 em narrow space character (zero width in NROFF)
1/12 em half-narrow space character (zero width in NROFF)
Non-printing, zero width character
Transparent line indicator
Beginning of comment
Interpolate argument 1

£.¥<9

Default optional hyphenation character

2.1

\(xx
\ex, \s(xx

Character named xx

7.1

9.1
12.3
4.2

11.1
2.2

\a
\b“abe...”
\¢

[nterpolate string x or xx
Non-interpreted leader character

Bracket building function
Interrupt text processing

Forward (down) 1/2em vertical motion (1/2 line in NROFF)
\d
\f NV Change to font named x or xx, or position N
\f
\xQe

12.1

\h’' V"’
\kx
\l“Ne’
\L'NC'
\nx,\n (e
\o'abc...”

Overstrike characters a, b, ¢, ...

4.1

Break and spread output line

11.1
11.3

12.4
12.4

11.1

\r
\sN\s=N
\t
\u

11.1

\'v'N’

11.2

\w string’

5.2

\ X'V’
\z¢

11.1

2.3
9.1

12.2

16
16
10.7

\{
\})

\(newline)
\X

Local horizontal motion; move right NV (negative lef)
Mark horizontal input place in register x

Horizontal line drawing function (optionally with ¢)
Vertical line drawing function (optionally with ¢)

Interpolate number register x or xx

Reverse | em vertical motion (reverse line in NROFF)
Point-size change function
Non-interpreted horizontal tab

Reverse (up) 1/2em vertical motion (1/2 line in NROFF)
Local vertical motion; move down N (negative up)
Interpolate width of string

Extra line-space function (negative before, positive after)
Print ¢ with zero width (without spacing)
Begin conditional input
End conditional input
Concealed (ignored) newline

X, any character not listed above

The escape sequences \\, \.. \", \S$, \«, \a, \n. \t. and \(newline) are interpreted in copy mode (§7.2).

Nroff/Troff Users Manual 5-55

Predefined General Number Registers
Register
Name

Description

Current page number.

11.2
7.4
7.4

Section

Reference

dl
dn

Height (vertical size) of last completed diversion.
Current day of the week (1-7).

11.3

Character type (set by width function).

Width (maximum) of last completed diversion.

dy
hp

Current day of the month (1-31).

Current horizontal place on input line.

Output line number.

Current month (1-12).

4.1

Vertical position of last printed text base-line.

11.2

Depth of string below base line (generated by widrh function).
Height of string above base line (generated by width function).

Last two digits of current year.

Predefined Read-Only Number Registers

7.3
11.1

11.1

5.2

]

S
&

[9]

7.4

N<hgeiErmbbbobbhannmadins
o

Section
Reference

Description

Number of arguments available at the current macro level.
Set to 1 in TROFF, if —a option used; always 1 in NROFF.
Available horizontal resolution in basic units.
Set to 1 in NROFF, if =T option used; always 0 in TROFF.
Available vertical resolution in basic units.

Post-line extra line-space most recently utilized using \x’ N
Number of lines read from current input file.
Current vertical place in current diversion; equal to nl, if no diversion.
Current font as physical quadrant (1-4).
Text base-line high-water mark on current page or diversion.
Current indent.
Current line length.

Length of text portion on previous output hne
Current page offset.
Current page length.
Current point size.
Distance to the next trap.

Equal to 1 in fill mode and 0 in nofill mode.
Current vertical line spacing.
Width of previous character.

Reserved version-dependent register.
Reserved version-dependent register.
Name of current diversion.

5-56

Nroff/Troff Users Manual

REFERENCE MANUAL
1.

General Explanation

1.1. Form of input. Input 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 con-

trol character—normaily . (period) or ° (acute accent) —followed by a one or two character name that
specifies a basic request or the substitution of a user-defined macro in place of the control line. The

control character * suppresses the break function—the forced output of a partially filled line —caused by
The control character may be separated from the request/macro name by white space

certain requests.

(spaces and/or tabs) for esthetic reasons. Names must be followed by either space or newline. Control

lines with unrecognized names are ignored.

Various special functions may be introduced anywhere in the input by means of an escape character,

normally \. For exampile, the function \nR causes the interpolation of the contents of the number regis-

ter R in place of the function; here R is either a single character name as in \nx, or left-parenthesisintroduced, two-character name as in \n (e

1.2. Formauter and device resolution. TROFF internally uses 432 units/inch, corresponding to the Graphic
Systems phototypesetter which has a horizontal resolution of 1/432 inch and a vertical resolution of

1/144 inch. NROFF internally uses 240 units/inch, corresponding to the least common multiple of the

horizontal

and

vertical

resolutions

various

typewriter-like

output

devices.

TROFF

rounds

horizontal/vertical numerical parameter input to the actual horizontal/vertical resolution of the Graphic
Systems typesetter. NROFF similarly rounds numerical input to the actual resolution of the output device indicated by the —T option (default Model 37 Teletype).
1.3. Numerical parameter input. Both NROFF and TROFF accept numerical input with the appended scale
indicators shown in the following table, where Sis the current type size in points, Vis the current vertical line spacing in basic units, and Cis a nominal character width in basic units.
Scale

Number of basic units

Indicator

Meaning

TROFF

NROFF

Inch

Centimeter

Pica = 1/6 inch

240/6

Em = § points

En = Em/2

6xS
IxS

C
C, same as Em

432
240
432x50/127 | 240x50/127

Point = 1/72 inch | 6

240/72

u
v

Basic unit

Vertical line space

none

Default, see below

In NROFF, both the em and the en are taken to be equal to the C, which is output-device dependent;
common values are 1/10 and 1/12 inch. Actual character widths in NROFF need not be all the same
and constructed characters such as —> (—) are often extra wide. The default scaling is ems for the

horizontally-oriented requests and functions 1l, in, ti, ta, It, po, me, \h, and \I: ¥s for the verticallyoriented requests and functions pl, wh, ch, dt, sp, sv, ne, rt, \v, \x, and \L; p for the vs request; and
u for the requests nr, if, and ie.

A4/l other requests ignore any scale indicators.

When a number regis-

ter containing an already appropriately scaled number is interpolated to provide numerical input, the

unit scale indicator u may need to be appended to prevent an additional inappropriate default scaling.

Nroff/Troff Users Manual 5-57

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 | may be prepended to a number N to generate the distance to the vertical
or horizontal place N. For vertically-oriented requests and functions, | ¥ becomes the distance in basic
units from the current vertical place on the page or in a diversion (37.4) to the the vertical piace V.

For

all other requests and functions, | N becomes the distance from the current horizontal place on the inpur

line to the horizontal place .

For example,

sp |3.2¢
will space in the required direction to 3.2 centimeters from the top of the page.

1.4. Numerical expressions.

Wherever numerical input is expected an expression involving parentheses,

the arithmetic operators +, —, /, =, % (mod), and the logical operators <, >, <= D> == (or =m=),
& (and), : (or) may be used. 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 respectively.

In the presence of default

scaling, the desired scale indicator must be attached to every number in an expression for which the

desired and default scaling differ.
point size is 10, then

For example, if the number register x contains 2 and the current

J1 (4.2514+\nxP+3)/2u
will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 30 points.
1.5. Notation.

Numerical parameters are indicated in this manual in two ways.

=+ 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 ini-

tial algebraic sign is mor an increment indicator, but merely the sign of N.

Generally, unreasonable

numerical input is either ignored or truncated to a reasonable value.

For example, most requests

expect to set parameters to non-negative values; exceptions are sp, wh, ch, nr, and if.

The requests

ps, ft, po, vs, ls, 11, in, and It restore the previous parameter value in the absence of an argument.

Single character arguments are indicated by single lower case letters and one/two character arguments
Character string arguments are indicated by multi-character

are indicated by a pair of lower case letters.
mnemonics.

Font and Character Size Control

2.1. Character set.

The TROFF character set consists of the Graphics Systems Commercial Il character

set plus a Special Mathematical Font character set—each having 102 characters. These character sets
are shown in the attached Table I. All ASCII characters are included, with some on the Special Font.
With three exceptions, the ASCII characters are input as themseives, and non-ASCII characters are input

in the form \(xxx where xx is a two-character name given in the attached Table II.

The three ASCII

exceptions are mapped as follows:
ASCII Input

Printed by TROFF

Character

Name

Character

Name

acute accent

’

close quote

)
-

grave accent
minus

‘
-

open quote
hyphen

The characters °, *, and = may be input by \’, \', and \~ respectively or by their names (Table II).

The ASCII characters @, #, ", ", °, <, >, \, {, ], 7, °, and _ exist only on the Special Font and are
printed as a l-em space if that Font is not mounted.
NROFF understands the entire TROFF character set, but can in general print only ASCII characters,
additional characters as may be available on the output device, such characters as may be able to be

constructed by overstriking or other combination, and those that can reasonably be mapped into other

printable characters. The exact behavior is determined by a driving table prepared for each device. The

5-58 Nroff/Troff Users Manual

characters °, ', and _ print as themselves.

2.2 Fonts. The default mounted fonts are Times Roman (R), Times Italic (I), Times Boid (B), and
the Special Mathematical Font (S) on physical typesetter positions 1, 2, 3, and 4 respectively. These

fonts are used in this document. The current font, initially Roman, may be changed (among the
mounted fonts) by use of the ft request, or by imbedding at any desired point either \fx, \f(xx, or \fN

where x and xx are the name of a mounted font and N is a numerical font position. It is not necessary

to change to the Special font; characters on that font are automatically handled. A request for a named
but not-mounted font is ignored. TROFF can be informed that any particular font is mounted by use of
the fp request. The list of known fonts is installation dependent. In the subsequent discussion of
font-related requests, F represents either a one/two-character font name or the numerical font position,
1.4. The current font is available (as numerical position) in the read-only number register .f.
NROFF understands font control and normally underlines Italic characters (see §10.5).
2.3. Character size. Character point sizes available on the Graphic Systems typesetter are 6, 7, 8, 9, 10,
11, 12, 14, 16, 18, 20, 22, 24, 28, and 36. This is a range of 1/12 inch to 1/2 inch. The ps request is
used to change or restore the point size. Alternatively the point size may be changed between any two
characters by imbedding a \s/N at the desired point to set the size to N, or a \s=/N (1<N<K9) to
increment/decrement the size by N, \sO restores the previous size. Requested point size values that are
between two valid sizes yield the larger of the two.

The current size is available in the .s register.

NROFF ignores type size control.

Regquest
Form

Initial
Value

If No
Argument

Notes® Explanation

ps N

10 point

Point size set to = N. Alternatively imbed \sNV or \s=
/.
Any positive size value may be requested; if invalid, the
next larger valid size will result, with 2 maximum of 36.
A paired sequence +N, —N will work because the previous

requested

value

is also

remembered.

Ignored

NROFF.

Ss N

12/36em

ignored

Space-character size is set to N/36ems.
minimum

word

spacing

adjusted

This size is the

text.

Ignored

NROFF.

s FNM

off

Constant character space (width) mode is set on for font

F (if mounted); the width of every character will be
taken to be
b 4% Wy

N/36 ems.

“whbdlwie

M is absent.

4F4

bnd

DBWAdWwihbbg

the em is that o| |&¢ of
bidWw

bed

GAALA

the character’s point size; if M is given, the em is M-

points.

All affected characters are centered in this space,

including those

with an actual

space.

Font

Special

characters

width

larger than this

occurring

current font is F are also so treated.

while

the

If N is absent, the

mode is turned off. The mode must be still or again in
effect when the characters are physically printed. Ignored
in NROFF.
bd F N

off

The characters in font F will be artificially emboldened by

printing each one twice, separated by N—1 basic units.

reasonable value for ¥ is 3 when the character size is in

the vicinity of 10 points.

mode

turned

off.

printed with .bd I 3.

If N is missing the embolden

The column

heads

above

effect when the characters are physically printed.
in NROFF.
*Notes are explained at the end of the Summar

y and [ndex above.

were

The mode must be still or again in

Ignored

Nroff/Troff Users Manual

bdS FN

off

5-59

The characters in the Special Font will be emboldened
whenever the current font is £

with .bd SB3.

This manual was printed

The mode must be still or again in effect
when the characters are physically printed.

t F

Roman

Font changed to F.

Alternatively, imbed \fF.

- name P is reserved to mean the previous font.

fp NF

R,I,B,S

ignored

The font

Font position. This is a statement that a font named Fis
mounted on position N (1-4). It is a fatal error if Fis
not known. The phototypesetter has four fonts physically
mounted. Each font consists of a film strip which can be
mounted

numbered

quadrant

of a

wheel.

The

default mounting sequence assumed by TROFF is R, [, B,

and S on positions 1, 2, 3 and 4.
3.

Page control

Top and bottom margins are not automatically provided; it is conventional to define two macros and to

set traps for them at vertical positions 0 (top) and —N (N from the bottom). See §7 and Tutorial
Examples §T2. A pseudo-page transition onto the first page occurs either when the first break occurs or
when the first non-diverted text processing occurs.

Arrangements for a trap to occur at the top of the

first page must be completed before this transition.

In the following, references to the current diversion

(§7.4) mean that the mechanism being described works during both ordinary and diverted output (the

former considered as the top diversion level).

The useable page width on the Graphic Systems phototypesetter is about 7.54 inches, beginning about

1/27 inch from the left edge of the 8 inch wide, continuous roll paper.

The physical limitations on

NROFF output are output-device dependent.

Reguest
Form
pl =N

Initial
Value

Ilf No
Argument

Notes

Explanation

llin

1lin

Page length set to

= /N.

The internal limitation is about

75 inches in TROFF and about

136 inches in NROFF.

The current page length is available in the .p register.
bp =N

N ]

B*,v

Begin page.
is begun.

The current page is ejected and a new page

If £ N is given, the new page number will be

+= N. Also see request ns.

pn =N

Na=

ignored

Page number.

The next page (when it occurs) will have

the page number

= /N. A pn must occur before the ini-

tial pseudo-page transition to effect the page number of
the first page. The current page number is in the %
register.

po =N

0; 26/27int previous

Page offset. The current left margin is set to =N. The
TROFF initial value provides about | inch of paper mar-

gin including the physical typesetter margin of 1/27 inch.
th) is
+ (page-offset)
In TROFF the maximum (line-leng
about 7.54 inches. See §6. The current page offset is
available in the .o register.

.ne N

N=1V

D,y

Need XN vertical space. If the distance, D, to the next
trap position (see §7.5) is less than N, a forward vertical

space of size D occurs, which will spring the trap.
there are no remaining traps on the page,

*The use of " ° " as control character (instead of ".") suppresses the break function.
tValues separated by ;" are for NROFF and TROFF respectively.

D is the

5-60 Nroff/Troff Users Manual

distance to the bottom of the page.

If D< ¥V, another

line could still be output and spring the trap.

In a diver-

sion, D is the distance to the diversion trap, if any, or is
very large.

.mk R

none

internal

Mark the current vertical place in an internal register
(both associated with the current diversion level), or in
register R, if given. See rt request.

at =N

none

internal

D,y

Return upward only to a marked vertical place in the
current diversion. If =N (w.r.t. current place) is given,
the place is = .V from the top of the page or diversion or,
if .V is absent, to a place marked by a previous mk.

Mote

that the sp request (§3.3) may be used in all cases
instead of rt by spacing to the absolute place stored in a
explicit

e. g.

using

the

sequence

.mk R

.sp |\n Ru.
4.

Text Filling, Adjusting, and Centering

4.1, Filling and adjusting.

Normally, words are collected from input text lines and assembled into a out-

put text line until some word doesn’t fit. An autempt is then made the hyphenate the word in effort to
assemble a part of it into the output line. The spaces between the words on the output line are then
increased to spread out the line to the current lire length minus any current indent.

A word is any string
Any adjacent pair
of words that must be kept together (neither split across output lines nor spread apart in the adjustment
of characters delimited by the space character or the beginning/end of the input line.

process) can be tied together by separating them with the unpaddable space character "\ " (backslashspace). The adjusted word spacings are uniform in TROFF and the minimum interword spacing can be

controlled with the ss request (§2). In NROFF. they are normally nonuniform because of quantization
to character-size spaces; however, the command line option —e causes uniform spacing with full output

device resolution.

Filling, adjustment, and hypiaenation (§13) can all be prevented or controlled. The

text length on the last line output is available in the .n register, and text base-line position on the page

for this line is in the nl register. The text base-line high-water mark (lowest place) on the current page
is in the .h register.

An input text line ending with ., ?, or ! is taken to be the end of a sentence, and an additional space
character is automatically provided during filling.

Multiple inter-word space characters found in the

input are retained, except for trailing spaces; initial spaces also cause a break.

When filling is in effect, a \p may be imbedded or attached to a word to cause a break at the end of the
word and have the resuiting output line spread out to fill the current line length.
A text input line that happens to begin with a control character can be made to not look like a control

line by prefacing it with the non-printing, zero-width filler character \&.

Still another way is to specify

output translation of some convenient character into the control character using tr (§10.5).
4.2. Interrupted text. The copying of a input line in nofill (non-fill) mode can be interrupted by terminat-

ing the partial line with a \e. The nexr encountzred 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 terminat-

ing the word (and line) with \¢; 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 wnll be forced out along

with any partial word.

Request

Initial

If No

Form

Value

Argument

Notes

Explanation

.br

Break.

The filling of the line currently being collected is

stopped and the line is output without adjustment.

Text

linas

text

beginning

with

space characters and

linss (blank lines) also cause a break.

empty

Nroff/Troff Users Manual 5-61

fill on

B.E

Fill subsequent output lines.

The register .u is | in fill

mode and 0 in nofill mode.

.nf

fill on

B,E

Nofill.

Subsequent output lines

are

neither filled

nror

adjusted.

Input text lines are copied directly to output
lines without regard for the current line length.

.ad ¢

adj,both

adjust

Line adjustment is begun.

If fill mode is not on, adjust-

ment will be deferred until fill mode is back on.
type

indicator

present,

the

adjustment

If the
type

changed as shown in the following table.

adiust

Indicator

Adjust Type

adjust left margin only

adjust right margin only

center

born

adjust both margins

absent

unchanged

Noadjust. Adjustment is turned off; the right margin will
be ragged.

The adjustment type for ad is not changed.

Output line filling still occurs if fill mode is on.

ce N

off

Nes |

B,E

Center the next N input text lines within the current

(line-length minus indent).
is cleared.

lines.

§.

If AN=0, any residual count

A break occurs after each of the N input

If the input line is too long, it will be left adjusted.

Vertical Spacing

5.1. Base-line spacing. The vertical spacing (V) between the base-lines of successive output lines can be
set using the vs request with a resolution of 1/144inch
= 1/2 point in TROFF, and to the output device
resolution in NROFF. V must be large enough to accommodate the character sizes on the affected output lines. For the common type sizes (9-12 points), usual typesetting practice is to set ¥ to 2 points
greater than the point size; TROFF default is 10-point type on a 12-point spacing (as in this document).

The current Vis available in the .v register.

Multiple- ¥ line separation (e.g. double spacing) may be

requested with ls.

J.2. Extra line-space.

1f a word contains a vertically tall construct requiring the output line containing it

to have extra vertical space before and/or after it, the extra-line-space function \x’ N’ can be imbedded
in or attached to that word.

In this and other functions having a pair of delimiters around their parame-

ter (here °), the delimiter choice is arbitrary, except that it can’t look like the continuation of a number
expression for N. If N is negative, the output line containing the word will be preceded by N extra
vertical space; if N is positive, the output line containing the word will be followed by N extra vertical

space. If successive requests for extra space apply to the same line, the maximum values are used.
The most recently utilized post-line extra line-space is available in the .a register.
3.3. Blocks of vertical space.

A block of vertical space is ordinarily requested using sp, which honors the

no-space mode and which does not space past a trap.

A contiguous block of vertical space may be

reserved using Sv.

Request

Initial

If No

Form

Value

Argument

Notes

Explanation

Ys ¥

1/6in;12pts

E.p

Set vertical

base-line spacing size

Transient

extra

vertical space available with \x’ V" (see above).

Jds N

Ne=1

Line spacing set

N-1

appended to each output text line.

(blank lines) are

Appended blank lines

are omitted, if the text or previous appended blank line

5-62 Nroff/Troff Users Manual

reached a trap position.

Ssp N

Nem] V

B,y

Space vertically in either direction.

If N is negative, the

Sv N

NeslV

Save a contiguous vertical block of size N.

motion is backward (upward) and is limited to the distance to the top of the page. Forward (downward)
motion is truncated to the distance to the nearest trap. If
the no-space mode is on, no spacing occurs (see ns, and
rs below).

If the dis-

tance to the next trap is greater than N, N vertical space

is output. No-space mode has no effect. If this distance
is less than N, no vertical space is immediately output,
but N is remembered for later output (see os). Subsequent sv requests will overwrite any still remembered M.

.0S

Qutput saved vertical space.
effect.

No-space mode has no

Used to finally output a block of vertical space

requested by an earlier sv request.

space

No-space mode turned on. When on, the no-space mode
inhibits sp requests and bp requests without a next page

aumber. The no-space mode is turned off when a line of
output occurs, or with rs.

space

Blank text line.

Restore spacing. The no-space mode is turned off.

Causes a break and output of a blank line exactly like
sp 1.

6. Line Length and Indenting

The maximum line length for fill mode may be set with ll. The indent may be set with in; an indent
applicable to only the next output line may be set with ti. The line length includes indent space but nor
page offset space. The line-length minus the indent is the basis for centering with ce. The effect of 1I,
in, or ti is delayed, if a partially collected line exists, until after that line is output. In fill mode the
length of text on an output line is less than or equal to the line length minus the indent. The current
line length and indent are available in registers .1 and .I respectively. The length of three-part titles produced by tl (sce 314) is independently set by lt.
Request
Form

Initial
Value

If No
Argument

Notes

Explanation

Jl =N

6.5in

E.m

Line length is set to =N In TROFF the maximum
(line-length) + (page-offset) is about 7.54 inches.

dn =N

Ne=()

B,E,m Indent is set to £/N. The indent is prepended to each

g1 =N

ignored

B,E.m Temporary indent.

output line.

indented a distance
indent.

The next output text line will be
=N with

respect

the current

The resulting total indent may not be negative.

The current indent is not changed.

7. Macros, Strings, Diversion, and Position Traps
7.1. Macros and strings. A macro is a named set of arbitrary lines that may be invoked by name or with

a trap. A string is a named string of characters, not including a newline character, that may be interpolated by name at any point.

Request, macro, and string names share the same name list.

Macro and

<eting names may be one or two characters long and may usurp previously defined request, macro, or

string names. Any of these entities may be renamed with rn or removed with rm. Macros are created
by de and di, and appended to by am and da; di and da cause normal output to be stored in a macro.
Strings are created by ds and appended to by as. A macro is invoked in the same way as a request; a

Nroff/Troff Users Manual 5-63

control line beginning .xx will interpolate the contents of macro xx. The remainder of the line may
contain up to nine arguments. The strings x and xx are interpolated at any desired point with \ex and
\*(xx respectively. String references and macro invocations may be nested.
7.2. Copy mode input interpretation. During the definition and extension of strings and macros (not by
diversion) the input is read in copy mode. The input is copied without interpretation except that:

e The contents of number registers indicated by \n are interpolated.
o Strings indicated by \e are interpolated.
e Arguments indicated by \$ are interpolated.
o Concealed newlines indicated by \(newline) are eliminated.
o Comments indicated by \" are eliminated.
e \t and \a are interpreted as ASCII horizontal tab and SOH respectively (§9)
« \\ is interpreted as \.
\. is interpreted as ".".

These interpretations can be suppressed by prepending a \. For example, since \\ maps into a \, \\n
will copy as \n whnch will be interpreted as a number register indicator when the macro or string is
reread.

7.3. Arguments. When a macro is invoked by name, the remainder of the line is taken to contain up to
nine arguments. The argument separator is the space character, and arguments may be surrounded by
double-quotes to permit imbedded space characters. Pairs of double-quotes may be imbedded in

double-quoted arguments to represent a single double-quote. If the desired arguments won’t fit on a
line, a concealed newline 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.

macro’s own arguments can be interpolated at any point within the macro with \$#, which interpolates
the Nth argument (1< N<9). If an invoked argument doesn’t exist, a null string results.
ple, the macro xx may be defined by

For exam-

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

.Xxx Monday 14th
to produce the text

Today is Monday the 14th.

Note that the \$ was concealed in the definition with a prepended \ The number of currently available
arguments is in the .$ register.

No arguments are available at the top (non-macro) level in this implementation.

Because string

referencing is implemented as a input-level push down, no arguments are available from within a string.
No arguments are available within a trap-invoked macro.

Arguments are copied in copy mode onto a stack where they areavailable for reference. The mechanism does not allow an argument to contain a direct reference to a long string (interpolated at copy time)
Lo i B @

Py g, e

o o om m

and it is advisable to conceal string references (with an extra \) to delay interpolation until argument
reference time.

7.4. Diversions. Processed output may be diverted into a macro for purposes such as footnote processing

(see Tutorial §TS) or determining the horizontal and vertical size of some text for conditional changing

of pages or columns. A single diversion trap may be set at a specified vertical position. The number
registers dn and dl respectively contain the vertical and horizontal size of the most recently ended

diversion. Processed text that is diverted into a macro retains the vertical size of each of its lines when

reread in nofill mode regardless of the current V. Constant-spaced (es) 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

5-64 Nroff/Troff Users Manual

to do this is to imbed in the diversion the appropriate ¢s or bd requests with the transparent mechanism

described in §10.6.

Diversions may be nested and certain parameters and registers are associated with the current diversion
level (the top non-diversion level may be thought of as the Oth diversion level). These are the diver-

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

7.5. Traps. Three types of trap mechanisms are available-—page traps, a diversion trap, and an inputline-count trap. Macro-invocation traps may be planted using wh at any page position including the top.
This trap position may be changed using ch. Trap positions at or below the bottom of the page have no

effect unless or until moved to within the page or rendered effective by an increase in page length.
Two traps may be planted at the same position only by first planting them at different positions and
then moving one of the traps; the first planted trap will conceal the second unless and until the first one
is moved (see Tutorial Examples §TS). If the first one is moved back, it again conceals the second
trap. The macro associated with a page trap is automatically invoked when a line of text is output
whose vertical size reaches or sweeps past the trap position. Reaching the bottom of a page springs the
top-of-page trap, if any, provided there is a next page. The distance to the next trap position is available in the .t register; if there are no traps between the current position and the bottom of the page, the
distance returned is the distance to the page bottom.
A macro-invocation trap effective in the current diversion may be planted using dt. The .t register
works in a diversion; if there is no subsequent trap a large distance is returned. For a description of
input-line-count traps, see it below.

Regquest
Form

Initial
Value

If No
Argument

Notes

Explanation

de xxyy

Jy=.,

Define or redefine the macro xx

The contents of the

macro begin on the next input line.

Input lines are
copied in copy mode until the definition is terminated by a
line beginning with .yy, whereupon the macro yy is
called. In the absence of yy, the definition is terminated
by a line beginning with "..".

A macro may contain de

requests provided the terminating macros differ or the

contained definition terminator is concealed. ".." can be
concealed as \\.. which will copy as \.. and be reread as

.am xx yy

Y=,

ds xx string -

ignored

Append to macro (append version of de).

Define a string xx containing string. Any initial doublequote in string is stripped off to permit initial blanks.

.4§ XX string -

ignored

Append string to string xx (append version of ds).

rm ¢

ignored

Remove

request,

macro,

or string.

The

name xx is

removed from the name list and any related storage
space is freed. Subsequent references will have no effect.

qn xcyy

ignored

Rename request, macro, or string xx to yy.

If yyexists, it

is first removed.
di xx

end

Divert

output

macro

xx.

Normal

text

processing

occurs during diversion except that page offsetting is not
done.

The

diversion ends when the request di or da is

encountered without an argument; extraneous regquests

of this type should not appear when nested diversions are
being used.

Nroff/Troff Users Manual 5-65

.da xx
wh

Nxx

end

Divert, appending to xx (append version of di).
Install a trap to invoke xx at page position NV, a negative N
will be interpreted with respect to the page botrom.

macro previously planted at N is replaced by xx

N refers to the top of a page.

Any

A zero

In the absence of xx, the

first found trap at &, if any, is removed.
ch xx
N

dt N xx

off

D,y

Change the trap position for macro xx to be V.
absence of N, the trap, if any, is removed.

In the

Install a diversion trap at position N in the current diversion to invoke macro xx.

diversion trap.

Another dt will redefine the

If no arguments are given, the diversion

trap is removed.

it N xx

off

Set an input-line-count trap to invoke the macro xx after
N lines of text input have been read (control or request

lines don’t count).

The text may be in-line text or text

interpoiated by inline or trap-invoked macros.

.em xx

norne

none

The macro xx will be invoked when all input has ended.
The effect is the same as if the contents of xx had been
at the end of the last file processed.

Number Registers

A variety of parameters are available to the user as predefined, named number registers (see Summary
and Index, page 7). In addition, the user may define his own named registers. Register names are one
or two characters long and do not conflict with request, macro, or string names. Except for certain
predefined read-only registers, a number register can be read, written, automatically incremented or
decremented, and interpolated into the input in a variety of formats. One common use of user-defined
registers is to automatically number sections, paragraphs, lines, etc. A number register may be used
any time numerical input is expected or desired and may be used in numerical expressions (§1.4).

Number registers are created and modified using nr, which specifies the name, numerical value, and
the auto-increment size. Registers are also modified, if accessed with an auto-incrementing sequence.
If the registers x and xx both contain NV and have the auto-increment size M, the following access

sequences have the effect shown:

|
Effect on

Value
Interpolated

\nx
\n (x

none
none

N
N

\n<+x

x incremented by M

N+M

Sequernce

\n=x
x decremented by M
\n+ (xx | xxincremented by M
\n-(xx | xxdecremented by M

N—-M
N+M
N—-M

When interpolated, a number register is converted to decimal (default), decimal with leading zeros,
lower-case Roman, upper-case Roman, lower-case sequential alphabetic, or upper-case sequential alpha-

betic according to the format specified by af.
Request
Form

Initiai
Value

ArRE=NM

[f No
Argument

Notes

Explanation

The number register R is assigned the value =/N with
respect to the previous value, if any.
auto-incrementing is set to M.

The increment for

5-66 Nroff/Troff Users Manual

af Rc¢

arabic

Assign format ¢ to register R. The available formats are:

Numbering

Format

Sequence

1
001

0,1,2,3,4,5,...
| 000,001,002,003,004,005,...
0,1,11,113,1v,v,...
...
o.IILIIIV,V
0.a.b,c,...,z,aa,ab,...,zz,aaa,...
0,A.B.C.....Z,AA AB.....ZZ . AAA...

i
I
a
A

An arabic format having N digits specifies a field width of
N digits (example 2 above). The read-only registers and
the width function (§11.2) are always arabic.

Ir R

ignored

Remove register R. If many registers are being created

dynamically, it may become necessary to remove no
longer used registers to recapture internal storage space
for newer registers.

9. Tabs, Leaders, and Fields

9.]. Tabs and leaders. The ASCII horizontal tab character and the ASCII SOH (hereafter known as the

leader character) can both be used to generate either horizontal motion or a string of repeated charac-

ters. The length of the generated entity is governed by internal tab stops specifiable with ta. The
default difference is that tabs generate motion and leaders generate a string of periods; tc and lc offer
the choice of repeated character or motion. There are three types of internal tab stops—/eft adjusting,

right adjusting, and centering. In the following table: D is the distance from the current position on the
input line (where a tab or leader was found) to the next tab stop; next-string consists of the input charac-

ters following the tab (or leader) up to the next tab (or leader) or end of line; and W is the width of
next-string.

Length of motion or

Location of

type

repeated characters

next-string

Left
Right

D
D—W
D—W/?

Following D
Right adjusted within D
Centered on right end of D

Tab

Centered

The length of generated motion is allowed to be negative, but that of a repeated character string cannot
be. Repeated character strings contain an integer number of characters, and any residual distance IS
prepended as motion. Tabs or leaders found after the last tab stop are ignored, but may be used as
next-string terminators.

Tabs and leaders are not interpreted in copy mode. \t and \a always generate a non-interpreted tab and
leader respectively, and are equivalent to actual tabs and leaders in copy mode.

9.2. Fields. A field is contained between a pair of field delimiter characters, and consists of sub-strings
separated by padding indicator characters. The field length is the distance on the input line from the
position where the field begins to the next tab stop. The difference between the total length of all the
sub-strings and the field length is incorporated as horizontal padding space that is divided among the
indicated padding places. The incorporated padding is allowed to be negative. For example, if the field
delimiter is # and the padding indicator is °, # xxx"right# specifies a right-adjusted string with the
string xxx centered in the remaining space.

Nroff/Troff Users Manual 5-67

Request
Form

Initial
Value

If No
Argument

Notes

ta Nt ...

0.8; 0.5in

none

E.m

Explanation
Set tab stops and types.

(=R,

centering; ¢ absent, left adjusting.

right adjusting;

¢=C,

TROFF tab stops are

preset every 0.5in.; NROFF every 0.8in.

The stop values

are separated by spaces, and a value preceded by <+
treated as an increment to the previous stop value.

tc ¢

none

The tab repetition character becomes ¢, or is removed

specifying motion.

dec

. none

The leader repetition character becomes ¢, or is removed
specifying motion.

fcab

off

The field delimiter is set to a; the padding indicator is set
to the space character or to b, if given. In the absence of
arguments the field mechanism is turned off.

10.

Input and Output Conventions and Character Translations

10.1. Input character translations. Ways of inputting the graphic character set were discussed in §2.1.
The ASCII control characters horizontal tab (§9.1), SOH (§9.1), and backspace (§10.3) are discussed
elsewhere. The newline delimits input lines. In addition, STX, ETX, ENQ, ACK, and BEL are accepted,
and may be used as delimiters or translated into a graphic with tr (§10.5).

A4/l others are ignored.

The escape character \ introduces escape sequences—causes the following character to mean another
character, or to indicate some function.

A complete list of such sequences is given in the Summary

and Index on page 6. \ should not be confused with the ASCII control character ESC of the same name.
The escape character \ can be input with the sequence \\. The escape character can be changed with
ec, and all that has been said about the default \ becomes true for the new escape character.
used to print whatever the current escape character is.

\e can be

If necessary or convenient, the escape mechan-

ism may be turned off with eo, and restored with ec.

Regquest
Form

Initial
Value

Argument

If No
Notes

Explanation

.ec ¢

Set escape-character to \, or to ¢, if given.

.80

Turn escape mechanism off.

10.2. Ligatures. Five ligatures are available in the current TROFF character set — fi, fl, ff, fii, and fH.
They may be input (even in NROFF) by \(fi, \(fl, \(ff, \(Fi, and \(F] respectively. The ligature mode
is normally on in TROFF, and automatically invokes ligatures during input.

Request

Initial

If No

Form

Value

Argument

Notes

Explanation

Jdg N

off; on

Ligature mode is turned on if N is absent or non-zero.
and turned off if NM=0. If N=2, only the two-character
ligatures are automatically invoked. Ligature mode is
inhibited
-

for

request,
S

macro,

names, and in copy mode.

10.3. Backspacing, underlining, overstriking, etc.

string,

file

Unless in copy mode, the ASCII backspace character is

replaced by a backward horizontal motion having the width of the space character.

form of line-drawing is discussed in §12.4.

No effect in NROFF.
Underlining as a

A generalized overstriking function is described in $12.1.

NROFF automatically underlines characters in the underline font, specifiable with uf, normally that on

font position 2 (normally Times [talic, see §2.2).
selected by ul and cu.

characters.

In addition to ft and \fF the underline font may be

Underlining is restricted to an output-device-dependent subset of reasonable

5-68 Nroff/Troff Users Manual

If No

Regquest

Initial

Value

Argument

Notes

al v

off

Nass |

Form

Explanation

Underline in NROFF (italicize in TROFF) the next N

input text lines. Actually, switch to underline font, saving
the current font for later restoration; other font changes

within the span of a ul will take effect, but the restora-

tion will undo the last change.

Output generated by tl

(§14) is affected by the font change, but does not decre-

ment N If ¥>1, there is the risk that a trap interpolated macro may provide text lines within the span;
environment switching can prevent this.

cu VY

off

Na= ]

uf F

[talic

A variant of ul that causes every character to be under-

lined in NROFF. Identical to ul in TROFF.

Underline font set to F. In NROFF, F may not be on

position 1 (initially Times Roman).

10.4. Control characters. Both the control character . and the no-break control character * 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 of any trap-invoked macros.
Request

Initial

.CC ¢

£2c

Form

[f No

Argument

Notes

Explanation

The basic control character is set to ¢, or reset to ".".

’

Value

The nobreak control character is set to ¢, or reset to "TM".

10.5. Output translation. One character can be made a stand-in for another character using tr. All text
processing (e. g. character comparisons) takes piace with the input (stand-in) character which appears to
have the width of the final character. The graphic translation occurs at the moment of output (including diversion).

If No

Request

Initial

Form

Value

Argument

Notes

Explanation

Ar abcd....

none

Translate a into b, ¢ into 4, etc. If an odd number of
characters is given, the last one will be mapped into the
space character. To be consistent, a particular transiation
must stay in effect from input to outpus time.

10.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 imbed control lines in a
macro created by a diversion.

10.7. Comments and concealed newlines. An uncomfortably long input line that must stay one line (e. g.

a string definition, or nofilied text) can be split into many physical lines by ending ail but the last one

with the escape \. The sequence \(newline) is a/ways ignored—except in a comment. Comments may

be imbedded at the end of any line by prefacing them with \". The newline at the end of a comment
cannot be concealed. A line beginning with \* will appear as a blank line and behave like .sp 1; a comment can be on a line by itself by beginning the line with .\".
11. Local Horizontal and Vertical Motions, and the Width Function

11.1. Local

Motions. The functions \v'V° 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.

local motion is one contained within a line. To avoid unexpected vertical dislocations, it 1S necessary
that the net vertical local motion within a word in filled text and otherwise within a line balance to zero.
The above and certain other escape sequences providing local motion are summarized in the following
lable.

Nroff/Troff Users Manual 5-69

Vertical
Local Motion

Effect in
TROFF

Horizontal

NROFF

\v'N°

Move distance

4 em up

' em down | 2 line down

1 em up

Y4 line up

1 line up

Effect in

Local Motion

\h'N’
\(space)
\0

TROFF

NROFF

Move distance N
| Unpaddable space-size space
Digit-size space

1/6 em space | ignored

1/12 em space | ignored

As an example, E2 could be generated by the sequence E\s=2\v'=0.4m"2\v'0.4m"\s+2; it should be
noted in this example that the 0.4 em vertical motions are at the smaller size.

11.2. Width Function. The width function \w’'string’ generates the numerical width of string (in basic
units). Size and font changes may be safely imbedded 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 st and sb are set respectively to the
highest and lowest extent of siring relative to the baseline; then, for example, the total height of the
string is \n(stu=\n(sbu. In TROFF the number register ct is set to a value between 0 and 3: 0 means
that all of the characters in string were short lower case characters without descenders (like e); 1 means

that at least one character has a descender (like y); 2 means that at least one character is tall (like H);
and 3 means that both tall characters and characters with descenders are present.

11.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 \kxword\h"|\nxu+2u’word will
embolden word by backing up to almost its beginning and overprinting it, resulting in word,
12. Overstrike, Bracket, Line-drawing, and Zero-width Functions

12.1. Overstriking. Automatically centered overstriking of up to nine characters is provided by the overstrike function \o’string’. The characters in string overprinted with centers aligned; the total width is

that of the widest character. string should not contain local vertical motion.
duces &, and \o"\(mo\
(sl’ produces £.

As examples, \o’e\’" pro-

12.2. Zero-width characters. The function \zc will output ¢ without spacing over it, and can be used to
produce left-aligned overstruck combinations. As examples, \z\(ci\(pl will produce &, and
\ (br\z\
(rn\ (ul\ (br will produce the smallest possible constructed box | .
12.3. Large Brackets. The Special Mathematical Font contains a number of bracket construction pieces

C{UYJ{
LT ) that can be combined into various bracket styles. The function \b'string” may 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 1 em and the total pile is centered 1/2em above the current base-

line (‘2 line in NROFF). For example, \b"\ (Ie\(f "E\|\b"\
(re\ (rf "\x" =0.5m"\x'0.5m" produces [E}

12.4. Line drawing. The function \1°N¢’ will draw a string of repeated ¢’s towards the right for a distance N. (\l is \(lower case L). If ¢ looks like a continuation of an expression for », it may insulated
from N with a \&. If cis not specified, the _ (baseline rule) is used (underline character in NROFF). If
N is negative, a backward horizontal motion of size N is made before drawing the string. Any space
resulting from N/(size of ¢) having a remainder is put at the beginning (left end) of the string. In the
L]

[

case of characters that are designed to be connected such as baseline-rule _, underrule _, and root-

en , the remainder space is covered by over-lapping. If Nis less than the width of ¢, a single ¢ is centered on a distance N.
.de us

\\$1\1°]0\ (ui’
@

As an example, a macro to underscore a string can be written

5-70 Nroff/Troff Users Manual

or one to draw a box around a string
.de bx

"\ 170N (ul”
|\ (Br\ 17O\ Gen\
\(be\\\SI
such that

.u] "underlined words”
and

.bx "words in a box"

vield underlined words and [words in a box.
The function \L* N¢” will draw a vertical line consisting of the (optional) character ¢ stacked vertically
apart 1 em (1 line in NROFF), with the first two characters overlapped, if necessary, to form a continuous line. The default character is the box rule | (\(br); the other suitable character is the bold verrical |
(\(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 baseline 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 Ys-em wide underrule were designed to form corners when using l-em
vertical spacings.

For example the macro

.de eb

.sp —1
.nf

\"compensate for next automatic base-line spacing
\"avoid possibly overflowing word buffer

\h’'=.5n"\L \\nau=1"\I"\\nC.lu+1n\(ul"\L’ = |\\nau+1"\1'|0u=.5n\(ul®°

\"draw box

will draw a box around some text whose beginning vertical place was saved in number register a (e. g.

using .mk a) as done for this paragraph.
13.

Hyphenation.

The automatic hyphenation may be switched off and on.

When switched on with hy, several variants

may be set. A hyphenation indicator character may be imbedded in a word to specify desired hyphenation points, or may be prepended to suppress hyphenation. In addition, the user may specify a small
exception word list.

Only words that consist of a central alphabetic string surrounded by (usually null) non-alphabetic
strings are considered candidates for automatic hyphenation. Words that were input 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.

Regquest

Initial

If No

Form

Value

Argument

Notes

Explanation

.nh

hyphenate

Automatic hyphenation is turned off.

hy N

on, N=|

on,N=|

Automatic hyphenation is turned on for

N=0.

¥ =1, or off for

If N=2 last lines (ones that will cause a trap)

are not hyphenated.

For =24 and 8, the last and first

two characters respectively of a word are not split off.

These values are additive;

i.e.

N=14 will invoke all

three restrictions.

he ¢

Jhw word] ...

Hyphenation indicator character is set to ¢ or to the
defauit \%. The indicator does not appear in the output.

ignored

Specify

hyphenation

minus signs.

points

words

with

imbedded

Versions of a word with terminal

s are

Nroff/Troff Users Manual 5-71

implied; i. e. dig—it implies dig—its.

This list is exam-

ined initiaily and after each suffix stripping.

The space

available is small—about 128 characters.

14.

Three Part Titles.

The titling function tl provides for automatic placement of three fields at the left, center, and right of a

line with a title-length specifiable with It.
text collecting process.

tl may be used anywhere, and is independent of the normal

A common use is in header and footer macros.

Regquest

Initial

{f No

Form

Value

Argument

Notes

Explanation

The strings left,

t1 “left’ center’ right’

adjusted,

center, and

right are respectively left-

centered,

title-length.

and right-adjusted in the current
Any of the strings may be empty, and over-

lapping is permitted.

If the page-number character (ini-

tially %) is found within any of the fields it is replaced by
the current page number having the format assigned to
Any character may be used as the string del-

pc ¢

off

The page number character is set to ¢, or removed.

The

page-number register remains %.

Jdt =N

6.5in

E.m

Length of title set to =N.
length are independent.

The line-length and the title-

Indents do not apply to titles:

page-offsets do.

15. Output Line Numbering.
Automatic sequence numbering of output lines may be requested with nm.

When in effect, a

three-digit, arabic number plus a digit-space is prepended to output text lines.

The text lines are

3 thus 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 tl are not numbered.

Numbering can be temporarily suspended with

6 nn, or with an .nm followed by a later .nm +0.

In addition, a line number indent /. and the

number-text separation S may be specified in digit-spaces.

Further, it can be specified that only

those line numbers that are multipies of some number M are to be printed (the others will appear

9 as blank number fields).
Reguest

Initial

If No

Form

Value

Argument

Notes

off

nam =NMS/

Explanation

Line number mode.

If +/V is given, line numbering is

turned on, and the next output line numbered is numbered =/N. Default values are M=],6 S=1, and /=0.

Parameters

corresponding

missing

arguments

are

unaffected; a non-numeric argument is considered missing.

In the absence of all arguments, numbering is
turned off; the next line number is preserved for possible

further use in number register In.

an N

Noa=]

The next N text output lines are not numbered.

As an example, the paragraph portions of this section are numbered with M=3: .nm 1 3 was
placed at the beginning, .nm was placed at the end of the first paragraph; and .nm +0 was placed

12 in front of this paragraph; and .nm finally placed at the end.

\w'0000°u) to keep the right side aligned.

Line lengths were also changed (by

Another example is .nm +5 5 x 3 which turns on

numbering with the line number of the next line to be 5 greater than the last numbered line, with

15 M=35, with spacing S untouched, and with the indent /set to 3.

5-72

Nroff/Troff Users Manual

16.

Conditional Acceptance of Input

In the following, ¢ is a one-character, built-in condition name, ! signifies not, N is a numerical expres-

sion, string/ and stringl are strings delimited by any non-blank, non-numeric character

no¢ in the

strings. and anyrhing represents what is conditionally accepted.

Request

Initial

If No

Form

Value

Argument

Notes

if ¢ anvthing

If condition c false, accept anyrhing.

Af N anything

If expression N > 0, accept anything.

Af 1N anything

If expression N < 0, accept anything.

Af “stringl string2” anything

If stringl identical to string2, accept anything,

Af ! stringl stringl” anything

If setringl not identical to string2, accept anything.

e ¢ anything

If portion of if-else; all above forms (like if).

.el anything

Else portion of if-else.

Af ¢ anything

Explanation

If condition ¢ true, accept anything as input; in multi-line

case use \{anything\}.

The built-in condition names are:
Condition
Name

True If

Current page number is odd

Current page number is even

Formatter is TROFF

Formatter is NROFF

If the condition c is true, or if the number N is greater than zero, or if the strings compare identically

(including motions and character size and font), anything is accepted as input.

If a ! precedes the ccndi-

tion, 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 multi-line 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 then uses the reverse sense of that state. ie - el pairs may be nested.
Some examples are:

.if e .t]l

"Even Page %"’

which outputs a title if the page number is even; and

de \n%>1 \{\
‘e N &%
SPp

v.oil

"Page %'"°

sp|1.2i \}

el .sp|2.5i

which treats page 1 differently from other pages.

17.

Environment Switching.

A number of the parameters that control the text processing are gathered together into an environment.
which can be switched by the user.

The environment parameters are those associated with requests

noting E in their Notes column; in addition, partially collected lines and words are in the environment.

Everything

else

global;

examples

are

page-oriented

parameters,

diversion-oriented

parameters.

Nroff/Troff Users Manual 5-73

number registers, and macro and string definitions.

All environments are initialized with default

parameter values.

Regquest
Form -

Initial
Value

If No
Argument

Notes

Explanation

ev N

Na=()

Environment switched to environment 0 < N<2.

Switch-

ing is done in push-down fashion so that restoring a previous environment

must be done with

.ev

rather

than

specific reference.

18. Insertions from the Standard Input
The input can be temporarily switched to the system standard input with rd, which will switch back
when two newlines in a row are found (the extra blank line is not used). This mechanism is intended

for insertions in forme-letter-like documentation.

On UNIX, the standard input can be the user’s key-

board, a pipe, or a file.

Request
Form

Initial
Value

If No
Argument

.xrd prompt

prompt =BEL -

Notes

Explanation
Read insertion from the standard input until two newlines in a row are found.

If the standard input is the

user’s keyboard, prompt (or a BEL) is written onto the
user’s terminal.

rd behaves like a macro, and arguments

may be placed after prompt.

.ex

Exit from NROFF/TROFF. Text processing is terminated
exactly as if all input had ended.

If insertions are to be taken from the terminal keyboard while output is being printed on the terminal,
the command line option —q will turn off the echoing of keyboard input and prompt only with BEL.
The regular input and insertion input cannot simultaneously come from the standard input.

As an example, multiple copies of a form letter may be prepared by entering the insertions for all the
copies in one file to be used as the standard input, and causing the file containing the letter to reinvoke

itself using nx (§19); the process would ultimately b;es,\;f,pndcd by an ex in the insertion file.
19. Input/Output File Switching
Regquest
Form

Initial
Value

.80 filename

If No
Argument

Notes

Explanation

Switch source file. The top input (file reading) level is
switched to filename. The effect of an so encountered in
a macro is not feit until the input level returns to the file
level.

When the new file ends, input is again taken from

the original file.

.nx filename

end-of-file

Next file

so’s may be nested.

is filename.

The current file

is considered

ended, and the input is immediately switched to filename.

.pi program

Pipe output to program (NROFF only).
must occur before any printing occurs.

This request

No arguments are

transmitted to program.

20.

Miscellaneous

Request
Form

Initial
Value

If No
Argument

Notes

Explanation

.mec ¢ N

off

E,m

Specifies that a margin character ¢ appear a distance N to
the right of the right margin after each non-empty text

line (except those produced by tl).
too-lor

If the output line is

‘s can happen in nofill mode) the character will

5-74 Nroff/Troff Users Manual

be appended to the line. If NV is not given, the previou:
N is used; the initial M is 0.2 inches in NROFF and len
in TROFF.

The margin character used with this para

graph was a 12-point box-rule.

.tm string

newline

After skipping initial blanks, string (rest of the line) i
read in copy mode and written on the user’s terminal.

g yy

Yy,

Ignore input lines. ig behaves exactly like de (§7) excep
that the input is discarded.
mode,

and

any

The input is read in cop

auto-incremented

registers

will

affected.

.pm ¢

all

Print macros. The names and sizes of all of the definec
macros and strings are printed on the user’s terminal; if
is given, only the total of the sizes is printed.

The size:

is given in blocks of 128 characters.

Flush output buffer.

Used in interactive debugging t«

force output.

21. Output and Error Messages.

The output from tm, pm, and the prompt from rd, as well as various error messages are written ont
UNIX's standard message output. The latter is different from the standard output, where NROFF format
ted output goes. By default, both are written onto the user’s terminal, but they can be independent!
redirected.

Various error conditions may occur during the operation of NROFF and TROFF.

Certain less seriou

errors having only local impact do not cause processing to terminate. Two examples are word overflown
caused by a word that is too large to fit into the word buffer (in fill mode), and line overflow, caused b
an output line that grew too large to fit in the line buffer; in both cases, a message is printed, th
offending excess is discarded, and the affected word or line is marked at the point of truncation with a
in NROFF and a = in TROFF. The philosophy is to continue processing, if possible, on the ground
that output useful for debugging may be produced. If a serious error occurs, processing terminates, an
an appropriate message is printed. Examples are the inability to create, read, or write files, and th
exceeding of certain internal limits that make future output unlikely to be useful.

Nroff/Troff Users Manual 5-75

TUTORIAL EXAMPLES

T1.

initial pseudo-page transition (§3).

Introduction

Although NROFF and TROFF have by design a

syntax

reminiscent

of earlier

text

processors®

with the intent of easing their use, it is almost

always necessary to prepare at least a small set of

macro definitions to describe most documents.
Such common formatting needs as page margins
and footnotes are deliberately not built into
NROFF and TROFF. Instead, the macro and
string definition, number register, diversion,
environment switching, page-position trap, and
conditional input mechanisms provide the basis
for user-defined implementations.
The examples to be discussed are intended to be
useful and somewhat realistic, but won’t necessarily cover all relevant contingencies. Explicit
numerical parameters are used in the examples to
make them easier to read and to illustrate typical
In many cases, number registers would

values.

In fill mode,

the output line that springs the footer trap was
typically forced out because some part or whole

word didn’t fit on it.

If anything in the footer

and header that follows causes a break, that word
or part word will be forced out.

In this and other

examples, requests like bp and sp that normally
cause breaks are invoked using the no-break con-

trol character ° to avoid this.
When the
header/footer design contains material requiring
independent

text

processing,

the

environment

may be switched, avoiding most interaction with

the running text.
A more realistic example would be

.de hd

\"header

Af t .t "\(m
"\ (rn° \"troff cut mark
Af \\n%>1 \{\
"sp |0.5i—1
\"tl base at 0.5i
Al = Y = \"centered page number

really be used to reduce the number of places

.ps

where numerical information is kept, and to con-

centrate conditional parameter “initialization like
that which depends on whether TROFF or NROFF

s \}
"sp |1.0i

is being used.

.ns

\"turn on no-space mode

de fo

\"footer

.ps 10
ft R

\"set footer/header size
\"set font

T2.

Page Margins

As discussed in §3, header and footer macros are
usually defined to describe the top and bottom
page margin areas respectively.

A trap is planted

at page position 0 for the header, and at =N (N
from the page bottom) for the footer. The simplest such definitions might be

.de hd
‘sp 1i
.
de fo

.vs 12p
\"set base-line spacing
Af \\n% =1 \{\
sp [\\n(.pu=0.5i—1 \"tl base 0.5i up
Al = % =""\} \"first page number

.wh 0 hd

\"end definition
\"define footer

\"restore vs
\"space to 1.0i

\"define header

\"restore size
\"restore font

.wh —1i fo
which sets the size, font, and base-line spacing

\"end definition

for the

.wh 0 hd

header/footer material,

restores them.

wh =1i fo

and

ultimately

The material in this case is a page

number at the bottom of the first page and at the

which provide blank 1 inch top and bottom mar-

top of the remaining pages.

gins.

cut mark is drawn in the form of root-en’s at each

The header will occur on the first page,
only if the definition and trap exist prior to the

margin.
avoid

*For

example:

P. A. Crisman,

Ed.,

The

Comparible

Time-

If TROFF is used, a

The sp’s refer to absolute positions to
dependence

the

base-line

spacing.

Another reason for this in the footer is that the

Sharing System, MIT Press, 1965, Section AH9.01 (Descrip-

footer is invoked by printing a line whose vertical

tion of RUNOFF program on MIT’s CTSS system).

spacing swept past the trap position by possibly as

5-76 Nroff/Troff Users Manual

much as the base-line spacing. The no-space
mode is turned on at the end of hd to render
ineffective accidental occurrences of sp at the top
of the running text.

The above method of restoring size, font, etc.
presupposes that such requests (that set previous
value) are nor used in the running text.

A better

The prespacing parameter is suitable for TROFF;
a larger space, at least as big as the output device
vertical

resolution,

would

suitable

NROFF.

The choice of remaining space to test

for in the ne is the smallest amount greater than

one line (the .V is the available vertical resolution).

scheme is save and restore both the current and

A macro to automatically number section head-

previous values as shown for size in the follow-

ings might look like:

ing:

.de sc
\"section
., ee=
\"force font, etc.
.sp 0.4
\"prespace
.ne 2.4+\\n(.Yu \"want 2.4+ lines

.de fo

.nr s1 \\n(.s

\"current size

.PS

.ar s2 \\n(.s
, oma

\"previous size
\"rest of footer

\\n+S.
arSo01

.de hd

. o=
.ps \\n(s2
.ps \\n(si

\"header stuff
\"restore previous size
\"restore current size

\"init S

The usage is .sc, followed by the section heading
text, followed by .pg.

The ne test value includes

one line of heading, 0.4 line in the following pg,
and one line of the paragraph text. A word con-

Page numbers may be printed in the bottom mar-

sisting of the next section number and a period is

gin by a separate macro
footer’s page ejection:

of the number may be set by af (38).

.de bn

Al - Y -

triggered during

the

\"bottom number
\"centered page number

produced to begin the heading line.

The format

Another common form is the labeled, indented
paragraph, where the label protrudes left into the

indent space.

.wh —=0.5i=1v bn \"tl base 0.5i up
T3.

.de lp
-Pg

Paragraphs and Headings

The housekeeping associated with starting a new
paragraph

macro

should

that,

preparagraph

for

collected

example,

spacing,

forces

does

paragraph

the

requests a temporary indent.

\"paragraph indent

.ta 0.2i 0.5

\"label, paragraph

\t\\S$1\t\e

font,

size, base-line spacing, and indent, checks that

.in 0.5i
41 0

desired

the correct

enough space remains for more than one line, and

\"flow into paragraph

The intended usage is ".Ip label"; label will begin
at

0.2inch,

0.3inch

.de pg
\"paragraph
br
\"break
t R
\"force font,
.ps 10
\"size,
.vs 12p
\"spacing,
.in 0
\"and indent
.sp 0.4
\"prespace
.ne 1+\\n(.Vu \"want more than 1 line
i 0.21

\"labeled paragraph

and

without

cannot

exceed

intruding

into

the

length

paragraph.

The label could be right adjusted against 0.4 inch
by setting the tabs instead with .ta 0.4iR 0.5i.

The last line of lp ends with \¢ so that it will
become a part of the first line of the text that follows.

T4. Muitiple Column Output
The

\"temp indent

production

muitiple

column

pages

requires the footer macro to decide whether it
was invoked by other than the last column, so

The first break in pg will force out any previous
partial lines, and must occur before the vs.

The

forcing of font, etc. is partly a defense against
prior error and partly to permit things like section heading macros to set parameters only once.

that it will begin a new column rather than produce the bottom margin.

The header can initial-

ize a column register that the footer will increment and test.

The following is arranged for two

columns, but is easily modified for more.

Nroff/Troff Users Manual 5-77

ev \}

\"pop environment

.de hd

\"header

nrclo1l
.mk

\"init column count
\"mark top of text
.de fx

\"process footnote overflow

.de fo

\"footer

Af\\nx .di fy

\"divert overflow

.po +3.4i
It

\"next column: 3.1+0.3

.de fn

\"start footnote

\"back to mark

.ns \}
el \{\
.po \\nMu

\"no-space mode

.da FN
ey 1

\"restore left margin

Af\\n+x=1 .fs \"if first, include separator
fi
\"fill mode

de\\n+ (cl<
2 \{\

"bp \}
A1 3.1

.nr

M\\n(.o

\"column width
\"save left margin

Footnote Processing

The footnote mechanism to be described is used
by imbedding the footnotes in the input text at
the point of reference, demarcated by an initial

.de fs
\I' 1§’

fn and a terminal .ef:

de fz

Footnote rext and control lines...

.nf
fy

In the following, footnotes are processed in a
separate environment and diverted for later
printing in the space immediately prior to the
bottom margin. There is provision for the case

.ef

where the last collected footnote doesn’t com-

.wh 0 hd

pletely fit in the available space.

.wh 12i fo

\"header

.arx 01
.nar Yy 0=\\nb
.ch fo =\\nbu
Af\\n{dn .fz

\"init footnote count
\"current footer place
\"reset footer trap
\"leftover footnote

.de fo
.nr dn 0

Af \\nx \ [\

\"footer
\"zero last diversion size

\"separator

\"1 inch rule

\"get leftover footnote

.de hd

\"divert (append) footnote
\"in environment 1

.de ef
\"end footnote
br
\"finish output
.nrz\\n(.v
\"save spacing
.ev
\"pop ev
.di
\"end diversion
.nry =\\n(dn \"new footer position,
Jdf\\nx=1 .nry —O\\n(v-=\\n2) \
\"uncertainty correction
.ch fo\\nyu
\"y is negative
Af (\\n(nl+1v)> (\\n(.p+\\ny) \
.ch fo\\n(nlu+1v \"it didn’t fit

Typically a portion of the top of the first page
contains fuil width text; the request for the narrower line length, as well as another .mk would
be made where the two column output was to
begin.
TS.

.nr b 1.0i

\"retain vertical size
\"where fx put it

\"bottom margin size
\"header trap

\"footer trap, temp position
.wh =\\nbu fx\"fx at footer pasition
.ch fo =\\nbu \"conceal fx with fo

The header hd initializes a footnote count register X, and sets both the current footer trap position register y and the footer trap itself to a nom-

inal position specified in register b.

In addition,

if the register dn indicates a leftover footnote, fz
iIs invoked to reprocess it.

The

footnote start

macro fn begins a diversion (append) in environment 1, and increments the count x; if the count

ev 1
.nf

\"expand footnotes in evl
\"retain vertical size

FN
.rm FN

\"footnotes
\"delete it

Af "\\n(.2°fy" .di \"end overflow diversion
.nr x 0
\"disable fx

is one, the footnote separator fs is interpolated.

The separator is kept in a separate macro to permit user redefinition. The footnote end macro ef
restores the previous environment and ends the

diversion after saving the spacing size in register

y is then decremented by the size of the

5-78 Nroff/Troff Users Manual

footnote, available in dn; then on the first footnote, y is further decremented by the difference
in vertical base-line spacings of the two environments, to prevent the late triggering the footer

trap from causing the last line of the combined

footnotes to overflow.

The footer trap is then set
to the lower (on the page) of y or the current
page position (nl) plus one line, to allow for
printing the reference line.

If indicated by x, the

footer fo rereads the footnotes from FN in nofill
mode in environment !, and deletes FN.

If the

footnotes were too large to fit, the macro fx will
be trap-invoked to redivert the overflow into fy,
and

the

will

later

header whether fy is empty.

indicate

the

Both fo and fx are

planted in the nominal footer trap position in an
order that causes fx to be concealed unless the fo

trap is moved. The footer then terminates the
overflow diversion, if necessary, and zeros x to
disable

fx,

together

because

with

the

uncertainty

not-too-late

correction

triggering

of the

footer can result in the footnote rereading finishing before reaching the fx trap.
A good exercise for the student is to combine
the multiple-column and footnote mechanisms.

T6.

The Last Page

After the last input file has ended, NROFF and
TROFF invoke the end macro (§7), if any, and
when it finishes, eject the remainder of the page.

During the eject, any traps encountered are processed normally.

At the end of this last page,
processing terminates unless a partial line, word,

partial

word

remains.

If it

desired

that

another page be started, the end-macro

.de en
\¢

\"end-macro

£ en

will

deposit

another last page.

null

partial

word,

and

effect

Nroff/Troff Users Manual

Table I
Font Style Examples

The following fonts are printed in 12-point, with a vertical spacing of 14-point, and with nonalphanumeric characters separated by 4 em space. The Special Mathematical Font was specially
prepared for Bell Laboratories by Graphic Systems, Inc. of Hudson, New Hampshire. The Times
Roman, ltalic, and Bold are among the many standard fonts available from that company.

Times Roman

abcdefghijklmnopqgrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
1234567890

18%
& () "*+ —.,/::=2[]]

e —--_hAUAfFHifM°oT
¢®C
Times [talic
abcdefghijkimnopqrstuvwxyz

ABCDEFGHIJKLMNOPQRSTUVWXYZ
1234567890

ISH& ()t =

)= 2]

~D~--%%%fiflmfifi preee

Times Bold
abcdefghijklmnopqrstuvwxyz

ABCDEFGHIJKLMNOPQRSTUVWXYZ
1234567890

1$%
& ()’ *+ — .,/ =21]]
o] —-_YahsfififfhfA°t
¢2C
Special Mathematical Font

/< >{|#@+—=»

&fi‘y&igfigcnA;.LVgUTfiO‘?TUéXQ’iw

TAOAZNIYOPVQ

VvV

Z2S$E~=F——1|X+xUNCDC2=)

§V-[coctmwwm@ Of|)){H LI

5-79

5-80 Nroff/Troff Users Manual

Table 11

Input Naming Conventions for °, ,and and for Non-ASCII Special Characters

Non-ASCII characters and minus on the standard fonts.

3/4 Em dash

hyphen or

—
e

\(hy
\=
\(bu

hyphen
current font minus
bullet

O
-~
Ve
o
Yo

\(sq
\ru
\(14
\N(12
\(34

square
rule
1/4
1/2
3/4

\(em

—

open quote

close quote

Input Character
Char Name Name

\(i

\(1

\(f
\(Fi
\(FI
\(de
\(dg
\(fm
\(ct
\(rg
\(co

A
1

ff
ffi
degree
dagger
foot mark

cent sign
registered
copyright

Non-ASCII characters and °, °, _y +, =, =, and « on the special font.

The ASCII characters @, #, ", , ', <, >, \, {, ], °, %, and _ exist only on the special font and are
printed as a 1-em space if that font is not mounted.

The following characters exist only on the special

font except for the upper case Greek letter names followed by t which are mapped into upper case

English letters in whatever font is mounted on font position one (default Times Roman).

The special

math plus, minus, and equals are provided to insulate the appearance of equations from the choice of

standard fonts.

math minus
math equals
math star
section
acute accent

_
/

\(ga
\Mul
\(sl

grave accent
underrule

\(*b

\(*a

y
&

\(*g
\(*d

{

\(®z

n
8
¢

\(®e

slash (matching backslash)
alpha

Dbeta

gamma
delta
epsilon

zeta

\(®%
\(*h

eta
theta

\(*i

iota

> X

\(mi
\(eq
\(**
\(sc
\(aa

-~
=
=

ovaT

math plus

\(pl

Input Character
Char Name Name

4 v

Character

WP
&Xx 6 ¢

Input

Char Name Name

\(*k
\(*!
\(*m
\(*n
\(®*c
\(*0
\(°*p

kappa
lambda
mu
nu
xi
omicron
pi

\(*s
\(ts

sigma
terminal sigma

\(*t

tau

\(*u
\(*f
\(*x
\(*q
\(*w
\(*A
\(*B

upsilon
phi
chi
psi
omega
Alphat
Betat

\(*r

rho

Nroff/Troff Users Manual 5-81

_DOEX@e~<AMOoOO0OMZL
>R —~O LI NMP T

\(*G
\(*D

ne A —t defuUuNUNDCH
+x—— 1T | XL RIAV

Char Name Name

= >=
\(>
<
\( == £ ==
\ (e o identically equal
\ (o= approx =
approximates
\(ap
not equal
==
\ (!
arrow
right
=>
\(
arrow
left
<
\(
up arrow
\(ua

Gamma
Delta

\(*E
\(*Z
\(*Y
\(*H
\(°1
\V("K
\(*L
\(*M
\(*N
\(*C
\(*O
\(°P

Epsilont
Zetat
Etat
Theta
Iotat

\(*R

Rhot

\(*S
\(*T

Sigma

Kappat

Lambda

Mut
Nut
Xi

Omicront
Pi

Taut

\(*U

Upsilon

\(*F
\V(*X
\(*Q
\(*W
\(sr

Chift
Psi
Omega

Phi

square root

\(rn

root en extender

\(da
\(mu
\(di
\(+~\(cu
\(ca
\(sb

down arrow

\(sp
\(ib

\(ip
\ (if
\(pd
\(gr

multiply

divide

plus-minus

cup (union)
cap (intersection)
subset of
superset of
improper subset
improper superset

|
infinity
partial derivative
gradient

\(no
\(is

not

\(es
\(mo

empty set

\(pt

integral sign
proportional to

member of

Input Character
Char Name Name

0~ @4\

Character

sl ooy Stam

Input

\(br

box vertical rule

\(dd

double dagger
right hand

\(th
\(bs
\(or

left hand

\(rh

Bell System logo
or

\ (ci
\ (1t
\(1b
\ (rt
\(rb
\ (1k
\(rk
\(bv

circle

\ (rf
\(lc
\(rc

right floor (right bottom)
left ceiling (left top)
right ceiling (right top)

\(If

left top of big curly bracket
left bottom
right top

right bot

left center of big curly bracket
right center of big curly bracket
bold vertical

left floor (left bottom of big
square bracket)

5-82 Nroff/Troff Users Manual

Summary of Changes to N/TROFF Since October 1976 Manual
Options
-t

(Nroff only) OQutput tabs used during horizontal spacing to speed output as well as
reduce output byte count. Device tab settings assumed to be every 8 nominal character
widths. The default settings of input (logical) tabs is also initialized to every 8 nominal
character widths.

Efficiently suppresses formatted output.
and diagnostics).

Only message output will occur (from "tm"s

Old Requests
.ad ¢

The adjustment type indicator "¢” may now also be a number previously obtained from

the ".j" register (see below).
S0 name

The contents of file "name"” will be interpolated at the point the "so” is encountered.
Previously, the interpolation was done upon return to the file-reading input level.

New Request
.ab text

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

fz FN

forces font "F" to be in size N. N may have the form N, +N, or -N. For example,
fz 3 -2
will cause an implicit \s-2 every time font 3 is entered, and a corresponding \s+2 when
it is left. Special font characters occurring during the reign of font F will have the same
size modification. If special characters are to be treated differently,
fzSFN
may be used to specify the size treatment of special characters during font
F. For
example,

fz 3-3
fzS3-0
will cause automatic reduction of font 3 by 3 points while the special characters would
not be affected.

Any ‘‘.fp’’ request specifying a font on some position must precede

‘*“.f2’" requests relating to that position.
New Predefined Number Registers.
K

Read-onlv. Contains the horizontal size of the text portion (without indent) of the
current partially collected output line, if any, in the current environment.
Read-only. A number representing the current adjustment mode and type.

Can be

saved and later given to the "ad” request to restore a previous mode.

Read-only.

1 if the current page is being printed, and zero otherwise.

Read-only.

Contains the current line-spacing parameter ("ls").

General register access to the input line-number in the current input file.
same value as the read-only " ¢” register.

Contains the

A Troff Tutorial 5-83

A TROFF Tutorial
Brian W. Kernighan
Bell Laboratories

Murray Hill, New Jersey 07974
ln accocdance with this philosophy of let-

The single most important rule of using

troff is not to use it dicectly, but through some
intermediary. In many ways, troff resembles an

assembly language — a remarkably powerful and
flexible one -= but nonetheless such that many

operations must be specified at a level of detail
and in a form that is too hard for most people to
use effectively.

For'two special applications, there are pro-

grams that provide an interface to troff for the
majority of users. eqm (2] provides an easy to

learn language for typesetting mathematics: the
eqn user need know no troff whatsoever (0

tvpeset mathematics. tbl [3] provides the same
convenience for producing tables of arbitrary
complexity.

For producing straight text (which may

well contain mathematics or tables). there area

number of ‘macro packages’ that define formatting rules and operations for specific styles of
documents, and reduce the amount of direct

contact with troff. ln particular, the *=—ms’ (4]

and PWB/MM (5] packages for Beil Labs internal memoranda and external papers provide most
of the facilities needed for a wide range of document prepacation. (This memo was prepared
with "=ms'.) There are also packages for viewgraphs. for simulating the older roff formatters
on UNIX and GCOS, and for other special applications.

Typically you will find

these packages

easier to use than troff once you get beyond the
most trivial operations; you should always consider them first.

In the few cases where existing packages

don't do the whole job, the solution s ror (O
weite an entirelty new set of troff instructions
from scratch. but to make small changes to adapt
packages that already exist.

although it tries to concentrate on the more use-

ful parts. [n any case, there is nd auempt to be
complete. Rather. the emphasis is on showing
how to do simple things. and how to make incremental changes to what already exists. The contents of the remaining sections are:
.

Point sizes and line spacing

Tabs

P ]

ment is an example of troff output.

described here is only a small part of the whole.

O A B

ol (1] is a text-formatting program. writJ. E. Ossanna, for producing high-quality
by
ten
printed output from the phototypesetter on the
UNIX and GCOS operating systems. This docu-

ting someone eise do the work, the part of troff

0 90

1. Intreduction

.
10.

Fonts and special characters

Indents and line length

Local motions: Drawing lines and characters

Strings
Introduction (0 macros

Titles. pages and numbering
Number registers and arithmetic

11.

Macrog with arguments

12.

Conditionals

13.
14.

Eavironments
Diversions

Appendix: Typesetter character set

The troff described here is the C-language version running on UNIX at Murray Hill, as documented in {1].

To use troff you have to prepare not only

the actual text you want printed. but some infor-

mation that tells how vou want it printed.
(Readers who use .roff will find the approach
familiar.) For troff the text and the formatting
information are often intertwined quite inti-

on 2
mately. Most commands to troff are placed’

line separate {rom the text itself, beginning with
a period (one command per line). For example.
Some (axt.

.ps 14

Some more text.

wiil change the poinu size . that is, the size or
the letters being printed. 10 "14 point’ (one point
is 1/72 inch) like this:

5-84 A Troff Tutorial

Some text.

OOIME more text.

Occasionally,

though,

something

\s=2UNIX\s+2

special

occurs in the middle of a line = to produce

temporarily decreases the size, whatever it is, by
iwo

points,

changes

Area = fi‘fz

then

have

the

restores

it.

advantage

Relative

size

that

size

the

difference is independent of the starting size of
the document.
The amount of
change is restricted to a single digit.

you have to type

Area = \ (p\fIAfR\[\s8\u2\d\s0
(which we will explain shortly). The backslash
character \ is used to inwwoduce troff commands
and speciai characters within 2 line of text.

the

relative

The other parameter that determines what
the type looks like is the spacing between lines.
which

set

independently

of the

point

size.

Vertical spacing is measured from the bottom of
2.

Point Sizes; Line Spacing
As

mentioned above,

one line to the bottom of the next.
the command .ps

sets the point size. One point is 1/72 inch, so
6-point characters are at most 1/12 inch high,
and 36-point characters are s inch. There are 1§
point sizes, listed below.

ning text. it is usually best to set the vertical

spacing about 20% bigger than the character size.
- For example, so far in this document, we have

used “*9 on 11", that is,
9
.ps
vs llp

¢ powrt: Pack mwy boa wuk Rve dosn liguer jugs.

7 powai: Pack my box with five dozen liquor jugs.

8 point: Pack my box with five dozen liquor jugs.

9 point: Pack my box with five dozen liquor jugs.

If we changed to

10 point: Pack my box with five dozen liquor

.ps 9

11 point: Pack my box with five dozen

12 point: Pack my box with five dozen

14 point: Pack my box with five

16 point 18 point 20 point

22 24 28
If the number after .ps is not one of these
legal sizes, it is rounded up to the next valid
value, with a maximum of 36. If no number fol-

lows .ps, troff reverts to the previous size, whatever it was.,

troff begins with point size

which i3 usually fine.

10,

This document is in 9

poiat.

The point size can also be changed in the
middle of 2 line or even a word with the in-line

command \s. To produce
UNIX runs on a POP-11/45

\s8UNIX\s10 runs on a \s8PDP-\sl011/45
As above, \s should be followed by 2 legal point

size, except that \sO causes the size to revert to
Notice that \s10ll can be

understood correctiy as

size 10, {ciloweu by au

L', if the size is legal. but not otherwise.

.vs 9p
the running text would look like this.

After a

[ew lines, you will agree it looks a little cramped.
The right vertical spacing is partly a matter of
taste, depending on how much lext you want to
squeeze into a given space, and pardy 2 matter

of traditional printing style.
uses 10 on 12.

By default,

troff

Point size and vertical spacing
make a substantial difference in the
amount of text per square inch.
This is 12 on 14,
Poim mis and verucal specing maie & subsianual diferencs
the smount
of tent per squsre
mcn. For ezameie. |0 on 13 uses abows

rowce a8 Mvech soece 38 T on §.

This v & on 7, which 18 sven smalier.

pecis & I8t MOre words per ling. Dyt yOu caa §6 Blng trywng (O read i

When used without arguments, .ps and .vs
revert (o the previous size and vertical spacing

respectively.

The command .sp is used to get extra vertUnadorned, it gives you one extra
blank line (one :vs, whatever that has been set
to). Typically, that's more or less than you
ical space.

type

its previous value.

The com-

mand to control vertical spacing is .vs. For run-

cautious with similar constructions.

Relative size changes are aiso legal and
useful:

want,

so sp can be followed by
about how much space you wan{ -

information

.$p 2i
means 'two inches of vertical space’.

.Sp 2p
means ‘two points of vertical space’; and

SD 2
means ‘two vertical spacss’ = two of whatever

A Troff Tutorial

\fBbold\iP\fIfac=\[P\IR texi\(P

.v8 i$ set to (this can also be made explicit with

$p 2v): troff also undersiands decimal fractions
in most places. so

Because oanly the immediately previous foat is
remembered, you have (0 restore the previous

.sp 1.5

font after each change or vou can lose it.

is 2 space of 1.5 inches.

These same scale fac-

tors can be used after .vs to define line spacing.

argument.

There are other fonts available besides the
standard set. although you can still use oalv four

physical dimensions.

It should be noted that all size numbers
are converted internally to ‘machine units’,
which are [/432 inch (1/6 point). For most pur-

at any given time.
what

fonts

worry

representation.

about

the

The situation

accuracy

not quite

the

good vertically, where resolution is /144 inch

(172 pont).
J.

mounted

the

fp3H
says that the Helvetica font is mounted on posi-

tion 3.

(For a complete list of fonts and what

they look like, see the troff manual.) Appropriate

fp commands should appear at the beginning of

troff and the typesetter allow four different
fonts at any one ume. Normally three fonts
(Times roman, iwlic and bold) and one collection of special characters are permanently
mounted.
|
abedefghijkimnopqrstuvwxyz 0123456789
ABCDEFGHUKLMNOPQRSTUVYWXYZ

foats.

[t is possible 10 make a2 document celalively independent of the actual (onts used (o
print it by using font numbers instead of aames;

for exampie, \{3 and .f1"3 mean ‘whatever font
is mounted at position J°, and thus work for any
setting.

Normal settings are roman fonat oa 1.
italic on 2, bold oa 3, and special on 4.

abedesg hijklmnopqrsuvwxyz 0123456789
ABCDEFGHIIKLMNOPQRSTUYWXYZ

There is alsoc 2 way to get ‘synthetic’ bold
fonts by oversiriking letters with 3 slight ctfsst.

abedefghijkimnopqrstuvwxyz 0123456789

Look at the .bd command in (1].

ABCDEFGHIJKLMNOPQRSTUYWXYZ

The greek, mathematical symbols and miscellany
of the special font are listed in Appendix A.

troffl prints in roman uniess old otherwise.
To switch into bold, use the .ft command
B

Special
characters
have
names beginning with \(. and
inserted anywhere. For example.

four-character
they may be

Yo 4 1y = Y

is produced by

and for italics,

\(14 4+ \(12 = \(34

qul

In particular, greek letters are all of the form

To return t0 roman, use .ft R: to return to the
previous font, whatever it was, use either .ft P oc
just [t. The ‘underline’ command
ul

\(e=, where = is an upper or lower case roman
letter reminiscent of the greek. Thus to get

L(axB) = ca
in bare troff we have (o type

.ul

can be f{ollowed by a count to indicate that more
than ode line is to be (talicized.

Fonts can aiso be changed within 2 line or
word with the in-line command \{:

boldface text
is produced by

\{Bbold\fIface\(R text
If you want 0o do this so the previous foat,
whatever it was, 1S left undisturbed, insert extra

\fP commands. like this:

The command .{p tells troff
physically

your document if you do not use the standard

Fonts and Special Characters

causes the next input line to print in italics.

are

typesetter:

poses, this is enough resolution that you doa't
to

The

same is true of .ps and .vs when used without an

and in fact after most commands that deal with

have

5-85

\ (S (\ (ea\ (mu\ («b) \(=> \ (i
That line is unscrambled as follows:

\ (=S

(
\ (-2
\{mu
\ (b
)
\(=>

\Gf

(
e
X
g
)
e
o

A complete list of these special names occurs in
Appendix A.

5-8 A Troff Tutorial

In eqn (2] the same effect can be achieved

Pater
noster
qui
est
in
caelis
sanctificetur nomen tuum: adveniat
regnum tuum; fiat voluntas tua, sicut
in caelo, et in terra. ... Amen.

with the input

SIGMA ( alpha times beta ) = > inf
which is less concise, but clearer to the uninitiated.

Notice that each four-character name is a
single character as {ar as troff is concerned = the
‘translate’ command

Notice the use of ‘+' and ‘=" to specify the
amount of change. These change the previous
setting by the specified amount, rather than just
overriding it.

them one inch long.

2 \(mi\(em

With .in. .l and .po, the previous value is
used if no argument is specified.

is perfectly clear, meaning
Af =

To indent a single line, use the ‘temporary

that is. to translate = into =,

Some
translated

into

The distinction is quite imporiant:

Jl +1i makes lines one inch longer: .I1 1i makes

characters

are

others: grave

automatically
and acute

indent’ command .ti. For example, all paragraphs
in this memo effectively begin with the command

accents (apostrophes) become open and close

A1 3

single quotes *TM"; the combination of **..."”" is generally preferable to the double quotes °...°. Simi-

Three of what?

larly a typed minus sign becomes a2 hyphen -. To

explicit

sign,

use \-. To

get

backslash printed, use \e.
4. Indents and Line Lengths

trofl starts with a line length of 6.5 inches,

too wide for 8%xll paper. To reset the line
length, use the .l command, as in

1 6i
As with .sp, the actual length can be specified in
several ways: inches are probably the most intui-

tive,

The maximum line length provided by the

typesetter is 7.5 inches, by the way.

To use the

full width, you will have to reset the default physical left margin (“*page offset’”), which is nor-

mally slightly less than one inch from the left

edge of the paper. This is done by the .po command.

.po), is ems; an em is roughly the width of the
letter ‘m’ in the current point size.

(Precisely, a
em in size p is p points.) Although inches are
usually clearer than ems (o people who don’'t set

type for a living, ems have a place: they are a
measure of size that is proportional to the
current point size. If you want to make text that
keeps its proportions regardless of point size., you
should use ems {or all dimensions. Ems can be

specified as scale factors directly, as in .ti 2.5m.

Lines can also be indented negatively if the
indent is already positive:

i =030
causes

the

next line

teaths of an inch.

The indent command .in causes the left
margin 0 be indented by some specified amount

from the page offset.

[ we use .in to move the

left margin in. and .1l t0 move the right margin
to the left, we can make offset blocks of text:

in Q.34

J =0
3§
text to be set iato a block

Al +0.31
in =Q.3i
will create a biock that looks like this:

moved back three

maand:
noster

i~ sanctificetur

sets the offset as far 10 the left as it will go.

to be

Thus to make a decorative

initial capital, we indent the whole paragraph,
then move the letter *P° back with a3 .ti comY dter

.po 0

The defauit unit for .ti, as for

most horizontally orieated commands (Il .in.

qui

est

nomen

caelis

tuum;

ad-

veniat regnum tuum; at volun-

ag tua, sicut in caelo, et in terra. ..
Amen.

Of course, there is ilso some trickery to make
the *P° bigger (just a “\s36P\s0"), and to move it
down from its normal position (see the section
on local motions).

5. Tabs
Tabs (the ASCII ‘horizontal tab’ character)
can be used (0 produce output in columns. or L0
set the horizontal position of output. Typically

tabs are used only in unfilled text. Tab stops are
set by default every haif inch from the curreat
indent, but can be changed by the .ta comman

To set stops every inch. for example.

A Troff Tutorial 5-87

a2 1i 21 3t 44 §i 6i

Unfortunately the stops are left-justified

only (as oa a typewriter), so lining up columns
of right-justified numbers can be painful. [ you
have many numbers. or if you need more complicated table layout, doa't use troff directly. use

the tbl program described in (3].

.af

Then change each leading blank into the string
\0. This is a character that does not print, but

that has the same width as a digit.

When

3
60
900

2
50
800

It is also possibie 0 fill up tabbed-over
space with some characier other than blanks by
setting the ‘tab replacement character’ with the
*

N\ (eu is °.")

Name

smaller,

bracket

with

point size, be sure to put them either both inside

Sometimes the space given by \u 2and \d
isn't the right amount. The \v command can be
used to request an arbitrary amount of vertical
motion. The in-line command
\v (amount)’
causes

motion

up or down

the

page

the

.in +0.6i
J-0.3%
A ~=0.3i

(move paragraph in)
(shorten lines)
(move P back)
\v'2\s36P\sO\v
= 2"ater noster qui est
in caelis ..

A minus sign causes upward motion, while no

There are many other ways to specifv the
ammount of motion —
Age

the tab replacement character

(o a

tion 6.)

\v'0.11°
\v3p’
\v' =0.5m’
and so on are all legal.

Notice that the scale

specifier { or p or m goes inside the quotes. Aay

troff also provides a very general mechanism called ‘fields’ for setting up complicated

(This is used by thl).

We will not go

into it in this papes.
6.

‘2°

line spaces.

blank, use .ic with no argument. (Lines can also
be drawn with the \| command, described in Sec-

columns.

the

sign or a plus sign means down the page. Thus

produces

ceset

make

\s=2..\s0. Since \u and \d c=fer to the current

\v'=2’ causes an upward vertical motion of two

Name wb Age b

amount specified in ‘(amount)’. For example. to
move the ‘P° down, we used

printed, this will producs

L2 1.5t .58
e\ (eu

Area = wr°

an unbalanced vertical motion.

A command:

produces

or both outside the size changes, or you wiil ge:

Aa li 2 3i
3
2 wmb
l wb
0 ws 50 wb 60
700 tab 800 wb 900

Area = \(=pr\u\d

For a handful of numeric columns, you
can do it this way: Precede every number by
enough blanks to make it line up when (yped.

1
40
700

local motions \u and \d. To go back up the pag=
half a point-size, insert a \u at the desired place:
to go down, insert a2 \d. (\u and \d should always
be used in pairs. as explained below.) Thus.

Local Motions: Drawing lines and charac-

{ers

Remember ‘Area = 7¢°’ and the big P’

in the Paternoster.

How are they doane?

troff

provides a host of commands for placing characters of any size at any place.

You can use them

character can be used in place of the quotes: this

is also true of all other troff commands described
inn this section.

Since troff does not take within-the-line
vertical motions into account when figuring out

where it is on the page. output lines can have
unexpected positions
'if the left and right ends
aren't at the same vertical position. Thus \v,
like \u and \d. should aiways balance upward
vertical motion in a4 line with the same amount
in the downward direction.

to draw special chiaracters or to tune your output

Acrbitrary horizontal motions ace also wail.

for a particular appearance. Most of these commands are striighttorward, but messy (0 read

able = \h is quite analogous to \v. except that
the default scale f{actor is 2ms instead of line

and tough to type correctly.

spaces.

[f you won't use eqn, subscripts and super-

scTipts are most easily done with the haif-line

As an example,

\RT=0.
17

5-88 A Troff Tutorial

sysiéme télephonique

causes a backwards motion of a tenth of an inch.
As

practical

matter,

coasider

mathematical symbol *> >°.

printing

the

The default spacing

i$ t0o wide, so eqn replaces this by

command. \zx suppresses the normal horizontal

to produce >>,

Frequently \h is used with the ‘width function’ \w to generate motions equal to the width
of some character string. The construction

\w'thing’
to the width of ‘thing

machine units (1/432 inch).
tions are

ultimately

remember that each is just one character to troff.

You can make your own overstrikes with
another special conveation., \z, the zero-motion

>\h'=0.3m">

IS a number equal

The accents are \(ga and \(aa, or \" and \’;

done

motion after printing the single character x, so
another

character

can

Although sizes can

laid

be changed

top

within \o,

it
centers the characters oa the widest, and there

can be no horizontal or vertical motions, so \z
may be the only way to get what you want:

All troff computathese

units.

move horizontally the width of aa ‘x’, we can
sy

is produced by

\n\woxoua

Sp 2

\s8\z\ (sq\s14\z\ (sq\s22\z\ (sq\s36\ (sq

As we mentioned above, the default scale factor

for all horizoatal dimensions is m. ems, so hese
we must have the u for machine units, or the

motion produced will be far oo large. troff is
quite happy with the nested quotes, by the way,

The .sp is nesded to leave room for the result.
As another example, an extra-heavy semicolon that looks like

30 long as you don't leave any out.

y instead of ; or |

As a live example of this kind of construction. all of the command names in the text, like

Sp, were done by oversturiking with a slight
offset. The commands for .sp are

Sp\h’ =\w".sp'u’\h'lu".sp

can be constructed with a big comma and a big
period above it

\s+80\z\v'=0.25m"\v'0.25m"\s0
*0.25m" is an empirical constant.

That is, put out ‘.sp’, move left by the width of
*.sp°, move right | unit, and print ‘.sp’ again.

(Of course there is a way to avoid typing that

much input for each command name, which we
will discuss in Section 11.)

A more ornate overstrike is given by the

bracketing function \b, which piles up characters
vertically,

‘Unpaddable’ means

the

current

baseline.

There are also several special-purpose troff

the same width as a digit.

with piled-up smaller pieces:

commands for local motion.

We have aiready
seen \0, which is an unpaddable white space of

centered

Thus we can get big brackets, constructing them

by typing in only this:

that it will never be widened or split across a line

\bA I\ (Ik\ (16" \BA I\ (I x \B\ (e (e \ b\ (21\ (£k\ (¢d’

line justification and filling.

There is also

\(blank). which is an unpaddable character the
width of a space, \| which is half that width, \°,

which is one quanter of the width of 2 space, and

\&, which has zero width.

(This last one is use-

ful, for example, in entering a text line which
would otherwise begin with a *.".)

The command \o. used like

\o’set of characters’
causes (up to 9) characters to be oversiruck, centered on the widest.

This is nice for acceats, as

syst\o”e\ (ga"me \o"e\(aa"No"e\ (aa"phonique
which makes

troff also provides a coavenient facility for
drawing horizontal and vertical lines of arbitrary
length with arbitrary characters. \I'li’ draws a
line one inch long, like this:

The length can be followed by the character to
use if the . isa't appropriate; \I'0.5i.' draws a
half-inch line of dots: ............... The construce
tion \L is entirely analogous, except that it draws
a vertical line instead of horizontal.

7. Strings

Obviously

paper

contains

large

number of occurrences of an acute accent over a
letter ‘e’,

typing \o"e\TM for each & would be a

A Troff Tutorial 5-89

great nuisance.

Fortunately. troff provides a way in which
you can store an arbitrary collection of text in a

that would be treated by troff exactly as
.$p

"string’. and thereafter use the siring name as a
shorthand for its contents.

A1 +2m

Strings are one of

several

trofl mechanisms whose judicious use
lets you type a document with less effort and
organize it so that extensive format changes can

PP is called a macro. The way we tell troff what
PP means is 10 define it with the .de command:
.de PP

be made with few editing changes.

A ceference (0 a string is replaced by what-

ever text the string was defined as.

Strings are

defined with the command .ds. The line
.ds e \o"e\"TM

defines the string e to have the value \0"e\TM
String names may be either one or two
characters long, and are referred 0 by \ex for

one character names or \e(xy for two character
names.
Thus (o get 1iéléphone, given the
definition of the string e as above, we can say
t\eei\ sephone.

The first line names the macro (we used °.PP°
for ‘pacagraph’, and upper case so it wouldn't
conflict with any name that troff might already
know about). The last line .. marks the ead of
the definition. [n betwes=n is the text, which is
simply inserted whenever troff sees the ‘command’ or macro call

If a string must begin with blanks, define it

A macro can contain any mixture of text and
formatting commands.

ds xx °

The definition of .PP has to precede its
first use; undefined macros are simply ignored.

text

The double quote signals the beginning of the
definition. There is no trailing quote: the end of
the line terminates the string.
A sturing may actually be several lines long;

if troff encounters a \ at the end of any line, it is
throwa away

and the next line added

the

current one. So you can make a long string simply

A +2m

ending

each

line

but

the

last

with a2

backsiash:

Names are restricted to one or two characters.

Using

occurring

Not only does it save typing, but it makes later

Suppose we decide that
the paragraph indent is (0o small. the vertical
space is much too big, and roman font should be

forced.

Instead of changing the whole docu-

ment, we need only change the definition of .PP

.de PP

Sp 2p

long string

\° parageaph macro

Al +3Im

Strings may be defined in terms of other
strings, or even in terms of themselves; we will

discuss some of these possibilities later.

and the change takes effect everywhere we used

PP,

§. Introduction to Macros

Before we can go much further in troff, we
rreed to learn a bit about the macro [acility.

its simplest form, 3 macro is just a shorthand
Suppose we

want every paragraph to start in exactly the same

-- with a space and a temporary indent of

Iwo ems:

\" is a troff command that causes the rest

of the line to be ignored.

4 +2m

Then 0 save typing, we would like to collapse
these into one shorthand line. a troff ‘command’

We use it here 10 add

comments to the macro definition (3 wise idea

once definitions get complicated).

As another example of macros. consider
these two which start and end a block of offset.

unfilled text, like most of the examples in this
papes:

.Sp

commonly

changes much easier.

is a very \

way

for

to something like

.ds xx this
\

notation quite similar to a swring.

macros

sequences of commands is critically important.

5-90 A Troff Tutorial

.de BS

\" start indented block

Then we space down half an inch, print the title

af
in +0.3i

.de BE

issue a ‘begin page' command "Bp. which causes

a skip to top-of-page (we'll explain the " shortly).
(the use of .t should be self explanatory: later
we will discuss parameterizing the titles), space

\" end indented block

another 0.3 inches, and we're done.
To ask {or NP at the bottom of each page.

A
ia =0.3i

we have 10 say something like ‘when the text is

within an inch of the bottom of the page, start

the processing for a new page.’ This is done with
a ‘when’ command .wh:

Now we can surround text like

.wh

Copy to
John Doe
Richard Roberts
Stanley Smith

by the commands .BS and BE, and it will come
out as it did above. Natice that we indented by
ia +0.3i instead of .in 0.3i. This way we can
nest our uses of .BS and BE (o get blocks within
blocks.

(No *.° is used before NP:. this is simply the
name of a macro, not a macro call.) The minus
sign means ‘measure up from the bottom of the
page’, so ‘= 1i" means ‘one inch from the bottom’.
The .wh command appears in the input
outside the definition of .NP; typically the input
would be

If later on we decide that the indent shouid
be 0.5i, then it is only necessary to change the
definitions of .BS and .BE, not the whole paper.

.de NP

wh =1§ NP

9. Titles, Pages and Numbering

This is an area where things get tougher,
because nothing is done {or you automatically.
Of necessity, some of this section is a cookbook,
to be copied literally until you get some experience.

Suppose you want a title at the top of each

page, saying just
—left top

=1i NP

center 0p

right topTM

In roff, one can say

.he ‘left top’center topright top’
Lo ‘left bottom’center bottom right bottom’
to get headers and (ooters automatically on every
page. Alas, this doesn't work in troff, a serious
hardship for the novice. Instead you have to do
a lot of specification.

You have 10 say what the actual tite is

(easy); when to print it (easy enough); and what
o do at and around the title line (harder). Taking these in reverse order, first we define a
macro NP (for ‘new page’) to process titles and
the like at the end of one page and the beginning

of the aext:
.de INE
bp

'sp 0.5i
U “left top’center top’right top’
‘sp 0.3i

Now what happens? As text is actually
being output, trofl keeps track of its vertical
posilion on the page, and after a line is printed
within one inch {rom the bottom, the .NP macro

is activated. (In the jargon. the .wh command
sets a map at the specified piace. which s
‘sprung’ when that point is passed.) .NP causes a
skip to- the top of the next page (that's what the
‘bp was for), then prints the titde with the
appropriate margins.

Why Bp and 'sp instead of .bp and .sp?
The answer is that .sp and .bp, like several other
commands, cause a break 10 take place. That is.
all the input text collected but not yet printed is

flushed out as soon as possible, and the next
input line is guaranteed to start a new line of

output. If we had used .sp or .bp in the .NP
macro, this would cause a break in the middle of
the

current

line

when

new

page

lowed by the next input line on a new output

line. This is nor what we want. Using ' instead
of . for a command tells troff that no break is to
take

place

the output

line

currently

being

filled should nor be forced out before the space
or new page.

The list of commands that cause a break is
short and natural:

bp
To make sure we're at the top of a page. we

output

started. The effect would be to print the leftover part of that line at the top of the page, fol-

.af

Al cthers cause rnc break, recardless of whether

A Troff Tutorial 5-91

you use a . or a2 . If you really ne=d a break, add

10. Number Registers and Arithmetic

a .br command at the appropriate place.

troff has a facility for doing arithmetic., and
for defining and using variables with numeric

One other thing to beware of — if you're
changing fonts or point sizes a lot, you may find
that if you cross 2 page boundary in an unexpected font or size, your titles come out in that
size and f(ont instead of what you intended.
Furthermore, the leagth of a title is independent
of the current line leagth, so titles will come out
at the default leagih of 6.5 inches. unless you
change it, which is done with the .It command.

There are several ways to fix the problems
of point sizes and fonts in titles. For the simplest applications, we can change .NP (o set the
proper size and (ont for the title, then restore
the previous values, like this:

.de NP
bp

‘sp 0.5i
JtR

\" set title font to roman
.ps 10
\" and size to 10 point
Jt 6i
\’ and length to 6 inches
Al “left’center right’
.ps
\° revert 10 previous size
ftP
\" and to previous f{ont

values, called aumber registers. Number registers, like strings and macros. can be useful in
setting up a document sO it is easy 0 change

later.

Like strings, number registers have one or
two character names. 1They are set by the .ne
command, and are referenced anywhere by \nx

(one character name) or \a(xy (two character

name).
There are quite a few pre-defined number
registers maintained by troff, among them % (or
the current page number; al for the current vertical position on the page: dy., mo and yr for the
current day, month and year: and .8 and .[ for
the current size and font. (The font is 2 aumber
from | to 4.) Aay of these can be used in comsputations like any other register, but some, like

.8 and .{, canno¢ be changed with .ar.
As an example of the use of number regis-

ters, in the =-ms macro package (4], most
significant parameters are defined in terms of the
values of a handful of number registers. These

‘sp 0.3i
[-2
4

This version of NP does nor work if the
fields in the .Ul command contain size or font
changes. To cope with that requires tmfl's
‘eavironment’ mechanism, which we will discuss
in Section 13.
To get a footer at the bottom of a page.
you can modify NP so it does some processing

include the point size [oc text, the vertical spacing, and the line and title lengths. To set the
point size and vertical spacing {or the following
paragraphs, for example, a user may say

nrPsS9
qar VS 11

The paragraph macro .PP is defined (roughly) as
follows:

before the bp command, or split the job into a
(ooter macro invoked at the bottom margin and

.de PP

a header macro invoked at the wop of the page.
These variations are left ag exercises.

Qutput
page
numbers are computed
automatically as each page is produced (starting
at 1), but no numbers are printed unless you ask
for them explicitly.
To get page numbers
printed, include the character % in the .U line at
the

position

where

you

want

the

aumber

this page. You can set the page number at any
ime with either .bp n, which immediately starts
the

numbered g, or with

page

JtR
.5p 0.5v
2 +3m

\* foat
\" half a line

and line spacing to whatever vilues are stored in

the number registers PS and VS.

Why are there two backslashes?

centers the page number inside hyphens, as on

new page

\" reset size
\" spacing

This is

the eternai probiem of how to quote a quote.

A e % .7

sets

.ps \\n{(PS
v$ \\n(VSp

This sets the font (0o Romaa and the point size

appear. For example

And of course they serve for any soct of

arithmetic computation.

number for

the

.pa n. which

page

but

doesn’t cause a skip to the new page. Again.
.bp +n sets the page number (0 n more than its

current value: .bp means .bp +1.

When troff originally reads the macro definition,
it peels off one backslash to ses what's coming
aext.

ensure

that

another

igs

left

the

definition when the macro is used, we have to
put in two backslashes in the definition. [f only
one

backslash is used,

point size and verucal

spacing will be frozen at the ume the macro is

defined. not when it is used.
Protecting by an extra layer of backslashes

5-92 A Troff Tutorial

is only needed for \a. \e, \$ (which we haven't

ar 1 7v/2
AP \\n(llu

come (0 vet), and
\ iself. Things like \s. \f. \h,

\v, and so oa do not need an extra backslash,

since they are converted by troff to an internal
code immediately upon being seeq.
Arithmetic

expressions

can

where that a2 number is expected.

appear

any-

As a twivial

example,

The next step is to define macros that can
change from one use to the next according to

reiational operators >, >=,

£,

= and

'= (not equal), and parentheses.
Although the arithmetic we have done so

far has been straightforward, more complicated
things are somewhat tricky. First, number regishold onily

integers.

integer

troff arithmetic uses
division, just like Fortran.

Second, in the absence of parentheses, evaluation i3 done left-to-right without any operator

precedence
Thus

(including

relational

operators).

To=d+3/13
becomes *—1°.

To make this

work, we need two things: first, when we define

decrements PS by 2. Expressions can use the
arithmetic operators +, =, «, /, % (mod), the

truncating

11. Macros with arguments

parameters supplied as arguments.

e PS \\a(PS =2

ters

does just what vou want, so long as you don't
forget the 4 on the .l command.

the macro, we have to indicate that some parts

of it will be provided as arguments when the
macro is called. Then when the macro is cailed
we

have

provide

actual

argumentss

plugged into the definition.

Let us illustrate by defining a macro .SM
that will print its argument (wo points smaller
than the surrounding text.

That is, the macro

call

SM TROFF
will produce TROFF.

The definition of .SM is
.de SM

Number registers can occur any-

where in an expression. and so can scale indica-

tors like p, i, m, and so on (but no spaces).
Although integer division causes truncation, each

number and its, scale indicator is converied to
machine units (1/432 inch) before any arithmetic
is done, so li/2u evaluates to 0.5i correctly.
The scale indicator u often has to appear
when you wouldn't expect it = in particular,
when arithmetic is being done in 2 context that
implies horizoatal or vertical dimensions.

For

example,

\s=2\\Sl\s+2
Within 2 macro definition. the symbol \\Sa
refers 10 the ath argument that the macro was
called with. Thus \\$1 is the string to be placed
in a smaller point size when .SM is called.
As a slightly more complicated version, the

following definition

of .SM

permits

optional

second and third arguments that will be printed

in the normal size:

.de SM

WSA\s=2\S1\s +2\\S2

M T7/2
would seem obvious enough - 3% inches.
Sorry. Remember that the defauit units for horizontal parameters like .1l are ems.

That's really

*T ems / 2 inches’. and when t(ranslated into
machine units, it becomes zero.

How about

Sorry, still no good - the ‘2" is ‘2 ems’. so
It/
<" 18 small, although not zero.

the

macro

SM TROFF ),
produces TROFF), while

SM TROFF ). (

A T2
oMo paBQ

Arguments not provided when
called are treated as empty, so

You muse use

A 7i/ 24
So again. a safe rule is to attach a scale indicator
o every number, even constants.

For arithmetic done within a2 .nr command,
there is no implication of horizontal or vertical

dimension, so the default units are ‘units’, and

7i/2 and 71/2u mean the same thing. Thus

produces (TROFF).

[t is convenient 0 reverse

the order of arguments because trailing punciuation is much more common than leading.

By the way, the number of arguments that
a macro was called with is available 11 number

The following macro .BD is the one used
to make the ‘bold roman’ we have beea using

for troff command names in text [t combines
horizontal motions. width computations. and
argument rearrangement

A Troff Tutorial 5-93

.de BD

with something like

VEMNSINCINSIVR =\ w \ ST u+ 1 \\SI\[P\\$2
The

and

commands

need

ds CT -% -

exira

backslash, as we discussed above. The \& is
there in case the argument begins with a period.

Two backslashes are needed with the \\Sa
commands, though. to protect one of them when

the macro is being defined.
example

will

make

this

Perhaps a second

clearer.

Consider

macro called SH which produces section headings rather like those in this paper, with the sec-

tions numbered automatically, and the title in
bold in a smaller size. The use is

to give just the page number betwesa hvpnens

(as on the top of this page). but a user could

supply private definitions for any of the strings.
12. Conditionals

Suppose we want the .SH macro to leave

two extra inches of space just before section 1,
but nowhere else. The cleanest way to do that is

to test inside the .SH macro whether the section

number is |. and add some space if it is. The .if
command provides the conditional test that we

can add just before the heading line is output:

A \\n(SH=| _sp 2i

SH “Section title ...

(If the argument to a macro is to conuin blanks,

thea it must be surrounded by double quotes,
unlike a string, where only one leading quote is

permitted.)

Here is the definition of the .SH macro:
e SH O
.de SH

\" initialize section number

\" first section oaly

The condition after the .if can be any

arithmetic or logical expression.

If the condition

is logically true, or arithmetically greater than
zero. the rest of the line is treated as if it were
lext

—

here a2 command.

[f the condition

false, or zero or negative, the rest of the line is
skipped.

It is possibie to do more than one com-

3p 0.3i

ft'B

a0 SH\\a(SH+1
.ps \\a(PS—1
Wa(SH. \\St
-ps \\n(PS
.$p 0.3i
JtR

\” increment number
\* decrease PS

\" number. title

mand if a condition is wrue. Suppose several
operations are to be done before section 1. One
possibility is (0 define 2 macro Sl and invoke it
if we are about to do section | (as determined by

an .if).

\" restore PS

.de S1
--

The section number is kept in number register
SH, which is incremented each time just before it
is used. (A number register may have the same

processing for seczion | -

:&e SH

if\\n(SH=1 St

name as a macro without conflict but a string

may not.)

We used \\a(SH instead of \n(SH and
Wa(PS instead of \a(PS. If we had used \n(SH,
we would get the value of the register at the time

the macro was defined, not at the time it was

used. [f that's what you want, fine, but not here.
Similarly, by using \\a(PS. we get the point size
at the time the macro is called

An alternate way is to use the extended
form of the .if, like this:

A \\n(SH
=1 \{-- processing
foe section | —-\}

The braces \{ and \} must occur in the positions
shown or you will get unexpecied extra lines in
troff aiso provides an ‘if-else’ con-

your output.
As

example

that

does

not

invoive

aumbers, recall our .NP macro which had a

.t “left’center’right’

We could make these into parameters by using
insiead

A N\(LT\\«(CT\\«(RT
so the title comes {rom three strings cailed LT,

CT and RT.

If these are empty. then the tisle

will be a blank line.

Normaily CT would be set

struction, which we will not go into here.
A condition can be negated by precading it
with !, we get the same effect as 1bove (but less

clearly) by using

A N\n(SH>1 S1

There are a handful of other conditions
that can be tested with .if. For exampie. is the
current page even or odd?

5-94 A Troff Tutorial

version shown keeps all the processing in one

if e .t “even page title”
if 0 .Ul “odd page title”

place

gives facing pages different titles when

used

inside an appropriate new page macro.

Two other coaditions are t and a. which
tell you whether the formatter is troff or nroff.

does °‘stufl” if sering! is the same as sring2. The
character separating the strings can be anything
reasonable that is not contained in either string.

The strings themselves can reference strings with

\*, arguments with \$, and so on.

(0o

understand

and

14. Diversions

There are numerous occasions in page layout when it is necessary to store some text for a

Foot-

the footnote usually appears in the input well
before the piace on the page where it is (0 be
printed is reached.

In fact, the place where it is

implies that there must be a way to process the

footnote

least

enough

decide

its

size

without printing it.

troff provides 3 mechanism called a diversion for doing this processing. Any part of the
output may be diverted into 2 macro instead of

being printed, and then at some convenient time

13. Eavironments
there

is a potential

problem when going across a page boundary:

parameters like size and font for a page title may

well be different (rom those in effect in the text
when the page boundary occurs.

troff provides a

very general way to deal with this and similas

situations. There are three ‘eavironments’, each
of which has indeperidently settable versions of
many of the parameters associated with processing, including size, font,-line and title lengths,
fill/nofill mode, b stops. and even partiaily collected lines.

easier

output normally depends on how big it is, which

if “stringlstring2” souff

mentioned,

thus

notes are the most obvious example: the text of

Finally, string comparisons may be made
in an .if°

period of time without actually printing it.

Af t troff stuff ...
Aif n aroff stuff ...

and

change.

Thus the titling problem may be

readily solved by processing the main text in one
environment and titles in a separate one with its
own suitable parameters.

The command .ev n shifls to environment

n; 8 must be 0, | or 2. The command .ev with
noe argument returns (0 the previous egviron-

ment. Environment names are maintained in a
stack, so calls for different environments may be
nested and unwound consistently.

Suppose we say that the main text is processed in eavironment 0. which is where troff
begins by defauit. Then we can modify the new
page macro .NP (o process titles in eavironment
l like this:

the macro may be put back into the input.

The command .di xy begins a diversion =
all subsequent output is collected into the macro
Xy until the command .di with no arguments is

encountered.
This terminates the diversion.
The processed text is available at any time
thereafter, simply by giving the command
XY

The vertical size of the last finished diversion is
contained in the built-in number register dn.

As a simple example. suppose we want (0
implement a ‘keep-release’

operation.

that

text between the commands .KS and .KE will not

be split across a page boundary (as for a figure or

table).

Clearly, when a KS is encountered, we

have to begin diverting the output so we can find

out how big it is.

Then when a .KE is seen, we

decide whether the diverted text will fit on the
current page, and print it either there if it fits, or

at the top of the next page if it doesn’t. So:

.de KS
.br
ev |
A

di XX

\° start keep
\" start fresh line
\* collect in new eavironment
\" make it filled text

\" collect in XX

.de NP

ev i
At 6i
Lt R
.ps 10

\® shift t0 new eavironment
\" set parameters here

... anly other processing ...

\" return (o previous enviroament

.de KE
\" end keep
br
\" get last partial line
di
\" end diver<inn
Af\\n(dn> =\\n(.t .bp \" bp if doesn’t tit
af
\" bring it back in no-{ill
XX
\" text
eV
\" return to normal eavironment

[t is also possible to initialize the parameters for
an eaviroament outside the NP macro, but the

Recall

that

number register

the

current

A Troff Tutorial 5-95

position on the output page. Since output was
being diverted. this remains at its value when the

diversion started. dn is the amount of text in
the diversion; .t (another built-in register) is the

distance (o the next trap. which we assume (s at
the bottom margin of the page. [f the diversion
is large enough (0 go past the trap, the .if is
satisfied, and a .bp is issued. [n either case, the

divested output is then brought back with .XX. [t
is essential to bring it back in no-fill mode so
troff will do no further processiag on it.

This is not the most general keep-release,
nor is it robust in the face of all conceivable
inputs, but it would require more space than we
have here to write it in {ull generality. This section is not intended to teach everything about
diversions., but to sketch out eaough that you
can read axisting macro packages with some
comprehensiorn.

Acknowledgements

[ am deeply indebted to J. F. Ossanna. the
author of trofl, for his repeated patient explana.
tions of fine poiats, and for his continuing willingness to adapt troff to make other uses easier.
[ am also grateful to Jim Blinn, Ted Dolotia,

Doug Mcliroy, Mike Lesk and Joel Sturman for
helpful comments on this paper.
References

(1]

(2]

(3]

(4]

Ossanna,

~NROFFITROFF

User's

Manual, Bell Laboratories Computing Science Technical R:port 54, 1976.

B. W. Kerighan, 4 System for Tvpesetting

Mathematics = User's Guide (Second Edition), Bell Laboratories Computing Science
Technical Report 17, 1977.

M. E. Lesk, TBL = A Program to Formar

Tables. Betl Laboratories Computing Science Technical Repoct 49, 1976.

M. E. Lesk, Typing Documents on UNIX,
Bell Laboratories, 1978.

(5]

J. R. Mashey and D. W. Smith, PWB/AM
- Programmer's Workbench Wemorandum
intemal
Laboratories
Beil
Wacros,

memorandurm.

5-96

A Troff Tutorial

Appéndix A: Phototypesetter Character Set
These characters exist in roman, italic, and bold.

To get the one on the left, type the four-character

name on the right.

ff \(f

®
®

- \(em
° \(de
e \(bu

\ru
\(co
\(rg

\(f

i \(Fi

ffl \(Fi

s \(14
a \(12
t \(dg
"
\(fm
O \(sq
- \(hy
(In bold, \(sqis ®)

\({fl

Yo \(34
¢ \(ct

The following are special-font characters:

\(pl

\(mi

\(mu

\(di

\(eq

\(lm

\(==
\(+-

\(>=
\(no

<€

(<=

~
-

\(ap
\G>

\Gs

=
-

\(=
\(<-

\(pd

«
1

\(pt
\(ua

\(if

vV
|

\(gr
\(da

\(sb

\sp

\lcu

\(ca

\(ib

\(aa

\(ga

€

\(mo

\(ci

\(bs

§
([

\(sc
\(t

t
)

w
[

\{f

w
]

\(rh
\(rc

\(b

\(lh
\c

}

\(dd
\ (rt

\(br

\(rk

\(bv

\(ts

{

\ (Ik

\(rb
\lor

\ul

\(sl

\sr

\(es

\Gf

\(rn

\(at

These four characters also have two-character names. The * is the apostrophe on terminals; the ' is the
other quote mark.

These characters exist only on the special font, but they do not have four-character names:

)

For greek, precede the roman letter by \ (¢ to get the corresponding greek; for example, \(*a is a.
abgdezyhiklImncoprstufxqw
afBydel{mbikAuvéomporTvodyvow

ABGDEZYHIKLMNCOPRSTUFXQW

ABTAEZHO
I KAMNEOINNPZTY®PXVQ

A System for Typesetting Mathematics

5-97

A System for Typesetting Mathematics
Brian W. Kernighan and Lorinda L. Cherry
Bell Laboratories
Murray Hill, New Jersey 07974

ABSTRACT
This paper describes the design and implementation of a system for typesetting
mathematics.

The language has been designed to be easy to learn and to use by people

(for example. secretaries and mathematical typists) who know neither mathematics nor
typesetting.

Experience indicates that the language can be learned in an hour or so. for

it has few rules and fewer exceptions.

For typical expressions. the size and font

changes,

the

positioning,

line

drawing,

and

mathematical conventions are all done automatically.

necessary

according

For example, the input

sum from i=0 to infinity x sub i = pi over 2
produces

Zx=

The syntax of the language is specified by a small context-free grammar; a
compiler-compiler is used to make a compiler that translates this language into typesetting commands.

Output may be produced on either a phototypesetter or on a terminal

with forward and reverse half-line motions.

The system interfaces directly with text

formatting programs, so mixtures of text and mathematics may be handled simply.
This paper is a revision of a paper originally published in CACM, March, 1975.

character of mathematics, which the superscript

Introduction

‘*Mathematics
difficult,

or penalty,

is known

copy because

the
it

trade as
is slower,

and limits in the preceding example showed in its
simplest form. This is carried further by

more difficult, and more expensive to set in type
a0

than any other kind of copy normally occurring

in books and journals.” {1]

One difficulty with mathematical text is the
muitiplicity of characters, sizes, and fonts.

expression such as

as+ -

and still further by

lim (tan x)¥" % = |

Rl TR

]

requires an intimate mixture of roman, italic and
greek letters, in three sizes, and a special charac-

ter or two.

(‘*Requires’ is perhaps the wrong

word, but mathematics has its own typographical

conventions which are quite different from those

of ordinary text.) Typesetting such an expression
by

traditional

methods

still

essentially

manual operation.

A second difficulty is the two dimensional

log JaeTM—b

Zrnsab
r

]

J ae'’"s —be ="

VaeTM +Jb

ey
N ey

m~ab an
"‘

‘We /

- ] \/; "~

th~='(
vasO

TM)

These examples also show line-drawing, built-up
characters like braces and radicals. and a spec-

trum of positioning problems.

(Section 6 shows

5-98 A System for Typesetting Mathematics

what a user has to type to produce these on our

without limit.

system.)

Third. ‘‘standard’” things should happen
automatically.
Someone
who
types
“xmy<z+]" should get ‘“‘xmy+4+:+=]"". Subscripts and superscripts should automatically be
printed in an appropriately smaller size, with no
special intervention. Fraction bars have to be
made the right length and positioned at the right

Photocomposition

Photocomposition techniques can be used
to solve some of the problems of typesetting
A phototypesetter 1s a device
mathematics.
which exposes a piece of photographic paper or
film, placing characters wherever they are

wanted. The Graphic Systems phototypesetter{2]
on the UNIX operating system([3] works by shin-

ing light through a character stencil. The character is made the right size by lenses, and the light
beam directed by fiber optics to the desired place
on a piece of photographic paper. The exposed
paper is developed and typically used in some
form of photo-offset reproduction.

On UNIX, the phototypesetter is driven by

height. And so on. Indeed a mechanisrh for
overriding default actions has to exist, but its
application is the exception, not the rule.
-

We assume that the typist has a reasonable

picture (a two-dimensional representation) of the
desired final form., as might be handwritten by
the author of a paper.

We also assume that the

input is typed on a computer terminal much like
an ordinary typewriter. This implies an input
alphabet of perhaps 100 characters, none of them

a formatting program called TROFF [4]. TROFF

special.

provides all of the facilities that one needs for
doing mathernatics, such as arbitrary horizontal
and vertical motions, line-drawing, size changing,
but the syntax for describing these special operations is difficult to learn, and difficult even for

our design was that the system should be easy to
implement, since neither of the authors had any

desire to make a long-term project of it. Since
our design was not firm, it was also necessary
that the program be easy to change at any time.

For this reason we decided to use TROFF
as an ‘‘assembly language,”” by designing a
language for describing mathematical expressions, and compiling it into TROFF.

To make the program easy to build and to
change. and to guarantee regularity (*‘it should
work everywhere'’), the language is defined by a
context-{ree grammar, described in Section 3.
The compiler for the language was built using a

was designed for setting running text.

[t also

experienced users to type correctly.

3. Language Design

The fundamental principle upon which we
based our language design is that the language
should be easy to use by people (for exampie,
secretaries) who know neither mathematics nor
typesetting.

This principle implies several things. First,
about
conventions
mathematical
“‘normal’’
operator precedence, parentheses, and the like
cannot be used, for to give special meaning to

such characters means that the user has to
understand what he or she is typing. Thus the
language should not assume, [or instance, that
parentheses are always balanced, for they are not

in the half-open interval (a.,5]. Nor should it
assume that that Va+b6 can be replaced by
4
\
e
8
s
5@
=
4
\fi“@"éiéq or that 1/{(1=x) is better written as

(or vice versa).

Second., there should be relatively few

rules, keywords, special symbols and operators,
and the like. This keeps the language easy (o

learn and remember. Furthermore. there should
be few exceptions to the rules that do exist: if
something works in one situation, it should work
everywhere. [f a variable can have a subscript,
then a subscript can have a subscript, and so on

A secondary, but still important, goal in

compiler-compiler.

A priori, the grammar/compiler-compiier
approach seemed the right thing to do. Our subsequent experience leads us to believe that uny
other course would have been folly. The original
language was designed in a few days. Construction of a working system sufficient to try
significant examples required perhaps a personmonth. Since then, we have spent a modest
amount of additional time over several years
tuning, adding facilities, and occasionally changing the language as users make critictsms and
suggestions.

We also decided quite early that we would
let TROFF do our work for us whenever possible.
TROFF is quitea powerful program, with a macro
facility, text and arithmetic variables, numerical
computation and testing, and conditional branching. Thus we have been able to avoid writing a
lot of mundane but tricky software. For example, we store no text strings, but simply pass
them on to TROFF. Thus we avoid having (o
write a storage management package. Further-

more, we have been able to isolate ourselves
from most details of the particular device and
character set currently in use. For example, we

let TROFF compute the widths of all strings of

A System for Typesetting Mathematics

we write

characters. we need know nothing about them.

third

design

goal

special

our

environment. Since our program is only useful
for typesetting mathematics, it is necessary that it
interface cleanly with the underlying typesetting
language for the benefit of users who want to set
intermingled mathematics and text (the usual
case). The standard mode of operation is that
when a document is typed, mathematical expres-

sions are input as part of the text, but marked by
user settable delimiters.

The program reads this

input and treats as comments those things which
are

not

mathematics,

through untouched.

simply

passing

5-99

them

At the same time it con-

verts the mathematical input into the necessary

TROFF commands.
The resulting ioutput is
passed directly to TROFF where the comments
and the mathematical parts both become text
and/or TROFF commands.

f(t) = 2 piint sin ( omega t )dt
Here spaces are necessarv in the input to indicate
that sin, pi, int, and omega are special, and potentially

worth

special

treatment.

EQN

looks

each such string of characters in a table, and if
appropriate gives it a translation.
and

In this case, pr

omega become their greek equivalents,

becomes the integral sign (which must be moved
down and enlarged so it looks ‘‘right’’), and sin

made

roman,

following

practice.

Parentheses,

mathematical

operators are automatically made

conventional
digits

roman

and

wher-

ever found.
Fractions are specified with

the keyword

over:

a+boverc+d+e = |

produces

4. The Language

a+b

We will not try to describe the language

precisely here; interested readers may refer to

the appendix for more details.

Throughout this

section, we will write expressions exactly as they
are

handed

the

typesetting

show the delimiters that the user types to mark
the beginning and end of the expression.

The

- interface between EQN and TROFF is described at

the end of this section.
, As we said, typing x=y-<+z+1 should produce x=y+z+1, and indeed it does.
are

made

italic,

operators

and

digits

Variables
become

roman, and normal spacings between letters and

operators

are

altered

slightly

give

pleasing appearance.

Input is free-form.

Spaces and new lines

in the input are used by EQN to separate pieces

of the input; they are not used to create space in
the output. Thus
X

Similarly, subscripts and superscripts are
introduced by the keywords subd and sup:

program

(hereinafter called “*EQN"’), except that we won't

¢ +d+e

X by lumal
is produced by

Xsup
2 + ysup2 = 2 sup
2

The spaces after the 2's are necessary to mark
the end of the superscripts; similarly the keyword
sup has to

be marked off by spaces or some

equivalent delimiter. The return to the proper
baseline is automatic.

Multiple levels of sub-

scripts

are

superscripts

“xsupysupz" is x*.

of course

allowed:

The construct ‘‘some-

thing sub something sup something’TM is recog-

nized as a special case, so **x sub i sup 2" is x,?

instead of x,2.
More complicated expressions can now be

formed with these primitives:

al!

af xt v

+2z+1

also gives x=y<+z+1.

Free-form input is easier

to type initially; subsequent editing is also easier,

dx?

is produced by

for an expression may be typed as many short

(partial sup 2 ] over {partial x sup 2| =

lines.

X sup 2 overasup 2 + y sup 2 aver b sup 2

Extra white space can be forced into the
output by several characters of various sizes.

Braces ] are used to group objects together; in
this case they indicate unambiguously what goes

tilde ** ~ "' gives a space equal to the normal word

over what on the left-hand side of the expres-

spacing

sion.

text;

circumflex

gives

half this

much, and a tab charcter spaces to the next tab

The language defines the precedence of sup

to be higher than that of over. so no braces are

stop.

needed to get the correct association on the right

Spaces (or tildes, etc.) also serve to delimit
pieces of the input. For example, to get

side.

S/ (()"wasin(wl)dt

Braces can always be used when in doubt

about precedence.

The braces convention is an example of

5-100 A System for Typesetting Mathematics

the power of using a recursive grammar to define
the language. It is part of the language that if a

we can (ype

sign (x) “= =" |aft |
rpile {1 above O above —1}
“Ipile {if above if above if}

construct can appear in some context, then any
expression in braces can also occur in that context.

There is a sqrt operator for making square
roots of the appropriate size: ‘‘sqrt a+b' pro-

duces Va +b , and

x = [=b 4+-— sqrt{b sup 2 —4ac}} over 2a

The construction ‘‘left {"° makes a left brace big
enough to enclose the ‘‘rpile {...]'", which is a
right-justified

pile

‘‘above

...

above

..»°

“Ipile’’ makes a left-justified pile. There are also

centered piles. Because of the recursive language
definition, a pile can contain any number of ele-

rm -b +/b~dac

ments; any element of a pile can of course con-

tain piles.

Since large radicais look poor on our typesetter,
sqrr is not useful for tall expressions.

Limits on summations, integrals and simi-

lar constructions are specified with the keywords
from and ro. To get
3

““Ipile {x >0 above x =0 above x <0}

Although EQN makes a valiant attempt to

use the right sizes and fonts, there are times
when

the

default

what is wanted.

assumptions

are

simply

not

For instance the italic sign in the

example

roman.

Slides and transparencies often require

would

conventionally

larger characters than normal text. Thus we also

x,—0

provide size and font changing commands: ‘‘sjze

12 bold {A"x"="y}" will produce A X = Y.

we need only type

sum from i=Q toinf x subi -=> 0
Centering and making the £ big enough and the
limits smalier are all automatic. The from and ro
parts are both optional, and the central part (e.g.,
the ) can in fact be anything:

Size is followed by a number representing a character size in points. (One pointis 1/72 inch; this
paper is set in 9 point type.)
If necessary, an input string can be quoted
in "...", which turns off grammatical significance,
and any font or spacing changes that might oth-

erwise be done on it. Thus we can say

lim from {x => pi /2} (tan~x) = inf

lim~ roman "sup” "x subn =0

to ensure that the supremum doesn’t become a

lim (tan x)eoo

superscript:

L=l

Again, the braces indicate just what goes into the

lim sup x,=0

[from part.

There

facility

for

making

braces,

brackets, parentheses, and vertical bars of the

Diacritical marks, long a problem in traditional typesetting, are straightforward:

right height, using the keywords /efr and right:

left [ x+y over 2a right |"="1

X+C+F+X=Y =2+Z
is made by typing

makes

x dot under + x hat <+ y tilde
+ X hat + Y dotdot = z+Z bar

2a =1

There are also facilities for globally chang-

A left need not have a corresponding right, as we
shall see in the next example.

Any characters

may follow /eft and right, but generally only various parentheses and bars are meaningful.
Big brackets, etc., are often used with
another facility, called prles, which make vertical
piles of objects. For example, to get
!

sign{x) =1

if x>0

0 if x=0
]

-1

if <0

ing default sizes and fonts, for example for making viewgraphs or for setting chemical equations.

The language allows {or matrices, and for lining
up equations at the same horizontal position.

Finally, there is a definition facility, so a
user can say

define name "..."
at any time in

the document;

henceforth, any

occurrence of the token ‘‘name’ in an expression will be expanded into whatever was inside
the

double quotes

users

tailor

the

its

definition.

language

This
their

lets
own

A System for Typesetting Mathematics

specifications, for it is quite possible to redefine
keywords like sup or over. Section 6 shows an
example of definitions.
text

The

EQN

preprocessor

and

equations,

and

reads

passes

intermixed

its

output

TROFF. Since TROFF uses lines beginning with a

period

control

words

(e.g.,

‘‘.ce’’

means

“‘center the next output line'’), EQN uses the
sequence ‘“‘.EQ’’ to mark the beginning of an
equation

and

°‘‘.EN’

mark the

end.

The

“.EQ” and **.EN’’ are passed through to TROFF
untouched,

they

can

also

used

knowledgeable user to center equations, number
them automatically,

etc.

By default,

however,

“.EQ’" and *“.EN" are simply ignored by TROFF,
so by default equations are printed in-line.
“.EQ” and ‘“.EN"’ can be supplemented

below.

of these are simple ones used only to guarantee
that some keyword is recognized early enough in

the parsing process.
are

terminal

i.e.,

in capital latters

lower case

syntactic

symbols

categories.

are

The

vertical bar | indicates an alternative, the brack-

ets [ ] indicate optional material.
string

non-blank

characters

A TEXT is a
or

any

string

inside double quotes; the other terminal symbols
represent literal occurrences of the corresponding
keyword.

eqn

: box | eqn box

box

: text

| { eqn ]

| box OVER box

| SQRT box
| box SUB box | box SUP box

| (L| C| R JPILE
{ list }

.ce

| LEFT text eqn [ RIGHT text ]
| box [ FROM box ] [ TO box ]
| SIZE text box

.EQ
Xxsubi=ysubi..

.EN
is

tedious

type

‘““.EQ’"

two characters to serve as the left and right del-

of expressions.

recognized anywhere

These

| [ROMAN| BOLD| ITALIC] box

and

““ EN’' around very short expressions (single
letters, for instance), the user can also define
characters

are

subsequent text.

For

example if the left and right delimiters have both
been set to **#”°, the input:

Let #x sub i#, #y# and #alpha# be positive
produces:

| DEFINE text text
list

:eqn] list ABOVE egn

text

: TEXT

The grammar makes it obvious why there
For example, the observa-

are few exceptions.

tion that something can be replaced by a more

complicated something in braces is implicit in the

productions:

Running a preprocessor is strikingly easy
on UNIX. To typeset text stored in file *‘f"’", one
issues the command:

| troff

The vertical bar connects the output of one process (EQN) to the input of another (TROFF).

§. Language Theory
The basic structure of the language is not a
particularly original one. Equations are pictured
as a set of ‘‘boxes,”’ pieced together in various
ways. For example, something with a subscript
is just a box followed by another box moved
downward and shrunk by an appropriate amount.

A fraction is just a box centered above another
box, at the right altitude, with a line of correct
length drawn between them.

The grammar for the language is shown

eqn : box | eqn box
box :text| { eqn |

Let x,, v and a be positive

eqn

Svmbols

symbols;

non-terminals,

the input:

imiters

In the original gram-

mar, there are about 70 productions, but many

by TROFF commands as desired; for example, a

For purposes of exposition, we have col-

lapsed some productions.

centered display equation can be produced with

Since

5-101

Anywhere a single character could be used, any
legal construction can be used.

Clearly, our grammar is highly ambiguous.
What, for instance, do we do with the input

a over boverc

Is it

over b} over ¢

or is it

a over {b overc}

To answer questions like this, the grammar
is supplemented with a small set of rules that
describe

operators.

the

precedence

and

associativity

[n particular, we specify (more or less

arbitrarily) that over associates to the left, so the
first alternative above is the one chosen.
other

hand,

subd

and

sup

bind

the

On the
right,

5-102 A System for Typesetting Mathematics

Width of output box =

because this is closer to standard mathematical
.

practice.

That is, we assume x“

slightly more than lurgest input width

is x'“ ', not

Height of output box =

(x9)°.

slightly more than sum of input heights
Base of output box =

The precedence rules resolve the ambiguity
in a construction like

slightly more than height of bottom input box

asup 2overb

String describing output box =
move down;,

We define sup to have a higher prccede?ce than

move right enough to center bottom box;

over, so this construction is parsed as --5- instead

draw bottom box (i.e., copy string for bottom box):
move up; move left enough to center top box;

of a®

draw top box (i.e.. copy string for top box);

Naturally, a user can always force a particular parsing by placing braces around expres-

move down and left; draw line full width;
return to proper base line.

sions.

Most of the other productions have equally sim-

The ambiguous grammar approach seems
to be quite useful. The grammar we use is small

ple semantic actions.

enough to be easily understood, for it contains
none of the productions that would be normally
used for resolving ambiguity. Instead the supplemental information about precedence and
associativity (also small enough to be understood) provides the compiler-compiler with the
information it needs to make a fast. deterministic
parser for the specific language we want. When
the language is supplemented by the disambiguating rules, it is in fact LR(1) and thus easy to

Picturing the output as a

set of properly placed boxes makes the right
sequence of positioning commands quite obvious. The main difficulty is in finding the right
numbers to use for esthetically pleasing positioning.

With a grammar, it is usuallv clear how to

extend the language.
users

suggesied

For instance, one of our

TENSOR

operator,

make

constructions like

parse(S].
The output code is generated as the input

is scanned. Any time a production of the grammar is recognized, (potentially) some TROFF
commands are output. For example, when the
lexical analyzer reports that it has found a TEXT

(i.e., a string of contiguous characters), we have

recognized the production:

text

: TEXT

The translation of this is simple. We generate a
local name for the string, then hand the name
and the string to TROFF, and let TROFF perform
the storage management. All we save is the
name of the string, its height, and its baseline.
As another example, the translation associated with the production

box

:box OVER box

Grammatically, this is easy: it is sufficient to add
a production like

box

: TENSOR { list |

Semantically, we need only juggle the boxes to
the right places.

Experience
There

are

really

interest—how well

three

aspects

EQN sets mathematics, how

well it satisfies its goal of being '‘easy to use.”

and how easyv it was (o build.

The first question is easily addressed. This
entire

paper

has

been

set

the

program.

Readers can judge for themselves whether it is

good enough

for their purposes.

One of our

users commented that although the output is not

as good as the best hand-set material, it i1s stll
better than average, and much better than the
worst. In any case. who cares? Printed books

cannot compete with the birds and flowers of
illuminated

manuscripts

either,

they

some

but

have

esthetic
clear

grounds,
economic

advantages.

Some

of the

deficiencies

the

output

could be cleaned up with more work on our part.

For

example,

sometimes

leave

too

much

space between a roman letter and an italic one.

If we were willing to keep track of the fonts
involved, we could do this better more of the

A System for Typesetting Mathematics 5-103

asub 0 + bsub | over

time.

{asubl + bsub 2 over
{a sub 2 + b sub 3 over
{asub3 + ... }}]

Some other weaknesses are inherent in our
output device. It is hard, for instance, to draw a
line of an arbitrary length without getting a perceptible overstrike at one end.

This is the input for the large integral of Section

As to ease of use, at the time of writing,
the system has been used by two distinct groups.

One user population consists of mathematicians,
chemists, physicists, and computer scientists.
Their typical reaction has been something like:

(1)

1It’s easy to write, although [ make the following mistakes...

(2)

How do Ido...?

(3)

It botches the following things....
don’t you fix them?

(4)

You really need the following features...

Why

1, notice the use of definitions:

define emx “{e sup mx|"
define mab "{m sqrt ab}”
define sa "{sqrt a}”
define sb "{sqrt b}"
int dx over {a emx — be sup —mx| "=~
left { Ipile {
1 over {2 mab) “log~
[sa emx — sb} over {sa emx + sb]
above

1 over mab ~ tanh sup —1 ( sa over sb emx )
above

-] over mab "~ coth sup =1 ( sa over sb emx )

The learning time is short. A few minutes
gives the general flavor, and typing a page or two
of a paper generally uncovers most of the
misconceptions about how it works.

The second user group is much larger, the
secretaries and mathematical typists who were
the original target of the system. They tend to
be enthusiastic converts. They find the language

ease

construction,

have

already mentioned that there are really only a

few person-months invested.

Much of this time

has gone into two things-fine-tuning (what is
the

most

between

esthetically

pleasing

space

use

the numerator and denominator of a

easy to learn (most are largely self-taught), and

fraction?), and changing things found deficient

have little trouble producing the output they
want. They are of course less critical of the
esthetics of their output than users trained in
mathematics. After a transition period, most
find using a computer more interesting than a

small, essentially unconnected modules for code

regular (ypewriter.

miscellany associated with

The main difficulty that users have seems
to be remembering that a blank is a delimiter;
even experienced users use blanks where they
shouldn’t and omit them when they are needed.
A common instance is typing

by our users (shouldn't a tilde be a delimiter?).
The

macro facility.

instead of

number

input

files and

the

The program is now about 1600

lines of C (6], a high-level language reminiscent
About 20 percent of these lines are

of BCPL.

“print’’ statements, generating the output code.

The semantic routines that generate the
TROFF

devices.

S (x,)

of a

parser which we did not have to write, and some

accommodate

which produces

consists

generation, a simple lexical analyzer, a canned

actual

f(x sub i)

program

commands

other

can

formatting

changed

languages

and

For example, in less than 24 hours, one

of us changed the entire semantic package to

drive NROFF, a variant of TROFF, for typesetting
mathematics on teletypewriter devices capable of

f{x)

reverse line motions.

Since many potential users

do not have access to a typesetter, but still have

Since the EQN language knows no mathermatics,
it cannot deduce that the right parenthesis is not
part of the subscript.

to type mathematics, this provides a way to get a

The language is somewhat prolix, but this
doesn’t seem excessive considering how much is

even for ultimate use.

typed version of the final output which is close

enough for debugging purposes, and sometimes

being done, and it is certainly more compact than

the corresponding TROFF commands. For example, here is the source for the continued fraction

Conclusions

to do acceptably good typesetting of mathematics

expression in Section 1 of this paper:

on a phototypesetter, with an input language that

We think we have shown that it is possible

iIs easy to learn and use and that satisfies many

users’ demands.

Such a package can be imple-

mented in short order, given a compiler-compiler

5-104 A System for Typesetting Mathematics

a decent typesetting program underneath.
and

Defining a language, and building a compiler for it with a compiler-compiler seems like
the only sensible way to do business.
OQur
experience with the use of a grammar and a
compiler-compiler has been uniformly favorable.

If we had written evervthing into code directly,
we would

design.

have

been

locked

into our original

Furthermore, we would have never been

sure where the exceptions and special cases were.
But because we have a grammar, we can change
our minds readily and .still be reasonably sure
that if a construction works in one place it will
work everywhere.

Acknowledgements

the

We are deeply indebted to J. F. Ossanna.
author of TROFF, for his willingness to

modify TROFF to make our task easier and for
his

continuous assistance during the development of our program. We are also grateful to A.
V. Aho for help with language theory, to S. C.

Johnson for aid with the compiler-compiler, and
to our early users A. V. Aho, S. [. Feldman, S.

C. Johnson, R. W. Hamming, and M. D. Mclliroy
for their constructive criticisms.
References

[11

(2]

A Manual of Siyle. 12th Edition. University of Chicago Press, 1969. p 295.

Mode! CIAIT Phorotvpeserter.

Graphic Sys-

tems, Inc.. Hudson, N. H.

(3]

Ritchie, D. M., and Thompson, K. L.,
““The UNIX time-sharing system.”” Comm.
ACM 17, 7 (July 1974), 365-373.

(4]

Ossafina. J. F., TROFF User's Manual.

{5]

Aho, A. V., and Johnson, S. C., “LR
Parsing.”” Comp. Surv. 6, 2 (June 1974),

Bell
Laboratories
Computing
Technical Report 54, 1977.

Science

99-124.

(6]

B. W. Kernighan and D. M. Ritchie, The C
Programming
Inc., 1978.

Language.

Prentice-Hall,

Typesetting Mathematics — User’s Guide

5-105

(Second Edition)

Typesetting Mathematics — User’s Guide

Brian W. Kernighan and Lorinda L. Cherry

Bell Laboratories
Murray Hill, New Jersey 07974

1. Introduction
EQN

program

for

X=y+2

typesetting

.EN

mathematics on the Graphics Systems pho-

totypesetters on UNIX and GCoOS.

The EQN

language was designed to be easy to use by

your output will look like
Xy ===

people who know neither mathematics nor

typesetting. Thus EQN knows relatively little
about
mathematics.
In
particular,

The

mathematical

by EQN. This means that you have to take
care of things like centering, numbering,
and so on yourself. The most common way

parentheses,

meanings.

symbols like
<+,
-,
X,
so on have no special

and

EQN is quite happy o set garbage

(but it will look good).

.EQ

and

.EN

are

copied

through

untouched: they are not otherwise processed

i$ 10 use the TROFF and NROFF macro pack-

EQN works as a preprocessor for the

typesetter formatter, TROFF{l], so the nor-

| “age package

‘=ms’

developed

Lesk(3]. which allows you to center, indent,

mal mode of operation is (0 prepare a docu-

left-justify and number equations.

ment with both mathematics and ordinary

With the ‘=ms’' package, equations are
centered by default. To left-justify an equa-

lext interspersed, and let EQN set the
mathematics while TROFF does the body of
the text.
mathematics on DASI and GS! terminals and

To indent it.
use .EQIL. Any of these can be followed by
an arbitrary ‘equation number’ which will be
placed at the right margin. For example,

on Modei 37 teletypes. The input is identi-

the input

UNIX,

EQN

will

also

produce

tion, use .EQL instead of EQ.

cal, but you have to use the programs NEQN

and NROFF instead of EQN and TROFF. Of
course, some things won't look as good
because terminals don't provide the variety
of characters, sizes and fonts that a
typesetter does, but the output is usually
adequate for proofreading.
To use EQN on UNIX,

eqn files | troff

EQI (3.1a)
x = f(y/2) + v/2
.EN
produces the output

x=f(y/2)+y/2

(3.1a)

There is also a shorthand notation so

in-line expressions like =° can be entered
without .EQ and .EN. We will talk about it in

GCOS use is discussed in section 26.

section 19.

2. Displayed Equations

To tell EQN where a mathematical
expression begins and ends, we mark it with
lines beginning .EQ and .EN. Thus if you

sion are thrown away by EQN.

type the lines

and EN,

Input spaces
Spaces and newlines within an expres-

(Normal text

is left absolutely alone.) Thus between

X=y+2

5-106 Typesetting Mathematics — User’s Guide

A complete list of EQN names appears

and

in section 23.

X =y
+ 2

use

Knowledgeable users can also

TROFF four-character

names

for any-

thing EQN doesn’t know about, like \ (bs for

and
X

=
+ 2

the Bell System sign @.

6. Spaces, Again

and so on all produce the same output
X==yt2

You should use spaces and newlines freely
to make your input equations readable and

easy to edit. In particular, very long lines
are a bad idea, since they are often hard to
fix if you make a mistake.

The only way EQN can deduce that
some sequence of letters might be special is
if that sequence is separated from the letters
on either side of it.
surrounding

To force extra spaces into the ourpui,
use a tilde ‘"’ for each space you want:

word

ordinary

the previous section.

You can also make special words stand
by

surrounding

them

with

tildes

circumflexes:

x~="2"pi"int"sin" (Comega~tTM) "dt
is

X ="y +z

This can be done by

special

spaces (or tabs or newlines), as we did in

out

4. Output spaces

much

the

same

the

last

example,

except that the tildes not only separate the

gives

magic words like sin, omega, and so on, but
also add extra spaces, one space per tilde:

Xm=my
4+ 2

You can also use a circumflex ‘TM", which
gives a space half the width of a tilde. It is
mainly useful for fine-tuning. Tabs may
also be used to position pieces of an expression, but the tab stops must be set by TROFF
commands.

x-2‘:rfsin(wt)dl
Special words can also be separated by

braces { | and double quotes "...", which
have special meanings that we will see soon.

7. Subscripts and Superscripts

S. Symbols, Special Names, Greek

Subscripts

EQN knows some mathematical sym-

bols,

some mathematical names,
Greek alphabet. For example,

and

the

x=2 pi int sin ( omega t)dt
produces

x=2 f sin(w?)
dr
Here the spaces in the input are necessary
to tell EQN that int, pi, sin and omega are

separate entities that should get special
treatment. The sin, digit 2, and parentheses

are set in roman type instead of italic; piand
omega are made Greek; and int becomes the
integral sign.

When in doubt, leave spaces around
separate parts of the input. A very common
error is to type fIpi) without leaving spaces
on both sides of the pi. As a result, EQN
does not recognize pi as a special word, and

it appears as f(pi) instead of f ().

and

superscripts

are

obtained with the words sub and sup.

Xsup 2 +ysubk
gives

x"'+y,‘
EQN takes care of all the size changes and
vertical motions needed to make the output

look right.

The words sub and sup must be

surrounded by spaces; x subdl will give you

xsub?2 instead of x, Furthermore, don’t
forget to leave a space (or a tilde, etc.) to
mark the end of a subscript or superscript.
A common error is to say something like

y = (x sup 2)+1
which causes
y,_(x2)+l

instead of the intended
y={x?)+1

Typesetting Mathematics — User’s Guide

Subscripted

subscripts

and

5-107

super-

scripted superscripts also work:

The general rule is that anywhere you could

X sub i sub !

use some single thing like x, you can use an

arbitrarily complicated thing if you enclose it

in braces. EQN will look after all the details
of positioning it and making it the right size.

X,!

subscript

and superscript

the

same

thing are printed one above the other if the

subscript comes first:

In all cases, make sure you have the
right number of braces. Leaving one out or
adding an extra will cause EQN to complain

bitterly.

X sub i sup 2

Occasionally
braces.

quotes, like "(".

X,-Z
group

the

right,

xsupy sub:z

Quoting is discussed in

To make a fraction, use the word over:
a+b over 2c =|

Braces for Grouping

Normally, the end of a subscript or
superscript is marked simply by a blank (or
tab or tilde, etc.) What if the subscript or
superscrint is something that has to be typed
with blanks in it? In that case, you can use

the braces { and } to mark the beginning and

end of the subscript or superscript:

gives
a+b

2¢

= |

The line is made the right length and positioned automatically. Braces can be used to
make clear what goes over what;

{alpha + beta) over {sin (x)}

e sup {i omega t}

atB

eiu(

Rule:

have

Fractions

means x’%, not x’,.
8.

will

more detail in section 14.

Other than this special case, sub and
sup

you

To do this, enclose them in double

sin(x)

Braces can al/ways be used to force

EQN to treat something as a unit, or just to

make your intent perfectly clear.

Thus:

What happens when there is both an over
and a sup in the same expression?

In such

an apparently ambiguous case, EQN does the

sup before the over, so

x sub {i sub 1} sup 2

-b sup 2 over pi

is --f—- instead of —4TM The rules which
decide which operation is done first in cases
like

with braces, but

this

When

x sub i sub | sup 2

are

summarized

doubt,

however,

section

use

23.

braces to

make clear what goes with what.

10. Square Roots

Xl.‘z

To draw a square root, use sgr:

which is rather different.

Braces
necessary:

can

occur

within

e sup (i pi sup {rho +1}]

braces

if
|

sqrt a+b + 1 over sqgrt {ax sup 2 +bx +c)

va+b+

Vax+bx+c

5-108 Typesetting Mathematics — User’s Guide

Warning - square roots of tall quantities
look lousy, because a root-sign big enough
to cover the quantity is too dark and heavy:

12. Size and Font Changes
By default, equations are set in

10-

point type (the same size as this guide),
with standard mathematical conventions to

sqrt {a sup 2 over b sub 2}

determine what characters are in roman and
what in italic.

Although EQN makes a vali-

ant attempt to use esthetically pleasing sizes
and fonts, it is not perfect. To change sizes
and fonts, use size n and roman, italic, bold

a‘

bs
Big square roots are generally better written
as something to the power 2.

and far Like sub and sup, size and font
changes affect only the thing that follows

(az/bz) A

them, and revert to the normal situation at

the end of it. Thus

which is

bold x y

(a sup 2 /b sub 2 ) sup half

IS
Xy

11. Summation, Integral, Etc.
Summations, integrals,
constructions are easy:

and

similar

and

size 14 bold x = y +

size 14 {alpha + beta}

sum from i=0 to {i= inf} x sup i
gives

produces

X=y+a+f

[l
-]

j={)

Notice that we used braces to indicate where
the upper part i=co begins and ends. No
braces were necessary for the lower part

i=() because it contained no blanks. The
braces will never hurt, and if the from and (o
parts contain any blanks,
braces around them.

you

must

use

The from and (o parts are both
optional, but if both are used, they have to
occur in that order.

Other useful characters can replace the
sum in our example:

int

inter

size 12 { ... }
Legal sizes which may follow size are
6, 7,8, 9,10, 11, 12, 14, 16, 18, 20, 22, 24,
28, 36. You can also change the size by a
given amount; for example, you can say
size +2 to make the size two points bigger,
or size—J to make it three points smaller.
This has the advantage that you don’t have
If you are using fonts other than
roman, italic and bold, you can say fomt X

become, respectively,

the size of an entire equation by

to know what the current size is.

union

prod

As always, you can use braces if you want to
affect something more complicated than a
single letter. For example, you can change

Since the thing before the from can be anything, even something in braces, from-to can
often be used in unexpected ways:

lim from {n => inf} x subn =0

where X is a one character TROFF name or

number for the font. Since EQN is tuned for
roman, italic and bold, other fonts may not
give quite as good an appearance.

The far operation takes the current
font and widens it by overstriking: far grad is

V and fat{x sub } is x,.

If an entire document is to be in a

lim x,=0

non-standard size or font, it is a severe nuisance to have to write out a size and font
change for each equation. Accordingly, vou
can set a ‘‘global” size or font which

Typesetting Mathematics — User’s Guide 5-109

therearter

affects

all

equations.

italic "sin(x)" + sin (x)

the

beginning of any equation, you might say,
for instance,

sin(x) +sin(x)

.EQ

gsize 16

Quotes are also used to get braces and

gfont R

other EQN keywords printed:

"{ size alpha }"

.EN

to set the size to 16 and the font to roman
thereafter. In place of R, you can use any
of the TROFF font names. The size after
gsize can be a relative change with + or —.
Generally, gsize and gfont will appear at
the beginning of a document but they can
also appear thoughout a document: the glo-

{ size alpha |
and

roman "{ size alpha }"
IS

[ size alpha }

bal font and size can be changed as often as
needed. For example, in a footnote} you
will typically want the size of equations to

match the size of the footnote text, which is
two points smaller than the main text.
Don’t forget to reset the global size at the

end of the footnote.
13.

The construction "" is often used as a
L4

place-holder when grammatically EQN needs
something, but you don’t actually want anything in your output.

For example, to make

e, you can't just type

sup 2 roman He

because a sup has to be a superscript

something. Thus you must say

Diacritical Marks

To get funny marks on top of letters,

" sup 2 roman He

there are several words:

To get a literal quote use ‘*\"”*

TROFF

x dot
x dotdot

x
X

characters like \(bs can appear unquoted,

X hat

X tilde

X vec

x dyad
X bar

X
X
X

and vertical motions with \ # and \v should
always be quoted. (If you’ve never heard of

X under

but more complicated things like horizontal

\ A and \v, ignore this section.)
15.

Sometimes it’s necessary to line up a

The diacritical mark is placed at the right
height. The bar and under are made the
right length for the entire construct, as in
x+y+z; other marks are centered.

input

series of equations at some horizontal position, often at an equals sign. This is done
with two operations called mark and lineup.

The word

mark may appear once at

any place in an equation.

14. Quoted Text
Any

Lining Up Equations

entirely

within

quotes

("...") is not subject to any of the font
changes and spacing adjustments normally

It remembers the

horizontal position where it appeared.

Suc-

cessive

one

equations

can

occurrence of the word

contain

lineup.

The place

where /ineup appears is made to line up with

done by the equation setter. This provides a

the place marked by the previous mark if at

way to do your own spacing and adjusting if

all possible. Thus, for example, you can say

needed:

tLike this one, in which we have a {ew random

expressions like x, and =%,

The sizes for these

were set by the command gsize — 2.

5-110 Typesetting Mathematics — User’s Guide

EQI

three,

X+y mark = z
.EN

parentheses

etc.

Second, big left and right
look poor, because the

character set is poorly designed.

EQI
X lineup == 1
.EN

something’’ need not have a corresponding
“‘right something’. If the righr part is omit-

often

The right part may be omitted: a ‘‘left

ted, put braces around the thing you want

to produce

the left bracket to encompass.

x+ym=mz

Otherwise,

the resulting brackets may be too large.

If you want to omit the /eft part, things

x=]
For reasogs too complicated to talk about,
when you use EQN and ‘=—ms’, use either

EQI or EQL.

mark and lineup don’t work

with centered equations.

are

because

technically

left TM ... right )

Also bear in mind

that mark doesn’t look ahead;

complicated,

you can't have a righr without a corresponding left. Instead you have to say

for example.

X mark =1

The lefr "TM means a *‘left nothThis satisfies the rules without hurt-

ing’’.

ing your output.

x+y lineup =2z

isn’t going to work, because there isn’t
room for the x-+y part after the mark
remembers where the xis.

17.

Piles

There is a general facility for making
vertical piles of things; it comes in several

flavors. For example:

16. Big Brackets, Etc.

A "=" left |

pile | a above b above ¢ }

To get big brackets [, braces {},
parentheses (), and bars || around things,

= pile { x above y above z |

right ]

use the lefrand right commands:

left { a over b + 1 right |

will make

"= left ( ¢ over d right )
+ left { e right |

a
A

The elements of the pile (there can be as
many as you want) are centered one above

a4
b

another, at the right height for most pur-

The resulting brackets are made big enough

to cover whatever they enclose.

Other char-

acters can be used besides these, but the are

not likely to look very good. One exception
is the floor and ceiling characters:

left floor x over y right floor
< = |eft ceiling a over b right ceiling

poses.

The

keyword

above

used

the entire list.

The elements of a pile can

be as complicated as needed, even contain-

ing more piles.

Three other forms of pile exist:

Ipile

makes a pile with the elements left-justified;
rpile makes a right-justified pile; and cpile
makes a centered pile, just like pile.

produces

separate the pieces; braces are used around

The

vertical spacing between the pieces is some-

what larger for /-, r- and cpiles than it is for
ordinary piles.

Several warnings about brackets are in

order. First, braces are typically bigger than
brackets and parentheses, because they are

made up of three, five, seven, etc., pieces,
while

brackets

can

made

of two,

roman sign (x)” ="

left {
Ipile {1 above 0 above ~1}
" Ipile

{ifF’ x>0 above if x=0 above i x <0}

Typesetting Mathematics — User’s Guide 5-111

EQN provides a shorthand for short in-

makes

line expressions.

{

if x>0

if x=0

sign(x) = {0
-1
Notice the

in-line equation, and then type expressions

right in the middle of text lines.

if x<0

left brace without a matching

signs, for example, add to the beginning of
your document the three lines

Matrices

delim SS

It is also possible to make matrices.

For example, to make a neat array like

Having done this, you can then say things

x, x?

y, y?

Let Salpha sub iS be the primary
variable, and let SbetaS be zero.

you have to type

Then we can show that 3x sub 1S is
S> =(8§,

matrix {
ccol { x sub i above y sub i |
ccol { x sup 2 above y sup 2 |

This works as vou might expect — spaces,

This produces a matrix with two centered
columns. The elements of the columns are
then listed just as for a pile, each element

separated by the word above. You can also
use Icol or rcol to left or right adjust
columns. Each column can be separately
adjusted, and there can be as many columns

as you like.

newlines, and so on are significant in the
text, but not in the equation part itself.
Multiple equations can occur in a single
input line.

Enough room is left before and after a
line

of two adjacent piles, by the way, is that if
the elements of the piles don’t all have the
same height, they won’t line up properly. A
matrix forces them to line up, because it
looks at the entire structure before deciding
what spacing to use.

A word of warning about matrices —

each column must have the same number of
elements in it. The world will end if you get
this wrong.

" In a mathematical document, it is

necessary to follow mathematical conventions not just in display equations, but also
in the body of the text, for example by making variable names like x italic. Although
be

done

surrounding

the

appropriate parts with EQ and EN, the con-

tinual repetition of .EQ and .EN is a nuisance.
Furthermore, with ‘=ms’, .EQ and EN imply
a dispiayed equation.

in-line

expressions

that

something like ) x, does not interfere with
oy

the lines surrounding it.

To turn off the delimiters,
EQ

delim off
.EN
Warning:

don’t

use

braces,

tildes,

circumflexes, or double quotes as delimiters
- chaos will result.

20.

Definitions

freguently-used

EQN provides a facility so you can give

name,

19. Shorthand for In-line Equations

could

that contains
”

The reason for using a matrix instead

this

To set

both the left and right characters to dollar

right one.

18.

You can define two char-

acters to mark the left and right ends of an

and

string

thereafter just

instead of the whole string.

characters

type

the

name

For example, if

the sequence

xsubisubl

+ ysubisubl

appears repeatedly throughout a paper, you

can save re-typing it each time by defining it
like this:

define xy 'xsubisub! -+ ysubisub l
This

makes

xv a shorthand

for whatever

characters occur between the single quotes

in the definition.

You can use any character

5-112 Typesetting Mathematics — User’s Guide

instead of quote to mark the ends of the
definition, so long as it doesn’t appear inside
the definition.
Now you can use xy like this:

You can also say back »n and

fwd n to move small amounts horizontally

n is how far to move in 1/100’s of an em

(an em is about the width of the letter ‘m’.)

Thus back 50 moves back about half the

f(x) = xy ...

width of an

.EN

Similarly

vou

can

move

things up or down with up nand down n.

and so on. Each occurrence of xy will
expand into what it was defined as. Be careful to leave spaces or their equivalent
around the name when you actually use it,
so EQN will be able to identify it as special.
There are several things to waich out

for.

horizontal spaces can be obtained with tilde

and circumtflex.

First, although definitions can use pre-

vious definitions, as in

As
with sub or sup, the local motions affect the

next thing in the input, and this can be

something

arbitrarily

complicated

if it

enclosed in braces.

22. A Large Example
Here is the complete source for the

three display equations in the abstract of this
guide.

.EQ

define xi "xsubi’
define xil "xisub 1’

EQI

G(z)"mark =" esup{In~G)}
“=m” exp left (

.EN

don'’t define something in terms of itselfs A
favorite error is to say

sum from k> =1 (S sub k z sup k} over k right )
“=" prod from k> =1 e sup {S sub k z sup k /k}
.EN
1
EQ

lineup = left

define X 'roman X'
This is a guaranteed disaster, since X is now
defined in terms of itself. If you say

define X 'roman "X"'

(1 + Ssublz +

{Ssublsup2zsup2)over ! + .. right)
left (1+ {Ssub2zsup2]over?2
+ {Ssub2sup2zsup4)
over{ 2sup2cdot?2]}
+ ... right) ..

.EN

however, the quotes protect the second X,
and everything works fine.
EQN keywords can be redefined.

You

can make / mean over by saying

EQ1

lineup =

sum from m> =( left (

sum from

pile { ksubl ksub2...ksubm >=0

above

ksubl +2k sub2 + ... +mk sub m =m]
{Ssublsuplksubl)]over {lsupksublksubl!]"
{Ssub2sup ksub2))over{2supksub2ksub2!'}"

define / 'over’
or redefine over as / with

{S submsup (ksubm) ) over (msupk submk subm !}

right ) z sup m

define over '/’

.EN

If you need different things to print on
a terminal and on the typesetter, it is some-

times worth defining a symbol differently in
NEQN

and

EQN.

This can

done with

ndefine and tdefine. A definition made with
ndefine only takes effect if you are running
NEQN: if you use rdefine, the definition only
applies for EQN. Names defined with plain
define apply to both EQN and NEQN.
21.

Keywords, Precedences, Etc.

If you don’t use braces, EQN will do
operations in the order shown in this list.
dyad vec under bar tilde hat dot dotdot

fwd back down up
far roman italic bold size
sub sup sqrr over

from 1o

Local Motions
Although EQN tries to get most things

at the right place on the paper, it isn’t perfect, and occasionally you will need to tune

the output to make it just right.

23.

Small extra

These operations group to the left:
over sqrt left right
All others group to the right.

Typesetting Mathematics — User’s Guide

Digits, parentheses, brackets, punctua-

beta

tau

tion marks, and these mathematical words

chi

theta

are converted to Roman font when encoun-

delta

upsilon

tered:

epsilon

€

eta

zeta

gamma

sin cos tan sinh cosh

tanh arc

max

min lim log In exp
Re Im and if for det

These character sequences

are

recognized

and translated as shown.

< o

|
4

< -

<KL

> >

inf
partial

C
0
'A2

half
prime
approx

nothing
cdot

- qqX

limes
del
grad

geoeq

sum

int

SCE

prod

union
inter

them out in whatever case you want:

above

17, 18

Ipile

back
bar

21
13

mark
matrix

15
18

bold
ccol

12
18

ndefine
over

20
9

col

pile

cpile

rcol

define

right

delim

roman

dot

rpiie

dotdot

size

down

sqrt

dyad
fat

13
12

sub
sup

10
7
7

font

tdefine

from

tilde

fwd
gfont

21
12

to
under

gsize
hat

12
13

up
vec

21
13

italic

4 6

Icol

(]

left
lineup

16
15

g8, 14

24. Troubleshooting

To obtain Greek letters, simply spell

DELTA

These are all the words known to EQN

(except for characters with names), together
with the section where they are discussed.

1 HHYHMAWV

> £ ]

5-113

iota

GAMMA T
LAMBDA A
OMEGA
PHI
b
PI
I1
PSI
R4
SIGMA
X

kappa
lambda
mu
nu
omega
omicron
phi

K
A
i
v
w
o
®

THETA
@
UPSILON Y

pi
pSi

T
W

rho

alpha

sigma

If you make a mistake in an equation,

like leaving out a brace (very common) or
having one too many (very common) or
having a sup with nothing before it (common), EQN will tell you with the message
syntax error between lines x and y, file =
where x and y are approximately the lines

between which the trouble occurred, and z1s

the name of the file in question.

The line

numbers are approximate — look nearby as
well.

There are also self-explanatory

mes-

sages that arise if you leave out a quote or

try to run EQN on a non-existent file.
If

you

want

check

document

before actually printing it (on UNIX only),

5-114

Typesetting Mathematics — User’s Guide

neqn files | nroff —=Tx

eqn files >/dev/null
will

throw away the output but print the

where x is the terminal type you are using.

such as J00 or 300S.

messages.

If you use something like doilar signs

EQN and

NEQN can be used with

the

as delimiters, it is easy to leave one out.

TBL program/(2] for setting tables that con-

This causes very strange troubles. The program checkeq (on GCOS, use ./checkeg
instead) checks for misplaced or missing

tain mathematics.

you get a message ‘‘word overflow’, you

have exceeded this limit.
sage

will

“line

usually

overflow’’

away.

indicates

The

message

you

have

exceeded an even bigger buffer. The only
cure for this is to break the equation into

On a related topic, EQN does not break
equations by itseif — vou must split long
equations up across multiple lines by your-

self, marking each by a separate .EQ ... .EN
EQN does warn about equations

that are too long to fit on one line.

25.

are

deeply

indebted

lingness to extend TROFF to make our task

easier,

and for his continuous assistance
during the development and evolution of
EQN. We are also grateful to A. V. Aho for

for

assistance

with

the

YACC

compiler-

compiler, and to all the EQN users who have

made helpful suggestions and criticisms.

References

[1]

J. F. Ossanna, ‘‘NROFF/TROFF User's
Manual’’, Bell Laboratories Computing
Science Technical Report #5354, 1976.

document

that

contains

mathematics on the UNIX typesetter,

eqn files | troff
the TROFF part of the command. For example,

eqn files | troff —ms
To run the same document on the GCOS
typesetter, use

eqn files | troff —g (other options) | gcat
A compatible version of EQN can be
used on devices like teletypes and DAS! and

GS! terminals which have half-line forward

and reverse capabilities.

To print equations

on a Mode} 37 teletype, for example, use

neqn files | nroff
The language for equations recognized by
NEQN is identical to that of EQN. aithough of
course the output is more restricted.

To use a GSI or DASI terminal as the

M. E. Lesk. “Typing Documents on
UNIX’’, Bell Laboratories, 1976.

[3]

If there are any TROFF options, they go after

output device.

Ossanna, the author of TROFF, for his wil-

Use on UNIX

Acknowledgments

advice on language design, to S. C. Johnson

(WO separate ones.

sequence.

26.

If you print the

equation as a displayed equation this mes-

(NJEQN.

tbl files | eqn | troff
tbl files | negn | nroff

dollar signs and similar troubles.

In-line equations can only be so big
because of an internal buffer in TROFF. If

Use TBL before

like this:

M. E. Lesk. “TBL — A Program for
Setting

Tables’,

Bell
Laboratories
Computing Science Technical Report
#49, 1976.

Tbl 5-115

Tbl — A Program to Format Tables
M. E. Lesk

Bell Laboratories
Murray Hill, New Jersey 07974

Introduction.

Tl turns a simple description of a table into a troff ot nroff (1] program
(list of commands) that prints the table. Tb/ may be used on the ppe-11 UNIX
[2] system and on the
Honeywell 6000 Gcos system. It attempts to isolate a portion of a job that
it can successfully
handle and leave the remainder for other programs. Thus r46/ may be
used with the equation
formatting program egn [3] or various layout macro packages (4,5,6]. but
does not duplicate
their functions.
This memorandum is divided into two parts. First we give the rules for
preparing b/
input: then some examples are shown. The description of rules is precise
but technical, and the
beginning user may prefer to read the examples first, as they show
some common table
arrangements. A section explaining how to invoke rb/ precedes the examples.
To avoid repetition, henceforth read rroffas “troffoc nroff. "
|
The input to 14/ is text for a document, with tables preceded by a **.TS" (table
start)

command and followed by a **.TETM (table end) command.

Tb/ processes the tables, generating

troff formatting commands, and leaves the remainder of the text unchanged

. The *“.TS'* and
*.TETM lines are copied, too, so that rroff page layout macros (such as
the memo formatting
macros (4]) can use these lines to delimit and place tables as they see fit.
In particular, any
arguments on the **.TSTM or **.TE"TM lines are copied but otherwise

document layout macro cammands.

ignored. and may be used by

The format of the input is as follows:
text

TS
table

.T1E
text

1S
rable

.TE
{ext

where the format of each table is as follows:

IS
options :

formar .
dara

. 1.E

Each table is independent, and must contain formatting information followed by the

data to be

rows of the table, muy be preceded by u few options that affect the entire table.
description of tables is given in the next section.

A detailed

entered in the table.

The formatting information, which describes the individual columns and

5-116 Thbl

Input commands.
As indicated above, a table contains, first, global options, then a format section
describing
the layout of the table entries, and then the data to be printed. The
format and data are always
required, but not the options. The various parts of the table are entered
as follows:

OPTIONS. There may be a single line of options affecting the whole table.

line must follow the

If present, this

.TS line immediately and must contain a list of option names

separated by spaces, tabs, or commas, and must be terminated
by a semicolon.
allowable options are:

center

— center the table (default is left-adjust):

expand

— make the table as wide as the current line length;

box

— enclose the table in a box;

allbox

— enclose each item in the table in a box:

doublebox

- enclose the table in two boxes:

tab (x)

— use x instead of tab to separate data items.

The

linesize (7) — set lines or rules (e.g. from box) in » point type;

delim (xy)

— recognize x and y as the egn delimiters.

The ¢bl program tries to keep boxed tables on one page by issuing appropriat
e ‘‘need"’

(.ne) commands. These requests are calculated from the number of lines in
the tables,

and if there are spacing commands embedded in the input, these requests may
rate; use normal rroff procedures, such as keep-release macros, in

that case.

be inaccu-

The user who

must have a multi-page boxed table should use macros designed for this
purpose, as
explained below under ‘Usage.’

FORMAT. The format section of the table specifies the layout of the columns.
Each line
in this section corresponds to one line of the table (except that the last line correspond
s to
all following lines up to the next .T&, if any — see below), and each line
contains a keyletter for each column of the table. It is good practice to separate the key letters
for each
column by spaces or tabs. Each key-letter is one of the following:

Lor 1

toindicate a left-adjusted column entry:

Ror r

toindicate a right-adjusted column entry:

Cor ¢

toindicate a centered column entry;

Normn

to indicate a numerical column entry, to be aligned with other numerical
entries so that the units digits of numbers line up:

Aor a

to indicate an alphabetic subcolumn: all corresponding entries are aligned on
the left, and positioned so that the widest is centered within the column (see
example on page 12):

Sor s

to indicate a spanned heading, i.e. to indicate that the entry from the previous
column continues across this column (not allowed for the first column, obvi-

ously): or

to indicate a vertically spanned heading, i.e. to indicate that the entry from

previous row continues down through this row.

of the table, obviously).

the

(Not allowed for the first row

When numerical alignment is specified, a location for the decimal point is sought. The
rightmost dot (.) adjacent to a digit is used as a decimal point: if there is no dot adjoining

a digit, the rightmost digit is used as a units digit; if no alignment is indicated,

the item is
However, the special non-printing character string \& may be
used to override unconditionally dots and digits, or to align alphabetic
data; this string

centered in the column.

lines up where a dot normally would, and then disappears from the final output.
In the
example below, the items shown at the left will be aligned (in a numerical
column) as

Tbhl 5-117

shown on the right:

4.2

4.2
26.4.12
abe
abc

26.4.12
ab¢
abc\&
43\&3.22

433.22

749.12

Note: If numerical data are used in the same column with wider L or r type table entries,
the widest number is centered relative to the wider L or ritems (L is used instead of | for
readability; they have the same meaning as key-letters). Alignment within the numerical
items is preserved.

This is similar to the behavior of a type data, as explained above.

However, alphabetic subcolumns (requested by the a key-letter) are always slightly

indented relative to L items; if necessary, the column width is increased to force this.
This is not true for n type entries.
Warning: the n and a items should not be used in the same column.

For readability, the key-letters describing each column should be separated by spaces.
The end of the format section is indicated by a period. The layout of the key-letters in
the format section resembles the layout of the actual data in the table. Thus a simple format might appear as:
css

l an.

which specifies a table of three columns. The first line of the table contairs a heading cen-

tered across all three columns; each remaining line contains a left-adjusted item in the

first column followed by two columns of numerical data. A sample table in this format
might be:

Overall title
[tem-a
34.22
Item-b
12.65
Items: ¢, d.e
23
Total
69.87

9.1
.02
5.8
14.92

There are some additional features of the key-letter system:

Horizontal lines — A Kkey-letter may be replaced by *_’ (underscore) to indicate a hor-

izontal line in place of the corresponding column entry, or by ‘="' to indicate a double horizontal line. If an adjacent column contains a horizontal line, or if there are
vertical lines adjoining this column, this horizontal line is extended to meet the
nearby lines. If any data entry is provided for this column, it is ignored and a warning message is printed.

Vertical lines — A vertical bar may be placed between column key-letters. This will
cause a vertical line between the corresponding columns of the table. A vertical bar
to the left of the first key-letter or to the right of the last one produces a line at the

edge of the table. If two vertical bars appear between key-letters, a double vertical
line is drawn.

Space between columns
— A number may follow the key-letter. This indicates the
amount of separation between this column and the next column. The number normally specifies the separation in ens (one en is about the width of the letter ‘n’)." If
the ‘*expand’” option is used, then these numbers are multiplied by a constant such
that the table is as wide as the current line length. The default column separation

* More precisely, an en is 3 aumber of points (1 noint = /72 inch) equal to half the current type size.

5-118 Thl

number is 3.

If the separation is changed the worst case (largest space requested)

governs.

Vertical spanning — Normally, vertically spanned items extending over several rows of
the table are centered in their vertical range. If a key-letter is followed by t or T,

any corresponding vertically spanned item will begin at the top line of its range.

Font changes — A key-letter may be followed by a string containing a font name or
number preceded by the letter f or F. This indicates that the corresponding column
should be in a different font from the default font (usually Roman). All font names
are one or two letters; a one-letter font name should be separated from whatever

follows by a space or tab. The single letters B, b, I, and i are shorter synonyms for
fB and fI. Font change commands given with the table entries override these
specifications.
Point size changes - A key-letter may be followed by the letter p or P and a number to
indicate the point size of the corresponding table entries. The number may be a

signed digit, in which case it is taken as an increment or decrement from the current
point size. If both a point size and a column separation value are given, one or
more blanks must separate them.
Vertical spacing changes — A key-letter may be followed by the letter v or V and a
number to indicate the wvertical line spacing to be used within a multi-line

corresponding table entry.

The number may be a signed digit., in which case it is

taken as an increment or decrement from the current vertical spacing.

A column

separation value must be separated by blanks or some other specification from a
vertical spacing request.

This request has no effect unless the corresponding table

entry is a text block (see below).

Column width indication — A key-letter may be followed by the letter w or W and a width
value in parentheses.

This width is used as a minimum column width.

If the largest

element in the column is not as wide as the width value given after the w, the largest element 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 included text blocks.

WNormal rroff units can be used to scale the

width value; if none are used, the default is ens.

less integer the parentheses may be omitted.
column, the last one given controls.

If the width specification is a unit-

If the width value is changed in a

Equal width columns — A key-letter may be followed by the letter e or E to indicate
equal width columns. All columns whose key-letters are followed by e or E are
made the same width.

This permits the user to get a group of regularly spaced

columns.

Note: The order of the above features is immaterial; they need not be separated by
spaces, except as indicated above to avoid ambiguities involving point size and font

changes.

Thus a numerical column entry in italic font and 12 point type with a

minimum width of 2.5 inches and separated by 6 ens from the next column could be

specified as

npl2w(2.51)f1 6
Alternative notation — Instead of listing the format of successive lines of a table on con-

secutive lines of the format section, successive line formats may be given on the
same line, separated by commas, so that the format for the example above might
have been written:
¢css,lnn.

Default — Column descriptors missing from the end of a format line are assumed to be

L. The longest line in the format section, however, defines the number of columns
in the table; extra columns in the data are ignored silently.
PR

Thl 5-119

DATA. The data for the table are typed after the format. Normally, each table line is
typed as one line of data. Very long input lines can be broken: any line whose last character is \ is combined with the following line (and the \ vanishes). The data for different
columns (the table entries) are separated by tabs, or by whatever character has been
specified in the option rabs option. There are a few special cases:

Troff commands within tables — An input line beginning with a *." followed by anything
but a number is assumed to be a command to roff and is passed through unchanged,
retaining its position in the table. So, for example, space within a table may be produced by **.sp’’ commands in the data.

Full width horizontal lines — An input line coataining only the character _ (underscore)
or = (equal sign) is taken to be a single or double line, respectively. extending the
full width of the rable.
Single column horizontal lines — An input table enrry containing only the character _or =
is taken to be a single or double line extending the full width of the columa. Such
lines are extended to meet horizontal or vertical lines adjoining this column. To
obtain these characters explicitly in a column, either precede them by \& or follow
them by a space before the usual tab or newline.
Short horizontal lines — An input table entry containing only the string \_ is taken to be a
single line as wide as the contents of the column. It is not extended to meet adjoining lines.
Repeated ckaracters — An input table entry containing only a string of the form \Rx
where x is any character is replaced by repetitions of the character x as wide as the

data in the column.

The sequence of x's is not extended to mest adjoining

‘columns.
Vertically spanned items — 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 a table format key-letter of *°°,

Text blocks — In order to include a block of text as a table entry, precede it by T{ and

follow it by T}. Thus the sequence
A |
block of
text

T} ...
is the way to enter, as a single entry in the table, something that cannot conveniently be typed as a simple string between tabs. Note that the T} end delimiter
must begin a line; additional columns of data may follow after a tab oa the same
line. See the example on page 10 for an illustration of included text blocks in a
table. If more than twenty or thirty text blocks are used in a table, various limits in
the rroff program are likely to be exceeded, producing diagnostics such as ‘too many

string/macro names’ or ‘to0 many number registers.’
Text blocks are pulled out from the table, processed separately by rroff and replaced
in the table as a solid block. If no line length is specified in the black of rexr itself,
or in the table format, the default is to use L xC/(,V+1) where L is the current line
length, C is the number of table columns spanned by the text. and V is the total
number of columns in the table.

The other parameters (point size. font. etc.) used

in setting the block of text are those in effect at the beginning of the table (including
the effect of the **.TSTM macro) and any table format specifications of size. spacing
and font, using the p, v and ( modifiers to the column key-letters.
within the text block itsell are also recognized, of course.

Commands

However, trof commands

within the table data but not within the text block do not affect that block.

5-120

Thbl

Warnings: — Although any number of lines may be present in a table, only the first 200

lines are used in calculating the widths of the various columns. A multi-page table,
of course, may be arranged as several single-page tables if this proves to be a prob-

lem. Other difficulties with formatting may arise because, in the calculation of
column widths all table entries are assumed to be in the font and size being used
when the **.TS" command was encountered, except for font and size changes indi-

cated (a) in the table format section and (b) within the table data (as in the entry
\s +3\fIdata\fP\sO). Therefore, although arbitrary rroff requests may be sprinkled in
a table, care must be taken to avoid confusing the width calculations; use requests

such as *.ps’ with care.

ADDITIONAL COMMAND LINES. If the format of a table must be changed after many simi-

lar lines, as with sub-headings or summarizations, the *‘.T&" (table continue) command
can be used to change column parameters. The outline of such a table input is:

TS
options

Sormat .
data

T&
format .
data

.TE
as in the examples on pages 10 and 12.
to its corresponding format line.

Using this procedure, each table line can be close

Warning: it is not possible to change the number of columns, the space between columns,

the global options such as box, or the selection of columns to be made equal width.

Usage.

On UNIX, b/ can be run on a simple table with the command

tbl input-file | troff
but for more complicated use, where there are several input files, and they contain equations

and ms memorandum layout commands as well as tables, the normal command would be

tbl file-1 file-2 . . .| eqn | troff —ms
and, of course, the usual options may be used on the troff and eqgn commands.

The usage for
nroff is similar to that for troff, but only TELETYPE® Model 37 and Diablo-mechanism (DASI or

GSs1) terminals can print boxed tables directly.

For the convenience of users employing line printers without adequate driving tables or
post-filters, there is a special —TX command line option to 4/ which produces output that does
not have fractional line motions in it. The only other command line options recognized by rb/

are

—ms and

—mm which are turned into commands to fetch the corresponding macro files:

usuaily it is more convenient to place these arguments on the rroff part of the command line.
but they are accepted by rb/ as well.

Note that when egn and 16/ are used together on the same file 16/ should be used first.

there are no equations within tables, either order works, but it is usually faster to run ¢/ first.
since eqn normally produces a larger expansion of the input than r4/. However. if there are
equations within tables (using the deflim mechanism in egn), rbi must be first or the output will
be scrambled.

Users must also beware of using equations in n-style columns: this is nearly

Tbl 5-121
always wrong, since (b/ attempts to split numerical format items into two parts and this is not

possible with equations. The user can defend against this by giving the defim(xx) table option;
this prevents splitting of numerical columns within the delimiters. For example, if the egn delimiters are SS, giving delim(SS) a numerical column such as **1245 S+- 165" will be divided
after 1245, not after 16.
Tbl limits tables to twenty columns; however, use of more than 16 numerical columns
may fail because of limits in rroff, producing the ‘too many number registers’' message. Trof
number registers used by rb/ must be avoided by the user within tables: these include two-digit

names from 31 to 99, and names of the forms #x, x+, x| -x, and x—, where x is any lower
case letter.

The names ##, #—, and #" are also used in certain circumstances.

To conserve

number register names, the n and a formats share a register; hence the restriction above that
they may not be used in the same column.

For aid in writing layout macros, 16/ defines a numbetl register TW which is the table
width: it is defined by the time that the **.TE' macro is invoked and may be used in the

expansion of that macro. More importantly, to assist in laying out multi-page boxed tables the
macro [# is defined to produce the bottom lines and side lines of a boxed table, and then
invoked at its end. By use of this macro in the page footer a multi-page table can be boxed. In
particular, the ms macros can be used to print a multi-page boxed table with a repeated heading

by giving the argument H to the **.TS" macro. [f the table start macro is written
IS H
a line of the form
.TH
must be given in the table after any table heading (or at the start if none). Material up to the
**.TH" is placed at the top of each page of table; the remaining lines in the table are placed on
several pages as required. Note that this is nor a feature of b/, but of the ms layout macros.

Examples.
Here are some examples

illustrating features of r6l.

represents a tab character.

Input:

box;

the input

Output:
|

cce

REP

Language @ Authors @ Runs on
Fortran @ Many @ Almost anything

PL/1®IBM®360/370

CO®BTL®11/45,H6000,370
BLISS @ Carnegie-Mellon ® PDP-10,11
IDS @ Honeywell @ H6000
Pascal @ Stanford ® 370
.TE

The symbol
|

Language
Fortran

Authors
Many

Runs on
Almost anything

PL/1

IBM

360/370

BLISS

Carnegie-Mellon

PDP-10,11

Pascal

Stanford

370

IDS

BTL
Honeywell

11/45.H6000.370

H6000

5-122 Thbl

Input:

Output:

allbox;
gz2

AT&T Common Stock

Year | Price | Dividend
1971 | 41-54 | $2.60

| 41-54

2.70

AT&T Common Stock

3 | 46-35

2.87

4 | 40-53
5 | 45-52
TSI T

3.24
3.40
55

* (first quarter only)

4D40-53®3.24

5®@45-52®3.40
6@51-59@.95°
.TE

* (first quarter only)
Input:

Output:

box:
glscslc
l|l|n

.
Major New

Major New York Bridges

Bridge
Brooklyn
Manhattan

:
York Bridges

_aJ rHew Tork

Williamsburg

Bndge

Brooklyn ®J. A. Roebling®1595

Manhattan
@G. Lindenthal
® 1470

| Triborough

Length
1595

G. Lindenthal

1470

Palmer &

1182

L. L. Buck

Queensborough

Bridge @ Designer @ Length

Designer
J. A. Roebling

Hornbostel

0. H. Ammann

1600

s
383

Williamsburg
@L. L. Buck®@® 1600

Bronx Whitestone

O. H. Ammann

2300

Throgs Neck

O. H. Ammann

1800

Queensboroug
@ Paimer
h & @ 1182
®

Hornbostel

@ ®1380

Triborough®0. H. Ammann®_

@ @383

Bronx Whitestone@0O. H. Ammann ®2300
Throgs Neck®0. H. Ammann
® 1800

aeorge Washington®@0. H. Ammann® 3500
.TE

George Washington | O. H. Ammann | 3500

Thl 5-123

Output:

B
S

6.5

Stack

2.1

QOutput:

january

january @ february @ march
april @ may
june @july @ Months
august @september

october @ november

.TE

@december

february

april

may

june

july

august

september

october

november

march

Months
december

0-124 Tbl

Input:

Output:

Composition of Foods

:i?;:s .

Percent by Weight

Composition of Foods
“I&

cless

Food

Protein | Fat

Apples

Halibut

18.4

5.2

Carbo-

hydrate
13.0

¢cless

Lima beans

7.5

22.0

Milk

3.3

4.0

5.0

Mushrooms

3.3

lele le.

Food
@ Percent by Weight

\"®

Rye bread

9.0

6.0

52.7

\" @ Protein @ Fat ® Carbo-

\"@\"
@\ " @hydrate

| In In |n.
Apples®.4®.5@13.0

Halibut®18.4®5.29. . .
Lima beans®7.5®.8®22.0
Milk®3.3®4.0®5.0
Mushrooms ®3.5®@ .4®6.0
Rye bread @9.0® .6®52.7

.TE"

Input:

Output:

a;llbox;

g z;w(sm ew(1i)

Era

|
New York Area Rocks

Formation

Precambrian | Reading Prong

1p9 1p9 1p9.

Paleozoic

Manhattan Prong

New York Area Rocks

Mesozoic

Ncwark Basin,

Era @ Formatio
® Age
n (years)

incl. Stockton,

Paleozoic @ Manhattan Prong @400 million

sg’t?jxfz é‘;"

Precamb
@ rian
Reading Prong
® > 1 billion

Newark Basin, incl.

Stockton, Lockatong, and Brunswick

formations:
also Watchungs
|

’

T) ®200 million

Cenozoic
@ Coastal Plain @ T{

On Long Island 30,000 years:
Cretaceous sediments redeposited
by recent glaciation.
.ad

T}
.TE

| 400 million

200 million

Lockatong, and

fi:sozmc@'r(
'

Age (years)

> 1 billion

Watchungs and
,

Cenozoic

Palisades.

— ,

Coastal Plain

?; Oolbong [sland

Cretaceous sedi
ment

depo-

sited by recone
glaciation.

Thl 5-125

Input:

Output:

-EQ

Name

Definition

Gamma

I"(:)-_I; r:=te~"dr

Sine

sin(x)--il-,,-(e“-e"")

Error

erf (:)--:/-z-_z _[; :e"'zdr

delim SS

.EN

doublebox:
cc
1.

Name
@ Definition

Bessel

|
e
-/o(Z)"‘f;L cos(zsind)de

Zeta

{(s)=3 k~*

.Sp

(Res>1)

(=)

VS +2p

Gam
@ SGAMMA
ma (z) = int sub 0 sup inf t sup {z-1} e sup -t dtS
Sine @Ssin (x) = | over 2i (e sup ix - & sup -ix )S
Error
@S roman erf (z) = 2 over sqrt pi int sub 0 sup z e sup {-t sup 2} dt$S
Bessel
®S J sub 0 (z) = 1 over pi int sub O sup pi cos ( z sin theta ) d theta S
Zeta®S zeta (s) = sum from k=1 to inf k sup -s —~( Re"s > 1)$
VS <2p
.TE

Input:

Output:

TS
box, tab(:):

cbssss
cp-2sssS
clelelele

r2lln2|n2|n2|n.
"

Readability of Text
l:ne Width and Leading for 10-Point Type

Line:Set: 1-Point: 2-Point : 4-Point

Width : Solid: Leading : Leading : Leading

9 Pica:\<9.3:\-6.0:\-5.3:\-7.1
14 Pica:\-4.5:\-0.6:\-0.3:\-1.7
19 Pica:\-5.0:\-5.1
31 Pica:\-3.7:\-3.8:\-2.4:\-3.6
43 Pica:\-9.1:\-9.0:\
.TE

Readability of Text
Line Width und Leading for 10-Point Type

Line || Set | 1-Point | 2-Point | 4-Point
Width Il Solid | Leading | Leuding | Laading
9Picall =9.5|
=60 | =53 | =71

14 Pical|

-4.5|

-=0.6

-0.3

-1.7

19 Pica || =5.0]

=5.1

0.0

-2.0

)

31 Pica || =3.7|
43 Pica ll =91

=38
—90

-4
—-59

-36
8.8

5-126 Thl

Output:

Input:

Some London Transport Statistics

(Year 1964)

cip-2'§
I n
an.
Some London Transport Statistics
(Year 1964)

Railway route miles
@ 244
Tube @ 66
Sub-surface @ 22
Surface @ 156

.Tp&.

l’ c
ar.

Passenger traffic \- railway
Journeys
@ 674 million
Average length®4.55 miles
Passenger miles
@ 3,066 million
T&

'a'r
Pas.senger traffic \-Cree
road

Journeys
@ 2,252 million
Average length
@ 2.26 miles

Passenger
miles
® ' 5,094 million
T&

Railway route miles
Tube
Sub-surface
Surface

244
66
22
156

Pasjsenger
traffic — railway
ourneys
Average length
Passenger miles

Passenger traffic - road

Journeys

Average length
Passenger miles

Vehicles

2,905
1,269
4,174
8,347

Staff
Adr.nimsx.rauv?, etc.
Civil engineering

73.739
3,582
5.134

Electrical en

Mech.
eng. — railway
Mech. eng. — road
Railway operations
Road operations

)
SP .5

Other

Total railway ®4,174
Omnibuses
@ 8,347
J&
in
an.

.Sp .5

Staff® 73,739
Administrative, etc. ® 5,582
Civil engineering @5,134
Electrical eng. @ 1,714
Mech. eng. \- railway®4.,310
Mech. eng. \- road ®9,152
Railway operations
@ 8,930
Road operations
@ 35,946
Other® 2,971
.TE

2.26 miles
5.094 million

12,521

l. 0

Railway motor cars
@ 2,905
Railway trailer cars
@ 1,269

2.252 million

Railway motor cars
Railway trailer cars
Total railway
Omnibuses

Vehicles® 12,521

674 mnll}on
4.55 r.m‘les
3.066 million

1 714

4,310
9.152
8.930
35.946

2,971

Tbl 5-127

Input:
.ps 8
.vs 10p

TS
center box:
cSsS

ciss
cce

IB1n.
~ New Jersey Representatives

(Democrats)

SP o5
Name
@ Office address
@ Phone
SP .5

James J. Florio®23 S. White Horse Pike, Somerdale 08083
@ 609-627-8222
William J. Hughes
® 2920 Atlantic Ave., Atlantic City 08401 ® 609-345-4844
James J. Howard
® 801 Bangs Ave., Asbury Park 07712® 201-774-1600
Frank Thompson, Jr. @ 10 Rutgers Pl., Trenton 08618 ©609-599-1619
Andrew Maguire®
115 W. Passaic St., Rochelle Park 07662
@ 201-843-0240
Robert A. Roe®U.S.P.O., 194 Ward St., Paterson 07510®201-523-5152
Henry Helstoski
@ 666 Paterson Ave., East Rutherford 07073
® 201-939-9090
Peter W. Rodino, Jr.
@ Suite 1435A, 970 Broad St., Newark 07102
® 201-645-3213
Joseph G. Minish
@ 308 Main St., Orange 07050
® 201-645-6363
Helen S. Meyner®
32 Bridge St., Lambertville 08530
@ 609-397-1830
Dominick V. Daniels
® 895 Bergen Ave., Jersey City 07306
® 201-659-7700

Edward J. Patten
® Natl. Bank Bldg., Perth Amboy 08861 ® 201-826-4610
SP 5
J&

ciss
IBin.

(Republicans)
.SP .Sv

Millicent Feawick @41 N. Bridge St., Somerville 08876
@ 201-722-8200
Edwin B. Forsythe
® 301 Mill St., Moorestown 08057
@ 609-235-6622
Matthew J. Rinaldo® 1961 Morris Ave., Union 07083 ®201-687-4235
.TE
.ps 10

.vs 12p

5-128 Thl

QOutput:
New Jersey Representatives
(Democrats)

Office address

Phone

23 S. White Horse Pike, Somerdale 08083
2920 Atlantic Ave., Atlantic City 08401
801 Bangs Ave., Asbury Park 07712
10 Rutgers Pi., Trenton 08618
115 W. Passaic St.. Rochelle Park 07662
U.S.P.O., 194 Ward St., Paterson 07510
666 Paterson Ave., East Rutherford 07073
Suite 1435A. 970 Broad St., Newark 07102

609-627-8222
609-345-4844

Name

James J. Florio
William J. Hughes

James J. Howard

Frank Thompson, Jr.
Andrew Maguire
Robert A. Roe
Henry Helstoski

Peter W. Rodino, Jr.

Joseph G. Minish
Helen S. Meyner

Dominick V. Daniels
Edward J. Patten

308 Main St., Orange 07050
32 Bridge St.. Lambertville 08530
895 Bergen Ave., Jersey City 07306
Natl. Bank Bldg.. Perth Amboy 08861

201-774-1600
609-599-1619
201-843-0240
201-523-5152
201-939-9090
201-645-3213
201-645-6363
609-397-1830
201-659-7700
201-826-4610

(Republicans)
Millicent Fenwick
Edwin B. Forsythe
Matthew J. Rinzldo

41 N. Bridge St.. Somerville 08876
301 Milt St.. Moorestown 08057
1961 Morris Ave.. Union 07083

201-722-8200
609-235-6622
201-687-423S5

This is a paragraph of normal text placed here only to indicate where the left and right margins
are. In this way the reader can judge the appearance of centered tables or expanded tables, and
observe how such tables are formatted.
Input:

.19
expand;
CSSS
cccc

ilnn.

Bell Labs Locations

Name @ Address @ Area Code @ Phone

Holmdel @ Holmdel, N. J. 07733 ®201 @ 949-3000
Murray Hill @ Murray Hill, N. J. 07974©201 @ 582-6377
Whippany @ Whippany, N. J. 079810201 @ 386-3000
Indian Hill ® Naperville, Illinois 60540 ® 312 ®690-2000
-TE

Output:

Bell Labs Locations

Name

Holmdel
Murray Hill

Whippany
Indian Hill

Address
Holmdel, N. J. 07733
Murray Hill, N. J. 07974
Whippany, N. J. 07981

Naperville, Illinois 60540

Area Code
201
201
201

312

Phone

949-3000
582-6377
386-3000
690-2000

Tbl 5-129

Input:

o 13
box:
¢cb §

clele s
Beiw (1) | lew(2i) | 1p8 | Iw(1.6i)p8.
Some [nteresting Places

Name
@ Description
@ Practical Information

T(
American Museum of Natural History

TI®
T

The collections fit 11.5 acres (Michelin) or 2§ acres (MTA)
of exhibition halls on four floors. There is a full-sized replica
of a blue whale and the world’s largest star sapphire (stolen in [964).

TI® Hours® 10-$. ex. Sun 11-5, Wed. t0 9
\"®\"
@ Location® T
%;:mral Park West & 79th St.

\"@\"® Admission D Donation: $1.00 asked
\:@\:QSubwzyQ AA to 81st St.
\"O\ D Telephone® 212-873-4225$
Broax Zoo®
T|

About 3 mile long and .8 mile wide, this is the largest z0oo in America.
A lion euts |8 pounds

of meat a day while a sea lion euts 1S pounds of fish.

TI® Hours
@T

%%«4:30 winter, to 5:00 summer

VOV
@ Locati@on
T

.;ra’sm St. & Southern Blvd, the Bronx.

\"D\"D Admission
D
$1.00, dut Tu.We.Th free
"D\
@ SubwayD 2, § to Eust Tremont Ave.
'O\
@ Telephone
D 212-933-1759
Brookiyn Museum
@ T|

Five floors of gulleries contain American and ancient art.
There are American period rooms and architectural ornaments saved
from wreckers, such as s classical figure from Pennsylvania Station.

TI® Hours
@ Wed-Sat. 10-5, Suna 12-$

\"@\"
@ Locatio
@ T
n

%mem Pacrkway & Washington Ave., Brookiyn.

\:@\'@ Admission D Free
\"@\"
@ Subwuy@
2.3 to Eustern Parkway.
\"O\
O Telephone
D 212-638-5000

New-York Historical Society

TIOT(

All the original paintings for Audubon’s

Birds of America
are here, 28 are exhibits of American decorative arts, New York history,
Hudson River school paintings. carriages. and glass paperweights.

TI® Hours® T{

TiiifioF?i & Sun, 1-3; Sat 10-3
T

\"O\
@ Locati@on
T

C’cnu:u Park West & 77th St.

\:@\:@ Admission
@ Eree
\.®\.®Subway® AA to 81st St.
\T%\ @ Telephone
D 212-873-3400

5-130 Thbl

Output:

Some Interesting Places
Name
American

um of
History

Description
Muse- | The collections

fill

Practical Information
11.5 acres | Hours

10-5. ex. Sun 11-5, Wed. to
9

largest

star

sapphire

(stolen in 1964).
Bronx Zoo

About 2 mile long and .6 mile | Hours

10-4:30 winter, to $:00 summer

wide, this is the largest zoo in | Location

185th St. & Southern Bivd, the

America.

pounds

lion

of meat

eats

day

while

sea lion eats 1S pounds of fish.
|

| Admission

Bronx,

| $1.00. but Tu,We,Th free

Subway

2. 5 to East Tremont Ave.

Telephone

212-933-1759

saved

from

wreckers,

| Subway

2.3 10 Eastern Parkway.

such as a classical figure from | Telephone | 212-638-5000

Pennsylvania Station.
New-York Hisror- | All
ical Society

the

original

paintings

for | Hours

Tues-Fri
& Sun, 1-§; Sat 10-$

Audubon’s Birds of

America are | Location
Central Park West & 77th St.
here, as are exhibits of Ameri- | Admission | Free

can decorative arts, New York | Subway
AA to 81st St.
history, Hudson River school | Telephone | 212-873-3400
paintings, carriages, and glass
paperweights.
Acknowledgments.

Many thanks are due to J. C. Blinn, who has done a large amount of testing and assisted
with the design of the program. He has also written many of the more intelligible sentences in

this document and helped edit all of it.

All phototypesetting programs on UNIX are dependent

on the work of the late J. F. Ossanna, whose assistance with this program in particular had been
most helpful. This program is patterned on a table formatter originally written by J. F. Gimpel.
The assistance of T. A. Dolotta, B. W. Kerighan, and J. N. Sturman is gratefully acknowledged.

References.

(11

J. F. Ossanna, NROFFITROFF User's Manual, Computing Science Technical Report No. 54,
Bell Laboratories, 1976.

(2]

K. Thompson and D. M. Ritchie, *“The UNix Time-Sharing System."” Comm. ACM. 17.
pp. 365—=75 (1974).

(3]

B. W. Kernighan and L. L. Cherry, *“*A System for Typesetting Mathematics." Comm.
ACM. 18, pp. 15157 (1975).

[4]

M. E. Lesk, Typing Documents on Unix, UNIX Programmesr's Manual, Volume 2.

Thl 5-131

(5]

M. E. Lask and B. W. Kernighan, Computer Typesetting of Technical Journals on Untx, Proc.
AFIPS NCC, vol. 46, pp. 879-888 (1977).

(6]

J. R. Mashey and D. W. Smith, **Documentation Tools und Techniques.” Proc. 2nd /.

Conf. on Software Engineering, pp. 177-181 (October, 1976).

List of Thl Command Characters and Words

Vertical spanning at top

Change data separator character
Text block
Vertical spacing change

Minimum width value
Included rroff command
Vertical line

Double vertical line
Vertical span
Yertical span

Double horizontal line
Horizontal line
Short horizontal line
Repeat character

center

doublebox

¢cC

Secrion

bB
box

Meaning
Alphabetic subcolumn
Draw box around all items
Boldface item
Draw box around table
Centered column
Center table in page
Doubled box around table
Equal width columns
Make table full line width
Font change
[talic item
Left adjusted column
Numerical column
Column s=paration
Point size change
Right adjusted column
Spanned item

Command
2 A
allbox

Refer — A Bibliography System 5-133

Refer — A Bibliography System
Bill Tuthill
Computing Services
University of California
Berkeley, CA 94720

Introduction

Taken together, the refer programs constitute a database system for use with variable-length

information. To distinguish various types of bibliographic material, the system uses labels composed
of upper case letters, preceded by a percent sign and followed by a space. For example, one document

might be given this entry:

%A Joel Kies

%T Document Formatting on Unix Using the -ms Macros
%1 Computing Services
%C Berkeley
%D 1980

Each line is called a field, and lines grouped together are called a record; records are separated from
each other by a blank line. Bibliographic information follows the labels, containing data to be used by
the refer system. The order of fields is not important, except that authors should be entered in the
same order as they are listed on the document. Fields can be as long as necessary, and may even be
continued on the following line(s).

The labels are meaningful to nroff/troff macros, and, with a few exceptions, the refer program
itself does not pay attention to them. This implies that you can change the label codes, if you also
change the macros used by nroff/troff . The macro package takes care of details like proper order-

ing, underlining the book title or journal name, and quoting the article’s title. Here are the labels
used by refer, with an indication of what they represent:

5-134 Refer — A Bibliography System

%H Header commentary, printed before reference
%A Author’s name
%Q Corporate or foreign author (unreversed)
%T Title of article or book
%S Series title
%d dJournal containing article
% B Book containing article
%R Report, paper, or thesis (for unpublished material)
%V Volume
% N Number within volume
%E Editor of book containing article
%P Page number(s)
%1 Issuer (publisher)
% C City where published
%D Date of publication
%0 Other commentary, printed at end of reference
%K Keywords used to locate reference
%L Label used by —k option of refer
%X Abstract (used by roffbib, not by refer)
Only relevant fields should be supplied.

Except for % A, each field should be given only once; in the

case of multiple authors, the senior author should come first. The %Q is for organizational authors,
or authors with Japanese or Arabic names, in which cases the order of names should be preserved.
Books should be labeled with the % T, not with the % B, which is reserved for books containing articles.

The %dJ and %B fields should never appear together, although if they do, the %J will override

the %B.

If there is no author, just an editor, it is best to type the editor in the %A field, as in this

example:

%A Bertrand Bronson, ed.
The %E field is used for the editor of a book (% B) containing an article, which has its own author.
For unpublished material such as theses, use the %R field; the title in the % T field will be quoted,

but the contents of the %R field will not be underlined.

Unlike other fields,

% H, %0, and %X

should contain their own punctuation. Here is a modest example:

Mike E. Lesk

%T
%B
%1
% C
%D
%V
%K
%X

Some Applications of Inverted Indexes on the Unix System
Unix Programmer’s Manual
Bell Laboratories
Murray Hill, NJ
1978
2a
refer mkey inv hunt
Difficult to read paper that dwells on indexing strategies,

giving little practical advice about using X¥Brefer XP.

Note that the author’s name is given in normal order, without inverting the surname; inversion is
done automatically, except when %Q is used instead of %A.

We use %X rather than %O for the

commentary because we do not want the comment printed all the time.

The %O and % H fields are

printed by both refer and roffbib; the % X field is printed only by roffbib, as a detached annotation paragraph.

Data Entry with Addbib

The addbib program is for creating and extending bibliographic databases.
the filename of your bibliography:

You must give it

Refer — A Bibliography System

5-135

% addbib database
Every time you enter addbib, it asks if you want instructions.

type RETURN.

To get them, type y; to skip them,

Addbib prompts for various fields, reads from the keyboard, and writes records con-

taining the refer codes to the database.

After finishing a field entry, you should end it by typing

RETURN. If a field is too long to fit on a line, type a backslash (|) at the end of the line, and you will
be able to continue on the following line.

Note: the backslash works in this capacity only inside add-

bib.
A field will not be written to the database if nothing is entered into it.

Typing a minus sign as

the first character of any field will cause addbib to back up one field at a time.

Backing up is the

best way to add multiple authors, and it really helps if you forget to add something important. Fields
not contained in the prompting skeleton may be entered by typing a backslash as the last character

before RETURN.

The following line will be sent verbatim to the database and addbib will resume

~with the next field.

This is identical to the procedure for dealing with long fields, but with new fields,

don’t forget the % key-letter.
Finally, you will be asked for an abstract (or annotation), which will be preserved as the % X
field.

Type in as many lines as you need, and end with a control-D (hold down the CTRL button, then

press the “d” key).

This prompting for an abstract can be suppressed with the —a command line

option.
After one bibliographic record has been completed, addbib will ask if you want to continue.

you do, type RETURN; to quit, type q or n (quit or no).
editors to correct mistakes made while entering data.

It is also possible to use one of the system

After the “Continue?” prompt, type any of the

following: edit, ex, vi, or ed — you will be placed inside the corresponding editor, and returned to

addbib afterwards, from where you can either quit or add more data.
If the prompts normally supplied by addbib are not enough, are in the wrong order, or are too
numerous, you can redefine the skeleton by constructing a promptfile.

after the —p command line option.

Create some file, to be named

Place the prompts you want on the left side, followed by a single

TAB (control-I), then the refer code that is to appear in the bibliographic database.

Addbib will

send the left side to the screen, and the right side, along with data entered, to the database.
Printing the Bibliography

Sortbib is for sorting the bibliography by author (% A) and date (% D), or by data in other
It is quite useful for producing bibliographies and annotated bibliographies, which are seldom

fields.

entered in strict alphabetical order.

It takes as arguments the names of up to 16 bibliography files,

and sends the sorted records to standard output (the terminal screen), which may be redirected
through a pipe or into a file.

The —sKEYS flag to sortbib will sort by fields whose key-letters are in the KEYS string,
rather than merely by author and date.

that all such fields are to be used.

Key-letters in KEYS may be followed by a ‘4’ to indicate

The default is to sort by senior author and date (printing the

senior author last name first), but —sA+D will sort by all authors and then date, and —sATD will sort
on senior author, then title, and then date.

Roffbib

for running off the

(probably sorted)

bibliography.

It can

handle

annotated

bibliographies — annotations are entered in the % X (abstract) field.

Roffbib is a shell script that

calls

definitions

refer

—B

and

nroff

—mbib.

wuses

the

macro

/usr/lib/tmac/tmac.bib, which you can redefine if you know nroff and troff.
print the

that

reside

Note that refer will

% H and %O commentaries, but will ignore abstracts in the %X field; roffbib will print

both fields, unless annotations are suppressed with the —x option.
The following command sequence will lineprint the entire bibliography, organized alphabetically

by author and date:

5-136 Refer — A Bibliography System

% sortbib database | roffbib | lIpr
This is a good way to proofread the bibliography, or to produce a stand-alone bibliography at the end

of a paper. Incidentally, roffbib accepts all flags used with nroff.

For example:

% sortbib database | roffbib —Tdtc —sl
will make accent marks work on a DTC daisy-wheel printer, and stop at the bottom of every page for
changing paper. The —n and —o flags may also be quite useful, to start page numbering at a selected
point, or to produce only specific pages.

Roffbib understands four command-line number registers, which are something like the two-

letter number registers in —ms. The —rN1 argument will number references beginning at one (1); use
another number to start somewhere besides one. The —rV2 flag will double-space the entire bibliography, while —rV1 will double-space the references, but single-space the annotation paragraphs. Finally,

specifying —rL6i changes the line length from 6.5 inches to 6 inches, and saying —rO1i sets the page
offset to one inch, instead of zero. (That’s a capital O after —r, not a zero.)
Citing Papers with Refer
The refer program normally copies input to output, except when it encounters an item of the
form:

partial citation

]
The partial citation may be just an author’s name and a date, or perhaps a title and a keyword, or
maybe just a document number. Refer looks up the citation in the bibliographic database, and
transforms it into a full, properly formatted reference. If the partial citation does not correctly identify a single work (either finding nothing, or more than one reference), a diagnostic message is given.
If nothing is found, it will say “No such paper.” If more than one reference is found, it will say “Too
many hits.” Other diagnostic messages can be quite cryptic; if you are in doubt, use checknr to verify that all your .[’s have matching .]’s.

When everything goes well, the reference will be brought in from the database, numbered, and

placed at the bottom of the page. This citation,! for example, was produced by:
This citation,

lesk inverted indexes

]

for example, was produced by

The .[ and .] markers, in essence, replace the .FS and .FE of the —ms macros, and also provide a
numbering mechanism. Footnote numbers will be bracketed on the the lineprinter, but superscripted
on daisy-wheel terminals and in troff. In the reference itself, articles will be quoted, and books and
journals will be underlined in nroff, and italicized in troff.
Sometimes you need to cite a specific page number along with more general bibliographic
You may have, for instance, a single document that you refer to several times, each time
giving a different page citation. This is how you could get “p. 10” in the reference:
material.

kies document formatting

]
The first line, a partial citation, will find the reference in your bibliography.

The second line will

Refer — A Bibliography System
insert the page number into the final citation.

5-137

Ranges of pages may be specified as “%
P 56-78.

When the time comes to run off a paper, you will need to have two files: the bibliographic database, and the paper to format. Use a command line something like one of these:

% refer —p database paperinrgff —ms
% refer —p database paperltblnroff —ms
% refer —p database paper|tb“neqn’nr0fi —ms
If other preprocessors are used, refer should precede tbl, which must in turn precede eqn or negn.
The —p option specifies a “private” database, which most bibliographies are.

Refer’s Command-line Options

Many people like to place references at the end of a chapter, rather than at the bottom of the
page.

The —e option will accumulate references until a macro sequence of the form

{

SLISTS

]
1s encountered (or until the end of file)‘.
point, collapsing identical references.

Refer will then write out all references collected up to that

Warning: there is a limit (currently 200) on the number of

references that can be accumulated at one time.

It is also possible to sort references that appear at the end of text.

The —sKEYS flag will sort

references by fields whose key-letters are in the KEYS string, and permute reference numbers in the

text accordingly.

It is unnecessary to use —e with it, since —s implies —e.

be followed by a ‘+’ to indicate that all such fields are to be used.

Key-letters in KEYS may

The default is to sort by senior

author and date, but -=-sA+D will sort on all authors and then date, and —sA+T will sort by authors

and then title.
Refer can also make citations in what is known as the Social or Natural Sciences format.
Instead of numbering references, the —! (letter ell) flag makes labels from the senior author’s last

name and the year of publication.

For example, a reference to the paper on Inverted Indexes cited

above might appear as [Lesk1978a].

It is possible to control the number of characters in the last

name, and the number of digits in the date.

For instance, the command line argument —16,2 might

produce a reference such as [Kernig78c].

Some bibliography standards shun both footnote numbers and labels composed of author and

date, requiring some keyword to identify the reference.

The —k flag indicates that, instead of

numbering references, key labels specified on the %L line should be used to mark references.
The —n flag means to not search the default reference file, located in /usr/dict/papers/Rv7man.
Using this flag may make refer marginally faster.
printing Jones, J. A. instead of J. A. Jones.

the senior author.

The —an flag will reverse the first n author names,

Often —al is enough; this will reverse the names of only

In some versions of refer there is also the —f flag to set the footnote number to

some predetermined value; for example, —f23 would start numbering with footnote 23.
Making an Index

Once your database is large and relatively stable, it is a good idea to make an index to it, so that
references can be found quickly and efficiently.

The indxbib program makes an inverted index to

the bibliographic database (this program is called pubindex in the Bell Labs manual).

An inverted

index could be compared to the thumb cuts of a dictionary — instead of going all the way through
your bibliography, programs can move to the exact location where a citation is found.
Indxbib itself takes a while to run, and you will need sufficient disk space to store the indexes.
But once it has been run, access time will improve dramatically.
several million characters can be indexed with no problem.

Furthermore, large databases of

The program is exceedingly simple to use:

5-138 Refer — A Bibliography System

% indxbib database
Be aware that changing your database will require that you run indxbib over again.

If you don’t, you

may fail to find a reference that really is in the database.

Once you have built an inverted index, you can use lookbib to find references in the database.
Lookbib cannot be used until you have run indxbib.

When editing a paper, lookbib is very useful

to make sure that a citation can be found as specified.

It takes one argument, the name of the

bibliography, and then reads partial citations from the terminal, returning references that match, or
nothing if none match.

Its prompt is the greater-than sign.

% lookbib database
> lesk inverted indexes

%A Mike E. Lesk
%'T Some Applications of Inverted Indexes on the Unix System
%d Unix Programmer’s Manual
%1 Bell Laboratories
% C Murray Hill, NJ
%D 1978
%V 2a
% X Difficult to read paper that dwells on indexing strategies,
giving little practical advice about using \ fBrefer\fP.
>

If more than one reference comes back, you will have to give a more precise citation for refer.

Experiment until you find something that works; remember that it is harmless to overspecify.

To get

out of the lookbib program, type a control-D alone on a line; lookbib then exits with an “EQT”
message.

Lookbib can also be used to extract groups of related citations.

For example, to find all the

papers by Brian Kernighan found in the system database, and send the output to a file, type:

% lookbib /usr/dict/papers/Ind > kern.refs
> kernighan
> EOT

% cat kern.refs
Your file, “kern.refs”, will be full of references.

A similar procedure can be used to pull out all papers

of some date, all papers from a given journal, all papers containing a certain group of keywords, etc.

Refer Bugs and Some Solutions
The refer program will mess up if there are blanks at the end of lines, especially the %A

author line.

Addbib carefully removes trailing blanks, but they may creep in again during editing.

Use an editor command — g/

*$/s/// — to remove trailing blanks from your bibliography.

Having bibliographic fields passed through as string definitions implies that interpolated strings

(such as accent marks) must have two backslashes, so they can pass through copy mode intact.

For

instance, the word ‘““téléphone” would have to be represented:

te\\*'le\\*'phone
in order to come out correctly.

instead.

In the %X field, by contrast, you will have to use single backslashes

This is because the %X field is not passed through as a string, but as the body of a para-

graph macro.

Another problem arises from authors with foreign names.

When a name like “Valéry Giscard

d’Estaing” is turned around by the —a option of refer, it will appear as “d’Estaing, Valéry Giscard,”
rather than as “Giscard d’Estaing, Valéry.” To prevent this, enter names as follows:

Refer — A Bibliography System 5-139

%A Vale\\*'ry Giscard\0d’Estaing
%A Alexander Csoma\0de\0Ko\\*:ro\\*:s
(The second is the name of a famous Hungarian linguist.) The backslash-zero is an nroff/troff

request meaning to insert a digit-width space.

against mis-sorting.

It will protect against faulty name reversal, and also

Footnote numbers are placed at the end of the line before the .[ macro. This line should be a
line of text, not a macro. As an example, if the line before the .[ is a .R macro, then the .R will eat

the footnote number. (The .R is an —ms request meaning change to Roman font.) In cases where the
font needs changing, it is necessary to do the following:

\flet al.\fR
I
awk aho kernighan weinberger

]

Now the reference will be to Aho et al.2 The \fI changes to i‘talics, and the \fR changes back to Roman

font.

Both these requests are nroff/troff requests, not part of —ms.
is added after this sequence, it will indeed appear in the output.

If and when a footnote number

Internal Details of Refer

tem.

You have already read everything you need to know in order to use the refer bibliography sys-

The remaining sections are provided only for extra information, and in case you need to change

the way refer works.

The output of refer is a stream of string definitions, one for each field in a reference. To create
string names, percent signs are simply changed to an open bracket, and an [F string is added, contain-

ing the footnote number. The %X, %Y and %Z fields are ignored; however, the annobib program
changes the %X to an .AP (annotation paragraph) macro. The citation used above yields this inter-

mediate output:

ds [F

J-

.ds [A Mike E. Lesk
.ds [T Some Applications of Inverted Indexes on the Unix System
.ds [J

Unix Programmer’s Manual

.ds [I

Bell Laboratories

.ds [C Murray Hill, NJ

ds [D 1978
ds [V 2a
ar [T 0

anr [A O
ar [O 0

These

1 journal-article

string

definitions

are

sent

nroff,

which

can

use

the

—ms

macros

defined

/usr/lib/mx/tmac.xref to take care of formatting things properly. The initializing macro .]— precedes

the string definitions, and the labeled macro .][ follows.
that running a file twice through refer is harmless.

These are changed from the input .[ and .] so

The .][ macro, used to print the reference, is given a type-number argument, which is a numeric
label indicating the type of reference involved. Here is a list of the various kinds of references:

5-140 Refer — A Bibliography System
Field

Value

%0d
1
3
%B
%R %G
2
%1
%M
5
none

Kind of Reference

Journal Article
Article in Book
4Report, Government Report
Book
Bell Labs Memorandum (undefined)
Other

The order listed above is indicative of the precedence of the various fields.

In other words, a refer-

ence that has both the %dJ and %B fields will be classified as a journal article.

If none of the fields

listed is present, then the reference will be classified as “other.”

The footnote number is flagged in the text with the following sequence, where number is the
footnote number:

\([.number\*(.]

The \*([+ and \*(.] stand for bracketing or superscripting. In nroff with low-resolution devices such
as the lpr and a crt, footnote numbers will be bracketed.
note numbers will be superscripted.

In troff, or on daisy-wheel printers, foot-

Punctuation normally comes before the reference number; this

can be changed by using the —P (postpunctuation) option of refer.
In some cases, it is necessary to override certain fields in a reference.

For instance, each time a

work is cited, you may want to specify different page numbers, and you may want to change certain
fields.

This citation will find the Lesk reference, but will add specific page numbers to the output,

even though no page numbers appeared in the original reference.

[

lesk inverted indexes

T7-13

Computing Services

%0 UNX 12.2.2.

]
The %1 line will also override any previous publisher information, and the % O line will append some

commentary.

The refer program simply adds the new %P, %I, and %O strings to the output, and

later strings definitions cancel earlier ones.
It is also possible to insert an entire citation that does not appear in the bibliographic database.
This reference, for example, could be added as follows:

%A Brian Kernighan
%'T A Troff Tutorial

%1
%D

Bell Laboratories
1978

]
This will cause refer to interpret the fields exactly as given, without searching the bibliographic database.

This practice is not recommended, however, because it’s better to add new references to the

database, so they can be used again later.
If you want to change the way footnote numbers are printed, signals can be given on the .[ and .]
lines.

For example, to say ‘“See reference (2),” the citation should appear as:

Refer — A Bibliography System

5-141

See reference

[(

partial citation

Note that blanks are significant on these signal lines. If a permanent change in the footnote format is

desired, it’s best to redefine the [. and .] strings.
Changing the Refer Macros

This section is provided for those who wish to rewrite or modify the refer macros. This is
necessary in order to make output correspond to specific journal requirements, or departmental standards. First there is an explanation of how new macros can be substituted for the old ones. Then
several alterations are given as examples. Finally, there is an annotated copy of the refer macros
used by roffbib .

The refer macros for nroff/troff supplied by the —ms macro package reside in
/usr/lib/mx/tmac.xref; they are reference macros, for producing footnotes or endnotes. The refer
macros used by roffbib, on the other hand, reside in /usr/lib/tmac/tmac.bib; they are for producing a
stand-alone bibliography.

To change the macros used by roffbib, you will need to get your own version of this shell script
into the directory where you are working. These two commands will get you a copy of roffbib and
the macros it uses:

% cp /usr/lib/tmac/tmac.bib bibmac

You can proceed to change bibmac as much as you like. Then when you use roffbib, you should
specify your own version of the macros, which will be substituted for the normal ones
% roffbib

—m bibmac filename

where filename is the name of your bibliography file.

Make sure there’s a space between —m and

bibmaec.

If you want to modify the refer macros for use with nroff and the —ms macros, you will need
to get a copy of “tmac.xref”:

% cp /usr/lib/ms/s.ref refmac

These macros are much like “bibmac”, except they have .FS and .FE requests, to be used in conjunction with the —ms macros, rather than independently defined .XP and .AP requests. Now you can
put this line at the top of the paper to be formatted:
.s0 refmac

Your new refer macros will override the definitions previously read in by the —ms package.

This

method works only if “refmac” is in the working directory.

Suppose you didn’t like the way dates are printed, and wanted them to be parenthesized, with
no comma before. There are five identical lines you will have to change. The first line below is the
old way, while the second is the new way:

if PAF(DTM , \\*(ID\c
if P\F(D” \& (\V([D)\c

In the first line, there is a comma and a space, but no parentheses. The “\c” at the end of each line
indicates to nroff that it should continue, leaving no extra space in the output. The “\&” in the
second line is the do-nothing character; when followed by a space, a space is sent to the cutput.
If you need to format a reference in the style favored by the Modern Language Association or
Chicago University Press, in the form (city: publisher, date), then you will have to change the middle
of the book macro [2 as follows:

5-142 Refer — A Bibliography System

\& (\c

it PA\FCTM \\*([C:

\V([T\c

.)i\f P\F(ID”” , \\*([D\c

This would print (Berkeley: Computing Services, 1982) if all three strings were present. The first line

prints a space and a parenthesis; the second prints the city (and a colon) if present; the third always
prints the publisher (books must have a publisher, or else they’re classified as other); the fourth line
prints a comma and the date if present; and the fifth line closes the parentheses. You would need to
make similar changes to the other macros as well.
Acknowledgements

Mike Lesk of Bell Laboratories wrote the original refer software, including the indexing pro-

grams. Al Stangenberger of the Forestry Department wrote the first version of addbib, then called
bibin. Greg Shenaut of the Linguistics Department wrote the original versions of sortbib and
roffbib. All these contributions are greatly appreciated.

Some Applications of Inverted Indexes 5-143

Some Applications of Inverted Indexes on the UNIX System
M. E. Lesk
Bell Laboratories

Murray Hill, New Jersey 07974

1. Introduction.

The UNIXT system has many utilities (e.g. grep, awk, lex, egrep, fgrep, ...) to search

through files of text, but most of them are based on a linear scan through the entire file, using
some deterministic automaton.

This memorandum discusses a program which uses inverted

indexes! and can thus be used on much larger data bases.
As with any indexing system, of course, there are some disadvantages; once an index is
made, the files that have been indexed can not be changed without remaking the index. Thus
applications are restricted to those making many searches of relatively stable data.

Further-

more, these programs depend on hashing, and can only search for exact matches of whole keywords.

It is not possible to look for arithmetic or logical expressions (e.g. “date greater than

1970”) or for regular expression searching such as that in lex.?

Currently there are two uses of this software, the refer preprocessor to format references, and the lookall command to search through all text files on the UNIX system.

uses.

The remaining sections of this memorandum discuss the searching programs and their
Section 2 explains the operation of the searching algorithm and describes the data col-

lected for use with the lookall command.

The more important application, refer has a user’s

description in section 3. Section 4 goes into more detail on reference files for the benefit of
those who wish to add references to data bases or write new troff macros for use with refer.

The options to make refer collect identical citations, or otherwise relocate and adjust references, are described in section 5. The UNIX manual sections for refer, lookall, and associated
commands are attached as appendices.

2. Searching.

The indexing and searching process is divided into two phases, each made of two parts.
These are shown below.

Construct the index.
(1)

Find keys — turn the input files into a sequence of tags and keys, where each tag
identifies a distinct item in the input and the keys for each such item are the

strings under which it is to be indexed.
(2)

Hash and sort — prepare a set of inverted indexes from which, given a set of keys,
the appropriate item tags can be found quickly.

Retrieve an item in response to a query.

T UNIX is a trademark of Bell Laboratories.

1 D. Knuth, The Art of Computer Programming: Vol. 3, Sorting and Searching, Addison-Wesley, Reading, Mass., 1977.

See section 6.5.

2 M. E. Lesk, “Lex — A Lexical Analyzer Generator,” Comp. Sci. Tech. Rep. No. 39, Bell Laboratories,
Murray Hill, New Jersey, October 1975.

5-144

Some Applications of Inverted Indexes

(3)

Search — Given some keys, look through the files prepared by the hashing and
sorting facility and derive the appropriate tags.

(4)

Deliver — Given the tags, find the original items.

This completes the searching

process.

The first phase, making the index, is presumably done relatively infrequently.

course, be done whenever the data being indexed change.

It should, of

In contrast, the second phase,

retrieving items, is presumably done often, and must be rapid.

An effort is made to separate code which depends on the data being handled from code

which depends on the searching procedure. The search algorithm is involved only in programs
(2) and (3), while knowledge of the actual data files is needed only by programs (1) and (4).
Thus it is easy to adapt to different data files or different search algorithms.

To start with, it is necessary to have some way of selecting or generating keys from input
files.

For dealing with files that are basically English, we have a key-making program which

automatically selects words and passes them to the hashing and sorting program (step 2). The
format used has one line for each input item, arranged as follows:

name:start,length (tab) keyl key2 key3 ...

where name is the file name, start is the starting byte number, and length is the number of
bytes in the entry.
These lines are the only input used to make the index.

The first field (the file name,

byte position, and byte count) is the tag of the item and can be used to retrieve it quickly.
Normally, an item is either a whole file or a section of a file delimited by blank lines.

the tab, the second field contains the keys.

After

The keys, if selected by the automatic program,

are any alphanumeric strings which are not among the 100 most frequent words in English

and which are not entirely numeric (except for four-digit numbers beginning 19, which are
accepted as dates).

Keys are truncated to six characters and converted to lower case.

selection is needed if the original items are very large.

Some

We normally just take the first n keys,

with n less than 100 or so; this replaces any attempt at intelligent selection.

One file in our

system is a complete English dictionary; it would presumably be retrieved for all queries.
To generate an inverted index to the list of record tags and keys, the keys are hashed

and sorted to produce an index.
associated with each key.

What is wanted, ideally, is a series of lists showing the tags

To condense this, what is actually produced is a list showing the

tags associated with each hash code, and thus with some set of keys. To speed up access and
further save space, a set of three or possibly four files is produced.

File

Contents

entry

Pointers to posting file

posting

Lists of tag pointers for

tag

Tags for each item

key

Keys for each item

These files are:

for each hash code

each hash code

(optional)
The posting file comprises the real data: it contains a sequence of lists of items posted under

each hash code.

To speed up searching, the entry file is an array of pointers into the posting

file, one per potential hash code.

Furthermore, the items in the lists in the posting file are not

referred to by their complete tag, but just by an address in the tag file, which gives the complete tags. The key file is optional and contains a copy of the keys used in the indexing.
The searching process starts with a query, containing several keys.

all items which were indexed under these keys.

The goal is to obtain

The query keys are hashed, and the pointers

in the entry file used to access the lists in the posting file.

These lists are addresses in the tag

file of documents posted under the hash codes derived from the query.

The common items

from all lists are determined; this must include the items indexed by every key, but may also

Some Applications of Inverted Indexes 5-145

contain some items which are false drops, since items referenced by the correct hash codes

need not actually have contained the correct keys. Normally, if there are several keys in the

query, there are not likely to be many false drops in the final combined list even though each

hash code is somewhat ambiguous. The actual tags are then obtained from the tag file, and to
guard against the possibility that an item has false-dropped on some hash code in the query,
the original items are normally obtained from the delivery program (4) and the query keys
checked against them by string comparison.

Usually, therefore, the check for bad drops is made against the original file. However, if
the key derivation procedure is complex, it may be preferable to check against the keys fed to
program (2). In this case the optional key file which contains the keys associated with each
item is generated, and the item tag is supplemented by a string

-start,length

which indicates the starting byte number in the key file and the length of the string of keys
for each item. This file is not usually necessary with the present key-selection program, since
the keys always appear in the original document.

There is also an option (-Cn) for coordination level searching.

This retrieves items

which match all but n of the query keys. The items are retrieved in the order of the number
of keys that they match. Of course, n must be less than the number of query keys (nothing is
retrieved unless it matches at least one key).

As an example, consider one set of 4377 references, comprising 660,000 bytes. This
included 51,000 keys, of which 5,900 were distinct keys. The hash table is kept full to save
space (at the expense of time); 995 of 997 possible hash codes were used. The total set of
index files (no key file) included 171,000 bytes, about 26% of the original file size. It took 8
minutes of processor time to hash, sort, and write the index. To search for a single query with
the resulting index took 1.9 seconds of processor time, while to find the same paper with a
sequential linear search using grep (reading all of the tags and keys) took 12.3 seconds of processor time.

We have also used this software to index all of the English stored on our UNIX system.
This is the index searched by the lookall command. On a typical day there were 29,000 files
in our user file system, containing about 152,000,000 bytes. Of these 5,300 files, containing
32,000,000 bytes (about 21%) were English text. The total number of ‘words’ (determined
mechanically) was 5,100,000. Of these 227,000 were selected as keys; 19,000 were distinct,
hashing to 4,900 (of 5,000 possible) different hash codes. The resulting inverted file indexes
used 845,000 bytes, or about 2.6% of the size of the original files. The particularly small

indexes are caused by the fact that keys are taken from only the first 50 non-common words

of some very long input files.

Even this large lookall index can be searched quickly. For example, to find this document by looking for the keys “lesk inverted indexes” required 1.7 seconds of processor time
and system time. By comparison, just to search the 800,000 byte dictionary (smaller than
even the inverted indexes, let alone the 27,000,000 bytes of text files) with grep takes 29

seconds of processor time. The lookall program is thus useful when looking for a document
which you believe is stored on-line, but do not know where. For example, many memos from
our center are in the file system, but it is often difficult to guess where a particular memo
might be (it might have several authors, each with many directories, and have been worked on
by a secretary with yet more directories). Instructions for the use of the lookall command are
given in the manual section, shown in the appendix to this memorandum.
The only indexes maintained routinely are those of publication lists and all English files.
To make other indexes, the programs for making keys, sorting them, searching the indexes,
and delivering answers must be used. Since they are usually invoked as parts of higher-level
commands, they are not in the default command directory, but are available to any user in the
directory /usr/lib/refer. Three programs are of interest: mkey, which isolates keys from input
files; inv, which makes an index from a set of keys; and hunt, which searches the index and

5-146 Some Applications of Inverted Indexes

delivers the items.

Note that the two parts of the retrieval phase are combined into one pro-

gram, to avoid the excessive system work and delay which would result from running these as
separate processes.

These three commands have a large number of options to adapt to different kinds of
The user not interested in the detailed description that now follows may skip to sec-

input.

tion 3, which describes the refer program, a packaged-up version of these tools specifically
oriented towards formatting references.

Make Keys.

The program mkey is the key-making program corresponding to step (1)
Normally, it reads its input from the file names given as arguments, and if there

in phase A.

are no arguments it reads from the standard input.

It assumes that blank lines in the input

delimit separate items, for each of which a different line of keys should be generated.

The
lines of keys are written on the standard output. Keys are any alphanumeric string in the
input not among the most frequent words in English and not entirely numeric (except that

all-numeric strings are acceptable if they are between 1900 and 1999). In the output, keys are
translated to lower case, and truncated to six characters in length; any associated punctuation
is removed.

The following flag arguments are recognized by mkey:

—c name

—f name

Name of file of common words; default is /usr/lib/eign.
Read a list of files from name and take each as an input argu-

—ichars

Ignore all lines which begin with ‘%’ followed by any character

ment.

in chars.

—-kn
—In

Use at most n keys per input item.

—-nm

Ignore items shorter than n letters long.
Ignore as a key any word in the first m words of the list of

—s

Remove the labels (file:start,length) from the output; just give

common English words.

The default is 100.

the keys. Used when searching rather than indexing.
—W

The

normal

Each whole file is a separate item; blank lines in files are
irrelevant.

arguments

/usr/lib/eign, —n100, and —I3.

for

indexing

references

are

the

defaults,

which

For searching, the —s option is also needed.

are

—c

When the big

lookall index of all English files is run, the options are —w, —k50, and —f (filelist).

When

running on textual input, the mkey program processes about 1000 English words per processor

second. Unless the —k option is used (and the input files are long enough for it to take effect)
the output of mkey is comparable in size to its input.
Hash and invert.
files.

The inv program computes the hash codes and writes the inverted
It reads the output of mkey and writes the set of files described earlier in this section.

It expects one argument, which is used as the base name for the three (or four) files to be
Assuming an argument of Index (the default) the entry file is named Index.ia, the

written.

posting file Index.ib, the tag file Index.ic, and the key file (if present) Index.id. The inv program recognizes the following options:

—a

Append the new keys to a previous set of inverted files, mak-

-d

Write the optional key file.

ing new files if there is no old set using the same base name.

—~hn

This is needed when you can not
check for false drops by looking for the keys in the original

inputs, i.e. when the key derivation procedure is complicated
and the output keys are not words from the input files.

The hash table size is n (default 997); n should be prime.
Making n bigger saves search time and spends disk space.

Some Applications of Inverted Indexes 5-147
—i[u] name

Take input from file name, instead of the standard input; if u
is present name is unlinked when the sort is started.

Using

this option permits the sort scratch space to overlap the disk
space used for input keys.
]

Make a completely new set of inverted files, ignoring previous

—-p

Pipe into the sort program, rather than writing a temporary

-V

Verbose mode; print a summary of the number of keys which

files.

input file. This saves disk space and spends processor time.
finished indexing.

About half the time used in inv is in the contained sort.

Assuming the sort is roughly

linear, however, a guess at the total timing for inv is 250 keys per second.

The space used is

usually of more importance: the entry file uses four bytes per possible hash (note the —h

option), and the tag file around 15-20 bytes per item indexed.

Roughly, the posting file con-

tains one item for each key instance and one item for each possible hash code; the items are
two bytes long if the tag file is less than 65336 bytes long, and the items are four bytes wide if
the tag file is greater than 65536 bytes long.

Note that to minimize storage, the hash tables

should be over-full; for most of the files indexed in this way, there is no other real choice,

since the entry file must fit in memory.
Searching and Retrieving.

The hunt program retrieves items from an index.

combines, as mentioned above, the two parts of phase (B): search and delivery.

The reason

why it is efficient to combine delivery and search is partly to avoid starting unnecessary

processes, and partly because the delivery operation must be a part of the search operation in
any case.

Because of the hashing, the search part takes place in two stages: first items are

retrieved which have the right hash codes associated with them, and then the actual items are
inspected to determine false drops, i.e.

doesn’t really have the right keys.

to determine if anything with the right hash codes

Since the original item is retrieved to check on false drops,

it is efficient to present it immediately, rather than only giving the tag as output and later
retrieving the item again.

If there were a separate key file, this argument would not apply,

but separate key files are not common.
Input to hunt is taken from the standard input, one query per line.

be in mkey —s output format; all lower case, no punctuation.

Each query should

The hunt program takes one

argument which specifies the base name of the index files to be searched.

Only one set of

index files can be searched at a time, although many text files may be indexed as a group, of
course.

If one of the text files has been changed since the index, that file is searched with

fgrep; this may occasionally slow down the searching, and care should be taken to avoid having many out of date files.

—a
—-Cn

The following option arguments are recognized by hunt:

Give all output; ignore checking for false drops.

Coordination level n; retrieve items with not more than n
terms of the input missing; default CO, implying that each
search term must be in the output items.

—-Flynd]

“—Fy” gives the text of all the items found; “—Fn” suppresses

them.

“—Fd” where d is an integer gives the text of the first

d items. The default is —Fy.
—g

Do not use fgrep to search files changed since the index was

made; print an error comment instead.
—istring

Take string as input, instead of reading the standard input.

—-1n

The maximum length of internal lists of candidate items is n;

—o string

Put text output (“—Fy”) in string; of use only when invoked

default 1000.
from another program.

5-148 Some Applications of Inverted Indexes

—Pp

Print hash code frequencies; mostly for use in optimizing hash
table sizes.

~T[ynd]

“—Ty” gives the tags of the items found; “—~Tn” suppresses
“—Td” where d is an integer gives the first d tags. The

them.

default is —=Tn.
—t string

Put tag output (“—Ty”) in string; of use only when invoked
from another program.

The timing of hunt is complex.

Normally the hash table is overfull, so that there will be

many false drops on any single term; but a multi-term query will have few false drops on all
terms.

Thus if a query is underspecified (one search term) many potential items will be exam-

ined and discarded as false drops, wasting time.

If the query is overspecified (a dozen search

terms) many keys will be examined only to verify that the single item under consideration has
that key posted.

below.

The variation of search time with number of keys is shown in the table

Queries of varying length were constructed to retrieve a particular document from the

file of references.

In the sequence to the left, search terms were chosen so as to select the

desired paper as quickly as possible.

In the sequence on the right, terms were chosen

inefficiently, so that the query did not uniquely select the desired document until four keys

had been used. The same document was the target in each case, and the final set of eight
keys are also identical; the differences at five, six and seven keys are produced by measurement error, not by the slightly different key lists.
Efficient Keys
No. keys

Inefficient Keys

Total drops

Retrieved

Search time

(incl. false)

Documents

(seconds)

1.27

No. keys

Total drops

Retrieved

Search time

(incl. false)

Documents

(seconds)

5.96

0.11

2.72

0.14

0.95

0.17

0.18

0.19

0.21

0.23

0.22

0.27

0.26

0.29

As would be expected, the optimal search is achieved when the query just specifies the answer;
however, overspecification is quite cheap.

Roughly, the time required by hunt can be approxi-

mated as 30 milliseconds per search key plus 75 milliseconds per dropped document (whether
it is a false drop or a real answer).

In general, overspecification can be recommended; it pro-

tects the user against additions to the data base which turn previously uniquely-answered
queries into ambiguous queries.

The careful reader will have noted an enormous discrepancy between these times and

the earlier quoted time of around 1.9 seconds for a search.

The times here are purely for the

search and retrieval: they are measured by running many searches through a single invocation
of the hunt program alone.

The normal retrieval operation involves using the shell to set up a

pipeline through mkey to hunt and starting both processes; this adds a fixed overhead of
about 1.7 seconds of processor time to any single search.

Furthermore, remember that all

these times are processor times: on a typical morning on our PDP 11/70 system, with about one

dozen people logged on, to obtain 1 second of processor time for the search program took
between 2 and 12 seconds of real time, with a median of 3.9 seconds and a mean of 4.8
seconds.

Thus, although the work involved in a single search may be only 200 milliseconds,

after you

add

the

1.7

seconds

startup

processor

time

and

then

elapsed/processor time ratio, it will be 8 seconds before any response is printed.

assume

4:1

Some Applications of Inverted Indexes 5-149

3. Selecting and Formatting References for TROFF
The major application of the retrieval software is refer, which is a troff preprocessor like

egn
.3 It scans its input looking for items of the form

imprecise citation

where an imprecise citation is merely a string of words found in the relevant bibliographic
citation. This is translated into a properly formatted reference. If the imprecise citation does
not correctly identify a single paper (either selecting no papers or too many) a message is
given. The data base of citations searched may be tailored to each system, and individual
users may specify their own citation files. On our system, the default data base is accumulated from the publication lists of the members of our organization, plus about half a dozen
personal bibliographies that were collected. The present total is about 4300 citations, but this
increases steadily. Even now, the data base covers a large fraction of local citations.
For example, the reference for the eqn paper above was specified as
preprocessor like
1 eqn.

kernighan cherry acm 1975

It scans its input looking for items

This paper was itself printed using refer. The above input text was processed by refer as well
as tbl and troff by the command

refer memo-file | tbl | troff —ms
and the reference was automatically translated into a correct citation to the ACM paper on
mathematical typesetting.
|
The procedure to use to place a reference in a paper using refer is as follows. First, use
the lookbib command to check that the paper is in the data base and to find out what keys
are necessary to retrieve it. This is done by typing lookbib and then typing some potential
queries until a suitable query is found. For example, had one started to find the eqn paper
shown above by presenting the query
$ lookbib

kernighan cherry
(EOT)

lookbib would have found several items; experimentation would quickly have shown that the
query given above is adequate. Overspecifying the query is of course harmless. A particularly
careful reader may have noticed that “acm” does not appear in the printed citation; we have
supplemented some of the data base items with common extra keywords, such as common
abbreviations for journals or other sources, to aid in searching.
If the reference is in the data base, the query that retrieved it can be inserted in the
text, between .[ and .] brackets. If it is not in the data base, it can be typed into a private file
of references, using the format discussed in the next section, and then the —p option used to
search this private file. Such a command might read (if the private references are called

myfile)
3 B. W. Kernighan and L. L. Cherry, “A System for Typesetting Mathematics,” Comm. Assoc. Comp.
Mach., vol. 18, pp. 1561-157, Bell Laboratories, Murray Hill, New Jersey, March 1975.

5-150 Some Applications of Inverted Indexes

refer —p myfile document | tbl | eqn | troff —ms . . .
where tbl and/or eqn could be omitted if not needed.
other macro package, however, is essential.

The use of the —ms macros? or some

Refer only generates the data for the references;

exact formatting is done by some macro package, and if none is supplied the references will

not be printed.
By default, the references are numbered sequentially, and the —ms macros format references as footnotes at the bottom of the page.

This memorandum is an example of that style.

Other possibilities are discussed in section 5 below.
4. Reference Files.

A reference file is a set of bibliographic references usable with refer. It can be indexed
using the software described in section 2 for fast searching. What refer does is to read the
input document stream, looking for imprecise citation references. It then searches through
reference files to find the full citations, and inserts them into the document. The format of

the full citation is arranged to make it convenient for a macro package, such as the —ms macros, to format the reference for printing.

Since the format of the final reference is determined

by the desired style of output, which is determined by the macros used, refer avoids forcing
any kind of reference appearance.

All it does is define a set of string registers which contain

the basic information about the reference; and provide a macro call which is expanded by the
macro package to format the reference. It is the responsibility of the final macro package to
see that the reference is actually printed; if no macros are used, and the output of refer fed
untranslated to troff, nothing at all will be printed.

The strings defined by refer are taken directly from the files of references, which are in

the following format.

The references should be separated by blank lines.

sequence of lines beginning with % and followed by a key-letter.

Each reference is a

The remainder of that line,

and successive lines until the next line beginning with %, contain the information specified by
the key-letter.

In general, refer does not interpret the information, but merely presents it to
the macro package for final formatting. A user with a separate macro package, for example,

can add new key-letters or use the existing ones for other purposes without bothering refer.
The meaning of the key-letters given below, in particular, is that assigned by the —ms
macros.

Not all information, obviously, is used with each citation. For example, if a document is both an internal memorandum and a journal article, the macros ignore the memoran-

dum version and cite only the journal article. Some kinds of information are not used at all in
printing the reference; if a user does not like finding references by specifying title or author

keywords, and prefers to add specific keywords to the citation, a field is available which is
searched but not printed (K).
The key letters currently recognized by refer and —ms, with the kind of information
implied, are:

* M. E. Lesk, Typing Documents on UNIX and GCOS: The -ms Macros for Troff, 19717.

Some Applications of Inverted Indexes 5-151

Key
A
B
C
D
E
G

Information specified
Author’s name
Title of book containing item
City of publication
Date
Editor of book containing item
Government (NTIS) ordering number

Issuer (publisher)

Journal name

K
L

Keys (for searching)
Label
Memorandum label

Key
N
O
P
R
T
V

Information specified
Issue number
Other information
Page(s) of article
Technical report reference
Title
Volume number

X
Y

or
or
Information not used by refer

For example, a sample reference could be typed as:

% T Bounds on the Complexity of the Maximal
Common Subsequence Problem
%74 ctr127

%A A. V. Aho
%A D. S. Hirschberg
%A J.D. Ulman
%d J. ACM
%V 23
%N 1

%P 1-12
% M abcd-78

%D Jan. 1976

Order is irrelevant, except that authors are shown in the order given. The output of refer is a
stream of string definitions, one for each of the fields of each reference, as shown below.
.-

.ds [A authors’ names ...

.ds [T title ...

.ds [J journal ...
.J[ type-number

The special macro .]— precedes the string definitions and the special macro .}[ follows. These
are changed from the input .[ and .] so that running the same file through refer again is
harmless. The .]— macro can be used by the macro package to initialize. The .]J[ macro,
which should be used to print the reference, is given an argument type-number to indicate
the kind of reference, as follows:

Value
1

Kind of reference
Journal article

Book

Article within book

Technical report

Bell Labs technical memorandum
Other

The reference is flagged in the text with the sequence
\* ([.number\* (.]

where number is the footnote number. The strings [. and .] should be used by the macro
package to format the reference flag in the text. These strings can be repiaced for a particuilar
footnote, as described in section 5. The footnote number (or other signal) is availablq to the

5-152 Some Applications of Inverted Indexes
reference macro .][ as the string register [F.

In some cases users wish to suspend the searching, and merely use the reference macro

formatting.

That is, the user doesn’t want to provide a search key between .[ and .] brackets,
but merely the reference lines for the appropriate document. Alternatively, the user can wish

to add a few fields to those in the reference as in the standard file, or override some fields.
Altering or replacing fields, or supplying whole references, is easily done by inserting lines
beginning with %; any such line is taken as direct input to the reference processor rather than

keys to be searched.

Thus

keyl key2 key3 ...

% Q New format item
%R Override report name

]
makes the indicates changes to the result of searching for the keys.
must be given before the first % line.

All of the search keys

If no search keys are provided, an entire citation can be provided in-line in the text. For
example, if the eqn paper citation were to be inserted in this way, rather than by searching

for it in the data base, the input would read

preprocessor like

I eqn.

[

%A B. W. Kernighan
%A L. L. Cherry
%'T A System for Typesetting Mathematics
%dJ Comm. ACM
%V 18
%N 3

%P 151-157
%D March 1975

]

It scans its input looking for items
This would produce a citation of the same appearance as that resulting from the file search.

As shown, fields are normally turned into troff strings. Sometimes users would rather
have them defined as macros, so that other troff commands can be placed into the data.
When this is necessary, simply double the control character % in the data. Thus the input

%V 23

% %M
Bell Laboratories,
Murray Hill, N.J. 07974

]
is processed by refer into

ds [V 23

.de [M
Bell Laboratories,

Murray Hill, N.J. 07974

The

information

after

% %M

defined

a macro to be

invoked

by .[M

while the

Some Applications of Inverted Indexes 5-153
information after %V is turned into a string to be invoked by X*([V. At present —ms expects
all information as strings.

5. Collecting References and other Refer Options
Normally, the combination of refer and —ms formats output as troff footnotes which are

consecutively numbered and placed at the bottom of the page.

However, options exist to

place the references at the end; to arrange references alphabetically by senior author; and to
indicate references by strings in the text of the form [Namel975a] rather than by number.

Whenever references are not placed at the bottom of a page identical references are coalesced.
For example, the —e option to refer specifies that references are to be collected; in this

case they are output whenever the sequence

[

SLISTS

]
is encountered. Thus, to place references at the end of a paper, the user would run refer with
the —e option and place the above $LIST$ commands after the last line of the text.
will then move all the references to that point.

Refer

To aid in formatting the collected references,

refer writes the references preceded by the line

and followed by the line
J>

to invoke special macros before and after the references.
Another possible option to refer is the —s option to specify sorting of references.

default, of course, is to list references in the order presented.

The

The —s option implies the —e

option, and thus requires a

$LIST$

]
entry to call out the reference list.

The —s option may be followed by a string of letters,

numbers, and ‘+’ signs indicating how the references are to be sorted.

The sort is done using

the fields whose key-letters are in the string as sorting keys; the numbers indicate how many
of the fields are to be considered, with ‘+’ taken as a large number.

—sAD meaning “Sort on senior author, then date.”

Thus the default is

To sort on all authors and then title,

specify —sA+T. And to sort on two authors and then the journal, write —s
A 2.
Other options to refer change the signal or label inserted in the text for each reference.
Normally these are just sequential numbers, and their exact placement (within brackets, as
superscripts, etc.) is determined by the macro package.

The —1 option replaces reference

numbers by strings composed of the senior author’s last name, the date, and a disambiguating
letter.

If a number follows the 1 as in —13 only that many letters of the last name are used in

the label string.

To abbreviate the date as well the form -1lm,n shortens the last name to the

~ first m letters and the date to the last n digits.

For example, the option —13,2 would refer to

the egn paper (reference 3) by the signal Ker75a, since it is the first cited reference by Kernighan in 1975.
A user wishing to specify particular labels for a private bibliography may use the —k

option. Specifying —kx causes the field x to be used as a label. The default is L.

If this field

ends in —, that character is replaced by a sequence letter; otherwise the field is used exactly as
given.

If none of the refer-produced signals are desired, the —b option entirely suppresses

automatic text signals.

5-154 Some Applications of Inverted Indexes
If the user wishes to override the —ms treatment of the reference signal (which is nor-

mally to enclose the number in brackets in nroff and make it a superscript in troff ) this can

be done easily. If the lines .[ or .] contain anything following these characters, the remainders
of these lines are used to surround the reference signal, instead of the default.

Thus, for

example, to say “See reference (2).” and avoid “See reference.?” the input might appear
See reference
imprecise citation ...

D.
Note that blanks are significant in this construction.

If a permanent change is desired in the

style of reference signals, however, it is probably easier to redefine the strings [. and .] (which

are used to bracket each signal) than to change each citation.
Although normally refer limits itself to retrieving the data for the reference, and leaves
to a macro package the job of arranging that data as required by the local format, there are
two special options for rearrangements that can not be done by macro packages.

option puts fields into all upper case (CAPS-SMALL CAPS in troff output).

The —¢

The key-letters

indicated what information is to be translated to upper case follow the ¢, so that —cAdJ means

that authors’ names and journals are to be in caps.

The —a option writes the names of

authors last name first, that is A. D. Hall, Jr. is written as Hall, A. D. Jr.

The citation form

of the Journal of the ACM, for example, would require both —¢A and —a options.

This pro-

duces authors’ names in the style KERNIGHAN, B. W. AND CHERRY, L. L. for the previous
example.

The —a option may be followed by a number to indicate how many author names

should be reversed; —al (without any —¢ option) would produce Kernighan, B. W. and L. L.
Cherry, for example.

Finally, there is also the previously-mentioned —p option to let the user specify a private
file of references to be searched before the public files.
previously made index for these files.

Note that refer does not insist on a

If a file is named which contains reference data but is

not indexed, it will be searched (more slowly) by refer using fgrep. In this way it is easy for
users to keep small files of new references, which can later be added to the public data bases.

Updating Publication Lists 5-155

Updating Publication Lists
M. E. Lesk

1. Introduction.

This note describes several commands to update the publication lists. The data base
consisting of these lists is kept in a set of files in the directory /usr/dict/papers on the Version 7 UNIXt system. The reason for having special commands to update these files is that
they are indexed, and the only reasonable way to find the items to be updated is to use the
index. However, altering the files destroys the usefulness of the index, and makes further
editing difficult. So the recommended procedure is to
(1)

Prepare additions, deletions, and changes in separate files.

(2)

Update the data base and reindex.

Whenever you make changes, etc. it is necessary to run the “add & index” step before logging
off; otherwise the changes do not take effect. The next section shows the format of the files in
the data base. After that, the procedures for preparing additions, preparing changes, preparing deletions, and updating the public data base are given.
2. Publication Format.

The format of a data base entry is given completely in “Some Applications of Inverted
Indexes on UNIX” by M. E. Lesk, the first part of this report, and is summarized here via a
few examples. In each example, first the output format for an item is shown, and then the
corresponding data base entry.
Journal article:

A. V. Aho, D. J. Hirschberg, and J. D. Ullman, “Bounds on the Complexity of the Maximal Common Subsequence Problem,” J. Assoc.
Comp. Mach., vol. 23, no. 1, pp. 1-12 (Jan. 1976).

% T Bounds on the Complexity of the Maximal Common
Subsequence Problem

%A A. V. Aho
%A D. S. Hirschberg
%A J. D. Ullman
%d J. Assoc. Comp. Mach.
%N 23
%N 1
%P 1-12
%D Jan. 1976
%M Memo abcd...

t UNIX is a trademark of Bell Laboratories.

5-156 Updating Publication Lists

Conference proceedings:
B. Prabhala and R. Sethi, “Efficient Computation of Expressions with

Common Subexpressions,” Proc. 5th ACM Symp. on Principles of
Programming Languages, pp. 222-230, Tucson, Ariz. (January 1978).

%A B. Prabhala
%A R. Sethi
% T Efficient Computation of Expressions with
Common Subexpressions
%dJ Proc. 5th ACM Symp. on Principles
of Programming Languages

% C Tucson, Ariz.
%D January 1978
%P 222-230
Book:

B. W. Kernighan and P. J. Plauger, Software Tools, Addison-Wesley,
Reading, Mass. (1976).

%'T Software Tools
%A B. W. Kernighan
%A P. J. Plauger
%1 Addison-Wesley
% C Reading, Mass.
%D 1976
Article within book:

J. W. de Bakker, “Semantics of Programming Languages,” pp. 173-227
in Advances in Information Systems Science, Vol. 2, ed. J. T. Tou,
Plenum Press, New York, N. Y. (1969).

%A J. W. de Bakker
%'T Semantics of programming languages
%E J. T. Tou

% B Advances in Information Systems Science, Vol. 2
%1 Plenum Press
%C New York, N. Y.
%D 1969
%P 173-227
Technical Report:

F. E. Allen, “Bibliography on Program Optimization,” Report RC5767, IBM T. J. Watson Research Center, Yorktown Heights, N. Y.
(1975).

%A F. E. Allen
|

%D 1975

%'T Bibliography on Program Optimization
%R Report RC-5767
%1 IBM T. J. Watson Research Center
% C Yorktown Heights, N. Y.

Updating Publication Lists 5-157
Other forms of publication can be entered similarly.

Note that conference proceedings are

entered as if journals, with the conference name on a %<J line.

This is also sometimes

appropriate for obscure publications such as series of lecture notes.

When something is both a

report and an article, or both a memorandum and an article, enter all necessary information
for both; see the first article above, for example.

Extra information (such as “In preparation”

or “Japanese translation”) should be placed on a line beginning % O.

The most common use

of %O lines now is for “Also in ...” to give an additional reference to a secondary appearance
of the same paper.

Some of the possible fields of a citation are:
Letter

Meaning

Letter

Meaning

Author

Extra keys

Book including item

Issue number

City of publication

Date

Other
Page numbers

Editor of book

Report number

Publisher (issuer)

Title of item

Journal name

Volume number

Note that % B is used to indicate the title of a book containing the article being entered; when
an item is an entire book, the title should be entered with a % T' as usual.

Normally, the order of items does not matter. The only exception is that if there are
multiple authors (%
A lines) the order of authors should be that on the paper.

If a line is too

long, it may be continued on to the next line; any line not beginning with % or . (dot) is

assumed to be a continuation of the previous line.
example of a long title.

Again, see the first article above for an

Except for authors, do not repeat any items; if two %4dJ lines are

given, for example, the first is ignored.

Multiple items on the same file should be separated

by blank lines.
Note that in formatted printouts of the file, the exact appearance of the items is deter-

mined by a set of macros and the formatting programs.
tion, etc. by editing the data base; it is wasted effort.

Do not try to adjust fonts, punctua-

In case someone has a real need for a

differently-formatted output, a new set of macros can easily be generated to provide alternative appearances of the citations.

3. Updating and Re-indexing.
This section describes the commands that are used to manipulate and change the data

base.

It explains the procedures for (a) finding references in the data base, (b) adding new

references, (c) changing existing references, and (d) deleting references.

Remember that all

changes, additions, and deletions are done by preparing separate files and then running an

‘update and reindex’ step.
Checking what’s there now.
base.

Often you will want to know what is currently in the data

There is a special command lookbib to look for things and print them out.

for articles based on words in the title, or the author’s name, or the date.

It searches

For example, you

could find the first paper above with
lookbib aho ullman maximal subsequence 1976
or

lookbib aho ullman hirschberg

If you don’t give enough words, several items will be found; if you spell some wrong, nothing
will be found.

There are around 4300 papers in the public file; you should always use this

command to check when you are not sure whether a certain paper is there or not.
Additions.
new papers.

To add new papers, just type in, on one or more files, the citations for the

Remember to check first if the papers are already in the data base.

For example,

5-158 Updating Publication Lists

if a paper has a previous memo version, this should be treated as a change to an existing
entry, rather than a new entry. If several new papers are being typed on the same file, be sure
that there is a blank line between each two papers.

Changes.

To change an item, it should be extracted onto a file. This is done with the

command

pub.chg keyl key2 key3 ...

where the items keyl, key2, key3, etc. are a set of keys that will find the paper, as in the lookbib command. That is, if
lookbib johnson yacc cstr

will find a item (to, in this case, Computing Science Technical Report No. 32, “YACC: Yet |
Another Compiler-Compiler,” by S. C. Johnson) then
pub.chg johnson yacc cstr

will permit you to edit the item. The pub.chg command extracts the item onto a file named
“bibxxx” where “xxx” is a 3-digit number, e.g. “bib234”. The command will print the file
name it has chosen. If the set of keys finds more than one paper (or no papers) an error message is printed and no file is written. Each reference to be changed must be extracted with a
separate pub.chg command, and each will be placed on a separate file. You should then edit
the “bibxxx” file as desired to change the item, using the UNIX editor. Do not delete or
change the first line of the file, however, which begins % # and is a special code line to tell the
update program which item is being altered. You may delete or change other lines, or add
lines, as you wish. The changes are not actually made in the public data base until you run
the update command pub.run (see below). Thus, if after extracting an item and modifying it,
you decide that you’d rather leave things as they were, delete the “bibxxx” file, and your
change request will disappear.

Deletions. To delete an entry from the data base, type the command
pub.del keyl key2 key3 ...

where the items keyl, key2, etc. are a set of keys that will find the paper, as with the lookbib
command. That is, if

lookbib Aho hirschberg ullman

will find a paper,
pub.del aho hirschberg ullman

deletes it. Note that upper and lower case are equivalent in keys. The pub.del command will
print the entry being deleted. It also gives the name of a “bibxxx” file on which the deletion
command is stored. The actual deletion is not done until the changes, additions, etc. are processed, as with the pub.chg command. If, after seeing the item to be deleted, you change your
mind about throwing it away, delete the “bibxxx” file and the delete request disappears.
Again, if the list of keys does not uniquely identify one paper, an error message is given.

Remember that the default versions of the commands described here edit a public data
base. Do not delete items unless you are sure deletion is proper; usually this means that there
are duplicate entries for the same paper. Otherwise, view requests for deletion with skepticism; even if one person has no need for a particular item in the data base, someone else may
want it there.

If an item is correct, but should not appear in the “List of Publications” as normally
produced, add the line

%K DNL

to the item. This preserves the item intact, but implies “Do Not List” to the to the commands that print publication lists. The DNL line is normally used for some technical reports,

Updating Publication Lists

5-159

minor memoranda, or other low-grade publications.

Update and reindex. When you have completed a session of changes, you should type
the command
pub.run filel file2 ...

where the names “filel”, ... are the new files of additions you have prepared. You need not
list the “bibxxx” files representing changes and deletions; they are processed automatically.
All of the new items are edited into the standard public data base, and then a new index is
made. This process takes about 15 minutes; during this time, searches of the data base will be
slower.

Normally, you should execute pub.run just before you logoff after performing some edit
requests. However, if you don’t, the various change request files remain in your directory
until you finally do execute pub.run. When the changes are processed, the “bibxxx” files are
deleted. It is not desirable to wait too long before processing changes, however, to avoid
conflicts with someone else who wishes to change the same file. If executing pub.run produces
the message “File bibxxx too old” it means that someone else has been editing the same file
between the time you prepared your changes, and the time you typed pub.run. You must
delete such old change files and re-enter them.

Note that although pub.run discards the “bibxxx” files after processing them, your files
of additions are left around even after pub.run is finished. If they were typed in only for purposes of updating the data base, you may delete them after they have been processed by
pub.run.

Example.

(1)

Suppose, for example, that you wish to

Add to the data base the memos “The Dilogarithm Function of a Real Argument” by R.
Morris, and “UNIX Software Distribution by Communication Link,” by M. E. Lesk and
A. S. Cohen;

(2)

Delete from the data base the item ‘“Cheap Typesetters”, by M. E. Lesk, SIGLASH
Newsletter, 1973; and

(3)

Change “J. Assoc. Comp. Mach.” to “Jour. ACM” in the citation for Aho, Hirschberg,
and Ullman shown above.

The procedure would be as follows.

First, you would make a file containing the additions,

here called “new.1”, in the normal way using the UNIX editor. In the script shown below, the
computer prompts are in italics.

$ ed new.1
2
a

%'T The Dilogarithm Function of a Real Argument
% A Robert Morris
%M abcd
%D 1978
% T UNIX Software Distribution by Communication Link
%A M. E. Lesk
%A A. S. Cohen
%M abced
%D 1978
w new.l1
199

Crng

ommand:

(")

las

[ nd

)

(oD

ioN

I
[

€

[

Next you would specify the

5-160 Updating Publication Lists

$ pub.del lesk cheap typesetters siglash
to which the computer responds:

Will delete:

(file bib176)

% T Cheap Typesetters
%A M. E. Lesk
%J ACM SIGLASH Newsletter
%V 6
% N 4

%P 14-16
%D October 1973
And then you would extract the Aho, Hirschberg and Ullman paper. The dialogue involved is

shown below. First run pub.chg to extract the paper; it responds by printing the citation and
informing you that it was placed on file bib123. That file is then edited.

Updating Publication Lists

5-161

$ pub.chg aho hirschberg ullman
Extracting as file bib123

% T Bounds on the Complexity of the Maximal
Common Subsequence Problem

%A A. V. Aho
%A D. S. Hirschberg
%A J. D. Ulman
% J. Assoc. Comp. Mach.
%V 23
%N 1
%P 1-12
% M abcd
%D Jan. 1976

$ ed bib123
312

/Assoc/s/ J/ Jour/p

% Jour. Assoc. Comp. Mach.
s/Assoc.*/ACM/p
% Jour. ACM

L3p

%t /usr/dict/papers/p76 233 245 change

% T Bounds on the Complexity of the Maximal
Common Subsequence Problem

%A A. V. Aho
%A D. S. Hirschberg
%A J. D. Ulman
% Jour. ACM
%V 23
%N 1

%P 1-12
%M abcd
%D Jan. 1976

292
q

$
Finally, execute pub.run, making sure to remember that you have prepared a new file
“new.1””:

$ pub.run new.1

and about fifteen minutes later the new index would be complete and all the changes would be
included.
|
4. Printing a Publication List
There are two commands for printing a publication list, depending on whether you want

to print one person’s list, or the list of many people.

To print a list for one person, use the

pub.indiv command:

pub.indiv M Lesk
This runs off the list for M. Lesk and puts it in file “output”.

the initial.

In case of ambiguity two initials can be used.

Note that no ‘.’ is given after

Similarly, to get the list for group of

5-162 Updating Publication Lists
people, say

pub.org xxx

which prints all the publications of the members of organization xxx, taking the names for the
list in the file /usr/dict/papers/centlist/xxx.

This command should normally be run in the

background; it takes perhaps 15 minutes. Two options are available with these commands:

pub.indiv —p M Lesk
prints only the papers, leaving out unpublished notes, patents, etc. Also

pub.indiv —t M Lesk | gcat
prints a typeset copy, instead of a computer printer copy.

In this case it has been directed to

an alternate typesetter with the ‘gcat’ command.

These options may be used together, and

may be used with the pub.org command as well.

For example, to print only the papers for all

of organization zzz and typeset them, you could type

pub.center —t —p zzz | gcat &
These publication lists are printed double column with a citation style taken from a set of
publication list macros; the macros, of course, can be changed easily to adjust the format of
the lists.

The Style and Diction Programs 5-163

Writing Tools - The STYLE and DICTION Programs
L. L. Cherry
Bell Laboratories
Murray Hill, New Jersey 07974

W. Vesterman

Livingston College
Rutgers University
1. Introduction

Computers have become important in the document preparation process, with programs
to check for spelling errors and to format documents.

As the amount of text stored on line

increases, it becomes feasible and attractive to study writing style and to attempt to help the

writer in producing readable documents.

The system of writing tools described here is a first

step toward such help. The system includes programs and a data base to analyze writing style
at the word and sentence level.

We use the term “style” in this paper to describe the results

of a writer’s particular choices among individual words and sentence forms.

Although many

judgements of style are subjective, particularly those of word choice, there are some objective
measures that experts agree lead to good style. Three programs have been written to measure

some of the objectively definable characteristics of writing style and to identify some commonly misused or unnecessary phrases.

Although a document that conforms to the stylistic

rules is not guaranteed to be coherent and readable, one that violates all of the rules is likely

to be difficult or tedious to read. The program STYLE calculates readability, sentence length
variability, sentence type, word usage and sentence openers at a rate of about 400 words per

second on a PDP11/70 running the UNIXt Operating System. It assumes that the sentences
are well-formed, i. e. that each sentence has a verb and that the subject and verb agree in
number. DICTION identifies phrases that are either bad usage or unnecessarily wordy.
EXPLAIN acts as a thesaurus for the phrases found by DICTION.

Sections 2, 3, and 4

describe the programs; Section 5 gives the results on a cross-section of technical documents;
Section 6 discusses accuracy and problems; Section 7 gives implementation details.
2, STYLE

The program STYLE reads a document and prints a summary of readability indices,

sentence length and type, word usage, and sentence openers. It may also be used to locate all
sentences in a document longer than a given length, of readability index higher than a given
number, those containing a passive verb, or those beginning with an expletive.

STYLE is

based on the system for finding English word classes or parts of speech, PARTS [1].

PARTS

is a set of programs that uses a small dictionary (about 350 words) and suffix rules to partially
assign word classes to English text.

It then uses experimentally derived rules of word order to

assign word classes to all words in the text with an accuracy of about 95%.

Because PARTS

uses only a small dictionary and general rules, it works on text about any subject, from physics to psychology.

Style measures have been built into the output phase of the programs that

make up PARTS.

Some of the measures are simple counters of the word classes found by

PARTS; many are more complicated. For example, the verb count is the total number of verb
T UNIX is a trademark of Bell Laboratories.

5-164 The Style and Diction Programs
phrases.

This includes phrases like:

has been going
was only going
to go

each of which each counts as one verb.

Figure 1 shows the output of STYLE run on a paper

by Kernighan and Mashey about the UNIX programming environment [2].

programming environment

readability grades:
(Kincaid) 12.3

(auto) 12.8

(Coleman-Liau) 11.8

(Flesch) 13.5 (46.3)

sentence info:
no. sent 335 no. wds 7419

av sent leng 22.1 av word leng 4.91
no. questions 0 no. imperatives 0

no. nonfunc wds 4362 58.8%

av leng 6.38

short sent (<17) 35% (118) long sent (>32)

16% (55)

longest sent 82 wds at sent 174; shortest sent 1 wds at sent 117
sentence types:

simple 34% (114) complex 32% (108)
compound

12% (41) compound-complex 21% (72)

word usage:

verb types as % of total verbs
tobe 45% (373) aux

16% (133) inf 14% (114)

passives as % of non-inf verbs 20% (144)
types as % of total

prep 10.8% (804) conj 3.5% (262) adv 4.8% (354)

noun 26.7% (1983) adj 18.7% (1388) pron 5.3% (393)
nominalizations

2 % (155)

sentence beginnings:
subject opener: noun (63) pron (43) pos (0) adj (58) art (62) tot 67%
prep 12% (39) adv

verb

0% (1)

expletives

9% (31)

sub conj

6% (20) conj

1% (5)

4% (13)

Figure 1

As the example shows, STYLE output is in five parts.

After a brief discussion of sentences,

we will describe the parts in order.
2.1. What is a sentence?

Readers of documents have little trouble deciding where the sentences end.
even have to stop and think about uses of the character
Jones, Ph.D., 1. e., or etc. .
is not as easy.

€6

People don’t

in constructions like 1.25, A. J.

When a computer reads a document, finding the end of sentences

First we must throw away the printer’s marks and formatting commands that

litter the text in computer form.

Then STYLE defines a sentence as a string of words ending

in one of:

A2
The end marker “/.” may be used to indicate an imperative sentence.
that are not so marked are not identified as imperative.

Imperative sentences

STYLE properly handles numbers

with embedded decimal points and commas, strings of letters and numbers with embedded

The Style and Diction Programs

5-165

decimal points used for naming computer file names, and the common abbreviations listed in
Appendix 1.

Numbers that end sentences, like the preceding sentence, cause a sentence break

if the next word begins with a capital letter.

Initials only cause a sentence break if the next

word begins with a capital and is found in the dictionary of function words used by PARTS.
So the string

J. D. JONES

does not cause a break, but the string
... system H.

does.

The ...

With these rules most sentences are broken at the proper place, although occasionally

either two sentences are called one or a fragment is called a sentence.

See also specific commands

pages with a macro, GEN

reference list, PGM 2-398

5-75E

Command (Mail)

specifying in text file, GEN 5-6

See also specific commands

starting, GEN 5-35

reference list, GEN 2-28 to 2-33,

text formatting commands for

double columns, GEN 5-15E,
5-35

Comma character (ed)
compared with semicolon, GEN
3-45

COMMA operator (C compiler)
defined, PGM 2-66
Command (Bourne shell)

See also specific commands

2-39T

Command (make)

defined, PGM 3-16
Command (nroff)
description, GEN 5-22 to 5-25

Command (nroff/troff)
See also specific commands
reference list, GEN 5-51

Command (vi)
- See also specific commands

grammar, GEN 4-26

case and, GEN 3-59

grouping, GEN 4-14

ex 3.5 changes and, GEN 3-103

Command (C shell)

See also Program
See also specific commands
defined, GEN 4-64

reference list, GEN 4-63 to 4-74
regenerating, SYS 5-118
repeating, GEN 4-41 to 4-43,
4-51E

substituting output for, GEN
4-61E

suspending temporarily, GEN
4-36

terminating, GEN 4-35 to 4-38

typing, GEN 2-4
within quotation marks, GEN
4-60

Command (DC)

See also specific commands

for file manipulation, GEN 3-71T
preceding counts and, GEN 3-70

Command file
description, GEN 1-29

Commmand line
running two programs with one,

GEN 2-11
Command line flag (Mail)
See Flag (Mail)

Command mode (ex)
defined, GEN 3-85

Command name
defined, GEN 4-64

Command procedure
See Shell procedure
Command substitution
See also Modifier (C shell)
defined, GEN 4-65

for human use

Index-11

Command-list
defined, GEN 4-8

grouping commands, GEN 4-14
Comment (awk)
defined, PGM 3-9
Comment (BC)
convention, GEN 2-49, 2-50
Comment (ex)
description, GEN 3-86

Comment (nroff/troff)
specifying, GEN 5-67

Communication domain
defined, SYS 3-6
Component

Configuration file (Cont.)
specifying multiple bootable
images, SYS 5-80

syntax, SYS 5-79 to 5-83

VAX-11/780 sample, SYS 5-84 to
5-87

connect system call
datagram sockets and, SYS 3-10
errors, SYS 3-8

establishing connection between
sockets, SYS 1-10
initiating connection, SYS 3-8E
Connect time accounting
summarizing, SYS 5-56

defined, GEN 4-65
Compound statement (BC)
forming, GEN 2-54

Connection

Computer-aided instruction

Constant (BC)

accepting, SYS 3-9E
receiving, SYS 3-8 to 3-9

See CAI scripts

defined, GEN 2-50

comsat program

Context search (ed)

4.2BSD improvement, SYS 1-19
CON operator (C compiler)
defined, PGM 2-66
Conditional

See if/fendif commands
conf.c file

4.2BSD improvement, SYS 5-14

installing device driver and, SYS
5-119

conf.h file

4.2BSD improvement, SYS 5-6
config program

4.2BSD improvement, SYS 1-19
adding nonstandard system
facilities, SYS 5-96
defined, SYS 5-73
description, SYS 5-73 to 5-105
SYS 5-99 to 5-100
device defaults,

backslash character and, GEN
3-43

defined, GEN 3-35
methods, GEN 3-30 to 3-31

question mark character and,
GEN 3-43

repeating a search, GEN 3-31
reverse order and, GEN 3-31
slashes and, GEN 3-39
Context search (edit)
d command and, GEN 3-16
delete command and, GEN 3-16C
move command and, GEN 3-15
repeating, GEN 3-20E
reversing, GEN 3-20

s command and, GEN 3-20
continue command (C shell)
defined, GEN 4-65

modifying system code, SYS 5-88

continue statement (awk)
defined, PGM 3-9

modifying system configuration,

Control character (C shell)

files generated by, SYS 5-76

SYS 5-76

prerequisite information, SYS
5-74

defined, GEN 4-65

Control character (nroff/troff)
changing, GEN 5-67

profiled systems and, SYS 5-78

commands and, GEN 5-56

specifying options items, SYS

Control character (vi)
in text file, GEN 3-61
Control statement (BC), GEN
2-47E
description, GEN 2-47 to 2-48
Cooper, E., & others
4.2BSD System Manual, PGM

5-75

Configuration clause

description, SYS 5-80
Configuration file
contents, SYS 5-76

creating, SYS 5-76
grammar, SYS 5-97 to 5-98

specifying devices, SYS 5-81

Index-12

4-15 to 4-52

copy command (C shell)

See cp command (C shell)
copy command (edit)

See co command (edit)
copy command (ex)

See co command (ex)
copy command (Mail)

See also save command (Mail)
description, GEN 2-29
using, GEN 2-23E
copy program

loading, SYS 5-24E
mini-root file system and, SYS
5-24

Core dump file

CSPACE operator (C compiler)

defined, PGM 2-64
css network driver

4.2BSD improvement, SYS 1-15
ctags

4.2BSD improvement, SYS 1-5
ctime library

4.2BSD improvement, SYS 1-14

CTRL-B
defined, GEN 3-75

description, GEN 3-56
CTRL-C
ULTRIX-32 and, GEN 2-1
CTRL-D