800 1755 10A_Using_NROFF_and_TROFF_198805 10A Using NROFF And TROFF 198805

800-1755-10A_Using_NROFF_and_TROFF_198805 800-1755-10A_Using_NROFF_and_TROFF_198805

User Manual: 800-1755-10A_Using_NROFF_and_TROFF_198805

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

Download
Open PDF In Browser	View PDF

Asun®
•

microsystems

Using NROFF and TROFF

L
Part Number: 800-1755-10
Revision A, of 9 May 1988

UNIX is a registered trademark of AT&T.
SunOS is a trademark of Sun Microsystems, Inc.
Sun Workstation is a registered trademark of Sun Microsystems, Inc.
Material in this manual comes from a number of sources: NrofJITroff User's
Manual, Joseph F. Ossanna, Bell Laboratories, Murray Hill, New Jersey; A Troff
Tutorial, Brian W. Kernighan, Bell Laboratories, Murray Hill, New Jersey; Typing Documents on the UNIX System: Using the -ms Macros with Troff and Nroff,
M. E. Lesk, Bell Laboratories, Murray Hill, New Jersey; A Guide to Preparing
Documents with -ms , M. E. Lesk, Bell Laboratories, Murray Hill, New Jersey;
Document Formatting on UNIX Using the -ms Macros, Joel Kies, University of
California, Berkeley, California; Writing Papers with Nroff Using -me, Eric P.
Allman, University of California, Berkeley; and Introducing the UNIX System,
Henry McGilton, Rachel Morgan, McGraw-Hill Book Company, 1983. These
materials are gratefully acknowledged.

Copyright © 1987, 1988 by Sun Microsystems, Inc.
This publication is protected by Federal Copyright Law, with all rights reselVed.
No part of this publication may be reproduced, stored in a retrieval system,
translated, transcribed, or transmitted, in any fonn, or by any means manual,
electric, electronic, electro-magnetic, mechanical, chemical, optical, or otherwise, without prior explicit written pennission from Sun Microsystems.

Contents

Chapter 1 Introduction ..........................................................................................................

1.1. nroff aIld troff ........................................................................................................

Text Fonnatting Versus Word Processing .....................................................

The Evolution of nroff and troff ..............................................................

Preprocessors and Postprocessors .......................................................................

1.2. troff, Typesetters, and Special-Purpose Formatters ..............................

1.3. Using the nroff and troff Text Formatters .............................................

Options Common to nroff and troff .......................................................

Options Applicable Only to nroff ..................................................................

Options Applicable Only to trof f ..................................................................

1.4. General Explanation of t ro f f and nr 0 f f Source Files .......................

Backspacing .....................................................................................................................

Comments .........................................................................................................................

Continuation Lines .......................................................................................................

Transparent Throughput ............................................................................................

Formatter and Device Resolution ........................................................................

Specifying Numerical Parameters .................................................. ,',:...................... .
Numerical Expressions .................................................................,., .....,;,.:......:0';..... ;-••.;:••••••••
1.5. Output and Error Messages .....................,......................... ":~~ ..; ....,...,...;.; ... ;;:;:;.:"~ .. ;.~,,......;;;;

Chapter 2 Line Fonnat ............................................................;;;........ ,~ ..:,:,.....:,:;,:;;;; ..............:,,:.:.:......

;:::>::>

2.1. Controlling Line Breaks ..................................................... i:••.•;.;";:;; ••..• ~~,, .......i;;... ;;;;;;.:..·.... ;; ••• >:::::>
. br -

Break Lines ........................................................................":;..;... ;.; . ;;.;:;..... ~;;.:." ... ,,.. .

Continuation Lines and Interrupted Text .....................................:••.,.;.:..............

- iii-

Contents -

Continued

2.2. Justifying Text and Filling Lines ............................................................................

· ad - Specify Adjusting Styles ........................................................................

· na -No Adjusting .................................................................................................

· nf and . f i-Tum Filling Off and On .....................................................

2.3. Hyphenation .......................................................................................................................

· nh and . h Y -

Control Hyphenation ............................................................

· hw - Specify Hyphenation Word List ........................................................

· he - Specify Hyphenation Character ..........................................................

2.4. . ee -

Center Lines of Text ....................................................................................

2.5. . ul and . eu - Underline or Emphasize Text ............................................

2.6. . uf -

Underline Font ................................................................................................

Chapter 3 Page Layout .........................................................................................................

3.1. Margins and Indentations ............................................................................................

· po -

Set Page Offset .............................................................................................

· 11 -

Set Line Length ...........................................................................................

· in -

Set Indent ........................................................................................................

· ti -Temporarily Indent One Line ..............................................................

3.2. Page Lengths, Page Breaks, and Conditional Page Breaks .....................

· pI -

Set Page Length ...........................................................................................

· bp -

Start a New Page .........................................................................................

· pn -

Set Page Numl>er ........................................................................................

· ne -

Specify Space Needed ..............................................................................

3.3. Multi-Column Page Layout by Marking and Returning ...........................

• mk -

Mark Current Vertical Position ..........................................................

· rt -

Return to Marked Vertical Position .................................................

Chapter 4 Line Spacing and Character Sizes ......................................................

4.1. . sp -

Space Vertically .............................................................................................

4.2. . ps -

Change the Size of the Type ...................................................................

4.3 . . vs -

Change Vertical Distance Between Lines .......................................

4.4. . 1 s -

Change Line Spacing ..................................................................................

4.5. \x Function -

Get Extra Line-Space ................................................................

-iv-

Contents -

Continued

4.6. . sv -

Save Block of Vertical Space ............................................................... ..

4.7 . . as -

Output Saved Vertical Space ................................................................ ..

4.8. . ns -

Set No Space Mode ......................................................................................

4.9. . r s -

Restore Space Mode ....................................................................................

53
53
53

4.10. . ss -

Set Size of Space Character ................................................................ ..

4.11 . . cs -

Set Constant-Width Characters ........................................................ ..

Chapter 5 Fonts and Special Characters ..................................................................

5.1 . . f t -

Set Font ...............................................................................................................

5.2. . fp -

Set Font Position ............................................................................................

5.3. . f

z -

Force Font Size ...............................................................................................

5.4. . bd -

Artificial Boldface .........................................................................................

5.5. Olaracter Set ..................................................................................................................... .

5.6. Fonts ........................................................................................................................................

5.7. . 1 g -

Control Ligatures ...........................................................................................

Chapter 6 Tabs, Leaders, and Fields ..........................................................................

6.1. . ta -

Set Tabs ...............................................................................................................

Setting Relative Tab Stops ......................................................................................

Right-Adjusted Tab Stops ........................................................................................

Centered Tab Stops ......................................................................................................

.t c -

Change Tab Replacement Olaracter ...............................................

Summary of Tabs ..........................................................................................................

6.2. Leaders -

Repeated Runs of Characters ..........................................................

Change the Leader Character ...............................................................

6.3. . f c - Set Field Characters .....................................................................................

Chapter 7 Titles and Page Numbering ......................................................................

7.1. Titles in Page Headers ..................................................................................................

7.2. Fonts and Point Sizes in Titles ................................................................................ .

7.3. . pc -

Page Number Character .............................................................................

011

7.4. . t 1 Request - Three Parameters ........................................................................

Chapter 8 traff Input and Output ...........................................................................

. 1c -

-v-

U"T

Contents -

Continued

8.1. . so -Read Text from a File .................................................................................

8.2. . nx -Read Next Source File ................................................................................

8.3. Pipe Output to a Specified Program (nrof f only) .....................................

8.4. . rd - Read from the Standard Input ................................................................

8.5. . ex -

Exit from nroff or troff ...................................................................

8.6. . tm -

Send Messages to the Standard Error File ......................................

Chapter 9 Strings .......................................................................................................................

9.1. . ds -

Define Strings ..................................................................................................

9.2 . . as -

Append to a String ........................................................................................

9.3. Removing or Renaming String Definitions ......................................................

101

Chapter 10 Macros, Diversions, and Traps ........................................................... lOS
10.1. Macros .................................................................................................................................
· de -

105

Define a Macro .............................................................................................

105

· rm - Remove Requests, Macros, or Strings ............................................

107

· rn -Rename Requests, Macros or Strings ..............................................

108

Macros With Arguments ..........................................................................................

108

· am-Append to a Macro ....................................................................................

112

Copy Mode Input Intetpretation ...........................................................................

112

10.2. Using Diversions to Store Text for Later Processing ...............................

112

· di -Divert Text .....................................................................................................

113

· da -

Append to a Diversion .............................................................................

114

10.3. Using Traps to Process Text at Specific Places on a Page ....................

114

· wh -

Set Page or Position Traps .....................................................................

115

· ch -

Change Position of a Page Trap .........................................................

116

· dt -

Set a Diversion Trap .................................................................................

116

· it -

Set an Input-Line Count Trap ..............................................................

116

· em -

Set the End of Processing Trap ...........................................................

117

Chapter 11 Number Registers ......................................................................................... 121
11.1 . . nr -

Set Number Registers ...............................................................................

121

11.2. Auto-Increment Number Registers .....................................................................

123

-vi-

Contents -

Continued

11.3. Arithmetic Expressions with Number Registers .........................................

124

11.4. . af -

Specify Fonnat of Number Registers ..............................................

125

11.5. . rr -

Remove Number Registers ...................................................................

127

Chapter 12 Drawing Lines and Characters ........................................................... 131
12.1. \ u and \ d Functions -

Half-Line Vertical Movements ......................

131

12.2. Arbitrary Local Horizontal and Vertical Motions ......................................

132

\ v Function -

Arbitrary Vertical Motion ....................................................

132

\h Function -

Arbitrary Horizontal Motion ..............................................

133

12.3. \ 0 Function -

Digit-Size Spaces ......................................................................

134

12.4. '\ ' Function -

Unpaddable Space ...................................................................

136

12.5. \ I and \ ... Functions - Thick and Thin Spaces .......................................

136

12.6. \& Function-Non-Printing Zero-Width Character ..............................

137

12.7. \

Function -

Overstriking Characters .........................................................

138

12.8. \ z Function -

Zero Motion Characters ........................................................

139

12.9. \ w Function -

Get Width of a String ..............................................................

140

12.10. \k Function -

Mark Current Horizontal Place ......................................

141

12.11. \b Function -

Build Large Brackets ...........................................................

142

12.12. \r Function -

Reverse Vertical Motions ..................................................

143

12.13. Drawing Horizontal and Vertical Lines ........................................................

143

\ 1 Function -

Draw Horizontal Lines ...........................................................

143

\ L Function -

Draw Vertical Lines ................................................................

144

Combining the Horizontal and Vertical Line Drawing
Functions ...........................................................................................................................

145

12.14. . mc -

Place Characters in the Margin ........................................................

145

Chapter 13 Character Translations .............................................................................. 149
13.1. Input Character Translations ..................................................................................

149

13.2. . ec and . eo -

Set Escape Character or Stop Escapes .......................

149

13.3. . cc and . c2 -

Set Control Characters ........................................................

150

Output Translation .....................................................................................

150

13.4. . tr -

Chapter 14 Automatic Line Numbering .................................................................. 153
14.1 . . nm -

Number Output Lines ...............................................................................

-vii-

153

Contents -

Continued

14.2. . nn -

Stop Numbering Lines .............................................................................

154

Chapter 15 Conditional Requests ................................................................................. 157
15.1. . if -

Conditional Request ..................................................................................

157

15.2. . ie and . e l - If-Else and Else Conditionals ..........................................

160

15.3. . ig -

160

Ignore Input Text ........................................................................................

Chapter 16 Debugging Requests ................................................................................... 165
16.1. . pm -

Display Names and Sizes of Defined Macros ............................

165

16.2. . f 1 - Flush Output Buffer ..................................................................................

166

16.3 . . ab -

166

Aoort ..................................................................................................................

Chapter 17 Environments ................................................................................................... 169
17.1 . . ev -

Switch Environment .................................................................................

169

Appendix A traff Request Summary ................................................................... 173
Appendix B Font and Character Examples ............................................................ 181
B.1. Font Style Examples .....................................................................................................

181

B.2. Non-ASCII Characters and minus on the Standard Fonts ..........................

182

B.3. Non-ASCII Characters and " "', G, +, -, =, and * on the Special
Font .........................................................................................................................................

182

Appendix C Escape Sequences ....................................................................................... 187
Appendix D Predefined Number Registers ............................................................ 191
Appendix E traff Output Codes .............................................................................. 195
E.1. Codes 0 Oxxxxxx -

Flash Codes to Expose Characters ...........................

196

E.2. Codes lxxxxxxx - Escape Codes Specifying Horizontal
Motion ...................................................................................................................................

197

E.3. Codes Ollxxxxx-Lead Codes Specifying Vertical Motion ..............

197

EA. Codes 010 lxxxx - Size Change Codes ..........................................................

197

E.5. Codes 010 Oxxxx -

Control Codes .....................................................................

198

E.6. How Fonts are Selected ...............................................................................................

199

- viii-

Contents - Continued

E.7. Initial State of the elM ............................................................................................

199

Index .......................................................................................................................................................

201

-ix-

Tables

Table 1-1 Scale Indicators for Numerical Input ............................................................

Table 1-2 Default Scale Indicators for Certain traff Requests and
Functions .......................................................................................................................

Table 1-3 Arithmetic Operators and Logical Operators for Expressions .......

Table 2-1 Constructs that Break the Filling Process ..................................................

Table 2-2 Formatter Requests that Cause a Line Break ...........................................

Table 2-3 Adjusting Styles for Filled Text ......................................................................

Table 5 -1 Exceptions to the Standard Ascn Character Mapping ........................

Table 6-1 Types of Tab Stops .................................................................................................

Table 7-1 Requests that Cause a Line Break ..................................................................

Table 11-1 Access Sequences for Auto-incrementing Number
Registers ........ _...........................................................................................................

124

Table 11-2 Arithmetic Operators and Logical Operators for
Expressions

124

Table 11-3 Interpolation Formats for Number Re gisters .. ,..,....:....;: .... ;;:.;;:,.;..,.......:... ;....:", . .
Table 12-1 t r a f f Width Function -

Table 12-2 Pieces for Constructing Large Brackets .......:•.•.;.... ,:,.;.;.:;; .............;;;,,;:.,., ...;:,.:;;..
Table 15-1 Built-In Condition Names for Conditional

-xi-

Yrolce~;smlg

." ................. ..

159

Tables -

Continued

Table A-I Summary of nraff and traff Requests .............................................

173

Table A-2 Notes in the Tables .................................................................................................

178

Table B-1 Summary of t ro f f Special Characters ....................................................

182

Table C-l t r 0 f f Escape Sequences .................................................................................

187

Table D-l General Number Registers .................................................................................

191

Table D-2 Read-Only Number Registers ..........................................................................

191

Table E-l Size Change Codes .................................................................................................

197

Table E-2 Single Point-Sizes versus Double Point-Sizes ........................................

198

Table E-3 C/A{f Corttrol Codes and their Meanings ................................................

198

Table E-4 Correspondence Between Rail, Mag, Tilt, and Font Number ........

199

-xii-

Figures

Figure 2-1 Filling and Adjusting Styles ............................................................................

Figure 3-1 Layout of a Page .....................................................................................................

- xiii-

Preface
This manual provides reference information and examples for the text fonnatters
nraff and traff. We assume you are familiar with a tenninal keyboard and
the Sun system. If you are not, see Getting Started with SunOS: Beginner's
Guide for infonnation on the basics, like logging in and the Sun file system. If
you are not familiar with text editors, read Doing More with SunOS: Beginner's
Guide and the chapter "Introduction to Text Editing" in Editing Text Files.
Finally, we assume that you are using a Sun Workstation, although specific terminal infonnation is also provided.
For additional details on Sun system commands and programs, see the SunOS
Reference Manual.

Summary of Contents

Here is a summary of the chapters that follow:

Introduction - Describes what t r a f f can do for you, some tools you can
use with traff or nraff to refine your results, how to use nraff and
traff, the differences between the two text formatting programs, and a little about the mechanisms built-in to nraf f and traf f.

Line Format- Explains how the text formatting programs fill and adjust
text input lines and how various formatting requests affect filling and adjusting functions in traff.

Page Layout - Describes the default page layout parameters built-in to
traff and how you can alter them. Also explains how certain fonnatting
requests interact in laying out pages.

Line Spacing and Character Sizes - Explains the availabl~>tYPejffid ·spacing sizes in traff and nraff, and how to change.theln. ..
. ....

Fonts and Special Characters - Describes thefoflt~av~¥apH~witlfhf6f:E
and t r a f f and how to change them.

Tabs, Leaders, and Fields - Explains what tabs, ldlderS,andfie14sarelarid
how to set them.

Titles and Page Numbering - Explains how to create page head.erS and
page footers. Also covers how to use the built-in traff pagcfriumber register to print page numbers on your document automatically.

. "..

-xv-

......

. .....

Preface -

Continued

troff Input and Output -

Describes how to embed files within files, to
switch input from one file to another, to display a message on your tenninal
when troff reaches a certain point in a file, and in nroff only, how to
pipe the output from a file to a program by using a special nroff command
in the file.

Strings - Explains how to give a string of characters a new name so you
can reference them easily. Also provides a facility for referencing the values
of the strings.

10. Macros, Diversions, and Traps - Describes how to define macros, store
infonnation in diversions, and use diversions and traps to process text at
specific places on pages.
11. Number Registers - Explains what troff number registers are and what
you can use their values for.

12. Drawing Lines and Characters - Describes the several built-in troff
functions for moving to arbitrary places on the page and for drawing things.
13. Character Translations - Describes how to change the escape character
and translate the value of one character into another.
14. Automatic Line Numbering - Explains how to use the troff requests for
numbering lines in the output file.

15. Conditional Requests - Describes troff mechanisms for conditionally
accepting input.
16. Debugging Requests - Explains requests for displaying names and sizes of
defined macros, flushing the output buffer, and aborting the fonnatting.
17. Environments - Describes how to shift input processing between the three
nroff /troff environments.
A. t ro f f Request Summary t ro f f requests.

A quick reference summarizing nro f f and

B. Font and Character Examples - Several tables of special characters like
Greek letters, foreign punctuation, and math'symbols.
C. Escape Sequences - Summarizes escape sequences for obtaining values of
number registers, for describing arbitrary motions and drawing things, and
for specifying certain miscellaneous functions.
D. Predefined Number Registers Number Registers
E.

Conventions Used in This
Manual

t ro f f Output Codes totypesetter.

Tables of trof f General and Predefined

A summary of the binary codes for the C/A{f pho-

Throughout this manual we use

(~h_o_s_t_n_a_m_e_%______________________________________________~]
-xvi-

Preface - Continued

as the prompt to which you type system commands. Bo1dface typewriter font indicates commands that you type in exactly as printed on the
page of this manual. Regular typewriter font represents what the system prints out to your screen. Typewriter font also specifies Sun system command names (program names) and illustrates source code listings. Italics indicates general arguments or parameters that you should replace with a specific
word or string. We also occasionally use italics to emphasize important tenns.

Notation Used in This Manual

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 initial algebraic sign is not an increment
indicator, but merely the sign of N. Generally, unreasonable numerical input is
either ignored or truncated to a reasonable value. For example, most requests
expect to set parameters to 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- or
two-character arguments are indicated by a pair of lower case letters. Character
string arguments are indicated by multi-character mnemonics.

- xvii-

1
Introduction

Introduction .......................................................................................................................................

1.1. nroff and troff ........................................................................................................

Text Fonnatting Versus Word Processing .....................................................

The Evolution of nroff and troff ..............................................................

Preprocessors and Postprocessors ......... ................................. ........................ .....

1.2. troff, Typesetters, and Special-Purpose Formatters ..............................

1.3. Using the nraff and traff Text Fonnatters .............................................

Options Common to nraff and troff .......................................................

Options Applicable Only to nroff ..................................................................

Options Applicable Only to trof f ..................................................................

1.4. General Explanation oftroff and nroff Source Files .......................

B ackspacing .....................................................................................................................

Comments .........................................................................................................................

Continuation Lines ...................................... .................................................................

Transparent Throughput ............................................................................................

Formatter and Device Resolution ........................................................................

Specifying Numerical Parameters .......................................................................

Numerical Expressions ..............................................................................................

1.5. Output and Error Messages ........................................................................................

1
Introduction

1.1. nroff and traff

nroff and troff are text processing utilities for the Sun system. nroff formats text for typewriter-like tenninals (such as Diablo printers). trof f is
specifically oriented to formatting text for a phototypesetter. nroff and traff
accept lines of text (to be printed on the final output device) interspersed with
lines of format control information (to specify how the text is to be laid out on
the page) and format the text into a printable, paginated document having a userdesigned style. nroff and troff offer unusual freedom in document styling,
including:

detailed control over page layout;

arbitrary style headers and footers;

arbitrary style footnotes;

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;

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. The formatters provide
requests (conditional input) so that you can embed input expressly destined for
either nroff or troff. nroff can prepare output directly for a variety ofterminal types and is capable of utilizing the full resolution of each terminal.
This manual provides a user's guide and reference section for nroff and
troff. Note that throughout the text we refer to nroff and troff more or
less interchangeably - places where the narrative refers specifically to one or the
other processor are noted. 1
You should be aware that using nroff or troff 'in the raw' requires a
detailed knowledge of the way that these programs work and a certain knowledge
1 The material in this chapter evolved fnm A troffTuJorial, by Brian Kernighan of Bell Laboratories, and
from nroffltroff User's Manual, originally wrinen by Joseph Os sanna of Bell Laboratories.

Revision A, of9 May 1988

Using nroff and troff

of typographical tenns. nroff and troff don't do a great deal of work for you
- for example, you have to explicitly tell them how to indent paragraphs and
number pages and things like that.
If what you are trying to do is just get a job done (like writing a memo), you

shouldn't be reading this manual at all, but rather the chapter "Fonnatting Documents with the -ms Macros" in the Formatting Documents manual. If, on the
other hand, you would like to learn the fine details of a programming language
designed to control a typesetter, this is the place to start reading.
In many ways, nroff's and troff's control language resembles an assembly

language for a computer - a remarkably powerful and flexible one - many
operations must be specified at a level of detail and in a form that is too hard for
most people to use effectively.
The single most important rule when using troff is not to use it directly, but
through some intermediary such as one of the macro packages, or one of the vari0us preprocessors described in Formauing Documents. In the few cases where
existing macro packages don't do the whole job, the solution is not to write an
entirely new set of t r 0 f f instructions from scratch, but to make small changes
to adapt existing packages. In accordance with this strategy of letting someone
else do the work, the part oftroff described here is only a small part of the
whole, although it tries to concentrate on the more useful parts. In any case,
there is no attempt to be complete. Rather, the emphasis is on showing how to
do simple things, and how to make incremental changes to what already exists.
If you are interested in the complete story, look into the t r 0 f f source itself.

Text Formatting Versus Word
Processing

Many newcomers to the UNIX system are surprised to find that there are no word
processors available. This is largely historical- the types of documents (such
as the Sun manuals) that people do with the UNIX system's text formatting packages just can't be done with existing word processors. Before you get into the
details of nrcff and troff, here is a short discussion on the differences
between text fonnatters and word processors, and their relative strengths and
weaknesses.
A word processor is a program that to some extent simulates a typewriter - text
is edited· and fonnatted by one program. You type text at a computer tenninal,
and the word processor fonnats the text on the screen for you as you go. You
usually get special effects like underlining and boldface by typing control indicators. The word processor usually displays these activated features using inverse
video or special marks on the screen. The document is displayed on the tenninal
screen in the same fonnat as it will appear on the printing device. The effects of
this are often tenned 'What You See Is What You Get' (usually called
WYSIWYG and pronounced 'wizzi-wig'). Unfortunately, as has been pointed
out, the problem with many WYSIWYG editors is that 'What You See Is All You
Get'. In general, word processors cannot handle large documents. In principle, it
is possible to write large manuals and even whole books with word processors,
but the process gets painful for large manuscripts. Sometimes a change, such as
deleting a sentence or inserting a new one, in the early part of a document can
require that the whole document has to be refonnatted. A change in the overall
structure of the formatting requirements (for example, a changed indentation
Revision A, of 9 May 1988

Chapter 1 - Introduction

depth) will also mean that the whole document has to be reformatted. Word processors usually don't cope with automatic chapter and section numbering (of the
kind you see in the Sun manuals), neither can they generate tables of contents
and indices automatically. These tasks have to be done manually, and are a
potential source of error. Word processors are eminently suitable for memos and
letters, and can handle short documents. But large documents, or formatting
documents for sophisticated devices like modem phototypesetters, requires a text
formatter.
A textformatter such as nroff or troff does not in general perform anyediting - its only job is reading text from a file and formatting that text for printing
on some device. Entering the text into the file, and formatting the text from that
file for printing are two separate and independent operations. You prepare your
file of text using a text editor such as vi (described elsewhere in this manual).
The file contains text to be formatted, interspersed with formatting instructions
which control the layout of the final text. The text formatter reads this file of
text, and obeys the fonnatting instructions contained in the file. The results of
the formatting process is a finished document. The disadvantage of a text formatter is that you have to run them to find out what the final result will look like.
Many people find the idea of embedded 'formatting commands' foreign, as they
do the idea of two separate processes (an edit followed by a run of the formatter)
to get the final document.
Notwithstanding all of the above, the UNIX system has had text formatting utilities since the very beginning, and many documents were written using the capabilities of nroff or traff.
The Evolution ofnraff and
traff

One of the very first text fonnatting programs was called runoff and was a utility
for the Compatible Time Sharing System (crSS) at MIT in the early 1960's.
Runoffwas named for the way that people would say 'I'll just run off a document'.
When the UNIX system came to have a text formatter, the text formatter was
called roff, because UNIX people like to call things by short and cryptic names.
Roffwas a simple program that was easy to work with as long as you were writing very small and simple documents for a line-printer. In some ways, roff is
easier to use than nraf f or traf f because roffhad built-in facilities such as
being able to specify running headers and footers for a document with simple
commands.
nraff stands for 'Newer roff. troff is an adaptation ofnroff to drive a
phototypesetting machine. Although traff is supposed to mean 'typesetter
roff, some people have formed the theory that traff actually stands for 'Times
Romanoff' because of t ra f f' s penchant for the Times Roman typeface.
nraff and traff are much more flexible (and much more complicated) programs - it's safe to say that they don't do a lot for you - for instance, you have
to manage your own pagination, headers, and footers. The way that nraff and
trof f ease the burden is via facilities to define your own text formatting commands (macros), define strings, and store and manipulate numbers. Without
these facilities, you would go mad (many people have - the author of this

Revision A, of 9 May 1988

Using nroff and troff

document among them). In ad~tion, there are supporting packages for doing
special effects such as mathematics and tabular layouts.
Preprocessors and
Postprocessors

Because troff or nroff are so hard to use 'in the raw', various tools have
evolved to convert from human-oriented ways of specifying things into codes
that troff or nroff can understand. Tools that do translations for troff or ,
nrof f before the fact are called preprocessors. There are also tools that hack
over the output of nroff for different devices or for other requirements. Tools
that do conversions of t r 0 f f or nr 0 f f output after the fact are called postprocessors. Refer to the manual Formatting Documents for explanations of nrof f
and tro f f pre- and postprocessors.

1.2.

Please be sure to read this: this section covers some aspects oftroff that

Typesetters,
and Special-Purpose
Formatters
troff,

are generally glossed over in the traditional UNIX system manuals. trof f was
originally designed as a text fonnatter targeted to one specific machine - that
machine was called a Graphics Systems Incorporated (GSI) C/Aff (Computer
Assisted Typesetter). The C/Aff is a strange and wonderful device with strips of
film mounted on a revolving drum, lenses, and light pipes. The C/A{f flashes
character images on film which you then develop to produce page proofs for your
book or manual or whatever. The C/Aff is almost extinct now except for some
odd niches like Berlceley.
troff was written very much with the C/Aff in mind. The internal units of
measurement that troff uses are C/A/f units, troff only understands four
fonts at a time, and so on. Throughout this chapter, much of the tenninology is
based on troff's intimate relationship with the C/Aff.

1.3. Using the nroff and
troff Text
Formatters

To use nroff or troff you first prepare your file of text with nroff or
troff requests embedded in the file to control the formatting actions. The
remainder of this document discusses the fonnatting commands. Then you run
the fonnatter at the command level like this:
( hostname% nroff

options files

or, of course:
( hostname% troff

options files

where options represents any of a number of option arguments and files
represents the list of files containing the document to be fonnatted.
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.

Options may appear in any order so long as they appear before the files. There
are three parts to the list of options below: the first list of options are common to
both nroff and troff; the second list of options are only applicable to
nroff; the third list of options are only applicable to troff.

Revision A, of 9 May 1988

Chapter 1 - Introduction

Each option is typed as a separate argument -

for example,

hostname% nroff -04,8-10 -T300S -ms file1 file2

fonnats pages 4, 8,9, and 10 of a document contained in the files namedfilel and
file2, specifies the output terminal as a DASI-300S, and invokes the -msun macro
package.

Options Common to nraff
and traff

-olist
Print only pages whose page numbers appear in list, which consists of
comma-separated numbers and number ranges. A number range has the
fonn N-M and means pages N through M; an initial -N means from the
beginning to page N; and a final N- means from N to the end.

-nN
Number first generated page N.
-aN
Stop every N pages. nraff will halt prior to every N pages (default N=I)
to allow paper loading or changing, and will resume upon receipt of a newline.

-mname
Adds the macro file /usr / lib/tmac/tmac. name before the inputfiles.
-raN
Register a (one-character) is set to N.
-i

Read standard input after the input files are exhausted.

-q Invoke the simultaneous input-output mode of the . rd request.

-z Suppress formatted output. The only output you get are messages from. tm
(tenninal message) requests, and from diagnostics.

Options Applicable Only to
nraff

- h Output tabs used during horizontal spacing to speed output as well as reduce
byte count. Device tab settings assumed to be every 8 nominal character

widths. Default settings of input (logical) tabs is also initialized to every 8
nominal character widths.

-Tname
Specifies the name of the output tenninal type. Currently-defined names are
37 for the (default) Model 37 Teletype®, tn300 for the GE TermiNet 300
(or any terminal without half-line capabilities), 300 S for the DASI-300S,
300 for the DASI-300, and 450 for the DASI-450 (Diablo Hytenn).
-e Produce equally-spaced words in adjusted lines, using full tenninal resolution.

Revision A, of 9 May 1988

Using nroff and troff

Options Applicable Only to
traff

-t Direct output to the standard output instead of the phototypesetter.

-a 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 elapsed time.

1.4. General Explanation
oftroff andnroff

Source Files

This section of the nraff and traff manual covers generic topics related to
the fonnat of the input file, how requests are fonned, and how numeric parameters to requests are stated.
To use traff, you have to prepare not only the actual text you want printed, but
some infonnation that tells how you want it printed. For traff, the text and the
formatting information are often intertwined. Most commands to tra f f are
placed on a line separate from the text itself, beginning with a period (one command per line). For example:
Here is some text in the regular size characters,
but we want to make some of the text in a
.ps 14
larger size to emphasize something

changes the 'point size', that is, the size of the letters being printed, to '14 point'
(one point is In2 inch) like this:
Here is some text in the regular size characters, but we want to make some of the
text in a larger size to emphasize something
Occasionally, though, something special occurs in the middle of a line - to
produce Area = 1tr 2 you have to type
(Area

\(*p\flr\fR\ I \s8\u2\d\sO

(which we will explain shortly). The backslash character (\) introduces traff
commands and special characters within a line of text.
To state the above more formally, an input file to be processed by traff or
nraff consists of text lines, which are destined to be printed, interspersed with
control lines, which set parameters or otherwise control subsequent processing.
A control line is usually called a request.
A request begins with a control character - nonnally. (period) or ' (apostrophe or acute accent) - followed by a one or two character name. A request is
either:
a basic request
(also called a command) which is one of the many predefined things that
nraff or traff can do. For example, .11 6. 5i is a basic request to set
the line-length to 6.5 inches, and . in 5 is a basic request to indent the left
margin by five en-spaces.

Revision A, of 9 May 1988

Chapter 1 - Introduction

a macro reference
specifies substitution of a user-defined macro in place of the request. A
macro is a predefined collection of basic requests and (possibly) other macros. For example, in the -ms macro package discussed elsewhere in this
manual, . LP is a macro to start a new left-blocked paragraph.
The ' (apostrophe or acute accent) control character suppresses the break
function- the forced output of a partially filled line- caused by certain
requests.
The control character may be separated from the request or macro name by white
space (spaces and/or tabs) for aesthetic reasons. Names must be followed by
either space or newline. nraff or traff ignores control lines whose names
are unrecognized.
Various special functions may be introduced anywhere in the input by means of
an escape character, normally \. For example, the function \ nR interpolates the
contents of the number register whose name is R in place of the function. Here R
is either a single character name in which case the escape sequence has the form
\ nx, or else R is a two-character name, in which case the escape sequence must
have the form \n (xx. In general, there are many escape sequences whose onecharacter form is \ fx and whose two-character form is \ f (xx, where f is the
function and x or xx is the name.
To print the escape character (usually backslash), use \e (backslash e).
Backspacing

Unless in copy mode, the ASCII backspace character is replaced by a backward
horizontal motion having the width of the space character. Underlining as a form
of line-drawing is discussed in the section on Arbitrary Motions and Drawing
Lines and Characters. A generalized overstriking function is also described in
the above- mentioned section.

Comments

Comments may be placed at the end of any line by prefacing them with \ ". A
comment line cannot be continued by placing a \ at the end of the line - see the
discussion on continuation lines below.
A line beginning with \" appears as a blank line and behaves like a . sp 1
request:
Here is a line of text.
\" Here is a comment on a line by itself.
Here is another line of text.

when we format the above lines we get this:
Here is a line of text.
Here is another line of text.

If you want a comment on a line by itself but you don't want it to appear as a
blank line, type it as . \ " :
Revision A, of 9 May 1988

Using nroff and troff

Here is a line of text
.\" and here is a comment on a line by itself
and here is another line of text

when we fonnat the above lines we get this:
Here is a line of text
and here is another line of text

Continuation Lines

An uncomfortably long input line that must stay one line (for example, a string
definition, or unfilled text) can be split into many physical lines by ending all but
the last one with the escape \. The sequence \ (newline) is always ignored except in a comment - see below. This provides a continuation line facility.
The \ at the end of the line is called a concealed newline in the jargon.

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 infonnation to a postprocessor or to embed control lines in a macro created by a diversion. Refer to
Chapter 10 for infonnation describing diversions.

Formatter and Device
Resolution

traff internally uses 432 units/inch, corresponding to the phototypesetter
which has a horizontal resolution of 1/432 inch and a vertical resolution of 1/144
inch. nraff internally uses 240 units/inch, corresponding to the least common
multiple of the horizontal and vertical resolutions of various typewriter-like output devices. traff rounds horizontal/vertical numerical parameter input to the
actual horizontal/vertical resolution of the Graphic Systems typesetter. nraff
similarly rounds numerical input to the actual resolution of the output device
indicated by the -T option (default Model 37 Teletype).

Specifying Numerical
Parameters

Many requests can have numerical arguments. Both nroff and traff accept
numerical input in a variety of units. The general fonn of such input is

(~_.x_x____n_n_nn____u_n_l_'t_s__________________________________________________________________________________-JJ
where. xx is the request, nnnn is the number, and units is the "scale indicator."
Scale indicators are shown in the following table, where S is the current type size
in points, V is the current vertical line spacing in basic units, and C is a nominal
character width in basic units.

Revision A. of 9 May 1988

Chapter 1 -Introduction

Table 1-1

Scale Indicatorsfor Numerical Input
Scale
Indicator

i
c
p

n
p
u

v
none

Number of basic units
troff
nroff

Meaning

Inch
Centimeter
Pica = 1/6 inch
Em = Spoints
En=Em/2
Point = 1n2 inch
Basic unit
Vertical line space
Default, see below

432
432><50/127
72
6XS
3XS
6
1

240
240><50/127
240/6
C
C,sameasEm
240n2
1

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 nraff 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,
V s for the vertically-oriented requests and functions, p for the vertical spacing
request; and u for the number register and conditional requests. See Table 1-2 for
a summary of the default scale indicators for the traff requests and functions
that take scale indicators.
Table 1-2

Default Scale Indicatorsfor Certain troff Requests and Functions
Request

.11
.in
.ti
.ta
.1t
.po
.mc
\h
\1
.nr
.if
.ie

Default Scaling Unit

ems
"
"
"
"
"
"

"
"
machine units (u)
"
"

Request

.pl
.wh
.ch
.dt
.sp
.sv
.ne
.rt
\v
\x

\L
.vs

Default Scaling Unit

vertical units (Vs)
"
"
"
"
"
"

"
"

"
"
picas (p)

All other requests ignore any scale indicators. When a number register 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. The number, N, may be specified in decimal fonn,
but the parameter finally stored is rounded to an integer number of basic units.
Revision A, of 9 May 1988

Using nroff and troff

The absolute position indicator I (the pipe character) may precede a number N to
generate the absolute distance to the vertical or horizontal place N. For
vertically-oriented requests and functions, I N becomes the absolute distance in
basic units from the current vertical place on the page or in a diversion (see
Chapter 10 for the section on diversions) to the vertical place N. For all other
requests and functions, I N becomes the distance from the current horizontal
place on the input line to the horizontal place N. For example,
[_,_S_P__
I_3_._2_C________________________________________J
will space in the required direction to 3.2 centimeters from the top of the page.
Numerical Expressions

Table 1-3

Wherever numerical input is expected, you can type an arithmetic expression.
An expression involves parentheses and the arithmetic operators and logical
operators shown in the table below:

Arithmetic Operators and Logical Operators for Expressions
Meaning

Arithmetic Operator

+
I

Addition
Subtraction
Division
Multiplication
Modulo

Logical Operator

Meaning

<
>
<=
>=
=or==
&

Less than
Greater than
Less than or equal to
Greater than or equal to
Equal to
and
or

Except where controlled by parentheses, evaluation of expressions is left-to-right
- there is no operator precedence.
In certain requests, an initial + or- is stripped and interpreted as an increment or
decrement indicator respectively. In the presence of default scaling, the desired

scale indicator must be attached to every number in an expression for which the
desired and default scaling differ. For example, if the number register x contains
2 and the current point size is 10, then
( ,II

(4,25i+\nxP+3)/2u

will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 30 points.

Revision A, of 9 May 1988

Chapter 1 -

1.5. Output and Error
Messages

Introduction

The output from . tm, . pm, and the prompt from . rd, as well as various error
messages are written onto the standard error message output. The latter is different from the standard output, where nroff fonnatted output goes. By
default, both are written onto the user's tenninal, but they can be independently
redirected - in the case of t r a f f, the standard output should always be
redirected unless the -a option is in effect, because troff's output is a strange
binary format destined to drive a typesetter.
Various error conditions may occur during the operation of nroff and traff.
Certain less serious errors having only local impact do not stop processing. Two
examples are word overflow, caused by a word that is too large to fit into the
word buffer (in fill mode), and line overflow, caused by an output line that grew
too large to fit in the line buffer; in both cases, a message is printed, the offending excess is discarded, and the affected word or line is marked at the point of
truncation with a * in nroff and a ¢:::: in traff. The philosophy is to continue
processing, if possible, on the grounds that output useful for debugging may be
produced. If a serious error occurs, processing tenninates, and an appropriate
message is printed. Examples are the inability to create, read, or write files, and
the exceeding of certain internal limits that make future output unlikely to be
useful.

Revision A, of 9 May 1988

2
Line Format
Line Fonnat ......................................................................................................................................

2.1. Controlling Line Breaks ..............................................................................................

Break Lines ....................................................................................................

Continuation Lines and Interrupted Text ........................................................

2.2. Justifying Text and Filling Lines ............................................................................

· ad -

Specify Adjusting Styles ........................................................................

· na -

No Adjusting .................................................................................................

· nf and . f i-Tum Filling Off and On .....................................................

2.3. Hyphenation .......................................................................................................................

· br -

· nh and . hy -

Control Hyphenation ............................................................

· hw -

Specify Hyphenation Word List ........................................................

· he -

Specify Hyphenation Character ..........................................................

Center Lines of Text ....................................................................................

2.4 . . ce -

2.5 . . ul and . eu 2.6. . uf -

Underline or Emphasize Text ............................................

Underline Font ................................................................................................

". s

•

~••

i!:

2
Line Format

Perhaps the most important reason for using troff or nroff is to use its filling
and adjusting capabilities. Here is what filling and adjusting mean:
Filling

means that t r 0 f f or nr 0 f f collects words from your input text
lines and assembles the collected words into an output text line until
some word doesn't fit. An attempt is then made to hyphenate the
word in an effort to assemble a part of it into the output line. Filling
continues until something happens to break the filling process, such
as a blank line in the text, or one of the troff or nroff requests
that break the line - things that break the filling process are discussed later on.

Adjusting

means that once the line has been filled as full as possible, spaces
between words on the output line are then increased to spread out the
line to the current line-length minus any current indent. The paragraphs you have just been reading are both filled and adjusted.
Justification implies filling - it makes no sense to adjust lines
without also filling them.

In the absence of any other infonnation, t ro f f 's or nro f f 's standard behavior

is to fill1ines and adjust for straight left and right margins, so it is quite possible
to create a neatly fonnatted document which only contains lines of text an9 no
fonnatting requests. Given this as a starting point, the simplest document of all
contains nothing but blocks of text separated by blank lines - t ro f f or nro f f
will fill and justify those blocks of text into paragraphs for you. To get further
control over the layout of text, you have to use requests and functions embedded
in the text, and that is the subject of this entire paper on using t ro f f.
A word is any string of characters delimited by the space character or the beginning or end of the input line. Any adjacent pair of words that must be kept
together (neither split across output lines nor spread apart in the adjustment process) can be tied together by separating them with the unpaddable space character '\ '(backslash-space)- also called a 'hard blank' in other systems. The
adjusted word spacings are unifonn in troff and the minimum interword spacing can be controlled with the .55 (space size) request. In nroff, interword
spaces are nonnally nonunifonn because of quantization to character-size spaces,
but the -e command line option requests unifonn spacing to the full resolution
of the output device. Multiple inter-word space characters found in the input are
retained, except for trailing spaces.
17

Revision A, of 9 May 1988

Using nroff and troff

Filling and adjusting and hyphenation can all be prevented or controlled by
requests that are discussed later in this part of the manual.
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.

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 the . t r (translate) request see the relevant section.
The text length on the last line output is available in the . n number register, and
text baseline position on the page for this line is in the nl number register. The
text baseline high-water mark on the current page is in the . h number register.

2.1. Controlling Line
Breaks

When filling is turned on, words of text are taken from input lines and placed on
output lines to make the output lines as long as they can be without overflowing
the line length, until something happens to break the filling process. When a
break occurs, the current output line is printed just as it is, and a new output line
is started for the following input text. There are various things that cause a break
to occur:

Revision A, of 9 May 1988

Chapter 2 - Line Format

Table 2-1
Construct

Constructs that Break the Filling Process
Explanation

Blank liners)

If your input text contains any completely blank lines, traff or nraff
assumes you mean them. So it prints the current output line, then your blank
lines, then starts the following text on a new line.

Spaces

at the beginning of a line are significant. If there are spaces at the start of a
line, traff or nraff assumes you know what you are doing and that you
really want spaces there. Obviously, to achieve this, the current output line
must be printed and a new line begun. Avoid using tabs for this purpose,
since they do not cause a break.

A . b r request

A . br request (break) request can be used to make sure that the following
text is started on a new line.

traff or nraff requests

Some traff or nraff requests cause a break in the filling process.
However, there is an alternate format of these requests which does not cause a
break. That is the format where the initial period character ( . ) in the request
is replaced by the apostrophe or single quote character ('). The list of
requests that cause a break appears in the table below this one.

A \p Function

When filling is in effect, the in-line \p function may be embedded or attached
to a word to cause a break at the end of the word and have the resulting output
line spread out to fill the current line length.

End offile

Filling stops when the end of the input file is reached.
Breaks caused by blank lines or spaces at the beginning of a line enable you to
take advantage of the filling and justification features provided by traff or
nraff without having to use any traff or nraff requests in your text.
As mentioned in the table above in the item entitled "traff or nraff
requests," there are some requests that cause a break when they are encountered.
The list of requests that break lines is short and natural:

Revision A, of9 May 1988

Using nroff and troff

Table 2-2

Formatter Requests that Cause a Line Break
Convnand
· bp
· br

· ce
·f i
· nf

· sp
· in
·t i

Ex.plananon
Begin a new page
Break the current output line
Center line(s)
Start filling text lines
Stop filling text lines
Space vertically
Indent the left margin
Temporary indent the left margin for the next line only

No other requests break lines, regardless of whether you use a . or a ' as the control character. If you really do need a break, add a . br (break) request at the
appropriate place, as described below.
. br -

Break Lines

The . b r (break) request breaks the current output line and stops filling that line.
Any new output will start on a new line.

Summary o/the . br Request
Mnemonic:

break

Form of Request:

.br

Initial Value:

Not Applicable

If No Argument:

cause break

Explanation:

Stop filling the line currently being collected and output the line without
adjustment. Text lines beginning with space characters and empty text lines
(blank lines) also cause a break.

Continuation Lines and
Interrupted Text

The copying of an input line in nofill (non-fill) mode (see below) can be interrupted by tenninating the partial line with a \ c. The next encountered input text
line will be considered to be a continuation of the same line of input text. Similarly, a word within filled text may be interrupted by tenninating the word (and
line) with \c; the next encountered text will be taken as a continuation of the
interrupted word. If the intervening control lines cause a break, any partial line
will be forced out along with any partial word.

Revision A. of 9 May 1988

Chapter 2 -

Line Format

2.2. Justifying Text and
Filling Lines
. ad -

Specify Adjusting

Styles

Table 2-3

To change the style of text justification, use the . ad (adjust) request to specify
one of the four different methods for adjusting text:
Adjusting Styles for Filled Text
Adjusting
Indicator

Adjusting
Style

.ad 1

Left

.ad r
.ad c

Right
Center

.ad b
.ad n
.ad

Both
Nonna!
Reset

Description
Produces flush-left, ragged-right output, which
is the same as filling with no adjustment.
Produces flush-right, ragged-left output
Centers each output line, giving both left and
right ragged margins.
Justifies both left and right margins.
Resumes adjusting lines in the last mode
requested.

It makes no sense to try to adjust lines when they are not being filled, so if filling
is off when a . ad request is seen, the adjusting is deferred until filling is turned
on again.

Summary of the . ad Request
Mnemonic:

adjust

Form of Request:

.adc

Initial Value:

. ad b - that is, adjust both margins.

If No Argument:

Adjust in the last specified adjusting mode.

Explanation:

Adjust lines - if fill mode is off, adjustment is be deferred until fill mode is
back on. If the type indicator c is present, the adjustment type is changed as
shown in Table 2-3.

Notes:

E (see Table A-2)
The current adjustment indicator c can be obtained from the . j number register.
The following figure illustrates the different appearances of filled and justified
text.

Revision A, of 9 May 1988

Using nroff and troff

This paragraph is filled and adjusted on both margins. This is the easiest fonnatting style to achieve
using nraff or traff because you don't have to place any requests in your text - you just type the
blocks of text into the input file and the formatter does something reasonably sane with them. Although
we specified nothing to get the paragraph filled and adjusted, we could have used an . ad b (adjust
both) request, or a . ad n (adjust normal) request - they both mean the same thing, namely, fill lines
and adjust both margins.

This paragraph is an example of 'flush left, ragged right', which is what you get when you have filling
without adjusting - words are placed on the line to fill lines out as far as possible, but no interword
spaces are inserted so the right-hand margin looks ragged. This paragraph was formatted using an . ad
1 (adjust left) request, which has the same effect as using a . na (no adjust) request described later.

Then this paragraph is an illustration of text fonnatted as 'flush right, ragged left' - words are placed on
the line to fill lines out as far as possible, then the lines are made to line up on the right-hand margin, no
interword spaces are inserted, and so the left-hand margin looks ragged. This paragraph was fonnatted
using an . ad r (adjust right) request.

Finally, this paragraph is an instance of a fonnatting style called 'centered' adjusting, also known as
'ragged left, ragged right' - words are placed on the line to fill lines out as far as possible, then the lines
are centered so that both margins look ragged. This paragraph was formatted using an . ad c (adjust
center) request.

Figure 2-1
. na -

No Adjusting

Filling and Adjusting Styles
If you don't specify otherwise, traff or nroff justifies your text so that both
left and right margins are straight. This can be changed if necessary - one way,
as we showed above, is to use the . ad 1 request to get left adjusting only so
that the left margin is straight and the right margin is ragged. Another way to
achieve this same effect is to use the . na (no adjust) request. Output lines are
still filled, providing that filling hasn't also been turned off - see the . n f (no
fill) and . f i (fill) requests below. If filling is still on, troff or nroff produces flush left, ragged right output. To tum adjusting back on (return to the previous state), use the . ad request.

Revision A, of9 May 1988

Chapter 2 - Line Format

Summary of the . na Request
Mnemonic:

no adjust

Form of Request:

.na

Initial Value:

Adjusting is on by default

If No Argument:

adjusting is turned off

Explanation:

Turn off adjustment - the right margin will be ragged. The adjustment
type for the . ad request is not changed. Output lines are still filled if fill
mode is on. To turn adjusting back on (return to the previous state), use the
. a d request.

Notes:

E (see Table A-2)

. n f and . f i-Turn Filling
Off and On

The . nf (no fill) request turns off filling. Lines in the result are neither filled
nor adjusted. The output text appears exactly as it was typed in, complete with
any extra spaces and blank lines you might type - this is often called 'asis text', or 'verbatim'. No filling is mainly used for showing examples, especially in computer books where you want to show examples of program source
code.
You should be aware that traditional typesetting people have trouble with the
concept of no filling, because their typesetting systems are geared up to fill and
adjust text all the time. When you ask for stuff to be printed exactly the way you
typed it, they have problems, especially when you want blank lines left in the
unfilled text exactly where you put them. In the world of typography, things that
don't fit into the Procrustean mold of filled text are often called 'displays' and
have to be handled specially.
The . f i (fill) request turns on filling. If adjusting has not been turned off by a
. na request, output lines are also adjusted in the prevailing mode set by any previous . ad request.

Summary of the . fi Request
Mnemonic:

fill

Form of Request:

.fi

Initial Value:

Filling is on by default

If No Argument:

filling is turned on

Exp lanation:

Fill subsequent output lines. The number register . u is 1 in fill mode and 0
in nofill mode.

Notes:

E,B (see Table A-2)

+~I!!

Revision A, of9 May 1988

Using nroff and troff

Summary o/the . nf Request
Mnemonic:

no fill

Form o/Request:

.nf

Initial Value:

Filling is on by default

If No Argument:

filling is turned off

Explanation:

Subsequent output lines are neither filled nor adjusted. Input text lines are
copied directly to output lines without regard for the current line length.
The number register . u is 1 in fill mode and 0 in nofill mode.

Notes:

E,B (see Table A-2)

2.3. Hyphenation

When troff or nroff fills lines, it takes each word in tum from the input text
line, and puts the word on the output text line, until it finds a word that will not
fit on the output line. At this point, troff or nroff tries to hyphenate the
word. If possible, the first part of the hyphenated word is put on the output line
followed by a -, and the remainder of the word is put on the next line. We
should emphasize that, although the examples show text that is both filled and
justified, it is during filling that troff or nroff hyphenates words, not adjusting.
If you have words in your input text containing hyphens (such as jack-in-the-box,

or co-worker), troff or nroff will, if necessary, split these words over two
lines, even if hyphenation is turned off.
. nh and . hy Hyphenation

Control

Nonnally, when you invoke troff or nroff, hyphenation is turned on, but
you can change this. The . nh (no hyphenation) request turns off automatic
hyphenation. When hyphenation is turned off, the only words that are split over
more than one line are those that already contain hyphens. Hyphenation can be
turned on again with the . h Y (hyphenate) request.
You can give. hy an argument to restrict the amount of hyphenation that troff
or nroff does. The argument is numeric. The request. hy 2 stops troff or
nroff from hyphenating the last word on a page .. hy 4 instructs troff or
nrof f not to split the last two characters from a word; so, for example,
'repeated' will never be hyphenated 'repeat-ed' .. hy 8 requests the same thing
for the first two characters of a word; so, for example, 'repeated' will not be
hyphenated 're-peated'.
The values of the arguments are additive: . h Y 12 makes sure that words like
'repeated' will never be hyphenated either as 'repeat-ed' or as 're-peated'. . h Y
14 calls up all three restrictions on hyphenation.
A . h y 1 request is the same as the simple . h y request - it turns on hyphenation everywhere. Finally, a . hy 0 request is the same as the . nh request - it
tums off automatic hyphenation altogether.

Revision A. of 9 May 1988

Chapter 2 -

Line Format

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 characters - such as mother-in-law - are always subject to splitting after those characters, whether or not automatic hyphenation is on or off.

Summary of the . nh Request
Mnemonic:

no hyphenation

Form of Request:

.nh

Initial Value:

Hyphenation is on by default

If No Argument:

hyphenation is turned off

Explanation:

Turn automatic hyphenation off.

Notes:

E (see Table A-2)

Summary of the . hy Request
Mnemonic:

hyphenation

Form of Request:

.hyN

Initial Value:

Hyphenation is on by default in mode 1.

If No Argument:

N=1.

Explanation:

Turn automatic hyphenation on for N ~ 1, or off for N =0. If n = 1, all words
are subject to hyphenation. If N =2, do not hyphenate last lines (ones that
cause a trap). If N =4, do not hyphenate the last two characters of a word. If
N =8, do not hyphenate the first two characters of a word. These values are
additive - that is, N =14 invokes all three restrictions. Note: odd values of
N (except 1) don't make sense.

Notes:

E (see Table A-2)

. h w - Specify Hyphenation
Word List

If there are words that you want troff or nroff to hyphenate in some special
way, you can specify them with the . hw (hyphenate words) request. This
request tells troff or nroff that you have special cases it should know about,

for example:
( .hw pre-empt ant-eater

Now, if either of the words 'preempt' or 'anteater' need to be hyphenated, they
will appear as specified in the . hw request, regardless of what troff or
nroff 's usual hyphenation rules would do. If you use the . hw request, be
aware that there is a limit of about 128 characters in total, for the list of special
words.

Revision A, of 9 May 1988

Using nroff and troff

Summary of the . hw Request
Mnemonic:

hyphenate word

Form of Request:

.hw word1 ...

Initial Value:

None

If No Argument:

Ignored

Explanation:

Specify hyphenation points in words with embedded minus signs. Versions
of a word with tenninal s are implied - that is, dig-it implies dig-its. This
list is examined initially and after each suffix stripping. The space available
is small- about 128 characters.

. he --- Specify

Character

Hyphenation

A hyphenation indicator character may be embedded in a word to specify desired
hyphenation points, or may precede the word to suppress hyphenation. For
example, hyphenation looks particularly disruptive if it occurs in titles. So, if
you had a long title like:
Input and Output Conventions and Character Translations,
you could shorten it, or you could insert the hyphenation character just before the
first character of each of the long words at the end of the title. The input might
look like this:
.R C "Input and Output Conventions and \%Character \%Translations'

(If you are using a reasonable line length, you don't need to worry about hyphenation occurring earlier in the title in this example.)
Here is an example of using the hyphenation character to specify acceptabl~
hyphenation points within a word. The word "workstation" is often mishyphenated because of the collection of consonants at the end of "work" and the
beginning of "station". So, your input might look like this:

(~w_o_r_k_\_%_s_t_a_t_i_o_n

__________________________________________________________________

Revision A, of 9 May 1988

Chapter 2 -

Line Format

Summary of the . he Request
Mnemonic:

hyphenation character

Form of Request:

.he c

Initial Value:

If No Argument:

Explanation:

Set hyphenation indicator character to c or to the default \ %. The indicator
does not appear in the output.

Notes:

E (see Table A-2)

2.4. . ce - Center Lines of
Text

When we described "Filling and Adjusting," we showed how the text produced
by nroff or troff could be centered by using the . ad e request. Setting
text adjustment for centering is a fairly unusual way of getting centered text,
because the text is being filled at the same time. The more usual use for centering is to have unfilled lines that are centered - that is, each line that you type is
centered within the output line. You get lines centered via the . ee (center)
request, which centers lines of text.
If you just use a . ee request without an argument, troff or nroff centers the
next line of text:

(.ce

centers the following line of text, whereas:

(.ce

centers the following five lines of text. Filling is temporarily turned off when
lines are centered, so each line in the input appears as a line in the output, centered between the left and right margins. For centering purposes, the left margin
includes both the page offset (see later) and any indentation (also see later) that
may be in effect.
An argument of zero to the . ee request simply stops any centering that might be
in progress. So, if you don't want to count how many lines you want centered,
you can ask for some large number of lines to be centered, then follow the last of
the lines with a . ee 0 request:

Revision A, of9 May 1988

Using nroff and troff

.ce 100

lines of text to be centered

.ce 0

The '100' in the example above could be any large number that you think is
bigger than the number of lines to center.
Note that the argument to the . ce request only applies to following text lines in
the input. Lines containing nroff or troff requests are not counted.

Summary of the . ce Request
Mnemonic:

center

Form of Request:

.ceN

Initial Value:

Centering is off by default.

If No Argument:

N=l

Explanation:

Center the next N input text lines within the current line (line-length minus
indent). If N=O, any residual count is cleared. A break occurs after each of
the N input lines. If the input line is too long, it is left adjusted.

Notes:

E,B (see Table A-2)

2.5. . ul and. cu Underline or
Emphasize Text

There are times when you want to lend emphasis to a word in a piece of text.
The nonnal way to do this is to place the word or piece of text in italics if you
have an italic font, or underline the word if you don't have an italic font. The
· ul (underline) request underlines alphanumeric characters in nroff, and
prints those characters in the italic font in troff. As with the . ce request, a
· ul request with no argument underlines a single line of text, so:

simply underlines the following line of text. Unlike. ce, though, . ul does not
tum filling off. A numeric argument to the . ul request specifies the number of
text lines you want underlined, so:
( .ul 3

)

underlines the next three lines of text. As with centering, an argument of zero
· u 1 0 cancels the underlining process.
Revision A, of 9 May 1988

Chapter 2 -

Line Format

Summary of the . ul Request
Mnemonic:

underline

Form of Request:

.ulN

Initial Value:

Underlining is off by default.

If No Argument:

N=l

Exp lanation:

Underline in nroff (italicize in troff) the next N input text lines. Actually, switch to underline font, saving the current font for later restoration;
other font changes within the span of a . ul will take effect, but the restoration will undo the last change. Output generated by a . t 1 request is
affected by the font change, but does not decrement N. If N > 1, there is the
risk that a trap-interpolated macro may provide text lines within the spanenvironment switching can prevent this.

Notes:

E (see Table A-2)

Another form of underlining is called up with the . eu request, and asks for continuous underlining. This is the same as the . ul request, except that all characters are underlined. Again, if you are using troff the characters are printed in
the italic font instead of underlined. There is a way to get characters underlined
in troff, and this technique is explained later in this manual.
As with. ee, only lines of text to be underlined are counted in the number given
to the underline request. nroff or troff requests interspersed with the text
lines are not counted.

Summary of the . eu Request
Mnemonic:

continuousl y underline

Form of Request:

.euN

Initial Value:

Underlining is off by default.

If No Argument:

N=l

Explanation:

A variant of . ul that underlines every character in nroff. Identical to
. ul in troff.

Notes:

E (see Table A-2)

2.6. . u f

Underline Font

nroff automatically underlines characters in the underline font, specifiable
with a . uf (underline font) request. The underline font is nonnally Times Italic
and is mounted on font position 2. In addition to the . ft (font) request and the
\fF, the underline font may be selected by the . ul (underline) request and the
. eu (continuous underline) request. Underlining is restricted to an outputdevice-dependent subset of reasonable characters.

Revision A, of9 May 1988

Using nroff and troff

Summary of the . uf Request
Mnemonic:

underline font

Form of Request:

.uf F

Initial Value:

Italic

If No Argument:

Italic

Explanation:

Set underline font to F. In nro f f, F may not be on position 1 (initially
Times Roman).

Revision A, of 9 May 1988

3
Page Layout
Page Layout ......................................................................................................................................

3.1. Margins and Indentations ............................................................................................

· po -

Set Page Offset .............................................................................................

· 11 -

Set Line Length ...........................................................................................

· in -

Set Indent ........................................................................................................

· t i-Temporarily Indent One Line ..............................................................

3.2. Page Lengths, Page Breaks, and Conditional Page Breaks .....................

· p l - Set Page Length ...........................................................................................

· bp -

Start a New Page .........................................................................................

· pn -

Set Page Number ........................................................................................

· ne -

Specify Space Needed ..............................................................................

3.3. Multi-Column Page Layout by Marking and Returning ...........................

· mk -

Mark Current Vertical Position ..........................................................

· rt -

Return to Marked Vertical Position .................................................

3
Page Layout
Now we get into the subject of altering the physical dimensions of the layout of
text on a page. There are two major parts to page control, and they can be
roughly divided into controlling the horizontal aspects of lines, and controlling
the vertical aspects of the page dimensions.
Horizontal page control
Vertical page control

Deals with subjects such as the location of the left margin, the location of the
right margin (the length of the line), and indentation of lines.
Deals with the physical length of the page, when pages get started, and whether
there's enough room on the current page for a block of text. Page numbering is
also covered in this area.
These topics are covered in this section. We deal first with horizontal page control, then with the vertical aspects of page control.
We should explain how traff thinks of a page. The next page contains a
diagram of a page of text, and here we explain what some of the terms mean:

Page Offset

is the distance from the physical edge of the paper to the place where all text
begins. In normal-world terms, this distance is called the 'left margin'. Normally you only set the page-offset at the very start of a formatting job and you
never change it again.

Line Length

is the distance from the left margin (or page-offset) to the right edge of the text.
The line-length is relative to the page-offset. In some respects, 'line-length' is a
bit of a misnomer, because once you have set the page-offset at the start of the
document (and assuming you never change it), the line-length really nails down
the position of the right margin and has little to do with the length of the line.

Indent

is where the left edge of your text starts. Normally the indent is zero, so that the
edge of the text is where the page-offset is, but you can change the indent so that
the text starts somewhere else. Note that the line-length is not affected by the
indent - that is, indenting the text doesn't change the position of the right margin.

Page Length

is the distance from the extreme top of the page to the extreme bottom of the
page, that is, the page length is the physical length of the paper.
The following figure is a diagram of a page of text with the relevant parts pointed
out. This diagram is a scale-model of an 8.5 x II-inch sheet of paper, so while
the numbers quoted in the text below are expressed in 'real' units, the actual
dimensions are scaled.
33

Revision A, of 9 May 1988

Using nroff and troff

Figure 3-1

left header

Layoutofa Page
center header

right header

This paragraph has the page-offset set to give a left margin of approximately one inch (scaled). The
line-length is set to 6.5 inches (scaled). This means there is a one-inch (scaled) left margin and a oneinch (scaled) right margin. The indent is set to zero so that the current left margin is at the same place
as the page-offset.
This paragraph has the page-offset and the line-length the same as the last paragraph, but
we've used a . in +0. Si request to indent the left margin by half an inch - the current left
margin is now page-offset + indent. Note that the position of the right margin remains the
same as in the previous paragraph - only the left margin moved, so the effective length of the
lines is shorter.
This paragraph now has the left margin back to the original position because we inserted a . in
- 0 . 5 i request before it.
This paragraph could have the left margin moved, not by indenting, but by changing the page-offset via
a .po +0. Si request. Now all text would be moved to the left, and because the line-length hasn't
changed, the right margin would move as well. The example can't show this because page offset is
measured from the margin, and because this example is in a box, changing the page offset within the
box is meaningless.
This is the regular old paragraph where the first line is indented and the rest of the text in the paragraph is flushed to the left margin. The first line was indented via a . ti +0. 25i request to give a
temporary indent of the first line.
•

This paragraph is an example of an 'item' or 'bulleted' or 'hanging' paragraph, where the left margin is moved to the right, and the 'bullet' or 'tag' is moved back to the old left margin. This effect
was achieved via a . in +0. 2Si request to move the left margin rightward, and then the 'bullet'
was preceded by a . t i - 0 . 25 i request to get a temporary indent to the old position of the left
margin.

Finally, note that tab stops are relative to the current left margin as we show here with a couple of
blocks of text with different indents. Note that the positions of the tab stops are shown with exclamation point ( ! ) characters:
!
!
!
!
You can see by the line of ! marks above where the tab stops are.
Now we have another block of text here but with the indent moved over a half-inch. As you
can see by the line of ! marks below, the tab stops have moved with the left margin:
!
!
!
!
!
left footer

center footer

right footer

Revision A, of 9 May 1988

Chapter 3 -

Page Layout

3.1. Margins and
Indentations

As we said above, the positions of the left-hand and right-hand margins are controlled via the page-offset and the line-length. After that, any movements of the
left-hand margin are controlled via indent and temporary indent requests. These
topics are discussed in the following subsections.

. po - Set Page Offset

The usable 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
The page-offset is the distance from the extreme left-hand edge of the paper to
the left margin of your text When you use 'standard' 8.5xll-inch paper, it is
customary to have the left and right margins be one inch each, so that the physical length of the printed lines are 6.5 inches - or you'd say that the measure was
39 picas if you're a typographer and can't handle inches.
In general, you only set the page-offset once in the course of formatting a docu-

ment. Setting the page-offset determines the position of the physical left margin
for the text, and then you (almost) never change the page-offset again - all
indentation is done via. in (indent) requests and . ti (temporary indent)
requests. We talk about these requests later in this part of the manual.
The position of the physical right margin for the text is determined by the linelength relative to the page-offset. The .11 (line length) request is discussed
below.

Summary of the . po Request
Mnemonic:

page offset

Form of Request:

.po±N

Initial Value:

o in nrof f, 26/27 inch in trof f

If No Argument:

Previous value

Explanation:

Set the current left margin to ±N. In trof f the initial value is 26{27 inch,
which provides about one inch of paper margin including the physical
typesetter margin of 1/27 inch. In trof f the maximum (linelength)+(page-offset) is about 7.54 inches. In nroff the initial page-offset
is zero.

Notes:

v (see Table A-2)

The current page-offset is available in the . 0 register.
. 11 -

Set Line Length

troff gives you full control over the length of the printed lines. By the way,
typographers don't use terms like 'line-length', they use the word 'measure' to
mean the length of a line. They always measure vertical distances in 'picas'.

Nevertheless, to set the line-length in troff, use the .11 (line length) request,
as in

Revision A, of 9 May 1988

Using nroff and troff

[ .11 6i

As with the . sp request, the actual length can be specified in several ways inches are probably the most intuitive unless you live in one of the very few
places in the world where they don't use inches.
The maximum line-length provided by the typesetter is 7.5 inches, by the way.
To use the full width, you have to reset the default physical left margin ('pageoffset'), which is nonnally slightly less than one inch from the left edge of the
paper. This is done by the . po (page offset) request discussed above.

( .po 0
sets the offset as far to the left as it will go.

Note that the line-length includes indent space but not page-offset space. The
line-length minus the indent is the basis for centering with the . ce request. The
effect of the .11 request 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 is available in
the . 1 number register. The length of three-part titles produced by a . t 1
request (see Chapter 7, Titles and Page Numbering) is independent of the linelength set by the . 11 request - the length of a three-part title is set by the . It
request.

Summary o/the .11 Request
Mnemonic:

line length

Form of Request:

.11±N

Initial Value:

6.5 inches

If No Argument:

Previous value

Explanation:

Set the line-length to N where N is the value of the line length, or an increment or decrement for the line-length. In t ro f f the maximum (linelength)+(page-offset) is about 7.54 inches.

Notes:

E, m (see Table A-2)

. in - Set Indent

Given that you've got your page-offset and line-length correctly set for a document to establish the position of the left and right margins, you now make all
other movements of the left margin via the . in (indent) request discussed here,
and via the . ti (temporary indent) request described below.
The . in (indent) request indents the left margin by some specified amount from
the page-offset. This means that all the following text will be indented by the
specified amount until you do something to change the indent. To get only the
first line of a paragraph indented, you don't use the . in request, but you use the

Revision ~ of 9 May 1988

Chapter 3 -

Page Layout

. t i (temporary indent) request described below.

As an example, a common text structure in books and magazines is the 'quotation' - a paragraph that is indented both on the right and the left of the line. A
quotation is used for precisely that purpose, namely to set some text off from the
rest of the copy. We can achieve such a paragraph by using the . in request to
move the left margin in, and the .11 request to move the right margin leftward:
.in +O.Si
.11 -O.Si
I was to learn later in life that we tend to meet any new
situation by reorganizing; and a wonderful method
it can be for creating the illusion of progress
while producing confusion, inefficiency, and demoralization .
. 11 +O.Si
.in -O.Si

When you fonnat the above construct you get a block that looks like this:
I was to learn later in life that we tend to meet any new situation

by reorganizing; and a wonderful method it can be for creating
the illusion of progress while producing confusion, inefficiency,
and demoralization. 2
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. The distinction is quite important: .11 +2.0 i makes lines two inches longer, whereas
. 11 2. 0 i makes them two inches long:
.11 2.0i
I was to learn later in life that we tend to meet any new
situation by reorganizing; and a wonderful method
it can be for creating the illusion of progress
while producing confusion, inefficiency, and demoralization.

I was to learn later in life that

we tend to meet any new situation by reorganizing; and a
wonderful method it can be for
creating the illusion of progress
while producing confusion,
inefficiency, and demoralization.
With . in, . 11, and . po, the previous value is used if no argument is specified.
So, in the above example, the lines:

2 Petronius Arbiter, A.D. 60.

Revision A, of 9 May 1988

Using nroff and troff

+O.5i

-O.Si

could have been

]
and would have had the same effect.
Note that the line-length includes indent space but not page-offset space. The
line-length minus the indent is the basis for centering with the . ce request. The
effect of the . in request 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 indent is available in the
. i number register.

Summary of the . in Request
Mnemonic:

indent

Form of Request:

.in±N

Initial Value:

If No Argument:

Previous value

Explanation:

Set the indent to ±N where N is the value of the indent, or an increment or
decrement on the current value of the indent. The . in request causes a
break.

Notes:

E, m (see Table A-2)

. t i-Temporarily Indent
One Line

The . t i (temporary indent) request indents the next text line by a specified
amount.
A common application for . t i is where the first line of a paragraph must be
indented just like the one you're reading now. You get such a construct with a
sequence like:
.ti 3
A common application for .

. .

and when the paragraph is formatted, the first line of the paragraph is
indented by three specified units just like this one. Three of what? The default
unit for the . t i request, as for most horizontally-oriented requests - . 11 (line
length), . in (indent), and . po (page offset) - is ems. An em is roughly the
Revision A, of 9 May 1988

Chapter 3 -

Page Layout

width of the letter 'm' in the current point size. Thus, an em is always proportional to the point size you are using. An em in size p is the number of p points
in the width of an 'm'. Here's an em followed by an em dash in several point
sizes to show why this is a proportional unit of measure. You wouldn't want a
20-point dash if you are printing the rest of a document in 12-point text. Here's
12-point text:

m
1-1
Here's 16-point text:

m
I-I
And here's 20-point text:

I~
Thus a temporary indent of . t i
of three m's width or Immmi.

3 in the current point size results in an indent

Although inches are usually clearer than ems to 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 for all dimensions. Ems can be specified as
scale factors directly, as in . ti 2. Sm.
Lines can also be indented negatively if the indent is already positive:
( .ti -O.3i

]

moves the next line back three tenths of an inch. A common text structure found
in documents is 'itemized lists' where the paragraphs are indented but are set off
by 'bullets' or some such. Item lists are often called 'hanging paragraphs'
because the first line with the item on it 'hangs' to the left. For example, you
could type the following series of lines like this (we've deliberately shortened the
length of the line to illustrate the effects):

+~t!!

Revision A, of 9 May 1988

Using nroff and troff

shorten lines for this example
.11 4.0i
.in +O.2i
indent left margin by afifth inch
.ta +O.2i
set a tab for the hanging indent
center a line of title
.ce
Indent Control Requests
· t i - 0 •2i
melle left margin back temporarily
\(bu tab the \fL\&.po\fp request sets the
page-offset to the desired amount thereby making
sure the left margin is correct.
· t i - 0 •2i
melle left margin back temporarily
\(bu tab the \fL\&.in\fp request sets the
indent from the left margin for all following text.
· t i - 0 •2i
melle left margin back temporarily
\(bu tab the \fL\&.ti\fP request sets the indent for
the following line of text only, thus providing for
fancy paragraph effects.

We had to play some tricks with tabs as well to get everything lined up, but that
won't affect the main point of the discussion. The tab markers in the lines above
show where there's a tab character, and the \ {bu sequence at the start of the
lines gets you a bullet ( • ) like that - we'll show the special character sequences
later in this manual. When you fonnat the text as shown in the example above,
you get this effect:
Indent Control Requests
• the. po request sets the page-offset to the desired amount
thereby making sure the left margin is correct.
• the. in request sets the indent from the left margin for all
following text.
• the. t i request sets the indent for the following line of text
only, thus providing for fancy paragraph effects.
Remember that the line-length includes indent space but not page-offset space.
The effect of a . ti request 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 indent is available
in the . i register.

Summary of the . ti Request
Mnemonic:

temporary indent

Form o/Request:

.ti±N

Initial Value:

1/ No Argument:

Ignored

Explanation:

Indent the next output text line a distance ±N with respect to the current
indent. The resulting total indent may not be negative. The current indent
is not changed. The . t i request causes a break.

Notes:

E, m (see Table A-2)

Revision A. of 9 May 1988

Chapter 3 -

3.2. Page Lengths, Page
Breaks, and
Conditional Page
Breaks

Page Layout

Neither nroff nor troff provide any facilities for top and bottom margins on
a page, nor for any kind of page numbering at all. The -ms macro package
described in a previous section of this manual sets things up so that reasonable
pagination with top and bottom margins and page numbers is done automatically.
If you want top and bottom margins when using raw troff or nroff, you have
to do some tricky stuff. The tricky stuff is done via traps and macros. The trap
tells troff or nroff when to do some processing for the margins (for exampIe, you might set a trap to start the bottom margin 0.75 inches from the bottom
of the page), and the macro defines what to do when the trap is sprung. It is conventional to set traps for them at vertical positions 0 (top) and -N (N from the
bottom).

A pseudo-page transition onto the first page occurs either when the first break
occurs or when the first 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 tables, references to the current diversion mean that the mechanism being described works during both ordinary and diverted output (the fonner
considered as the top diversion level). Refer to Chapter 10 for more infonnation
on diversions.
. pl -

Set Page Length

Just as the . po, .11, . in, and . ti requests changed the horizontal aspects of
the page, the . p 1 (page length) request detennines the physical length of the
page. In general you won't need to use the . pl request because the standard setting is right for all but the most esoteric purposes.

Summary of the . pi Request
Mnemonic:

page length

Form of Request:

.pl±N

Initial Value:

11 inches

If No Argument:

11 inches

Explanation:

Set page length 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 number register.

Notes:

v (see Table A-2)

. bp - Start a New Page

This request causes a break and skips to a new page.

Revision A, of9 May 1988

Using nroff and troff

Summary of the . bp Request
Mnemonic:

begin page

Form of Request:

.bp±N

Initial Value:

N=l

If No Argument:

Increment current page number by 1.

Explanation:

Eject the current page and start a new page. If ±N is given, the new page
number will be ±N. Also see the . ns (no space) request. The . bp request
causes a break.

Notes:

v (see Table A-2)

. pn -

Set Page Number

Summary of the . pn Request
Mnemonic:

page number

Form of Request:

.pn±N

Initial Value:

N=l

If No Argument:

Ignored

Explanation:

The next page (when it occurs) will have the page number ±N. A . pn
request must occur before the initial pseudo-page transition to affect the
page number of the first page. The current page number is in the % register.

. ne -

Specify Space Needed

In some applications you need to make sure that a few lines of text all appear

together on the same page. There are several ways to achieve this ranging from
simple to complicated. One of the simplest ways is to use the . ne (need) vertical space request:
.ne 3
some
lines
of
text
to
be
kept
on the
same page

specify we need at least three lines

The arrangement of the . ne request specifies that if there are many lines of text
in (say) a paragraph, at least three of the lines will appear together on the same
page, otherwise a new page will be started. The object of this exercise is to avoid
what typographers call 'orphans' - that is, the first line of a paragraph appearing
Revision A, of 9 May 1988

Chapter 3 - Page Layout

all alone and lonely on the bottom of a page, while the rest of the paragraph
appears on the next page. This is generally considered to be somewhat ugly and
should be avoided if possible. By itself, troff is too stupid to recognize the
existence of orphans (indeed of any text constructs at all), but the facilities are
there to avoid these situations. In general, macro packages such as the -ms
macro package discussed elsewhere have 'begin paragraph' macros such as . PP
which take care of controlling orphans.

Summary of the . ne Request
Mnemonic:

need

Form of Request:

.neN

Initial Value:

Not applicable

If No Argument:

Explanation:

Need N vertical space. If the distance, D, to the next trap position is less
than N, a forward vertical space of size D occurs, which will spring the trap.
If there are no remaining traps on the page, D is the distance to the bottom
of the page. If D < V, another line could still be output and spring the trap.
In a diversion, D is the distance to the diversion trap, if any, or is very large.

Notes:

v (see Table A-2)

3.3. Multi-Column Page
Layout by Marking
and Returning

It is possible to achieve multi-column output in trof f or nrof f via the . mk

(mark) and . rt (return) requests. Other useful special effects can also be
obtained using these requests, but one of the common uses is to do multi-column
output. Basically, the . mk request marks the current vertical position on the
page (you can place the result of the mark in a register). You do a column's
worth of output, then when you get to the end of the page, instead of starting the
next page, you return (via the . rt request) to the marked position, set up a new
indent and line-length, and crank out another column.

. mk - Mark Current
Vertical Position

Summary of the . mk Request
Mnemonic:

mark

Form of Request:

.mkR

Initial Value:

Not applicable

If No Argument:

R is an internal register

Explanation:

Mark the current vertical place in an internal register (both associated with
the current diversion level), or in register R, if given. See the . rt request.

Revision A, of9 May 1988

Using nroff and troff

. rt - Return to Marked
Vertical Position

Summary of the . rt Request
Mnemonic:

return

Form of Request:

.rt±N

Initial Value:

Not applicable

If No Argument:

return to place marked by a previous . mk request

Explanation:

Return upward only to a marked vertical place in the current diversion. If
±N (with respect to the current place) is given, the place is ±N from the top
of the page or diversion or, if N is absent, to a place marked by a previous
.mk. Note that the . sp request (refer to the chapter Line Spacing and
Character Sizes) may be used in all cases instead of . r t by spacing to the
absolute place stored in a explicit register; for example, using the sequence

.mkR . . . . sp - \nRu.

Revision A, of 9 May 1988

4
Line Spacing and Character Sizes
Line Spacing and Character Sizes ...................................................................................

4.1. . sp -

Space Vertically .............................................................................................

4.2. . p s -

Change the Size of the Type ...................................................................

4.3 . . vs -

Change Vertical Distance Between Lines .......................................

4.4. . 1 s -

Change Line Spacing ..................................................................................

4.5. \x Function -

Get Extra Line-Space ................................................................

4.6. . s v -

Save Block of Vertical Space .................................................................

4.7. . os -

Output Saved Vertical Space ..................................................................

4.8. . ns -

Set No Space Mode ......................................................................................

4.9. . rs -Restore Space Mode ....................................................................................

4.10. . S8

Set Size of Space Character ..................................................................

4.11. . C 8

Set Constant-Width Characters ..........................................................

4
Line Spacing and Character Sizes
4.1. . sp - Space
Vertically

You get extra vertical space with the . sp (space) request. A simple

)

( .sp

request with no argument gives you one extra blank line (one. VS, whatever that
has been set to). Typically, that's more or less than you want, so . sp can be followed by infonnation about how much space you want-

[_.SP_2i_ _ _ _ _ _ _J
means 'two inches of vertical space'.
( .sp 2p

means 'two points of vertical space'; and
( .sp 2

means 'two vertical spaces' - two of whatever . vs is set to (this can also be
made explicit with. sp 2v); troff also understands decimal fractions in most
places, so

( .sp 1.Si

is a space of 1.5 inches. These same scale factors can be used after the . vs
request to define line spacing, and in fact after most requests that deal with physical dimensions.
It should be noted that all size numbers are converted internally to 'machine
units', which are 1/432 inch 0/6 point). For most purposes, this is;enough resolution that you don't have to worry about the accuracy of the representation. The
situation is not quite so good vertically, where resolution is 1/144 inch (1/2
point).

Revision A, of9 May 1988

Using nroff and troff

Summary of the . sp Request
Mnemonic:

space

Form of Request:

.spN

Initial Value:

Not applicable

If No Argument:

N=lV

Explanation:

Space vertically in either direction. If N is negative, the motion is backward
(upward) and is limited to the distance to the top of the page. Forward
(downward) motion is truncated to the distance to the nearest trap. If the
no-space mode is on, no spacing occurs (see. ns, and . rs below).

Notes:

B, v (see Table A-2)

4.2. . ps - Change the
Size of the Type

In t ro f f, you can change the physical size of the characters that are printed on
the page. The . ps (point size) request sets the point size. One point is In2
inch, so 6-point characters are at most l/12-inch high, and 36-point characters are
l/2-inch. troff and the machine it was originally designed for understand 15
point sizes, listed below.

6 point: Pu:k my box with fiw: dozen liquor jugs.

7 point: Pack my box with five dazen liquor jugs.

8 point: Pack my box with five dozen liquor jugs.

9 point: Pack my box with five dozen liquor jugs.

10 point: Pack my box with five dozen liquor jugs.

11 point: Pack my box with five dozen liquor jugs.
12 point: Pack my box with five dozen liquor jugs.

14 point: Pack my box with five dozen liquor jugs.

16 point: Pack my box with five dozen liquor jugs.

18 point: Pack my box with five dozen liquor jugs.

20 point: Pack my box with five dozen liquor jugs.

22 point: Pack my box with five dozen liquor jugs.

24 point: Pack my box with five dozen liquor jugs.

28 point: Pack my box with five dozen liquor

36 point: Pack my box with five doz
If the nUIIlber after a . ps request is not one of these legal sizes, it is rounded up
to the next valid value, with a maximum of 36. If no number follows . ps,
troff reverts to the previous size, whatever it was. troff begins with point
size 10, which is usually fine. This document is in II-point.

Revision A, of 9 May 1988

Chapter 4 -

Line Spacing and Character Sizes

The point size can also be changed in the middle of a line or even a word with an
in-line size change sequence. In general, text which is in ALL CAPITALS in the
middle of a sentence tends to 100m large over the rest of the text and so it is customary to drop the point size of the capitals so that it looks like ALL CAPITALS
instead. You use the \8 (for size) sequence to state what the point size should
be. You can state the size explicitly as in this line here:

]

(The \s8POWER\sO of a \s8SUN\sO

to produce the output line like:
The POWER of a SUN
As above, \ s should be followed by a legal point size, except that \ 8 0 makes
the size revert to its previous value (before you just changed it).
Note that because there are a fixed number of point sizes that the system knows
about, the sequence \ s 96 gets you a nine-point 6 instead of 96;:POint type like you
wanted, whereas the sequence \ s 18 0 gets you an 18-point U instead of 180point type.
Stating the point size in absolute tenns as above is not always a good idea what you really want is for the changed size to be relative to the surrounding text,
so that if your document is in II-point type like this one, you'd really like the
bigger (or smaller stuff) to be a couple of points different without your having to
know explicitly what the actual size is. So in this case, you can use a relative
size-change sequence of the fonn \ 8+ n to raise the point size, and \ s- n to
lower the point size. The number n is restricted to a single digit. So we can
rework our previous example from above like this:

]

( The \s-2POWER\s+2 of a \s-2SUN\s+2

to produce the output line like:

[~T_h_e___p_O_~_R

___O_f___
a___
SU_N____________________________________________________________

Relative size changes have the advantage that the size difference is independent
of the starting size of the document. Of course this stuff only works really well
(in typography terms) when the changes in size aren't too violently out of whack
with the point size - a change of two points in 36-point type doesn't have quite
the same impact as it does for 12-point type - there is a question of the weight
of the type, but by the time you get to that stuff you'll be much more knowledgeable about typography.
The current size is available in the . s number register. nroff ignores type size
control.

Revision A. of 9 May 1988

Using nroff and troff

Summary of the . p s Request
Mnemonic:

point size

Form o/Request:

.ps±N

Initial Value:

10 points

If No Argument:

Previous value

Explanation:

Set point-size to ±N. Alternatively embed \ sN or \ s±N. Any positive size
value may be requested; if invalid, the next larger valid size will result, with
a maximum of 36. The sequence
.ps +N
.ps N

works the same as
.ps +N
.ps -N

because the previous requested value is also remembered. Ignored in
nroff.

Notes:

4.3. . vs - Change
Vertical Distance
Between Lines

E (see Table A-2)

The other parameter that detennines what the type looks like is the spacing
between lines, which is set independently of the point size. Vertical spacing is
measured from the bottom of one line to the bottom of the next. The bottom of
the text on a line is often called the baseline. The vertical spacing is often called
leading (pronounced 'led-ing') and comes from the days when text was produced
with lead slugs instead of electronic widgets like laser printers.
You control vertical spacing with the . vs (vertical spacing) request. For running 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 II-point type
with a vertical line-spacing of 13 points between baselines. Typographers call
this'll on 13', so when you hear some one say that a book is set in 'lIon 13',
you know that it's II-point type with 13-point vertical spacing.
So, somewhere at the start of this document, the macro package that formats this
document for us had requests like:

[

.ps IIp
.vs 13p

]

'------------

Had we set the point size and the vertical spacing like this:

[

.ps IIp
.vs IIp

]

'-----------Revision A, of 9 May 1988

Chapter 4 -

Line Spacing and Character Sizes

the running text would look like this. After a few lines, you will agree it looks a
little cramped. The right vertical spacing is partly a matter of taste, depending on
how much text you want to squeeze into a given space, and partly a matter of
traditional printing style. By default, troff uses 10 on 12.
Point size and vertical spacing make a substantial difference in the amount
of text per square inch. This is 12 on 14.
Point size and wrtic:al SJ*:ing IJlIIkc a substaDtial. difference in the amount oftcxt per rquam inch. For example, 10 on 12 USCII about twice as much
space as 7 on 8. This is 6 00 7, which is even smaller. It packs a lot IDOIC words per line, but you can go blind trying to n:ad it.

When used without arguments, both . ps and . vs revert to the previous size and
vertical spacing respectively.
The vertical spacing (V) between the base-lines of successive output lines can be
set using the . vs request with a resolution of 1/144 inch = 1/2 point in troff,
and to the output device resolution in nr 0 f f. V must be large enough to accommodate the character sizes on the affected output lines. For the common type
sizes (9-12 points), usual typesetting practice is to set V to 2 points greater than
the point size; troff default is 10-point type on a 12-point spacing. This document is set in II-point type with a 13-point vertical spacing. The current V is
available in the . v number register.

Summary of the . vs Request
Mnemonic:

vertical spacing

Form of Request:

.vsN

Initial Value:

1/6 inch in nroff, 12 points in troff.

If No Argument:

Previous value

Exp lanation:

Set vertical base-line spacing size V. Transient extra vertical space available with \x'N ' (see section on \x Function).

Notes:

E, p (see Table A-2)

4.4. . 1 s - Change Line
Spacing

Multiple- V line separation (for instance, double spacing) can be requested with
the . 1 s (line spacing) request.

Revision A, of 9 May 1988

Using nroff and troff

Summary of the .ls Request
Mnemonic:

line spacing

Form of Request:

.1sN

Initial Value:

N=l

If No Argument:

Previous value

Explanation:

Set line spacing to ±N. N-l Vs (blank lines) are appended to each output
text line. Appended blank lines are omitted, if the text or previous appended
blank line reached a trap position.

Notes:

E (see Table A-2)

4.5. \ x Function - Get
Extra Line-Space

If a word contains a vertically tall construct requiring the output line containing it
to have extra vertical space before and/or after it, the extra-line-space function
\ x'N ' can be embedded in or attached to that word. In this and other functions
having a pair of delimiters around their parameter (here '), the delimiter choice
is arbitrary, except that it can't look like the continuation of a number expression
for N. If N is negative, the output line containing the word will be preceded by N
extra vertical space; if N is positive, the output line containing the word will be
followed by N extra vertical space. If successive requests for extra space apply
to the same line, the maximum values are used. The most recently used post-line
extra line-space is available in the . a register.

4.6. . sv - Save Block of
Vertical Space

A block of vertical space is ordinarily requested using the . sp (space) request,
which honors the no-space mode and which does not space past a trap. A contiguous block of vertical space may be reserved using the . sv request (see
below).

Summary of the . sv Request
Mnemonic:

save space

Form of Request:

.svN

Initial Value:

Not applicable

If No Argument:

N=lV

Explanation:

Save a contiguous vertical block of size N. If the distance 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 the . as request). Subsequent. sv
requests will overwrite any still-remembered N.

Notes:

v (see Table A-2)

Revision At of 9 May 1988

Chapter 4 -

Line Spacing and Character Sizes

4.7. . os - Output Saved
Vertical Space

Summary of the . as Request
Mnemonic:

output saved space

Form of Request:

.os

Initial Value:

Not applicable

If No Argument:

Output saved vertical space

Explanation:

Output saved vertical space. No-space mode has no effect. Used to finally
output a block of vertical space requested by an earlier . s v request.

4.8. . ns - Set No Space
Mode

Summary of the . ns Request
Mnemonic:

no-space mode

Form of Request:

.ns

Initial Value:

Not applicable

If No Argument:

Tum on no-space mode

Explanation:

Tum on no-space mode - When on, the no-space mode inhibits . sp
requests and . bp requests without a next page number. The no-space mode
is turned off when a line of output occurs, or with . r s.

Notes:

D (see Table A-2)

4.9. . rs - Restore Space
Mode

Summary of the . r s Request
Mnemonic:

restore space mode

Form of Request:

.rs

Initial Value:

Not applicable

If No Argument:

Tum off no-space mode

Explanation:

Restore spacing - tum off no-space mode.

Notes:

D (see Table A-2)

Revision A, of 9 May 1988

Using nroff and troff

4.10. . 88 - Set Size of
Space Character

Summary of the . ss Request
Mnemonic:

space-character size

Form of Request:

.ssN

Initial Value:

12/36 em

If No Argument:

Ignored

Explanation:

Set space-character size to N/36 ems. This size is the minimum word spacing in adjusted text. Ignored in nroff.

Notes:

E (see Table A-2)

4.11. . C8 - Set ConstantWidth Characters

Summary of the . cs Request
Mnemonic:

constant spacing

Form of Request:

.csFNM

Initial Value:

Off

If No Argument:

Ignored

Explanation:

Constant character space (width) mode is set on for font F (if mounted); the
width of every character is taken as N/36 ems. If M is absent, the em is that
of the character's point size; if M is given, the em is M-points. All affected
characters are centered in this space, including those with an actual width
larger than this space. Special Font characters occurring while the current
font is F are also so treated. If N is absent, the mode is turned off. The
mode must be still or again in effect when the characters are physically
printed. Ignored in nroff.

Notes:

P (see Table A-2)

Revision A, of9 May 1988

5
Fonts and Special Characters

Fonts and Special Characters ..............................................................................................

5.1. . f t -

Set Font ...............................................................................................................

5.2 . . fp -

Set Font Position ............................................................................................

5.3 . . fz -Force Font Size ...............................................................................................

5.4. . bd - Artificial Boldface .........................................................................................

5.5. Character Set ......................................................................................................................

5.6. Fonts ........................................................................................................................................

5.7. . 1 g -

Control Ligatures ...........................................................................................

5
Fonts and Special Characters
trof f and the typesetter allow four different fonts at anyone time. Nonnally
three fonts (Times Roman, italic and bold) and one collection of special charac-

ters are pennanently mounted.
abcdefghijklmnopqrstuvwxyz 0123456789
ABCDEFGIDJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz 0123456789
ABCDEFGHIJKLMNOPQRSTUVWXYZ

abcdefghijklmnopqrstuvwxyz 0123456789
ABCDEFGIllJKLMNOPQRSTUVWXYZ

The Greek, mathematical symbols, and miscellany of the special font are listed in
Appendix B, Font and Character Examples.
troff prints in Roman unless told otherwise. To switch into bold, use the . ft
(font) request:

(.ft

and for italics,

(.ft

To return to Roman, use. f t R; to return to the previous font, whatever it was,
use either. f t P or just. ft.

Revision A. of9 May 1988

Using nroff and troff

5.1 • . f t -

Set Font

Summary of the . ft Request
Mnemonic:

font

Form of Request:

.ftF

Initial Value:

Roman

If No Argument:

Previous Font

Explanation:

Change font to F. Alternatively, embed \ fF. The font name P is reserved
to mean the previous font.

Notes:

E (see Table A-2)
The 'underline' request

]

( .ul

makes the next input line print in italics. . ul can be followed by a count to indicate that more than one line is to be italicized. Refer to Chapter 2 for a more
detailed description of the . ul request.
Fonts can also be changed within a line or word with the in-line request \f:

boldface text
is produced by the input

]

( \fBbold\flface\fR text

If you want to do this so the previous font, whatever it was, is left undisturbed,
insert extra in-line \fP commands, like this:

]

( \fBbold\fP\flface\fP\fR text\fP

Because only the immediately previous font is remembered, you have to restore
the previous font after each change or you lose it. The same is true of . p s and
. vs when used without an argument.
There are other fonts available besides the standard set, although you can still use
only four at any given time. The . fp (font position) request tells troff what
fonts are physically mounted on the typesetter:

]

( . fp 3 H

says that the Helvetica font is mounted on position 3. Appropriate . fp requests
should appear at the beginning of your document if you do not use the standard
fonts.

Revision A, of 9 May 1988

Chapter 5 -

Fonts and Special Characters

It is possible to make a document relatively independent of the actual fonts used
to print it by using font numbers instead of names; for example, \ f 3 and . f t 3
mean 'whatever font is mounted at position 3' , and thus work for any setting.
Nonnal settings are Roman font (R) on font position 1, italic
on position 2,
bold (B) on position 3, and special (S) on position 4 - the mnemonic 'R I B S'
might help you remember.

5.2. . fp - Set Font
Position

Summary of the . fp Request
Mnemonic:

font position

Form of Request:

.fpNF

Initial Value:

R,I,B,S

If No Argument:

Ignored

Explanation:

Font position - this is a statement that a font named F is mounted on position N (1-4). It is a fatal error if F is not known. The phototypesetter has
four fonts physically mounted. Each font consists of a film strip that can be
mounted on a numbered quadrant of a wheel. The default mounting
sequence assumed by traff is R, I, B, and S on positions 1,2,3 and 4.
Any . fp request specifying a font on some position must precede . f z
requests relating to that position.

5.3. . f z - Force Font Size

Summary of the . fz Request
Mnemonic:

font size

Form of Request:

. fz SF N

Initial Value:

None

If No Argument:

None

Explanation:

Forces font F or S for special characters to be in size N. A . f z 3 -2
causes implicit\S-2 every time font 3 is entered, and a matching\s+2 when
left. Same for special font characters that are used during F. Use S to handle special characters during F. . f z 3 -3 or . f z S 3 -0 causes
automatic reduction of font 3 by 3 points while special characters are not
affected. Any. fp request specifying a font on some position must precede
. f z requests relating to that position.
There is also a way to get 'synthetic' bold fonts by overstriking letters with a
slight offset. Look at the . bd request.

Revision A, of 9 May 1988

Using nroff and troff

5.4. . bd - Artificial
Boldface

Summary of the . bd Request
Mnemonic:

bold

Form of Request:

.bdFN

Initial Value:

Off

If No Argument:

No Emboldening

Explanation:

Artificially embolden characters in font F by printing each one twice,
separated by N-l basic units. A reasonable value for N is 3 when the character size is in the vicinity of 10 points. If N is missing the embolden mode
is turned off. The mode must be still or again in effect when the characters
are physically printed. Ignored in nroff.

Form of Request:

.bd SF N

Explanation:

Embolden characters in the special font whenever the current font is F. The
mode must be still or again in effect when the characters are physically
printed.

Notes:

P (see Table A-2)
Special characters have four-character names beginning with \ (, and they may
be inserted anywhere. For example,

Ih+ Ih= 3h
is produced by
(_\_(_1_4__
+__
\_(1_2__=__\_(_3_4__________________________________

In particular, Greek letters are all of the form \ (* x, where x represents an upper-

or lower-case Roman letter reminiscent of the Greek. Thus to get

in raw t ro f f we have to type
[ \(*S(\(*a\(mu\(*b)

\(-> \(if

]

That line is unscrambled as follows:

Revision A. of 9 May 1988

Chapter 5 - Fonts and Special Characters

Escape
Sequence

Character
Printed

\(*8

1:
(

Upper-case Sigma or Sum

\(*a

\ (mu

\(*b

x
J3

lower-case alpha
multiplication sign or signum
lower-case beta

)

(

\(->

\(if

Description

tends toward
infinity

A complete list of these special names occurs in Appendix B, Font and Character Examples.
In eqn, explained in the chapter "Fonnatting Mathematics with eqn" in Format-

ting Documents, you can achieve the same effect with the input
(

SIGMA ( alpha times beta ) -> inf

]

- - - - - -

,---,

which is less concise (31 keystrokes instead of 27!), but clearer to the uninitiated.
Notice that each four-character name is a single character as far as troff is concerned. For example, the translate request
(

.tr \ (mi\(em

]

--------

" ' - - - -

is perfectly clear, meaning
[ . tr - -

that is, to translate - (minus sign) into -

J
(em-dash).

Some characters are automatically translated into others: grave" and acute '
accents (apostrophes) become open and close single quotes' '; the combination
of" ... " is generally preferable to the double quotes" ... ". Similarly a typed
minus sign becomes a hyphen -. To print an explicit - sign, use \ -. To get a
backslash printed, use \ e.

5.5. Character Set

The troff character set consists of the Graphics Systems Commercial II character set plus a Special Mathematical Font character set - each having 102 characters. These character sets are shown in Appendix B, Font and Character
Examples. All ASCII characters are included, with some on the Special Font.
With three exceptions, the ASCII characters are input as themselves, and nonASCII characters are input in the fonn \ (.xx where .xx is a two-character name
also explained in Appendix B. The three ASCII exceptions are mapped as follows:

Revision A, of9 May 1988

Using nroff and troff

Table 5-1

Exceptions to the Standard ASCII Character Mapping
ASCII Input
Name
Character
,

..
-

acute accent
grave accent
minus

Printed by trof f
Character
Name

,
,

close quote
open quote
hyphen

The characters " ' , and - may be input by \ " \ ' , and \ - respectively or by
their names found in Appendix B. The ASCII characters @, :fI:, n, " ' , <, >, \, {,
}, -, ,. , and _ exist only on the Special Font and are printed as -a one-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 constructed by overstriking or other combination, and
those that can reasonably be mapped into other printable characters. The exact
behavior is determined by a driving table prepared for each device. The characters " ' , and _ print as themselves.

5.6. Fonts

The default mounted fonts are Times Roman (R), Times Italic (I), Times Bold
(B), and the Special Mathematical Font (S) on physical typesetter positions 1,2,
3, and 4 respectively. These fonts and others are used in this document. The
current font, initially Roman, may be changed (among the mounted fonts) by use
of the . f t request, or by embedding at any desired point either \fx, \ f (xx, or
\ fN where x and xx are the name of a mounted font and N is a 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. trof f can be infonned that any particular font is mounted by use of
the . fp request The list oflrnown fonts is installation-dependent. In the subsequent discussion of font-related requests, F represents either a one- or twocharacter font name or the numerical font position, 1 through 4. The current font
is available (as numerical position) in the read-only number register. f.
nroff understands font control and nonnally underlines italic characters.

5.7. . lg - Control
Ligatures

A ligature is a special way of joining two characters together as one. Way back
in the days before Gutenberg, scribes would have a variety of special fonns to
choose from to make lines come out all the same length on a manuscript. Some
of these forms are still with us today.
Five ligatures are available in the current troff character set - fi, fI, ff, ffi, and
ffl. They may be input (even in nroff) by \ (fi, \ (fl, \ (ff, \ (Fi, and
\ (Fl respectively.
The ligature mode is normally on in troff, and automatically invokes ligatures
during input.

Revision A, of 9 May 1988

Chapter 5 -

Fonts and Special Characters

If you want other ligatures like the cc, re, IE, andCE ligatures, you have to make
them up yourself- troff doesn't know about them. See Chapter 12 the section on "Arbitrary Horizontal Motion" (the \h function) for some examples on
constructing these ligatures.

Summary of the .lg Request
Mnemonic:

ligature

Form of Request:

.1gN

Initial Value:

Offin nroff, on in troff.

If No Argument:

Explanation:

Tum Ligature mode on if N is absent or non-zero. Turn ligature mode off if
N=O. If N=2, only the two-character ligatures are automatically invoked.
Ligature mode is inhibited for request, macro, string, register, or file names,
and in copy mode. No effect in nroff.

Revision A, of 9 May 1988

6
Tabs, Leaders, and Fields

Tabs, Leaders, and Fields .......................................................................................................

Set Tabs ...............................................................................................................

Setting Relative Tab Stops ......................................................................................

Right-Adjusted Tab Stops ........................................................................................

Centered Tab Stops ......................................................................................................

.t c -

Change Tab Replacement Character ...............................................

Summary of Tabs ..........................................................................................................

6.2. Leaders - Repeated Runs of Characters ..........................................................

Change the Leader Character ...............................................................

Set Field Characters .....................................................................................

6.1. . ta -

ole -

6.3. . f c -

6
Tabs, Leaders, and Fields
There are several ways to get stuff lined up in columns, and to achieve other
effects such as horizontal motion and repeated strings of characters. The three
related topics we discuss in this section are tabs, leaders, and fields .

tabs

behave just like the tab stops on a typewriter.

leaders

are for generating repeated strings of characters.

fields

are a general mechanism for helping to line stuff up into
columns.

This part of the document concentrates on the 'easy' parts, so to speak. Later
sections of this document contain discussions on the facilities for drawing lines
and for producing arbitrary motions on the page.

6.1. . t a - Set Tabs

Tabs (the ASCII horizontal tab character) can be used to produce output in
columns, or to set the horizontal position of output. Typically tabs are used only
in unfilled text. Tab stops are set by default every half inch from the current
indent (in troff) and every 0.8 inch from the current indent (in nroff), but
can be changed by the . ta (tab) request. In the example below, we set tab stops
every one-and-a-half inches and set some text in columns based on those tab
stops. We place a line of exclamation marks ( !) above and below the text to
show where the tabs stops are in the output page:
. t a l . 5 i 3. 0 i 4. 5 i 6. 0 i
set tabs
I tab ! tab I tab ! tab !
show where tabs are with! character
word-one tab word-two tab word-three tab word-four tab word-five
I tab ! tab I tab I tab I

When we format the above example, we get this output:

!
word-one

!
word-two

!
word-four

word-three

!
word-five

Revision A, of 9 May 1988

Using nroff and troff

Setting Relative Tab Stops

The tab stops set in the example above are in tenns of absolute position on the
line. You could also set tabs relative to previous tabs stops by preceding the tab
stop number with a + sign, and get exactly the same result:
.ta 1.Si +l.Si +l.Si +l.Si
set tabs
!tab!tab!tab!tab!
show where tabs are with! character
word-one tab word-two tab word-three tab word-four tab word-five
! tab ! tab ! tab ! tab !

Right-Adjusted Tab Stops

In the standard case as shown in the above examples, the tab stops are left-

adjusted (as on a typewriter). You can also make the tab stops right-adjusting for
doing things like lining up columns of numbers. When you right-adjust a tab
stop, the action of placing a tab before the field places the material behind the tab
stop on the output line. Here's an example of some input with both alphabetic
and numeric items:
.nf
.ta 2.0iR
July tab 5
August tab 9
September tab 15
October tab 60
November tab 85
December tab 126
.fi

Notice the . ta request - it has the letter R on the end to indicate that this is a
right-adjusted tab. When we fonnat that table, we get this result:
July
August
September
October
November
December

5
9
15
60

85
126

Notice how the numbers in the second column line up.
Centered Tab Stops

Finally you can make a centered tab stop, so that things get centered between the
tabs. We can use the centering tabs to put a title on our table from above:

Revision A, of 9 May 1988

Chapter 6 -

Tabs, Leaders, and Fields

.nf
.ta 2.0iC
Month tab Shipments
.ta 2.0iR
July tab 5
August tab 9
September tab 15
October tab 60
November tab 85
December tab 126
.fi

and when we fonnat this table now, we get this result:
Month
July
August
September
October
November
December

Shipments

5
9
15
60

85
126

Notice that the column headings are centered over the data in the table.
If you have a complex table, instead of using troff or nroff directly, use the
tbl program described in the chapter "Fonnatting Tables with tbl" in Formatting Documents. A good example of where tbl does more work for you is when
numerically-aligned items have decimal points in them - it is really hard to do
this using the raw troff or nroff capabilities.

. tc - Change Tab
Replacement Character

A tab inserts blank spaces between the item that came before and after it. You
can change this by filling up tabbed-over space with some other character. Set
the 'tab replacement character' with the . t c (tab character) request:

.ta 2.5i 4.5i
.tc

[~~_a_m_e__t_ab__
A_g_e_m_b____________________________________________~

This produces
Name _ _ _ _ _ _ _ _ _ _ _ _ Age
There is a more general mechanism for drawing lines, described in the sections
uDrawing Vertical Lines" and "Drawing Horizontal Lines" in the chapter "Arbitrary Motions and Drawing Lines and Characters."
To reset the tab replacement character to a space, use the . t c request with no
argument. Lines can also be drawn with the in-line \ 1 command, described in
the chapter "Arbitrary Motions and Drawing Lines and Characters."

Revision At of 9 May 1988

Using nroff and troff

Summary of the . tc Request
Mnemonic:

tab character

Form of Request:

.tc c

Initial Value:

space

If No Argument:

Removed

Explanation:

The tab repetition character becomes c, or is removed, specifying motion.

Notes:

E (see Table A-2)

Summary of Tabs

The table below is a summary of the types of tab stops. There are three types of
internal tab stops -left-adjusting, right-adjusting, and centering. In the following table:

Table 6-1

is the distance from the current position on the input line
(where a tab was found) to the next tab stop.

next-string

consists of the input characters following the tab up to the next
tab or end of line.

is the width of next-string.

Types of Tab Stops
Tab
letter

Tab
type

Length of motion or
repeated characters

Location of
next-string

blank

Left
Right
Centered

D-W

FollowingD
Right adjusted within D
Centered on right end of D

R
C

D-W/2

Revision A, of 9 May 1988

Chapter 6 - Tabs, Leaders, and Fields

Summary of the . ta Request
Mnemonic:

tab

Form of Request:

.taNt ...

Initial Value:

0.8 inches in nroff, 0.5 inches in troff.

If No Argument:

Ignored

Explanation:

Set tab stops and types - N is the tab stop value and t is the type. t ro f f
tab stops are preset every 0.5 inches; nroff tab stops are preset every 0.8
inches. t=R means right-adjusting tabs, t=C means centering tabs, and if t is
absent, the tabs are left-adjusting tab stops. Stop values in the list of tab
stops are separated by spaces, and a value preceded by + is treated as an
increment to the previous stop value.

Notes:

E, m (see Table A-2)

6.2. Leaders - Repeated
Runs of Characters

Leaders are repeated runs of the same character between tab stops. Leaders are
most often used to hang two separated pieces of text together. A common application is in tables of contents. If you look at the contents for this manual you
will see that the chapter and section titles (on the left of the line) are separated
from the page number (on the right end of the line) by a row of dots. In fact here
is a short example to illustrate what the leaders look like:

Contents

2.0 Blunt Uses of Clubs ................................................................. .
2.1 Social Clubs ........................................................................... .
2.2 Arthritic Clubs ....................................................................... .
2.3 Golf Clubs .............................................................................. .
2.4 Two-by-Four Clubs

13
16
18
25
29

The dots are called leaders, because they 'lead' your eye from one thing to the
other. It is not nearly so easy to read stuff like that if the leaders aren't there:

Contents

2.0 Blunt Uses of Clubs
2.1 Social Clubs
2.2 Arthritic Clubs
2.3 Golf Clubs
2.4 Two-by-Four Clubs

13
16
18
25
29

The leader character is normally a period, but it can in fact be any character you
like - some people prefer dots and some people prefer a solid line:

Revision A, of9 May 1988

Using nroff and troff

Contents
2.0 Blunt Uses of Clubs _ _ _ _ _ _ _ _ _ _ _ _ __
2.1 Social Clubs
2.2 Arthritic Clubs
2.3 Golf Clubs
2.4 Two-by-Four Clubs

13
16
18
25
29

A leader is very similar to a tab, but you get the" repeated characters by typing an
in-line \ a sequence instead of a tab or a \ t sequence. The \ a sequence is a
control-A character or an ASCn SOH (start of heading) character and is hereafter
known as the leader character for the purposes of this discussion. When the
leader character is encountered in text it generates a string of repeated characters.
The length of the repeated string of characters is governed by internal tab stops
specified just as for ordinary tabs as discussed in the section on tabs above. The
major difference between tabs and leaders is that tabs generate motion and
leaders generate a string o/periods. Let's look at a fragment of the text that generated the examples above:
.DS
.ta 5.0i-SnR S.OiR
2.0 Blunt Uses of Clubs \a\t13"
2.1 Social Clubs \a\t16"
2.2 Arthritic Clubs \a\t18"
2.3 Golf Clubs \a\t2S"
2.4 Two-by-Four Clubs \a\t29"
.DE

What we're trying to get here are lines of text with the section numbers and the
titles, followed by a string of leader characters, followed by some space and then
the page number at the right-hand end of the line. Tables of contents tend to look
better with shorter line lengths, so we set our first tab to five inches minus five
en-spaces to leave a gap at the end of the leader. The second tab is set to a rightadjusting tab at five inches. Each line of the table now contains the text to appear
on the left end, followed by a couple of spaces, followed by the \ a sequence to
indicated the leader, followed by the \ t sequence to indicate the tab, and finally
followed by the page number. The result of fonnatting all that stuff is:
2.0 Blunt Uses of Clubs ..................................................................
2.1 Social Clubs ............. ........... ............. ........... ............. ........... ....
2.2 Arthritic Clubs ......... ........................ ........................ ........... ....
2.3 Golf Clubs ...............................................................................
2.4 Two-by-Four Clubs ............ ................................................ ....

~~ sun
.,.

microsystems

13
16
18
25
29

Revision A, of 9 May 1988

Chapter 6 - Tabs, Leaders, and Fields

. Ie - Change the Leader
Character

Just as you could use the . te request to change the character that gets generated
with tabs, you can use the . I e (leader character) request to specify the character
that is generated by a leader. The standard leader character is the period. We can
show this by taking our last fragment and placing a Ie request before it to
change the leader character to an underline:
0

oDS

set leader character
.lc
. ta 50 Oi-5nR 5. OiR
set tabs
2.0 Blunt Uses of Clubs \a\t13"
2.1 Social Clubs \a\t16"
2.2 Arthritic Clubs \a\t18"
2.3 Golf Clubs \a\t25"
2.4 Two-by-Four Clubs \a\t29"
.DE

Then when we fonnat the thing, it looks like this:

13
16
18

2.0 Blunt Uses of Clubs
2.1 Social Clubs
2.2 Arthritic Clubs
2.3 Golf Clubs
2.4 Two-by-Four Clubs

25
29

Whereas the length of generated motion for a tab can be negative, the length of a
repeated character string cannot be. Repeated character strings contain an integer
number of characters, and any residual distance is added before the leaders as
space. Tabs or leaders found after the last tab stop are ignored, but may be used
as next-string tenninators.
Tabs and leaders are not intetpreted in copy mode. \ t and \ a always generate a
non-intetpreted tab and leader respectively, and are equivalent to actual tabs and
leaders in copy mode.

Summary of the ole Request
Mnemonic:

leader character

Form of Request:

.le

Initial Value:
If No Argument:

Removed - successive \ as act like tabs

Explanation:

The leader repetition character becomes c, or is removed. Successive leader
requests (\as) act like tabs.

Notes:

E (see Table A-2)

Revision A, of9 May 1988

Using nroff and troff

6.3. . f c - Set Field
Characters

A field is a more general mechanism for laying out material between tab stops.
Hardly anyone ever needs to use fields, but the tbl preprocessor uses them for
placing tabular material on the page. This section is a very short discussion on
how to use fields. In general, when you want to layout tabular material you
should use tbl to do the job for you. Fields are a way of reducing the number of
tab stops you have to set, and also have troff or nroff do some automatic
worlc in parceling out padding space for you.
A field lives between the current position on the input line and the next tab stop.
The start and end of the field are indicated by a field delimiter character. troff
or nroff places the field on the line and pads out any excess space with spaces.
You indicate where the padding actually goes by placing padding indicator characters at various places in the field. You set the field delimiter character and the
padding indicator character with the . fc (field characters) request. In the
absence of any other infonnation, troff or nroff has the field mechanism
turned off entirely. The . f c request looks like:
( .fc dp

]

where d is the field delimiter character and p is the padding indicator character.
If you do not specify any character for a padding indicator, the space character is
the default. However, this means that you could not have spaces within the field,
so you nonnally specify the padding indicator as something other than a space.
So let's start with a very simple example of a single field and see what we get.
Here is the input:
. t a 3. 0 i
. fc # @

! tab !
#string of characters#
! tab
.fc

set a single tab at three inches
setfield cklimiter character to # and
set padding indicator character to @
the ! characters show where tabs are
the ! characters show where tabs are

and here is the output after formatting:
!
string of characters
!

This is not very exciting - the characters in the field are simply left-adjusted in
the field, and the rest of the field up to the tab stop are padded with spaces. You
would get exactly the same result if you placed the padding indicator character at
the right end of the field to indicate that you wanted the padding on the right:

Revision A. of 9 May 1988

Chapter 6 - Tabs, Leaders, and Fields

.ta 3.0i
.fc # @
! tab !
#string of characters@#

set a single tab at three inches
setfield delimiter character to #
set padding indicator character to @
the ! characters show where tabs are
the ! characters show where tabs are

! tab

.fc

As you can see, the result is identical to the one just above:

!
string of characters
!
But now we can place a padding indicator character at the left end of the field
and get strings right-adjusted in the field:
.ta 3.0i
.fc # @

set a single tab at three inches
set field delimiter character to #
set padding indicator character as @
the! characters show where tabs are

! tab !
#@string of characters#
#@another string of characters#
! tab
the ! characters show where tabs are
.fc

We used two strings of different length here to show how they are right-adjusted
against the tab stop:

!
string of characters
another string of characters

!
You can see how the spaces were placed on the left end of the field because that
is we where we placed the padding indicator character, and the strings got
adjusted right to the tab stop.
Then we can get fields centered by placing the padding indicator character at
both ends of the string:
.ta 3.0i
.fc # @
! tab

set a single tab at three inches
setfield delimiter character to #
set padding indicator character as @
the ! characters show where tabs are

#@string of characters@#
#@longer string of characters@#
! tab
the ! characters show where tabs are
.fc

Again we used two strings of different lengths to show the effect of centering the
field:

Revision A, of 9 May 1988

Using nroff and troff

string of characters
longer string of characters

In general, a field or a sub-field between a pair of padding indicator characters is
centered in its space on the line.
Things get even more useful when you have multiple sub-fields in a field - the
padding spaces are then parceled out so that the sub-fields are unifonnly leftadjusted, right-adjusted, or centered between the current position and the next tab
stop:
.ta S.Oi
.fc #: @

set a single tab at five inches
set field delimiter character to #
set padding indicator character as @
use the ! characters to show where tabs are

! tab !
#:string of characters#
#:string of characters@another string#
! tab !
use the ! characters to show where tabs are

and here is the output after we fonnat that:

!
string of characters
string of characters

another string

And finally we can show three strings within a field, with the left part leftadjusted, the center part centered, and the right part right-adjusted:
.ta S.Oi
.fc # @
! tab !
#left string@center string@right string#
#longer left string@longer center string@longer right string#
! tab !

and here is the output after we fonnat that:

!
left string
longer left string

center string
longer center string

right string
longer right string

!
So to summarize, a field is contained between a pair of field delimiter characters.
A field consists of sub-fields 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-fields and
the field length is incorporated as horizontal padding space that is divided among
the indicated padding places. The incorporated padding can be negative.

Revision A, of 9 May 1988

Chapter 6 - Tabs. Leaders, and Fields

Summary of the . fc Request
Mnemonic:

field character

Form oj Request:

.fcJ p

Initial Value:

Field mechanism is off

If No Argument:

Field mechanism is turned off.

Explanation:

Set the field delimiter to f, set the padding indicator to p (if specified) or to
the space character if p is not specified. In the absence of arguments, the
field mechanism is turned off.

Revision A. of 9 May 1988

7
Titles and Page Numbering

Titles and Page Numbering ..................................................................................................

7.1. Titles in Page Headers ..................................................................................................

7.2. Fonts and Point Sizes in Titles .................................................................................

7.3. . pc - Page Number Character .............................................................................

7.4. . t 1 Request - Three Parameters ........................................................................

7
Titles and Page Numbering
7.1. Titles in Page Headers

This is an area where things get tougher, because troff doesn't do any of this
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

center top

right top

There was a very early text formatter called roff, where you could say
.he 'left top'center top' right top'
.fo 'left bottom'center bottom'right bottom'

to get headers and footers automatically on every page. Alas, this doesn't work
in troff, which is a serious hardship for the novice. Instead you have to do a
lot of specification:
o

You have to say what the actual title is (reasonably easy . t 1 request to specify the title).

you just use the

You have to specify when to print the title (also reasonably easy trap to call a macro that actually does the work),

and finally you have to say what to do at and around the title line (this is the
hard part).

you set a

Taking these three things in reverse order, first we define a . NP macro (for new
page) to process titles and the like at the end of one page and the beginning of the
next:
.de
'bp
'sp
.tl
'sp

NP
O.5i
'left top'center top'right top'
O.3i

To make sure we're at the top of a page, we issue a 'begin page' request 'bp,
which skips to top-of-page (we'll explain the' shortly). Then we space down
half an inch (with the ' sp O. 5 i request), and print the title (the use of . t 1

Revision A. of 9 May 1988

Using nroff and troff

should be self explanatory -later we will discuss the title parameters), space
another 0.3 inches (with the' sp O. 3i request), and we're done.
To ask for . NP at the bottom of each page, we have to 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' request. wh:

(~.W_h_-l_iN_P_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~)
See Chapter 10 for a more detailed description of the . wh request. No dot (.) is
used before NP in the when request because in this case, we're specifying the
name of a macro, not calling a macro. The minus sign means measure up from
the bottom of the page, so '-1 i' means one inch from the bottom.
The . wh request appears in the input outside the definition of . NP; typically the
input would be
.de NP
definition of the NP macro

.wh -li NP

Now what happens? As text is actually being output, traff keeps track of its
vertical position on the page. After a line is printed within one inch from the bottom, the . NP macro is activated. In the jargon, the . wh request sets a trap at the
specified place, which is 'sprung' when that point is passed. . NP skips to the top
of the next page (that's what the 'bp was for), then prints the title with the
appropriate margins.
Why 'bp and ' sp instead of . bp and . sp? The answer is that. bp and . sp,
like several other requests, break the current line - 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 . bp or . spin the
. NP macro, a break would occur in the middle of the current output line when a
new page is started. The effect would be to print the left-over part of that line at
the top of the page, followed by the next input line on a new output line, something like this:
last line but one at almost the bottom of the page
last line at the bottom of the

title on the bottom of the page

page break

Revision A, of 9 May 1988

Chapter 7 - Titles and Page Numbering

title on the top of the next page

page.

This is not what we want. Using' instead of. for a request tells troff that no
break is to take place - the output line currently being filled should not be
forced out before the space or new page.
The list of requests that break lines is short and natural:
Table 7-1

Requests that Cause a Line Break
Command
· bp

· br

· ce
·f i
·nf

·sp
· in

·t i

Explanation
Begin a new page
Break the current output line
Center line(s)
Start filling text lines
Stop filling text lines
Space vertically
Indent the left margin
Temporary indent the left margin for the next line only

No other requests break lines, regardless of whether you use a . or a '. If you
really do need a break, add a . br (break) request at the appropriate place.

7.2. Fonts and Point Sizes
in Titles

One other thing to beware of - if you're changing fonts or point sizes a lot, you
may find that if you cross a page boundary in an unexpected font or size, your
titles come out in that size and font instead of what you intended. Furthennore,
the length of a title is independent of the current line length, so titles will come
out at the default length of 6.5 inches unless you change it, which is done with
the .1 t (length of title) request.

Summary of the . 1 t Request
Mnemonic:

length of title

Form of Request:

.It ±N

Initial Value:

6.5 inches

If No Argument:

Previous value

Explanation:

Set length of title to ±N. The line-length and the title-length are independent. Indents do not apply to titles; page-offsets do.

Notes:

E, m (see Table A-2)
There are several ways to fix the problems of point sizes and fonts in titles. For

Revision A, of 9 May 1988

Using nroff and troff

the simplest applications, we can define the . NP macro to set the proper size and
font for the title, then restore the previous values, like this:
.de
'bp
'sp
. ft
.ps
.It
.tl
.ps
.ft
'sp

NP
O.Si
R

\" set title font to Roman
10
\" and size to 10 point
6i
\" and length to 6 inches
, left' center' right'
\" revert to previous size
P
\" and to previous font
0.3i

This version of . NP does not work if the fields in the . t 1 request contain size or
font changes. What we would like to do in cases like this is remember the status
of certain aspects of the environment, change them to meet our needs for the time
being, and then restore them after we're done with the special stuff. This requirement is satisfied by troff's environment mechanism discussed in Chapter 17,
Environments.
To get a footer at the bottom of a page, you can modify . NP so it does some processing before the 'bp request, or split the job so that there is a separate footer
macro invoked at the bottom margin and a header macro invoked at the top of the
page.
Output 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 . tIline at the position
where you want the number to appear. For example
[ .tl

]

% _u

centers the page number inside hyphens.

7.3. . pc - Page Number
Character

You can change the page number character with the . pc request.

Summary of the . pc Request
Mnemonic:

page-number character

Form of Request:

.pe c

Initial Value:

If No Argument:

Off

Explanation:

Set the page-number character to c, or remove it if there is no c argument.
The page-number register remains %.

Revision A, of 9 May 1988

Chapter 7 - Titles and Page Numbering

You can set the page number at any time with either. bp n, which immediately
starts a new page numbered n, or with . pn n, which sets the page number for the
next page but doesn't skip to the new page. Again, . bp +n sets the page number
to n more than its current value; . bp means . bp + 1.

7.4. . t 1 Request - Three
Parameters

The . t 1 (title) request automatically places three text fields at the left, center,
and right of a line (with a title-length specifiable via the . It (length of title)
request. The most common use for three-part titles is to put running headers and
footers at the top and bottom of pages just like those in this manual. In fact, the
. t l request may be used anywhere, and is independent of the nonnal text collecting process. For example, we just placed a three-part title right here in the
text:

-85-

Hunting the Snark

Smiles and Soap

by typing the a three-part title request that looks like:
.tl 'Hunting the Snark'- % -'Smiles and Soap'

and you might notice that the page number in the formatted example is the same
as the page number for this page.

Summary of the . t l Request
Mnemonic:

title

Form of Request:

. t 1 ' left' center' right'

Initial Value:

Nothing

If No Argument:

Nothing

Explanation:

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

Revision A, of9 May 1988

8
t ro f f Input and Output

traff Input and Output ........................................................................................................

8.1. . so -

Read Text from a File .................................................................................

8.2. . nx - Read Next Source File ................................................................................

8.3. Pipe Output to a Specified Program (nraff only) .....................................

8.4 . . rd - Read from the Standard Input ................................................................

8.5. . ex -

Exit from nraff or traff ...................................................................

8.6. . trn -

Send Messages to the Standard Error File ......................................

8
traff

Input and Output

We now describe two troff requests that we omitted earlier, because their usefulness is more apparent when you understand the troff command line. Normally troff takes its input from the files given when it is called up. However
there are ways in which the formatter can be made to take part of its input from
elsewhere, using t r 0 f f requests embedded in the document text.

8.1. . SO - Read Text
from a File

The . so request, which tells troff to switch over and take its source from the
named file. For example, suppose you have a set of macros that you have
defined, and you have them in a file called macros. We can call them up from
the troff command line:
hostname% troff macros document
hostname%

as we showed earlier, but it's a bit of a nuisance having to do this all the time.
Also, if only some of our documents use the macros, and others don't, it can be
difficult to remember which is which. An alternative is to make the first line of
the document file look like this:

(~_.s_o_m_a_c_r_o_s______________________________________________~]
Now we can format the document by:

hostname% troff document
[ hostname%

" " ' - - - - - - - - - - - - " ' "

The first thing troff sees in the file document is the request. so macros
which tells it to read input from the file called macros. When it finishes taking
input from macros, troff continues to read the original file document.
Another way of using the . so request lets you format a complete document, held
in several files, by only giving one filename to the troff command. Let us
create a file called document containing:

Revision A, of 9 May 1988

Using nroff and troff

.so
.so
.so
.so

macros
section.l
section.2
section.3
and so on through the document until . ..
. so appendix.C

We can now format it with the traff command line:
hostname% troff document I 1pr
hostname%

This is a lot easier than typing all the filenames each time you format the document, and a lot less prone to error.
This technique is especially useful if your filenames reflect the contents of the
various sections, rather than the order in which they appear. For instance, look at
this file which describes a whole book (something like the one you are reading):
hostname% cat book
.so bookmacros
.so preface
.so intro
.so login
\"Getting Started on the UNIX System
.so directs
\"Directories and the File System
.so stdio
\"Commands, Processes, and Standard Files

\"Bibliography
.so biblio
hostname%

It is obviously much easier to fonnat the whole thing with a traff command
line like this:
hostname% troff book I 1pr
hostname%

than it would be if you had to supply all the filenames in the right order. Notice
that we used the comment feature of traff to tie chapter titles to filenames.

Revision A, of 9 May 1988

Chapter 8 -

troff Input and Output

Summary of the . so Request
Mnemonic:

source

Form of Request:

· so filename

Exp lanation:

Switch source file - the top input (file reading) level is switched to
filename. The sourced-in file is read directly and processed immediately
when the . so line is encountered. When the new file ends, input is again
taken from the original file. . s os may be nested.

8.2. . nx - Read Next
Source File

Summary of the . nx Request
Mnemonic:

Form of Request:

· nxfilename

If No Argument:

end-of-file

Explanation:

Next file isfilename. The current file is considered ended, and the input is
immediately switched to filename. There is no return to the file containing
the . nx command.

8.3. Pipe Output to a
Specified Program

A couple of examples of programs you might want you pipe your nroff output
to are lpr and col. Your source line might look like this:

(nro f f only)

(.Pi /usr/ucb/lpr

or
( .pi /usr/bin/col

if you had formatted tables in your source file.

Summary of the . pi Request
Mnemonic:

pipe

Form of Request:

· pi program_name

Explanation:

Pipe output to program (nro f f only). This request must occur before any
printing occurs. No arguments are transmitted to program.

Revision A, of 9 May 1988

Using nroff and troff

8.4. . rd - Read from the
Standard Input

Another troff request that switches input from the file you specify is the . rd
(read) request. The standard input can be the user's keyboard, a pipe, or a file.
The . rd request reads an insertion from the standard input. When troff
encounters the . r d request, it prompts for input by sounding the tenninal bell or
flashing the screen. A visible prompt can be given by adding an argument to
. rd, as we show in the example below.
Everything typed up to a blank line (two newline characters in a row) is inserted
into the text being formatted at that point. This can be used to 'personalize' form
letters. If you have an input file with this text:
.po 10
.nf
.in 20
14th February
.in 0
Dear
.rd who
will you be my Valentine?
If you will, give me a sign
(I like roses, I like wine) .

then when you format it, you will be prompted for input:
hostname% troff valentine I Ipr
who:Peter
hostname%

After typing the name Peter you have to press the RETURN key twice, since
troff needs a blank line to end input. The result offonnatting that file is:
14th February

Dear
Peter
will you be my Valentine?
If you will, give me a sign
(I like roses, I like wine) .

To get another copy of this for Bill, you just run the t ro f f command again:
hostname% troff valentine I Ipr
who:Bill
hostname%

and again for Joe, and for Manuel, and Louis, and Alphonse, and ...

Revision A. of 9 May 1988

Chapter 8 -

troff Input and Output

Since traff takes input from the tenninal up to a blank line, you are not limited
to a single word, or even a single line of input. You can use this method to insert
addresses or anything else into form letters.

Summary of the . rd Request
Mnemonic:

read

Form of Request:

.rdprompt

Initial Value:

Not applicable

If No Argument:

prompt=BEL

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 tenninal. . rd behaves like a macro, and arguments
may be placed after prompt. Use the standard way to access arguments in
macros (see Chapter 10.
If insertions are to be taken from the tenninal keyboard while output is being
printed on the terminal, the command line option -q will tum 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 (see the previous
section); the process would ultimately be ended by a . ex in the insertion file.
Example:
Letter File
Dear
.rd

Names File
John
blank line
Bill
blank line
.ex

.nx Letter

To put everything together, you could use:
( hostname% cat Names I troff Letter

Revision A, of 9 May 1988

Using nroff and troff

8.5. . ex nroff

Exit from
or troff

Summary of the . ex Request
Mnemonic:

exit

Form of Request:

. ex prompt

Explanation:

Exit from nro f f or t ro f f. Text processing is terminated exactly as if all
input had ended.

8.6. . tm - Send Messages
to the Standard Error
File

The . tm (terminal message) request displays a message on the standard error
file. The request looks like:
( .tm tell me some good news

]

and when troff or nroff encounters this in the input file, it displays the string

(~t_e_l_l__m_e__s_o_m_e__g_O_O_d__n_e_w_s__________________________________~]
on the standard error file. This request has been used in older versions of the
-ms macro package to rebuke the user when (for instance) an abstract for a paper
was longer than a page. Other macro packages use the . tm request for assisting

in generating tables of contents and indices and such supplementary material.

Summary of the . tm Request
Mnemonic:

terminal message

Form of Request:

. tmstring

Initial Value:

Not applicable

If No Argument:

Display a newline

Explanation:

After skipping initial blanks, string (rest of the line) is read in copy mode
and written on the user's terminal.

Revision A. of 9 May 1988

9
Strings
Strings ...................................................................................................................................................

9.1 . . ds -

Define Strings ..................................................................................................

9.2. . as -

Append to a String ........................................................................................

9.3. Removing or Renaming String Definitions ......................................................

101

9
Strings
Obviously if a paper contains a large number of occurrences of an acute accent
over a letter 'e' , typing \ 0 " e \ ,,, for each e would be a great nuisance. (See
Chapter 12 for more detailed infonnation on drawing lines and characters.
Fortunately, troff provides a way that you can store an arbitrary collection of
text in a string, and thereafter use the string name as a shorthand for its contents.
Strings are one of several t ro f f mechanisms whose judicious use lets you type
a document with less effort and organize it so that extensive fonnat changes can
be made with few editing changes. A reference to a string is replaced in the text
by the string definition.
A string is a named sequence of characters, not including a newline character,
that may be interpolated by name at any point in your text. Note that names of
trof f requests, names of macros, and names of strings all share the same name
list. String names may be one or two characters long and may usurp previouslydefined request, macro, or string names.
You create a string (and give it an initial value) with the . ds (define string)
request. You can later add more characters to the end of the string by using the
. as (append to string) request.
String names may be either one or two characters long. You get the value of a
string placed in the text, where it is said to be interpolated, by using the notation:
(_____
'*X _ _ _ _ _- - - - - " )

for a one-character string named x, and the more complicated notation:

]

( \* (xx

for a two-character string named xx.
String references and macro invocations may be nested.

Revision A. of 9 May 1988

Using nroff and troff

9.1. . ds -

Define Strings

You create a string (and define its initial value) with the . ds (define string)
request The line
( .ds e \o"e\'"

defines the string e to have the value \ a " e \ ,,,
You refer to them with the sequence \ * x for one-character names or \ * ( xy for
two-character names. Thus, to get telephone, given the definition of the string e
as above, we can say t\*el\*ephone.
As another live example, in the section on ligatures in Chapter 5 , Fonts and Special Characters, we noted that traff doesn't know about the Scandinavian
ligatures - you have to decide for yourself how to define them. Here are our
definitions of the strings for those ligatures:
.ds
.ds
.ds
.ds

ae
Ae
oe
Oe

a\h'-(\w'a'u*4/10)'e
A\h'-(\w'A'u*4/10)'E
o\h'-(\w'o'u*4/10)'e
O\h'-(\w'O'u*4/10)'E

See the section entitled "\ h Function - Arbitrary Horizontal Motion" in
Chapter 12 for a discussion on what the \ h constructs are doing in the string
definitions above. Having defined the strings, all you have to do is type the
string references like this:
. . . the Scandinavian ligatures \*(oe, \*(ae, \*(Oe, and \*(Ae . . .

in order to get ... the Scandinavian ligatures re, 3!,
stream of text.

(E,

and IE ... into your

If a string must begin with spaces, define it as
( .ds xx "

text

The double quote character signals the beginning of the definition. There is no
trailing quote - the end of the line tenninates the string.
A string may actually be several lines long; iftraff encounters a \ at the end
of any line, the backslash and the newline characters are disregarded resulting in
the next line being added to the current one. So you can make a long string simply by ending each line except the last with a backslash:
.ds xx this \
is a very \
long string

Strings may be defined in tetms of other strings, or even in tenns of themselves.

Revision A. of 9 May 1988

Chapter 9 -

Strings

Summary of the . ds Request
Mnemonic:

define string

Form of Request:

. ds xx string

Initial Value:

Not applicable

IJ No Argument:

Ignored

Exp lanation:

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

9.2. . as - Append to a
String

The . as (append to string) request adds characters to the end of a string. You
use the . a s request like this:

]

( . as xx string-of-characters

where string-oJ-characters is appended to the end of whatever is already in the
string xx.
Note that the string mentioned in a . a s request is created if it didn't already
exist, so in that respect an initial. as request acts just like a . ds request.
For example, here's a short fragment from the . H macro that was used to generate the section numbers in this document. The . H macro is called up like

[~_.H__le_ve_l_-n_u_mV__er__"_Te_x_t_of_t_h_e_n_·d_e_"________________________________~]
where level-number is 1, 2, 3, ... to indicate that this is a first, second,
third, ... level heading. The . H macro keeps track of the various section
numbers via a bunch of number registers HI through H5, and they are tested for
and appended to the SN string if appropriate. For example:

Revision A, of9 May 1988

100

Using nroff and troff

. ds
.if
.if
.if
.if

SN \\n(Rl .
\\n(NS>l .as
\\n(NS>2 .as
\\n(NS>3 .as
\\n(NS>4 .as

SN
SN
SN
SN

\\n(R2.
\\n(R3.
\\n(R4.
\\n(RS.

set the initial section number string
append H2 if needed
append H3 if needed
append H4 if needed
append H5 if needed

more processing to compute indentations and such . ..

\\*(SN\\ \\ \t\c
\&\\$2

Now output the text

and yet more processing . ..

Let's unscramble that mess. The essential parts are the initial line that says:
.ds SN \\n(Rl.

set the initial section number string

which sets the SN (section number) string to the value of the HI number register
that counts chapter level numbers. Then the following four lines essentially all
perform a test that says:
. if the level-number is greater than N, append the next higher section counter to the string. That is, if the current section number is
greater than 2, we append the value of the level 3 counter, then if the
section number is greater than 3, we append the value of the level 4
counter, and so on.

Finally, the built-up SN string, followed by the text of the title, gets placed into
the output text with the lines that read:
\\*(SN\\ \\ \t\c
\&\\$2

Now output the text

And in fact we can use the mechanisms that exist to play games like that because
we are using a macro package to format this document, and those number registers are available to us. So we can define a string like this:
( .ds

\n(H!.

and interpolate that string like this:

(_\_*_(X_X__________________________________________

to get the value
Revision A, of 9 May 1988

Chapter 9 -

Strings

101

9.
printed in the text. Now we can append the rest of the section counters to that XX
string like this (without caring whether they have any values):
( .as

\n(H2.\n(H3.\n(H4.\n(HS.

and then when we interpolate that string we get this:
9.2.0.0.0.
which, if you look, should be the section number of the stuff you are now reading.

Summary of the . as Request
Mnemonic:

append to string

Form of Request:

. as xx string

Initial Value:

Not applicable

If No Argument:

Ignored

Explanation:

Append string to string xx (append version of . ds). The string xx is created
if it didn't already exist

9.3. Removing or
Renaming String
Definitions

Strings (just like macros) can be renamed with the . rn (rename) request, or can
be removed from the namelist with the . rm (remove) request. Refer to Chapter
10 for more detailed descriptions of the . rn and . rm commands.

Revision A, of 9 May 1988

10
Macros, Diversions, and Traps

Macros, Diversions, and Traps ........................................................................................... 105

10.1. Macros .................................................................................................................................

105

· de -

Define a Macro .............................................................................................

105

· rm -

Remove Requests, Macros, or Strings ............................................

107

· rn -

Rename Requests, Macros or Strings ..............................................

108

Macros With Arguments ..........................................................................................

108

Append to a Macro ....................................................................................

112

Copy Mode Input Interpretation ...........................................................................

112

10.2. Using Diversions to Store Text for Later Processing ...............................

112

· di -

Divert Text .....................................................................................................

113

· da -

Append to a Diversion .............................................................................

114

10.3. Using Traps to Process Text at Specific Places on a Page ....................

114

· wh -

Set Page or Position Traps .....................................................................

115

· ch -

Change Position of a Page Trap .........................................................

116

· dt -

Set a Diversion Trap .................................................................................

116

· it -

Set an Input-Line Count Trap ..............................................................

116

• ern -

Set the End of Processing Trap ...........................................................

117

· am -

10
Macros, Diversions, and Traps
10.1. Macros

Before we can go much further in nr 0 f f or t rof f, we need to learn something
about the macro facility. In its simplest form, a macro is just shorthand notation
similar to a string. A macro is a collection of several separate troff commands
which, when bundled together, achieves (sometimes complex) fonnatting when
the macro is invoked. Whereas a string is somewhat limited because its
definition is specific, a macro can interpret arguments that can change its
behavior from one invocation to the next.
A macro is a named set of arbitrary lines that may be invoked by name or with a
trap. Macros are created by . de and . di requests, and appended to by . am and
· da requests; . di and . da requests cause nonnal output to be stored in a
macro. A macro is invoked in the same way as a request; a control line beginning
· xx interpolates the contents of macro xx. The remainder of the line may contain
up to nine arguments. Request, macro, and string names share the same name
list. Macro names may be one or two characters long and may usurp previouslydefined request, macro, or string names. String references and macro invocations
may be nested. Any of these entities may be renamed with a . rn request or
removed with a . rm request.

. de -

Define a Macro

Suppose we want every paragraph to start in exactly the same way - with a
space and a temporary indent of two ems. We show a (very simplified) version
of the . PP (paragraph) macro from the -ms macro package:
.sp
]
[~.t_i+_2m_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~

Then to save typing, we would like to collapse these into one shorthand line, a
troff 'request' like
( .PP

that would be treated by t ro f f exactly as if you had typed:

]

[ .sp
.ti +2m

· PP is called a macro. The way we tell troff what. PP means is to define it
105

Revision A, of 9 May 1988

106

Using nroff and troff

with the . de (define) request:
.de PP
.sp
.ti +2m

The first line names the macro (we used. pp) which is a standard macro notation
for 'paragraph'. It is common practice to use upper-case names for macros so
that their names don't conflict with ordinary traff requests. The last line. .
marks the end of the definition. In between the beginning and end of the
definition, is the text (often called the replacement text), which is simply
inserted whenever troff sees the request or macro call
( .PP

The definition of . PP has to precede its first use; undefined macros are simply
ignored. Names are restricted to one or two characters.
Using macros for commonly-occurring sequences of requests is critically important. Not only does it save typing, but it makes later changes much easier. Suppose we decide that the paragraph indent should be greater, the vertical space
should be less, and the font should be Roman. Instead of changing the whole
document, we need only change the definition of the . PP macro to something
like
.de PP \" paragraph macro
.sp 2p
.ti +3m
.ft R

and the change takes effect everywhere we used . PP .
The notation \ " is an in-line t r a f f function that means that the rest of the line
is to be ignored. We use it here to add comments to the macro definition (a wise
idea once definitions get complicated).

Revision A, of 9 May 1988

Chapter 10 - Macros, Diversions, and Traps

107

Summary of the . de Request
Mnemonic:

define

Form of Request:

. de xxyy

Initial Value:

Not applicable

If No Argument:

.yy= . .

Explanation:

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
tenninated by a line beginning with . yy, whereupon the macro yy is called.
In the absence ofyy, the definition is tenninated by a line beginning with
'. .'. A macro may contain . de requests provided the tenninating macros
differ or the contained definition tenninator is concealed. '. .' can be concealed as \ \. . which will copy as \. . and be reread as '. .' .

. rm -

Remove Requests,

Macros, or Strings

Summary of the . rm Request
Mnemonic:

remove

Form of Request:

.rmxx

Initial Value:

Not applicable

If No Argument:

Ignored

Explanation:

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.

Revision A, of 9 May 1988

108

Using nroff and traff

. rn - Rename Requests,
Macros or Strings

Summary of the . rn Request
Mnemonic:

rename

Form of Request:

. rn xxyy

Initial Value:

Not applicable

If No Argument:

Ignored

Explanation:

Rename request, macro, or string xx to yy. Ifyy exists, it is removed first.
Refer to Chapter 9, Strings for information on defining strings.
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 paper:
.de BS \" start indented block
.sp
.nf
.in +O.3i
.de BE \" end indented block
.sp
.fi
.in -O.3i

Now we can surround text like
Copy to:
JobnDoe
Richard Roberts
Stanley Smith
by the requests. BS and . BE, and it will come out as it did above. Notice that
we indented by an incremental amount: . in +0. 3i instead of . in o. 3i.
This way we can nest our uses of . BS and . BE to get blocks within blocks.
If later on we decide that the indent should be half an inch, then it is only necessary to change the definitions of . BS and . BE, not the whole paper.

Macros With Arguments

The next step is to define macros that can change from one use to the next
according to parameters supplied as arguments to the macro. To make this work,
we need two things: first, when we define 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 called we have to provide actual arguments to be plugged into
the definition.

Revision A, of 9 May 1988

Chapter 10 - Macros, Diversions, and Traps

109

When a macro is invoked by name, the remainder of the line can contain up to
nine arguments. The argument separator is the space character, and arguments
may be surrounded by double-quotes to pennit embedded space characters. Pairs
of double-quotes may be embedded 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 the arguments on the next line.
When a macro is invoked the input level is pushed down and any arguments
available at the previous level become unavailable until the macro is completely
read and the previous level is restored. A macro's own arguments can be interpolated at any point within the macro with \ $N, which interpolates the Nth argument (l~~9). If an invoked argument doesn't exist, a null string results. For
example, the macro xx may be defined by
.de xx
\"begin definition
Today is \\$1 the \\$2.
\"end definition

and called by
( .XX

Monday 14th

to produce the text
( Today is Monday the 14th.

Note that the \$ was concealed in the definition with a preceding backslash (\).
The number of currently available arguments is in the . $ register.
No arguments are available at the top (non-macro) level in this implementation.
Because string referencing is implemented as an input-level push-down, no arguments are available from within a string. No arguments are available within a
trap-invoked macro.
Arguments are copied in copy mode onto a stack where they are available for
reference. The mechanism does not allow an argument to contain a direct reference to a long string (interpolated at copy time) and it is advisable to conceal
string references (with an extra \) to delay interpolation until argument reference
time.
Let's illustrate by defining a macro. SM that will print its argument two point
sizes smaller than the surrounding text. That is, the macro call
( .SM UNIX

will produce UNIX.
The definition of . SM is

Revision A, of9 May 1988

110

Using nroff and troff

[_~_~_~2_~_~_$_1\_S_+_2

____________________________________

Within a macro definition, the symbol \ \ $n refers to the nth 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 pennits
optional second and third arguments that will be printed in the nonnal size:
.de SM
~~$3\S-2\\$1\S+2\\$2

[

Arguments not provided when the macro is called are treated as empty, so
( .SM

UNIX

)

]

produces
UNIX),

while

.
UNIX
_______________
J
)

[ .SM

produces
(UNIX).

It is convenient to reverse the order of arguments because trailing punctuation is
much more common than leading.

The following macro. ED is the one used to make the 'bold Roman' we have
been using for troff request names in text. It combines horizontal motions,
width computations, and argument rearrangement.
.de BD

\&\\$3\fl\\$1\h'-\w'\\$1'u+lu'\\$1\fP\\$2

The \ h and \ w commands need no extra backslash, as we discuss in the section
Copy Mode Input Interpretation. The \ & is there in case the argument begins
with a period.
Two backslashes are needed with the \ \ $ n commands, though, to protect one of
them when the macro is being defined. Perhaps a second example will make this
clearer. Consider a macro called. SH which produces section headings like the
ones in this manual, with the sections numbered automatically, and the title in

Revision A, of 9 May 1988

Chapter 10 - Macros, Diversions, and Traps

111

bold in a smaller size. The use is
(.SH

)

"Section title ... n

If the argument to a macro is to contain spaces, then it must be surrounded by
double quotes, unlike a string, where only the leading quote is permitted.

Here is the definition of the . SH macro:
.nr SH 0 \" initialize section number
.de SH
.sp O.3i
.ft B
.nr SH \\n(SH+l\" increment number
.ps \\n(PS-l \" decrease PS
\ \n (SH.
\ \$1 \" number. title
.ps \\n(PS
\" restore PS
.sp O.3i
.ft R

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 name as a
macro without conflict but a string may not.
We used \ \n (SH instead of \n (SH and \ \n (PS instead of \n (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 called. If that's what you want, fine, but that isn't
the case here. Similarly, by using \ \n (PS, we get the point size at the time the
macro is called.
As an example that does not involve numbers, recall our . NP macro which had:
( .tl 'left'center'right'

We could make these into parameters by using instead

)

( .tl '\\*(LT'\\*(CT'\\*(RT'

so the title comes from three strings called LT, CT and RT for left title, center
title, and right title, respectively. If these are empty, then the title will be a blank
line. Normally CT would be set with something like
(___
.dS _CT_%
--_ _ _ _ _ _ _)

to give just the page number between hyphens, but a user could supply private
definitions for any of the strings.

Revision A, of 9 May 1988

112

Using nroff and troff

. am - Append to a Macro

Summary of the . am Request
Mnemonic:

append to macro

Form of Request:

.amxxyy

Initial Value:

Not applicable

If No Argument:

.yy=.

Explanation:

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

Copy Mode Input
Interpretation

•

During 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:
o

The contents of number registers indicated by \ n are interpolated.

Strings indicated by \ * are interpolated.

Arguments indicated by \ $ are interpolated.

Concealed newlines preceded by backslash (\ newline) are eliminated.

Comments indicated by \

\ t and \a are interpreted as ASCII horizontal tab and SOH respectively (see
Chapter 6, Tabs, Leaders, and Fields for more information).

\ \ is interpreted as \

\ . is interpreted as " • "

are eliminated.

These interpretations can be suppressed by adding another \ (backslash) to the
beginning of the command. For example, since \ \ maps into a \, \ \ n will copy
as \ n which will be interpreted as a number register indicator when the macro or
string is reread.

10.2. Using Diversions to
Store Text for Later
Processing

There are numerous occasions in page layout when it is necessary to store some
text for a period of time without actually printing it. Footnotes are the most
obvious example: the text of the footnote usually appears in the input well
before the place on the page where it is to be printed is reached. In fact, the place
where it is output normally depends on how big it is, which implies that there
must be a way to process the footnote at least enough to decide its size without
printing it.
traff provides a mechanism called a diversion for doing this processing. A

diversion is very similar to a macro and in fact uses the same mechanisms as the
macro facility. Any part of the output may be sent into a diversion instead of
being printed, and then at some convenient time the diversion may be brought
back into the input.

Revision A. of9 May 1988

Chapter 10 - Macros, Diversions, and Traps

. di -

Divert Text

113

The request . di .xy begins a diversion - all subsequent output is collected into
the diversion called xy until a . di request with no argument is encountered,
which tenninates the diversion. The processed text is available at any time
thereafter, simply by giving the request:

('---oxy_ _ _ _ _ _J
The vertical size of the last finished diversion is contained in the built-in number
register dn.
As a simple example, suppose we want to implement a 'keep-release' operation,
so that text between the requests . 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 \" start keep
.br
\" start fresh line
.ev 1
\" collect in new environment
.fi
\" make it filled text
.di XX \" collect in XX
.de KE \" end keep
.br
\" get last partial line
.di
\" end diversion
.if \ \n (dn>=\ \n (.t .bp
\" bp if doesn't fit
.nf
\" bring it back in no-fill
.xx
\" text
.ev
\" return to normal environment

Recall that number register n 1 is the current 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 to the next trap, which we assume is at the bottom margin of the page. If
the diversion is large enough to go past the trap, the . if is satisfied, and a . bp
is issued. In either case, the diverted output is then brought back with It . xx.
trof f will do no further processing 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
full generality. This section is not intended to teach everything about diversions,
but to sketch out enough that you can read existing macro packages with some
comprehension.
Processed output may be diverted into a macro for purposes such as footnote processing or determining the horizontal and vertical size of some text for conditional changing of pages or columns. A single diversion trap may be set at a
specified vertical position. The number registers dn and dl respectively contain
the vertical and horizontal size of the most recently ended diversion.
Revision A, of9 May 1988

114

Using nroff and troff

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
(. cs) or emboldened (. bd) text that is diverted can be reread correctly only if
these modes are again or still in effect at reread time. One way to do this is to
embed in the diversion the appropriate. cs or . bd requests with the 'transparent' mechanism described in the chapter Introduction to nroff and troff.
Diversions may be nested and certain parameters and registers are associated
with the current diversion level (the top non-diversion level may be thought of as
the Oth diversion level). These are the diversion trap and associated macro, nospace mode, lhe internally-saved marked place (see .rnk and . rt), the current
vertical place ( . d register), the current high-water text baseline (. h register), and
the current diversion name ( . z register).

Summary of the . di Request
Mnemonic:

divert

Form of Request:

.dixx

Initial Value:

Not applicable

If No Argument:

End of diversion

Explanation:

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

Notes:

D (see Table A-2)

. da -

Append to a Diversion

Summary of the . da Request
Mnemonic:

append to diversion

Form of Request:

.daxx

Initial Value:

Not applicable

If No Argument:

End of diversion

Explanation:

Append to diversion xx. This is the diversion equivalent of the . am (append
to macro) request.

10.3. Using Traps to
Process Text at
Specific Places on a
Page

Three types of trap mechanisms are available, namely page traps, diversion
traps, and input-line-count traps.
Macro-invocation traps may be planted using the . wh (when) request at any page
position including the top. This trap position may be changed using the . ch
(change) request. Trap positions at or below the bottom of the page have no
effect unless or until moved to within the page or rendered effective by an
Revision A, of 9 May 1988

Chapter 10 - Macros, Diversions, and Traps

115

increase in page length.
Two traps may be planted at the same position only by first planting them at different positions and then moving one of the traps; the first planted trap will conceal the second unless and until the first one is moved. If the first one is moved
back, it again conceals the second trap.
The macro associated with a page trap is automatically invoked when a line of
text is output whose vertical size reaches or 'sweeps past' the trap position.
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
the . dt (diversion trap) request. The . t register works in a diversion; if there is
no subsequent trap a large distance is returned. For a description of input-linecount traps, see the . it request below .
. wh - Set Page or Position
Traps

Summary of the . wh Request
Mnemonic:

when

Form of Request:

.whNxx

Initial Value:

Not applicable

If No Argument:

Not applicable

Explanation:

Install a trap to invoke xx at page position N; a negative N is interpreted
with respect to the page bottom. Any macro previously planted at N is
replaced by xx. A zero N refers to the top of a page. In the absence of xx,
the first-found trap at N, if any, is removed.

Notes:

v (see Table A-2)

+~t!!

Revision A, of 9 May 1988

116

Using nroff and troff

· ch - Change Position of a
Page Trap

Summary of the . ch Request
Mnemonic:

change trap

Form of Request:

.chxxN

Initial Value:

Not applicable

If No Argument:

Not applicable

Explanation:

Change the trap position for macro xx to be N. In the absence of N, the trap,
if any, is removed.

Notes:

v (see Table A-2)

· dt -

Set a Diversion Trap

Summary of the . dt Request
Mnemonic:

diversion trap

Form of Request:

.dtNxx

Initial Value:

Not applicable

If No Argument:

Tum off diversion trap

Explanation:

Install a diversion trap at position N in the current diversion to invoke macro
xx. Another . dt will redefine the diversion trap. If no arguments are
given, the diversion trap is removed.

Notes:

D, v (see Table A-2)

Set an Input-Line
Count Trap
· it -

Summary of the . it Request
Mnemonic:

input-line-count trap

Form of Request:

.it Nxx

Initial Value:

Not applicable

If No Argument:

Tum off trap

Explanation:

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 inline text or text interpolated by in-line or trap-invoked macros.

Notes:

E (see Table A-2)

Revision A, of9 May 1988

Chapter 10 - Macros, Diversions, and Traps

117

. em - Set the End of

Processing Trap

Summary of the . em Request
Mnemonic:

end macro

Form of Request:

. em xx

Initial Value:

Not applicable

If No Argument:

No trap installed

Exp lanation:

Call the macro xx 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.

+~,!!

Revision A, of 9 May 1988

11
Number Registers

Number Registers ......................................................................................................................... 121
11.1. . nr -

Set Number Registers ...............................................................................

121

11.2. Auto-Increment Number Registers .....................................................................

123

11.3. Arithmetic Expressions with Number Registers .........................................

124

11.4. . af -

Specify Format of Number Registers ..............................................

125

11.5. . rr -

Remove Number Registers ...................................................................

127

11
Number Registers
In a programmable text formatter such as troff, you need a facility for storing

numbers somewhere, retrieving the numbers, and for doing arithmetic on those
numbers. trof f meets this need by providing things called number registers.
Number registers give you the ability to define variables where you can place
numbers, retrieve the values of the variables, and do arithmetic on those values.
Number registers, like strings and macros, can be useful in setting up a document
so it is easy to change later. And of course number registers serve for any sort of
arithmetic computation.
Number registers, just like strings, have one- or two-character names. They are
set by the . nr (number register) request, and are referenced anywhere by \ n x
(one-character name) or \n ( .xy (two-character name). When you access a
number register so that its value appears in the printed text, the jargon says that
you have interpolated the value of the number register.
A variety of parameters are available to the user as predefined, named number
registers (see Appendix D). In addition, users may define their 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.
troff defines several pre-defined number registers listed in Appendix D.
Among them are % for the current page number, nl for the current vertical position on the page, dy, rna, and yr for the current day, month and year (see Table
D-l) for a complete list); and. s and . f for the current size and font - the font
is a number from 1 to 4. Any of these number registers can be used in computations like any other register, but some, like. s and . f, cannot be changed with a
. nr request because they are "read only" (see Table D-2) for a complete list).

11.1. . nr - Set Number
Registers

You create and modify number registers using the . nr (number register) request.
the
register is created if it doesn't already exist. The . nr request specifies the name
of the number register, and also specifies the initial value to be placed in there.
So the request

In its simplest form, the . nr request places a value into a number register -

121

Revision A. of 9 May 1988

122

Using nroff and troff

( .nr

]

1.5v

would be a request to set a register called PD (which we might know as 'Paragraph Depth' if we were writing a macro package) to the value 1.5v (l.5 of
troff's vertical units).
As an example of the use of number registers, in the -IDS macro package, most
significant parameters are defined in tenus of the values of a handful of number
registers (see the chapter "Formatting Documents with the -ms Macros" in F ormatting Documents). These include the point size for text, the vertical spacing,
and the line and title lengths. To set the point size and vertical spacing for the
following paragraphs, for example, a user may say:

]

.nr PS 10
(.. nr VS 12

The paragraph macro . PP is defined (roughly) as follows:
.de
.ps
.vs
.ft
.sp
.ti

PP
\\n(PS \" reset size
\\n(VSp \" spacing
R
\" font
O.5v
\" half a line
+3m

This sets the font to Roman and the point size and line spacing to whatever
values are stored in the P S and vs number registers.
Why are there two backslashes? When troff originally reads the macro
definition, it peels off one backslash to see what's coming next. To ensure that
another is left in the definition when the macro is used, we have to put two
backslashes in the definition. If only one backslash is used, point size and vertical spacing will be frozen at the time the macro is defined, not when the macro is
used.
Protecting by an extra layer of backslashes is only needed for \n, \ *, \$, and \
itself. Things like \ s, \ f, \ h, \ v, and so on do not need an extra backslash,
since they are converted by t ro f f to an internal code immediately upon being
seen

Revision A, of9 May 1988

Chapter II-Number Registers

123

Summary of the . nr Request
Mnemonic:

number register

Form of Request:

.nrR±NM

Initial Value:

Not applicable

If No Argument:

Ignored

Explanation:

Assign the value ±N to number register R, with respect to the previous
value, if any. Set the increment for auto-incrementing to M.

Notes:

u (see Table A-2)

11.2. Auto-Increment
Number Registers

When you set a number register with the . nr request, you can also specify an
additional number as an auto-increment value - that is, the number is added to
the number register every time you access the number register. You specify the
auto-increment value with a request such as:

(,---onr_ s n0 _ 1_

_ _ _ _]

to specify a (hypothetical) section number register that starts off with the value 0
and is incremented by 1 every time you use it. This might be applicable (for
instance) to numbering the sections of a document automatically - something
you might expect a computer to do for you. You might also define a numbered
list macro that would clock up the item number every time you added a new list
item.
Here's a very quick and dirty example of the use of auto-incrementing a number
register:
.nr en -1 2
the odd numbers \n+(cn, \n+(cn, \n+(cn, \n+(cn, \n+(cn, \n+(cn,

When we format the above sequence, we get the following:
... the odd numbers 1,3,5,7,9, 11, ...
The table below shows the effects of accessing the number registers x and .xx
after a . nr request that sets them to the value N with an auto-increment value of
M.

Revision A, of 9 May 1988

124

Using nroff and troff

Table 11-1

Access Sequences for Auto-incrementing Number Registers
Access
Sequence

Request

11.3. Arithmetic
Expressions with
Number Registers

Effect on
Register

Value
Interpolated

\n (xx

none
none

N
N

.nr x N M
.nr x N M

\n+x
\n-x

x incremented by M
x decremented by M

N+M
N-M

.nr xx N M
.nr xx N M

\n+ (xx
\n-(xx

xx incremented by M
xx decremented by M

N+M
N-M

.nr x N M
.nr XX N M

\nx

Arithmetic expressions can appear anywhere that a number is expected. As a
trivial example,
( .nr PS \\n(PS-2

]

decrements the value in the PS macro by 2.
Expressions can use the arithmetic operators and logical operators as shown in
the table below. Parts of an expression can be surrounded by parentheses.
Table 11-2

Arithmetic Operators and Logical Operators for Expressions
Arithmetic Operator

Meaning
Addition
Subtraction
Division
Multiplication
Modulo.

Logical Operator

Meaning

<
>
<=
>=
or =

Less than
Greater than
Less than or equal to
Greater than or equal to
Equal to
and
or

Except where controlled by parentheses, evaluation of expressions is left-to-right
- there is no operator precedence.

•,~\sun

microsystems

Revision A. of 9 May 1988

Chapter 11 -

Number Registers

125

Although the arithmetic we have done so far has been straightforward, more
complicated things are somewhat tricky. First, number registers hold only
integers. traff arithmetic uses truncating integer division. Second, in the
absence of parentheses, evaluation is done from left to right without any operator
precedence (including relational operators). Thus
7*-4+3/13

becomes' -1'. Number registers can occur anywhere in an expression, and so
can scale indicators like p, i, In, and so on (but no spaces). Although integer
division causes truncation, each number and its scale indicator is converted to
machine units (1/432 inch) before any arithmetic is done, so 1i/2u evaluates to
O.Si correctly.
The scale indicator u often has to appear where you would not expect it - in
particular, when arithmetic is being done in a context that implies horizontal or
vertical dimensions. For example,

]

[.11 7 /2i
would seem obvious enough - 3.5 inches. Sorry - remember that the default
units for horizontal parameters like the .11 request are ems. So that expression
is really '7 ems / 2 inches', and when translated into machine units, it becomes
zero. How about

]

(.11 7i /2
Still no good-the '2' is '2 ems', so '7i{2' is small, although not zero. You
must use

]

( .11 7i/2u

So again, a safe rule is to attach a scale indicator to every number, even constants.
For arithmetic done within a . nr request, there is no implication of horizontal or
vertical dimension, so the default units are 'units', and 7i/2 and 7i/2u mean the
same thing. Thus

.nr 11 7i/2

[_._1_1__
\_\n__
_\_h_'_-_O_o3_m_'_>__________________________________________)

to produce»

Frequently \h is used with the width function, \w, to generate motions equal to
the width of some character string. The construction

Omar Khayyam - the Rubdiytit

Revision A. of 9 May 1988

134

Using nroff and troff

( \ w' thing'

is a number equal to the width of 'thing' in machine units (1/432 inch). All
troff computations are ultimately done in these units. To move horizontally
the width of an 'x', we can say

( \h'\w'x'u'

As we mentioned above, the default scale factor for all horizontal dimensions is
m (ems), so here we must have the u for machine units, or the motion produced
will be far too large. troff is quite happy with the nested quotes, by the way,

so long as you don't leave any out.
As a live example of this kind of construction, the re, re, ffi, and IE ligatures discussed in the section on ligatures in the chapter Fonts and Special Characters,
were constructed using the \ h function to define the following strings:
.ds
.ds
.ds
.ds

ae
Ae
oe
Oe

a\h'-(\w'a'u*4/10)'e
A\h'-(\w'A'u*4/10)'E
o\h'-(\w'o'u*4/10)'e
O\h'-(\w'O'u*4/10)'E

and for any given one of those strings, the mess is unscrambled like this:
Construct

. ds ae
a
\h'-(\w'a'u*4/10)'

12.3. \ 0 FunctionDigit-Size Spaces

Explanation

Define a string called 'ae' .
Letter' a' in the string.
Move backward 0.4 of the width of the letter' a' .
Letter' e' in the string.

The in-line \ 0 function is an unpaddable white space of the same width as a
digit. 'Unpaddable' means that it will never be widened or split across a line by
line justification and filling. You could use the digit space to get numerical
columns correctly lined up. For example, suppose you have this list of items:

Revision A, of 9 May 1988

Chapter 12 -

Drawing Lines and Characters

135

.nf
. ta sr1
Step
Description
.sp sp
1. Unpack the handy dandy fuse blower.
2.
Inspect for obvious shipping defects.

9.
Find a wall socket.
10. Insert handy dandy fuse blower in wall socket.
11. Push red button to blow all fuses .
. fi

When you fornat this list of operations, you get this result:
Step Description
1.
2.

Unpack the handy dandy fuse blower.
Inspect for obvious shipping defects.

9.
10.
11.

Find a wall socket.
Insert handy dandy fuse blower in wall socket.
Push red button to blow all fuses.

As you can see, the numbers do not line up at the decimal point, but instead are
lined up on the left. Placing a space character in front of the digits in the input is
not sufficient measure to line up the digits at the decimal. A space is not the
same width as a digit (at least not in traff). A solution is to use the unpaddable digit-space character \ 0 in front of the single digits like this:
.nf
.ta sn
Step
.sp 5p
\01.
\02.

\ODescription
Unpack the handy dandy fuse blower.
Inspect for obvious shipping defects.

\09.
Find a wall socket.
10. Insert handy dandy fuse blower in wall socket.
11. Push red button to blow all fuses .
. fi

Now when you fornat the text, you get this result:

Revision A, of9 May 1988

136

Using nroff and troff

Step
1.
2.

9.
10.
11.

Description
Unpack the handy dandy fuse blower.
Inspect for obvious shipping defects.

Find a wall socket.
Insert handy dandy fuse blower in wall socket
Push red button to blow all fuses.

which looks better than the previous example.

12.4. '\ ' Function UnpaddabJe Space

There is also the in-line \ function, which is the \ character (backslash) followed
by a space character. This function is an unpaddable character the width of a
space. You can use this to make sure that things don't get split across line boundaries, for instance if you want to see something like nrof£ -T1p myfile in
the stream of text, with the command line set off like it was here and ensuring
that it all appears on one line, you would type it in as
\ \ \f(LBnroff\ -Tlp\fP\ \fImyfile\fP\ \
in-line in the text.

12.5. \ I and \ - Functions
- Thick and Thin
Spaces

In typography, there are times when you need spaces that are one-sixth or onetwelfth of the width of an em-space. troff supplies the in-line \ I function

which is one-sixth of an em -space wide - this is sometimes called a 'thick
space'. Where would you want such a thing? Well one place it could be used is
in making an ellipsis look better. In general, an ellipsis in a proportional font
looks too cramped if you just string three dots together:

["",---... - - - - - - - ]
and the dots tend to look too spread out if you just place spaces between them:

(. . .

]

and so the answer is often to use the thick space to get a more pleasing effect like
this:

(--..
----------]
_.

which was actually achieved by typing:

]

( .\ I.\ I.

Lastly, the in-line \ ... function is one-twelfth of the width of an em-space space.
This function is almost always used for a typographical application called italic
correction. Consider an italic word followed by some punctuation such as do
tell! Because the italic letters are slanted to the right, they lean slightly on the
Revision A. of 9 May 1988

Chapter 12 -

Drawing Lines and Characters

137

trailing punctuation, especially when the last letter is a tall one like the I in the
example. So, what typographers do is to apply the italic correction in the fonn of
a thin space just before the punctuation, so that the effect is now do tell! What
we actually typed here was

(~\_f_I_d_o__t_e_l_l_\_f_P_\_A_!________________________________________~J
with the italic correction just before the exclamation mark.
Typing the italic correction at every instance of adjacent Roman and italic text,
would be a lot of work. Some macro packages construct special-purpose macros
for applying the italic correction. For example, the -man macro package has a
• I R macro that joins alternating italic and Roman words together so that you can
italicize parts of words or have italic text with trailing Roman punctuation. You
use the . IR macro like:
( .IR well spring

to get the composite effect of wellspring in your text. The . IR macro (somewhat simplified) looks like this:
.de IR
\&\fI\\$1\~\fR\\$2\fI\\$3\~\fR\\$4\fI\\$5\~\fR\\$6\fI\\$7\~\fR\\$8\fI\\$9\~\fR

and you can see the italic correction applied after every parameter that is set in
the italic font.

12.6. \ & Function - NonPrinting Zero-Width
Character

The \ & function is a character that does not print, and does not take up any space
in the output text. You might wonder what use it is at all? One application of
the non-printing character used throughout this manual is to display examples of
text containing troff or nroff requests. To print a trof f request just as it
appears in the input, you have to distinguish it from a real troff request. You
cannot print an example whose input looks just like this:
.in +O.Si

indent the text half an inch

lots of lines of text to be processed

.in -O.Si

unindent the text half an inch

The . characters at the beginning of each line would be interpreted as troff
requests instead of text representing examples of requests. In such cases, we
have to use the \ & function to stop troff or nroff from interpreting the. at
the start of the line as a control character. We would type the example like this:

Revision A, of 9 May 1988

138

Using nroff and troff

indent the text half an inch
\&.
\&.
\&.
lots of lines of text to be processed
\&.
\&.
\&.
unindent the text half an inch
\&.in -O.Si
\&.in +O.Si

Another place where the \ & function is useful is within some of the other in-line
functions such as the \ 1 function. The \ 1 function draws lines and you type the
function like:
( \ l' length

]

character'

where length is the length of the line you want to draw, and character is the character to use. Sometimes, the character might look like a part of length, for
instance,
(\1'1.0i='

]

doesn't get you a one-inch line of = signs as you might expect, because the =
sign looks like an expression where you are trying to say that "1.Oi is equal to"
something else. When you encounter this situation, type the \ 1 function like
this:
( \l'l.Oi\&='

and the result is a one-inch line of

12.7. \ 0 Function Overstriking
Characters

]

=========== signs as you see here.

Automatically-centered overstriking of up to nine characters is possible with the
in-line \ a (overstrike) function. The \ a function looks like \ a' string' where
the characters in string are overprinted with their centers aligned. This means for
example, that you can print from one to nine different characters superimposed
upon each other. traff detennines the width of this "character" you are creating to be the width of the widest character in your string. The superimposed
characters are then centered on the widest character. The string should not contain local vertical motion. The in-line \ a function is used like this:

(~\_O_'_'s_e_to_if_c_ha_r_a_c_~_n_'_'__________________________________________]
This is useful for printing accents, as in
syst\o"e\(ga"me t\o"e\(aa"l\o"e\(aa"phonique

Revision A, of 9 May 1988

Chapter 12 -

Drawing Lines and Characters

139

which produces
systeme telephonique
The accents are \ (ga (grave accent) and \ (aa (acute accent), or \' and \ ';
remember that each is just one character to tr off.

(_\_o_"e_\_'_"________________________________________J
produces

e
and

( \0"\ (mo\

(51"

produces
fie

12.8. \ z Function - Zero
Motion Characters

You can make your own overstrikes with another special convention, \ z, the
zero-motion command. \ z x suppresses the normal horizontal motion after
printing the single character x, so another character can be laid on top of it.
Although sizes can be changed within \0, troff centers the characters on the
widest of them, and there can be no horizontal or vertical motions, so \ z may be
the only way to get what you want:

is produced by
.sp 2
\s8\z\(ci\s14\z\(ci\s22\z\(ci\s36\z\(ci

The . s p 2 line is needed to leave enough vertical space for the result.
As another example, an extra-heavy semicolon that looks like
; instead of ; or ;
can be constructed with a big comma and a big period above it:
( \s+6\z,\v'-O.25m' .\v'O.25m'\sO

where 0 . 2 Sm is an empirical constant.
As further examples, \ z \ (ci \ (pI produces
Ef)

Revision A, of9 May 1988

140

Using nroff and troff

and \ (br\z\ (rn \ (ul \ (br produces the smallest possible constructed box:

o
There is also a more general overstriking function for piling things up vertically
- this topic is discussed in the section "\b Function - Build Large Brackets"
later in this chapter.

12.9. \ w Function - Get
Width of a String

Back in the section on using tabs, we saw how we could set tab stops to various
positions on the line and lay stuff out in columns based on the tab stops. Sometimes it is hard to figure out where the tab stops should go because you can't
always tell in advance how wide things are - this is especially true for proportional fonts (by definition the characters aren't all the same size). Often what you
want is to set tab stops based on the width of an item. Then you can set tab stops
based on that width and remain independent of the size of the characters if you
decide to change point size.
The in-line width function \ w' string , generates the numerical width of string
(in basic units). For example, . ti -\ w' 1. 'u could be used to temporarily
indent leftward a distance equal to the size of the string '1. '. Size and font
changes may be safely embedded in string, and do not affect the current environment.
In a previous example we showed how a large capital letter could be placed in a
verse with vertical motions and we played some games with indenting to get the
thing to come out more-or-Iess right. The problem with that approach is that we
had to measure the size of the character and arrive at the indent by trial and error
(actually, error and trial). Another problem is that the measured indent didn't
take the point-size into account - if we decide to change sizes, the measurements are all wrong. The width function can measure the size of the thing
directly, so here's our example all over again using the \ w function:
.in +\w'\s36A\sO'u
.ti -\w'\s36A\sO'u
\v'1.O'\s36A\sO\v'-1.O'\h'-5p'wake! for Morning in the Bowl of Night
\h'lp'Has flung the Stone that puts the Stars to Flight:
.in -\w'\s36A\sO'u
And La! the Hunter of the East has caught
The Sultan's Turret in a Noose of Light.

and when we fonnat that text we get this result:

A wake! for Morning in the Bowl of Night
ft. Has flung the Stone that puts the Stars to Hight:
And Lo! the Hunter of the East has caught
The Sultan's Turret in a Noose of Light.
The width function also sets three number registers. The registers st (string top)
and sb (string bottom) are set respectively to the highest and lowest extent of
string relative to the baseline; then, for example, the total height of the string is
\n (stu-\n (sbu. In troff the number register ct (character type) is set to a
value between 0 and 3:
Revision A, of 9 May 1988

Chapter 12 -

Table 12-1

141

troff Width Function- ct Number Register Values
ct Number
Register
Value

1
2

12.10. \ k Function Mark Current
Horizontal Place

Drawing Lines and Characters

Meaning
all of the characters in
string were short lower
case characters without
descenders (like e)
at least one character has a
descender (like y)
at least one character is tall
(like H)
both tall characters and
characters with descenders
are present.

The in-line \k.x function stores the current horizontal position in the input line
into register x. As an example, we could get a bold italic effect by the construction:

)

( \kxword \h' I \nxu+2u 'word

This emboldens word by backing up to its absolute (hence, the I) beginning
(\kxword\h'I\rnm) plus 2 machine units (+2u) and overprinting it, resulting in

word

Revision A, of 9 May 1988

142

Using nroff and troff

12.11. \b Function Build Large
Brackets
Table 12-2

The Special (mathematical) font contains a number of characters for constructing
large brackets out of pieces. The table below shows the escape-sequences for the
individual pieces, what they look like, and their names.

Pieces for Constructing Large Brackets
Escape
Sequence

Character

Description

\(It

left top of big curly bracket

\(lb

left bottom of big curly bracket

\(rt

L
l

\(rb

right bottom of big curly bracket

\(lk

left center of big curly bracket

\(rk

right center of big curly bracket

\(bv

bold vertical

\(If

left floor (left bottom of big square bracket)

\(rf

right floor (right bottom of big square bracket)

right top of big curly bracket

\(le

left ceiling (left top of big square bracket)

\(re

right ceiling (right top of big square bracket)

These pieces can be combined into various styles and sizes of brackets and
braces by using the in-line \b (for bracketing) function. The \b function is used
like this:
( \b' string

]

to pile up the characters vertically in string with the first character on top and the
last on the bottom. The characters are vertically separated by one em and the
total pile is centered 1/2-em above the current baseline (1/2-line in nroff). For
example:
\x' -O.Sm' \x'O.Sm' \b' \(lc\(lf'E\I\b' \(rc\(rf'

produces [E] . As with previous examples, we should unscramble the whole
mess for you:

Revision A, of 9 May 1988

Chapter 12 - Drawing Lines and Characters

Escape
Sequence

Character

143

Description
start bracketing function

\b
\(le

left ceiling

\(If

leftfioor

letter E

start bracketing function

\(re

right ceiling

\(rf

right floor

Here's another example of using braces and brackets. You get this effect:

{[ xJ}
by typing this:
\b~\(lt\(lk\(lb~

\b~\(lc\(lf'

x \b'\(rc\(rf' \b'\(rt\(rk\(rb'

12.12. \r FunctionReverse Vertical
Motions
12.13. Drawing Horizontal
and Vertical Lines

The \r function makes a single reverse motion of one em upward in troff,
and one line upward in nroff.

\ 1 Function - Draw
Horizontal Lines

The in-line \ 1 (lower-case ell) function draws a horizontal line. For example,
the function \ 1 ' 1 . 0 i ' draws a one-inch horizontal line like this
_ _ _ _ _ _ in the text.

Typesetting systems commonly have commands to draw horizontal and vertical
lines. Of course typographers don't call them lines - they are called 'rules'
because once upon a time they were drawn with rulers. troff provides a convenient facility for drawing horizontal and vertical lines of arbitrary length with
arbitrary characters, and these facilities are described in the subsections following.

The line is actually drawn using the baseline rule character in troff, and the
underline character in nro f f, but you can in fact make the character that draws
the line any character you like by placing the character after the length designation. For example, you could draw a two inches of tildes by using \1'2 . Oi _I to
get
in the text. The construction \L is entirely
analogous, except that it draws a vertical line instead of horizontal.
The general form of the \ 1 function is

(~\_l__'l_en_g_t_h_Ch_a_r_a_ct_er_'_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __ _~J
Revision A, of 9 May 1988

144

Using nroff and troff

where length is the length of the string of characters to be drawn, and character
is the character to use to draw the line. If character looks like a continuation of
length, you can insulate character from length with the zero-width \ & sequence.
If length is negative, a backward horizontal motion of size length is made before
drawing the string. Any space resulting from length/ (size of character) having a
remainder is put at the beginning (left end) of the string. In the case of characters
that are designed to be connected such as baseline-rule (_), underrule C), and
root-en (-), the remainder space is covered by overlapping. If length is less than
the width of character, a single character is centered on a distance length. As an
example, here is a macro to underscore a string:

ode us

_~_~_$_l_\_l_'_I_O_\_(U_l_'____________________________________~

[

and you use the us macro like this:
0

[~_ou_s__'_'u_n_d_e_r_l_i_n_e_d__wo_r_d_s_'_'__________________________________~]
to yield underlined words in the stream of text. You could also write a macro to
draw a box around a string:
ode bx
\(br\\$l\(br\ l'IO\(rn'\ l'IO\(ul'

and SO you can type:

(.bX "words

]

in a box"

to get some !Words in a boX! in the text stream.
\ L Function - Draw Vertical
Lines

The in-line \L (upper-case ell) function draws a vertical line. As in the case of
the \ 1 function, the general fonn of the function is
[_\__L__'_k_n_g_ffl_C_ha
__ra_c_te_r_'______________________________________

This draws a vertical line consisting of the (optional) character character stacked
vertically apart 1 em (1 line in nroff), with the first two characters overlapped,
if necessary, to fonn a continuous line. The default character is the box rule,
I( \ (br); the other suitable character is the bold vertical I ( \ (bv). The line
is begun without any initial motion relative to the current base line. A positive
length specifies a line drawn downward and a negative length 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.

Revision A, of9 May 1988

Chapter 12 - Drawing Lines and Characters

145

Combining the Horizontal
and Vertical Line Drawing
Functions
The horizontal and vertical line drawing functions may be used in combination to produce large boxes. The zerowidth box-rule and the 1/2 - em wide underrule were designed to fonn comers when using one-em vertical spacings.
For example the macro
.de eb
.sp -1
\"compensate for next automatic baseline spacing
.nf
\"avoid possibly overflowing word buffer
\h '-.5n '\L' 1 \ \nzu-1 '\1'\ \n( .lu+1n\ (ul '\L '-1 \ \nzu+1 '\1' 1Ou-. Sn\ (ul'
\"draw box
.fi

draws a box around some text whose beginning vertical place was saved in number register z (using. mk z) as done
for this paragraph.

12.14. . me - Place
Characters in the
Margin

Many types of documents require placing specific characters in the margins. The
most common use of this is placing bars down the margins to indicate what's
changed in a document from one revision of a document to the next. This paragraph and the remainder of the text in this section were preceded by a
( .mc \s12\(br\sO

request (that is, place a l2-point box-rule character in the margin) to tum on the
marginal bars, and followed by a simple

[_.mc_ _ _ _ _ _ _ _ _

request to tum off the marginal bars.
Currently, this request is not bug-free, and the margin character only appears to
the right of the right margin, but not in left margins. Also, you'l1 notice that the
marginal bars do not appear on incomplete lines, such as this one .

• \sun
•

microsystems

Revision A, of 9 May 1988

146

Using nroff and troff

Summary of the . me Request
Mnemonic:

margin character

Form of Request:

.mccN

Initial Value:

Not applicable

If No Argument:

Tum off margin characters

Explanation:

Specifies that a margin character c appear a distance N to the right of the
right margin after each non-empty text line (except those produced by . tl).
If the output line is too long (as can happen in nofill mode) the character is
appended to the line. If N is not given, the previous N is used; the initial N
is 0.2 inches in nroff and 1 em in troff.

Notes:

E, m (see Table A-2)

Revision A, of 9 May 1988

13
Character Translations
Character Translations .............................................................................................................. 149
13.1. Input Character Translations ..................................................................................

149

13.2. . ec and . eo -

Set Escape Character or Stop Escapes .......................

149

13.3. . cc and . c2 -

Set Control Characters ........................................................

150

Output Translation .....................................................................................

150

13.4. . t r -

13
Character Translations
13.1. Input Character
Translations

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 a . t r
(translate) request (refer to the section entitled . t r - Output Translation). All
others are ignored.

13.2. . ec and. eo - Set
Escape Character or
Stop Escapes

The escape character \ introduces escape sequences - meaning the following
character is something else, or indicates some function. A complete list of such
sequences is given in a later chapter. The \ character should not be confused
with the ASCII control character ESC of the same name. The escape character
can be changed with an . e c (escape character) request, and all that has been said
about the default \ becomes true for the new escape character. \ e can be used to
print whatever the current escape character is. If necessary or convenient, the
escape mechanism can be turned off with an . eo (escape oft) request and
restored with the . e c request.

Summary of the . ec Request
Mnemonic:

escape character

Form of Request:

.ec c

Initial Value:

If No Argument:

Explanation:

Set escape character to \, or to c, if given.

Summary of the . eo Request
Mnemonic:

escape mechanism off

Form of Request:

.eo

Initial Value:

Escape mechanism is on

If No Argument:

Tum escape mechanism off.

Explanation:

Turn escape mechanism off.

149

Revision A, of 9 May 1988

150

Using nroff and troff

13.3. . cc and . c2 - Set
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.

Summary of the . cc Request
Mnemonic:

control character

Form of Request:

. cc

Initial Value:

If No Argument:
Explanation:

Set the basic control character to c, or reset to ' . '.

Summary of the . c2 Request
Mnemonic:

no-break control character

Form of Request:

. c2

Initial Value:

If No Argument:
Explanation:

13.4. . t r - Output
Translation

Set the no-break control character to c, or reset to '

One character can be made a stand-in for another character using the. t r
(translate) request. All text processing (for instance, character comparisons)
takes place with the input (stand-in) character that appears to have the width of
the final character. The graphic translation occurs at the moment of output
(including diversion).

Summary of the . t r Request
Mnemonic:

translate

Form of Request:

.tr

Initial Value:

Not Applicable

If No Argument:

No translation

Exp lanation:

Translate a into b, c into d, etc. If an odd number of characters is given, the
last one is mapped into the space character. To be consistent, a particular
translation must stay in effect from input to output time.

Notes:

o (see Table A-2)

abed....

Revision A, of 9 May 1988

14
Automatic Line Numbering

Automatic Line Numbering .................................................................................................. 153
14.1 . . nm - Number Output Lines ...............................................................................

153

14.2. . nn -

154

Stop Numbering Lines .............................................................................

14
Automatic Line Numbering
14.1. . nm - Number
Output Lines
3

Output lines may be numbered automatically via the . nm (number) request.
Refer to the following table for a summary of the . nm request. When in
effect, a three-digit, Arabic number and a digit-space begins each line of
output text. The text lines are thus offset by four digit-spaces, and otherwise
retain their line length. To keep the right margin aligned with an earlier
margin, you may want to reduce the line length by the equivalent of four
digit spaces. Blank lines, other vertical spaces, and lines generated by . t I
are not numbered. Numbering can be temporarily suspended with the . nn
(no number) request (see below), or with an . nm followed by a later . nm
+0. In addition, a line number indent I, and the number-text separation S
may be specified in digit-spaces. Further, it can be specified that only those
line numbers that are multiples of some number M are to be printed (the others will appear as blank number fields).

Summary of the . nm Request
Mnemonic:

numbering

Form of Request:

.nm±NMSI

Initial Value:

Line numbering turned off.

If No Argument:

Line numbering turned off.

Explanation:

Tum on line numbering if±N is given. The next output line numbered is
numbered ±N. Default values are M= 1, S= 1, and 1= O. N is the line
number counter (or incrementer if you use ±N), M is the multiple of the
numbered lines to be printed on the page, S is the spacing between line
numbers and text, and I is the amount of indent for the line numbers.
Parameters corresponding to missing arguments are unaffected; a nonnumeric 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.

Notes:

E (see Table A-2)

153

Revision A, of 9 May 1988

154

Using nroff and troff

14.2. . nn - Stop
Numbering Lines

When you are using the . nm request to number lines (as discussed above), you
can temporarily suspend the numbering with the . nn (no number) request.

Summary of the . nn Request
Mnemonic:

no numbering

Form of Request:

.nnN

Initial Value:

Not applicable

If No Argument:

N=l

Explanation:

The next N text output lines are not numbered.

Notes:

E (see Table A-2)
As an example, the paragraph portions of this chapter are numbered with

M= 3: . nm 1 3 was placed at the beginning of the chapter, . nm was
placed at the end of the first paragraph; and . nm + 0 was placed in front of
this paragraph; and . nm finally placed at the end. Line lengths were also
changed (by \ w ' 00 00 ' u) to keep the right side aligned.

Another example is

[.nm +5 5 x 3
21

which turns on numbering with the line number of the next line to be 5
greater than the last-numbered line, M= 5, spacing S is untouched, and with
the indent I set to 3.

Revision A, of 9 May 1988

15
Conditional Requests

Conditional Requests ................................................................................................................. 157
15.1. . if -

Conditional Request ..................................................................................

157

15.2. . ie and . e1 -If-Else and Else Conditionals ..........................................

160

15.3 . . ig -

160

Ignore Input Text ........................................................................................

15
Conditional Requests
15.1. . if - Conditional
Request

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 1, and add some space if it is. The . if
request provides the conditional test that we can add just before the heading line
is output:
( .if \\n(SH-1 .sp 2i \" first section only

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 text - here a request. If the condition is false, or zero, or
negative, the rest of the line is skipped.
It is possible to perfonn more than one request if a condition is true. Suppose
several operations are to be done before section 1. One possibility is to define a
macro . S 1 and invoke it if we are about to do section 1 (as detennined by a
. if) .
. de 81
processing for section 1 --.de 8H
.if \\n(SH=1 .S1

An alternate way is to use the extended fonn of the . if, like this:
.if \\n(SH=1 \{--- processing for section 1 ----\}

The braces \ { and \} must occur in the positions shown or you will get unexpected extra lines in your output. troff also provides an 'if-else' construction,
which we will not go into here.
A condition can be negated by preceding it with !; we get the same effect as
above (but less clearly) by using

157

Revision A. of 9 May 1988

158

Using nroff and troff

(~_.l_'f___!\_\_n_(_S_H_>_l__._S_l________________________________________~J
There are a handful of other conditions that can be tested with . if. For example, is the current page even or odd?
.if e .tl "even page title"
.if 0 .tl "odd page title"

gives facing pages different titles when used inside an appropriate new page
macro.
Two other conditions are t and n, which tell you whether the fonnatter is
troff or nroff.

.if t troff stuff ...
[ .if n nroff stuff .. .

' " - - - - - - - - - - - '

Finally, string comparisons may be made in an . if:
( .if

'stringl'string2'

stuff

does 'stuff' if string1 is the same as string2. 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.
In the following table, c is a one-character, built-in condition name, ! signifies
not, N is a numerical expression, string1 and string2 are strings delimited by any
non-blank, non-numeric character not in the strings, and anything represents
what is conditionally accepted .

• sun
~

microsystems

Revision A, of 9 May 1988

Chapter 15 - Conditional Requests

159

Summary of the . if Requests
Mnemonic :Iif, if-else, else
Form of Request:

· if c anything

Initial Value:

Not Applicable

If No Argument:

Not Applicable

Explanation

If condition c true, accept anything as input. In multi-line case use \{anythingV.

Form of Request:

· i f ! c anything

Explanation

If condition c false, accept anything.

Form of Request:

· if N anything

Explanation

If expression N > 0, accept anything.

Form of Request:

· if

Explanation

If expression N sO, accept anything.

Form of Request:

· if 'string1 'string2 ' anything

Explanation

If string1 identical to string2, accept anything.

Form of Request:

· i f ! ' string 1 'string2 ' anything

Explanation

If string1 is not identical to string2, accept anything.

Form of Request:

· ie c anything

Explanation

If portion of if-else (like above i f forms).

Form of Request:

· el anything

Explanation

Else portion of if-else.

!N anything

The built-in condition names are:
Table 15-1

Built-In Condition Namesfor Conditional Processing
Condition
Name
0

e
t
n

True 1f
Current page number is odd
Current page number is even
Formatter is traff
Formatter is nraff

Revision A, of 9 May 1988

160

Using nroff and troff

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 condition, number, or string comparison,
the sense of the acceptance is reversed.
Any spaces between the condition and the beginning of anything are skipped
over. The anything can be either a single input line (text, macro, or whatever) or
a number of input lines. In the multi-line case, the first line must begin with a
left delimiter \ { and the last line must end with a right delimiter \ }.

15.2. . ie and. el - IfElse and Else
Conditionals

The request . i e (if-else) is almost identical to . if except that the acceptance
state is remembered. A subsequent and matching . e1 (else) request then uses
the reverse sense of that state. . ie - . e1 pairs may be nested. Refer to the
Summary of the . if Requests for summaries of . ie and . el.
Some examples are:
( .if e .tl ' Even Page %'"

which outputs a title if the page number is even; and
.ie \n%>l \{\

'sp O.5i
.tl ' Page %'"

'sp - 1.2i \}
.el .sp - 2.Si

which treats page 1 different!y from other pages.

15.3. . i g - Ignore Input
Text

Another mechanism for conditionally accepting input text is via the . ig (ignore)
request. Basically, you place the . ig request before a block of text you want to
ignore:
. ig

start of ignored block of text

block of text you don't want to appear in the printed output

end of ignore block signalled with.

The . ig request functions like a macro definition via the . de request except
that the text between the . ig and the tenninating. . is discarded instead of
being processed for printing.
You can give the . ig request an argument -

that is, an

Revision A. of 9 May 1988

Chapter 15 -

Conditional Requests

. ig xy

(

161

' - - - - - - - request ignores all text up to and including a line that reads

[

]

.xy

which looks just like a request:
.ig

start of ignored block of text

block of text you don't want to appear in the printed output

. zz

end of ignore block signalled with . zz

You can of course combine the . ig request with the other conditionals to ignore
a block of text if a condition is satisfied. For example, you might want to omit
blocks of text if the printed pages are destined for different audiences:
This manual is for Wizards only

.nr W 1

further processing

.if \nW .ig

If the manual is for wizards

Tutorial material beneath the attention of wizards

.wz

.\sun
~~

microsystems

end of ignored block of text

Revision A, of 9 May 1988

162

Using nroff and troff

Summary of the . ig Request
Mnemonic:

ignore

Form of Request:

.igyy

Initial Value:

Not applicable

If No Argument:

Ignore text up to a line starting with.

Exp lanation:

Ignore input lines up to and including a line starting with . yy - use. . if
no argument is specified on the request .. ig behaves exactly like the . de
(define macro) request except that the input is discarded. The input is read
in copy mode, and any auto-incremented number registers will be affected.

+~t!!

Revision A, of 9 May 1988

16
Debugging Requests

Debugging Requests ................................................................................................................... 165
16.1. . pm -

Display Names and Sizes of Defined Macros ............................

165

16.2. . f 1 - Flush Output Buffer ..................................................................................

166

16.3. . ab -

166

Abort ..................................................................................................................

16
Debugging Requests
troff and nroff resemble languages for programming a typesetter rather than
a mechanism to describe how a document should be put together. There are

times when you just can't figure out why things are going wrong and not generating results as advertised. The requests described here are for dyed-in-the-wool
macro wizards.

16.1. . pm - Display
Names and Sizes of
Defined Macros

The . pm (print macros) request displays the names of all defined macros and
how big they are. Why would anybody want to do such a thing? Well, if you're
using a macro as a diversion, you might find out (by printing its size) that it is far
bigger than you expect (that it's swallowing your entire file).

Summary of the . pm Request
Mnemonic:

print macros

Form of Request:

.pmt

Initial Value:

Not applicable

If No Argument:

All

Explanation:

Print macros. The names and sizes of all of the defined macros and strings
are printed on the user's terminal; if tis given, only the total of the sizes is
printed. The sizes are given in blocks of 128 characters.

165

Revision A, of9 May 1988

166

Using nroff and troff

16.2. . f1 - Flush Output
Buffer

The . f 1 (flush) request flushes the output buffer using nroff interactively.

this can be used when you're

Summary of the . f1 Request
Mnemonic:

flush

Form of Request:

.fl

Initial Value:

Not applicable

If No Argument:

adjusting is turned off

Exp lanation:

Hush output buffer. Used in interactive debugging to force output.

16.3. . ab -

Abort

A final useful request in the debugging category is the . ab (abort) request which
basically bails out and stops the formatting.

Summary of the . ab Request
Mnemonic:

abort

Form of Request:

. ab text

Initial Value:

Not applicable

If No Argument:

No text is displayed

Explanation:

Displays text and terminates without further processing. If text is missing,
'User Abort' is displayed. Does not cause a break. The output buffer is
flushed .

• ~sun
•

microsystems

Revision A, of 9 May 1988

17
Environments

Environments ................................................................................................................................... 169
17.1. . ev -

Switch Environment .................................................................................

169

17
Environments
As we mentioned, there is a potential problem when going across a page boundary: parameters like size and font for a page title may well be different from
those in effect in the text when the page boundary occurs. traff provides a
very general way to deal with this and similar situations. There are six environments, each of which has independently-settable versions of many of the parameters associated with processing, including size, font, line and title lengths,
fill/nofill mode, tab stops, and even partially-collected lines. 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.

17.1. . ev - Switch
Environment

The command. ev n shifts to environment n; n must be in the range 0 through 2.
A . ev command with no argument returns to the previous environment.
Environment names are maintained in a stack, so calls for different environments
may be nested and unwound consistently.
When t r 0 f f starts up, environment 0 is the default environment, so in general,
the main text of your document is processed in this environment in the absence
of any information to the contrary. Given this, we can modify the . NP (new
page) macro to process titles in environment 1 like this:
.de
.ev
.it
.ft
.ps

1
6i

\" shift to new environment

\" set parameters here

10
any other processing
.ev
\" return to previous environment

It is also possible to initialize the parameters for an environment outside the . NP
macro, but the version shown keeps all the processing in one place and is thus
easier to understand and change.

Another major application for environments is for blocks of text that must be
kept together.
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

~\sun
~

microsystems

169

Revision A, of 9 May 1988

170

Using nroff and troff

addition, partially-collected lines and words are in the environment. Everything
else is global; examples are page-oriented parameters, diversion-oriented parameters' number registers, and macro and string definitions. All environments are
initialized with default parameter values.

Summary of the . ev Request
Mnemonic:

environment

Form of Request:

.evN

Initial Value:

N=O

If No Argument:

Switch back to previous environment

Explanation:

Switch to environment N, where 0g{'5:2. Switching is done in push-down
fashion so that restoring a previous environment must be done with. ev
rather than specific reference.

Revision A, of9 May 1988

A
traff Request Summary

troff Request

Summary ..................................................................................................... 173

A
traff Request Summary

This appendix is a quick-reference summary oftroff and nroff requests. In
the following table, values separated by a : are for nroff and troff respectively.
The notes in column four are explained at the end of this summary.
Table A-I

Summary oJnroff andtroff Requests
Initial
Value

Request
Form

If No
Argument

.ab text

none

User Abort

.ad c

adj,both

adjust

Notes

Explanation
Displays text and tenninates without
further processing; flush output buffer.

Adjust output lines with mode c from
.

. af Rc

Assign fonnat to register R (c

Arabic

1, i,

I,a,A).

. am xxyy

.yy= ..

Append to a macro .

. as xx string

ignored

Append string to string xx.

. bd FN

off

Embolden fontF by N-l units.t

.bd S FN

off

Embolden Special Font when current
font is F.t

.bp ±N

N=1

B:j:,v

Eject current page. Next page is
numberN.

. br

Break.

.c2 c

Set nobreak control character to c.

. cc c

Set control character to c .

173

Revision A, of9 May 1988

174

Using nroff and troff

Table A-I

Summary oJnroff and troff Requests- Continued

Request
Form
.ce N

Initial
Value
off

IJNo
Argument
N=l

.ch xxN
.cs FNM

off

.cu N

off

.da

.de xxyy

Notes
B,E

Explanation
Center following N input text lines.

Change trap location.

Constant character space (width) mode
(fontF).t

N=l

Continuous underline in nroff; like
. ul in t roff.

end

Divert and append to xx.
Define or redefine macro xx; end at call

.YY= ..

ofyy.

.di

end

.ds xx string

ignored

.dt Nxx

off

.ec c

Define a string xx containing string.
D,v

Else portion of if-else .
none

. eo

.ev N

N=O

End macro is xx .

none

Turn off escape character mechanism .
previous

Environment switched (push down).

. ex
.fc ab

Set a diversion trap.
Set escape character.

. el anything
• em

Divert output to macro xx.

Exit from nroff/troff .
off

off

Set field delimiter a and pad character

b.
.f i

fill

B,E

.f 1
.fp NF

B
R,I,B,S

ignored

Fill output lines.
Flush output buffer.
Font named F mounted on physical
position 1~~4.

Revision A, of9 May 1988

Appendix A - troff Request Summary

Table A-I

Summary oJnroff and troff Requests- Continued

Request
Form

Initial
Value

.ft F

Roman

. fz SFN

none

.hc c

.hw word1 ...

ignored

.hy N

If No
Argument
previous

Notes
E

Explanation
Change to font F = x, xx, or 1 through
4. Also \fr, \f(xx, 'iN.
Forces font F or S for special characters
to be in size N.

Hyphenation indicator character c.
Exception words.

Hyphenate. N = mode.

· ie c anything

If portion of if-else; all above forms
(like. if).

· if c anything

If condition c true, accept anything as
input, for multi-line use \{anything V.

· if ! c anything

If condition c false, accept anything.

· if N anything

If expression N > 0, accept anything.

· if !N anything

If expression N

· if 'string1 'string2 ' anything

If string1 identical to string2, accept
anything.

· if ! 'string1 'string2 ' anything -

If string1 not identical to string2,
accept anything .

. iq yy
. in ±N

175

.yy= ..
N=O

0, accept anything.

Ignore until call of yy .
B,E,m

Indent.

.it Nxx

off

Set an input-line count trap.

. lc c

none

Leader repetition character.

.lq N

.11 ±N

6.5 in

E,m

. 1s N

N=1

Ligature mode on if N>O.
Line length .
Output N-I V s after each text output
line.

Revision A, of 9 May 1988

176

Using nroff and troff

Table A-I

Summary o/nroff and traff Requests- Continued
Initial
Value

Request
Form
. It ±N
.InC

6.5 in

.mk R

none

II No
Argument

Notes

Explanation

E,m

Length of title .

off

E,m

Set margin character c and separation
N.

internal

Mark current vertical place in register

R.
.na

adjust

.ne N

N=lV

No output line adjusting.

D,v

Need N vertical space (V = vertical
spacing).

B,E

No filling or adjusting of output lines.

.nf

fill

.nh

hyphenate

No hyphenation.

.nm±NMSI

off

Number mode on or off, set parameters.

Do not number next N lines.

.nn N

N=l

.nr R±NM

Define and set number register R by

±N; auto-increment by M.

.ns
. nx

space

filename

Next file.

end-of-file

. os

.pc e

Tum no-space mode on.

Output saved vertical distance .
%

off

Page number character.

.pi program

Pipe output to program (nroff only).

.pm t

Print macro names and sizes. If t
present, print only total of sizes .

all

. ps ±N

10-point

Point size, also \S±N.t

.pl ±N

11 in

Page length.

.pn ±N

N=l

ignored

.po ±N

0: 26/27 in

Next page number is N.
v

Page offset.

Revision A, of 9 May 1988

Appendix A -

Table A-I

troff Request Summary

Summary oJnraff and traff Requests-- Continued
Initial
Value

Request
Form

IJNo
Argument

Notes

Explanation

. rd prompt

prompt=BEL

Read insertion.

.rn xxyy

ignored

Rename request, macro, or string xx to
yy.

ignored

Remove request, macro, or string.

.rIn

Remove register R .

. rr R

.rs

.rt ±N

none

internal

Restore spacing. Turn no-space mode
off.

D,v

Return (upward only) to marked vertical place.
Interpolate contents of source file name
when . so encountered.

. so filename

.sp N

.ss N

177

N=lV

12{36 em

.sv N

B,v

ignored

Space-character size set to N/36 em.t

N=lV

Save vertical distance N.

E,rn

.ta Nt ...

0.8: O.Sin

none

.tc e

space

removed

ignored

B,E,m

.ti ±N

Space vertical distance N in either
direction.

. tl 'left 'center 'right'

Tab settings: left type, unless t equals R
(right), or C (centered).
Tab repetition character.
Temporary indent.
Three-part title.

.tm string

Print string on terminal (to standard
error) .

newline

. tr abed....

none

. uf F

Italic

. ul N

off

N=l

Translate a into b, c into d, etc. on output.
Underline font set to F (to be switched
to by . ul) .

Underline N input lines (italicize in
troff) .

•~~~sun

microsystems

Revision A, of 9 May 1988

178

Using nroff and troff

Table A-I
Request
Form
. vs N

Summary oJnroff and troff Requests- Continued
Initial
Value
1I6in: 12pts

If No
Argument
previous

.wh Nxx

Explanation

Notes
E,p
v

Vertical base line spacing (V) .
Set location trap. Negative is with
respect to page bottom.

t Point size changes have no effect in nroff.

+The use of ' as the control character (instead of .) suppresses the break function.
Table A-2
Note

B
D
E

P
v
p
m
u

Notes in the Tables

Explanation

Request nonnally causes a break.
Mode or relevant parameters associated with current diversion level.
Relevant parameters are a part of the current environment.
Must stay in effect until logical output.
Mode must be still or again in effect at the time of physical output.
Default scale indicator - if not specified, scale indicators are ignored.
Default scale indicator - if not specified, scale indicators are ignored.
Default scale indicator - if not specified, scale indicators are ignored.
Default scale indicator - if not specified, scale indicators are ignored.

Revision A, of 9 May 1988

B
Font and Character Examples

Font and Character Examples ............................................................................................. 181
B.1. Font Style Examples .....................................................................................................

181

B.2. Non-ASCII Characters and minus on the Standard Fonts ..........................

182

B.3. Non-ASCII Characters and " ',G, +, -, =, and * on the Special
Font .........................................................................................................................................

182

B
Font and Character Examples
B.1. Font Style Examples

The following fonts are printed in 12-point, with a vertical spacing of 14-point,
and with non-alphanumeric characters separated by lA-em space. They are Times
Roman, Italic, Bold, and a special mathematical font.

Times Roman
abcdefghijklmnopqrstuvwxyz
ABCDEFGIDJKLMNOPQRSTUVWXYZ

1234567890
!$%&()"*+-.,/:;=?[]I
• 0 - - _ IA ~ % fi fl ff ffi ffl 0

t ' ¢ ® © TM

Times Italic
abcdefg hijklmnopqrstuvwxyz

ABCDEFGHllKLMNOPQRSTUVWXYZ
1234567890
!$%&()"*+-.,I:;=?[]/

• 0 - - _ 114 lh 314 fiflffffiffl 0 t' ¢ ® © TM
Times Bold
abcdefghijklmnopqrstuvwxyz
ABCDEFGHUKLMNOPQRSTUVWXYZ

1234567890
!$% &()"*+-.,/:;=?[]I
- _ 1;" ~

•0 -

¥4

fi ft ff ffi fft

t ' ¢ ® © TM

Special Mathematical Font
"

'\ A

,_ /

< > { } #@+_=*

apyOE~~etKA~v~oxpO~~U$X~ro

rL\8AEII1:YlJIQ
-V-~~=-~:#~f- i .tx+±U(lC::)C::)ood
§ V -, f oc 0

+~t!!

E =I:

~ <= lor L1Ji

r I LJ rl I

181

Revision A, of 9 May 1988

182

Using nroff and troff

B.2. NOn-ASCII Characters
and minus on the
Standard Fonts

Char

Input
Name

\(em
\(hy

•

Ih
3A

B.3. Non-ASCII Characters
and ',', ,+, -, =, and
* on the Special Font

Table B-1

Char

+
=

*
§

ex
~
y

8
e
~
11

e
t

\(bu
\(sq
\(ru
\(14
\(12
\(34

Character
Name

Char
fi
fl
ff
ffi
ffl

close quote
open quote
3/4 Em dash
hyphen or
hyphen
current font minus
bullet
square
rule
1/4

t
¢

®
©

1/2

Input
Name

Character
Name

\(fi
\(fl
\(ff
\(Fi
\(Fl
\(de
\(dg
\(fm
\(ct
\(rg
\(co

fi
fl
ff
ffi
ffl
degree
dagger
foot mark
cent sign
registered
copyright

3/4

The ASCII characters @, #, ", " " <, >, \ {, }, -, "', and _ exist only on the special
font and are printed as a I-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.

Summary oftroff Special Characters

Input
Name

Character
Name

\(pl
\ (mi
\(eq
\(**
\(sc
\(aa
\(ga
\(ul
\(sl
\(*a
\(*b
\(*g
\(*d
\(*e
\(*z
\(*y
\(*h
\(*i

math plus
math minus
math equals
math star
section
acute accent
grave accent
underrule
slash (matching backslash)
alpha
beta
gamma
delta
epsilon
zeta
eta
theta
iota

+~!t!!

Char
cr
<;
't

u
=
\«=
\(==
\(-=
\(ap
\ (! =
\(->

kappa
lambda
mu
nu
xi
omicron
pi
rho
Taut
Upsilon
Phi
Chit
Psi
Omega
square root
root en extender
>=
<=
identically equal
appro x =
approximates
not equal
right arrow

\«-

\(ua
\(da
\ (mu

left arrow
up arrow
down arrow
multiply

\(di

Char
K:

v
~
0
1t

p
T
y

X
'P

n
...J
~
~

;::::

t:
~

Char
A
M
N

...
......

n
P
L

a
V
--,

J
oc

0
E

I
=1=

=>
¢=

r
L

Input
Name

Character
Name

\(*L
\(*M
\(*N
\(*C
\(*0
\(*P
\(*R
\(*S
\(if
\(pd
\(gr
\(no
\(is
\(pt
\(es
\ (mo
\(br
\(dd
\(rh
\(lh
\(or
\(ei
\(It

Lambda
Mut
Nut
Xi
Omicront
Pi
Rhot
Sigma
infinity
partial derivative
gradient
not
integral sign
proportional to
empty set
member of
box vertical rule
double dagger
right hand
left hand
or
circle
left top of big curly
bracket
left bottom
right top
right bot
left center of big
curly bracket
right center of big
curl y bracket
bold vertical
left floor (left bottom
of big square bracket)
right floor (right
bottom)
left ceiling (left top)
right ceiling (right top)
backslash (escape character;

\(lb
\(rt
\(rb
\(lk

divide

\(rk

\(+\(eu

plus-minus
cup (union)

I
L

\(bv
\(If

()

\(ea

cap (intersection)

\(rf

\(sb
\(sp
\(ib
\(ip

subset of
superset of
improper subset
improper superset

!
x

::)

~
~

183

1
j

1
\

\(Ie
\(re
\e

Revision A, of 9 May 1988

8
Manipulating Files

Manipulating Files ....................................................................................................................... 185
8.1. Comparing Different Files .........................................................................................

185

Comparing Binaries with crop ..............................................................................

185

Comparing Text with di f f .................................................................................

186

diff -First Form ...............................................................................................

187

Second Form .........................................................................................

187

diff -Third Form .............................................................................................

187

diff -

diff3 .............................................................................................

191

Finding Common Lines with cormn .................................................................

192

Combining Files with join ................................................................................

195

Repeated Lines and uniq .....................................................................................

196

8.2. Modifying Files ................................................................................................................

197

8.3. Printing Files ................. .....................................................................................................

197

Three Files -

8
Manipulating Files
8.1. Comparing Different
Files

Occasionally you want to know whether two files are identical, or if they are not,
what the differences are. There exist several different text utilities for comparing
the contents of files. You can choose the command best for the task at hand,
based on what kind of infonnation it conveys to you. Most of the commands
issue no output if the files are the same. Some return terse output stating barely
more than the fact that the files differ. Others give a more complete summary of
how the files differ and how you would have to modify one file to match the
other(s).
The command crop is an example of a command that issues terse output. At
most, crop prints the byte and line number where the files differ. Two other
functions for directly comparing files are diff and camm. camm compares two
files, putting the comparison infonnation into three different columns: column
one lists lines only injilel, column two lists lines only injile2, and column three
lists lines common to both files. di f f compares files and also directories. A
special version of diff, diff3, also compares three files, identifying the
differing contents with special flags.
The relational database operator j a in compares a specific field or fields in two
files. Each time j a in finds the compared fields in the two files identical, it produces one output line.
For comparing adjacent lines in a single file, there is the command uniq. uniq
can be made to report merely the repeated lines or to count them or to remove all
but the first occurrence.

Comparing Binaries with crop

The command crop is for comparing two files. The synopsis of the crop command is:
( cmp [-1]

[-8] file 1 file2

crop comparesjilel andjile2. Iffilel is the standard input ('-'), crop reads from
the standard input. Under default options, cmp makeS no comment if the files
are the same. If the files differ, crop announces the byte and line number at
which the difference occurred. If one file is an initial subsequence of the other,
that fact is noted.

185

Revision A, of9 May 1988

186

Editing Text Files

The options available with crop are:
-1 Print the byte number (decimal) and the differing bytes (octal) for each

difference.
-g

Comparing Text with diff

Print nothing for differing files; return codes only.

For summarizing the differences between two files or directories, diff is the
appropriate tool. To use the di f f command, you would follow one of these
models:
di££ [-cefh]

[-b] filelfile2

di££ [-D5tring]
di££ [-1]

[-r]

[-b] filelfile2
[-5]

[ ]

[-Sname]

[-cefh]

[-b] dirl dir2

diff is a differential file comparator. When run on regular files, and when com-

paring text files that differ during directory comparison (see the notes below on
comparing directories), diff tells what lines must be changed in the files to
bring them into agreement. Except in rare circumstances, diff finds a smallest
sufficient set of file differences. If neither filel nor file2 is a directory, either may
be given as '-', in which case the standard input is used. Ufilel is a directory, a
file in that directory whose file-name is the same as the file-name of file2 is used
(and vice versa).
There are several options for output format; the default output format contains
lines of these fonns:
[ nl a nJ.n4
nl,n2 d n3
~l ,n2 c n3 ,n4

These lines resemble ed commands to convertfilel intofile2. The numbers after
the letters pertain to file2. In fact, by exchanging 'a' for 'd' and reading backward you can see how to convertfile2 into filel. As in ed, identical pairs where
nl = n2 or n3 = n4 are abbreviated as a single number.
Following each of these specification lines come all the lines that are affected in
the first file flagged by the character '<', then all the lines that arc affected in the
second file flagged by the '>' character.
If both arguments are directories, di f f sorts the contents of the directories by
name, and then runs the regular file di f f program as described above on text
files that are different. Binary files that differ, common subdirectories, and files
that appear in only one directory are listed.

Revision A, of 9 May 1988

Chapter 8 - Manipulating Files

di f f -

First Form

187

To produce a script of append (a), change (c), and delete (d) commands for the
editor ed, which will recreatefile2 fromfileJ, use the first form of diff with the
option -e.
Extra commands are added to the output when comparing directories with diff
-e, so that the result is a Bourne shell (sh) script for converting text files common to the two directories from their state in dir J to their state in dir2.
To produce a script similar to that using -e, but in the opposite order, that is, to
recreatefilel fromfile2, use diff -f. The script generated with the -f option
is not useful with ed, however.
To surround the specification lines the simplest use of diff puts out with some
lines of context, use di f f -c. The default is to present three lines of context.
To change this (to 10, for example), add 10 to the -c option (-cl0). With the-c
option, the output format is slightly different from other di f f output. It begins
by identifying the files involved and the dates they were created. Then each
change is separated by a line with a dozen stars (*). The lines removed fromfilel
are marked with '-'; those added to file2 are marked '+'. Lines that are changed
from one file to the other are marked in both files with' !'.
If you know you've only made small changes to the files you are comparing, and
you want to speed up the time diff takes to work, you can use diff -h. This
command only does a fast, half-hearted job. diff -h works only when changed
stretches are short and well-separated, but does work on files of unlimited length.
Except for the -b option, which my be given with any of the others, the options
-c, -e, -f, and -h are mutually exclusive.

di f f -

Second Form

To create a merged version offilel andfile2 on the standard output with C
preprocessor controls included, use the second form of diff with the option Dstring. Compiling the result without defining string is equivalent to compiling
file 1 , while compiling the result with string defined will yieldfile2.
If you want diff to ignore trailing blanks (spaces and tabs), use the option -b.
Other strings of blanks compare equal. The way di f f works, when it compares
directories with the -b option specified, diff first compares the files (as in
cmp), and then decides to run the di f f algorithm if they are not equal. This
may cause a small amount of spurious output if the files then tum out to be identical, because the only differences are insignificant blank string differences.

di f f -

Third Form

When comparing directories, you might be interested in several different things.
If diff puts out a lot of output, you probably want to use the -1 option (for
long output). Each text file di f f is piped through the program pr to paginate it,
(see "Printing Files" later in this manual). Other differences are remembered and
summarized after all text file differences are reported.
To compare directories and subdirectories, use the -r option. -r applies di f f
recursively to common subdirectories encountered.
Since di f f ordinarily only outputs information on files and directories that
differ, if a file or several files are identical in directories you are comparing, you
won't see the identical files listed in the output. The -8 option reports files that
Revision A, of 9 May 1988

188

Editing Text Files

are the same, in addition to the usual di f f output, which are otherwise not mentioned.
Here are two directories, macros and new. For this example, here are lists of
their contents.
hostname% 1s macros
Makefile
SunMacros.msun
contents.pic
contentsfile.msun
document.styles.msun
intro.msun

making. index. msun
mechanisms.msun
mmemo.7
model.makefile.msun
process.pic
structures.msun

summary.msun
test.tr
text.effects.msun
troff.msun

hostname% 1s new
Makefile
SunMacros.msun
contents.pic
contentsfile.msun
document.styles.msun
intro.msun

making. index. msun
mechanisms.msun
mmemo.7
model.makefile.msun
process.pic
structures.msun

summary. msun
test.tr
text.effects.msun
troff.msun

Right now these two directories are identical. The output of dif f for these two
directories macros and new, if there are no differences is:

]

( hostname% diff macros new

The nonnal output is nothing, no response. Now if we edit some files and
remove some others in the directory new, leaving the files like this:
hostname% 1s macros new
macros:
Makefile
making.index.msun
SunMacros.msun
mechanisms.msun
contents.pic
mmemo.7
contentsfile.msun
model.makefile.msun
document.styles.msun process.pic
structures. msun
intro.msun
new:
Makefile
SunMacros.msun
contents.pic
document.styles.msun

intro.msun
making.index.msun
mechanisms.msun
model.makefile.msun

summary.msun
test.tr
text.effects.msun
troff.msun

structures .msun
summary .msun
text.effects.msun
troff.msun

Revision A. of 9 May 1988

Chapter 8 - Manipulating Files

189

The regular diff output looks like this:
hostname% diff macros new
diff macros/Makefile new/Makefile
7c7
< FORMATTER
/usr/local/iroff

> FORMATTER
/usr/doctools/bin/troff
Only in macros: contentsfile.msun
diff macros/intro.msun new/intro.msun
Oal
> .LP
6,lOc7,9
< Document preparation at Sun Microsystems relies on variations of the
< .I troff
< text formatter as the underlying mechanism for turning your wishes into
< printed words and outlines on paper. Using
< .I troff
> Document preparation at Sun Microsystems relies on variations of the
> troff text formatter as the underlying mechanism for turning your wishes
> into printed words and outlines on paper. Using troff
Only in macros: mmemo.7
diff macros/model.makefile.msun new/model.makefile.msun
3,7c3
< The
< .I Makefile
< below is the
: < . I Makefile
< used to actually make this document:
> The Makefile below is the Makefile used to actually make this document:
Only in macros: process.pic
Only in macros: test.tr
hostname%

The output of diff is rather cryptic. But if you look carefully at the
specification lines and the direction of the angle brackets, you can decipher the
results accurately.
To get a more complete picture of how the two directories compare, you might
want to know which files are identical and which files exist only in one directory.
For this, you use di f f -8. The di f f -8 output from our example above
looks like this:

Revision A, of 9 May 1988

190

Editing Text Files

hostname% diff -s macros new
diff -s macros/Makefile new/Makefile
7c7
< FORMATTER
/usr/local/iroff

> FORMATTER
/usr/doctools/bin/troff
Files macros/SunMacros.msun and new/SunMacros.msun are identical
Files macros/contents.pic and new/contents.pic are identical
Only in macros: contentsfile.msun
Files macros/document.styles.msun and new/document.styles.msun are identical
diff -s macros/intro.msun new/intro.msun
Oal
> .LP
6,lOc7,9
< Document preparation at Sun Microsystems relies on variations of the
< .1 troff
< text formatter as the underlying mechanism for turning your wishes into
< printed words and outlines on paper. Using
< .1 troff
> Document preparation at Sun Microsystems relies on variations of the
> troff text formatter as the underlying mechanism for turning your wishes
> into printed words and outlines on paper. Using troff
Files macros/making.index.msun and new/making.index.msun are identical
Files macros/mechanisms.msun and new/mechanisms.msun are identical
Only in macros: mmemo.7
diff -s macros/model.makefile.msun new/model.makefile.msun
3,7c3
< The
< .1 Makefile
< below is the
< .1 Makefile
< used to actually make this document:

> The Makefile below is the Makefile used to actually make this document:
Only in macros: process.pic
Files macros/structures.msun and new/structures.msun are identical
Files macros/summary.msun and new/summary.msun are identical
Only in macros: test.tr
Files macros/text.effects.msun and new/text.effects.msun are identical
Files macros/troff.msun and new/troff.msun are identical
hostname%

To compare two directories beginning somewhere in the middle of the directories, use the option - Sfilename where filename is a file in one of the directories
you are comparing. The syntax for this command is

(~d_i_f_f__-_S_~_k_n_anre
___d_U_l_~_·r_2______________________________________~]
For example, comparing the two directories from the example above, and

Revision A, of 9 May 1988

Chapter 8 -

Manipulating Files

191

beginning with the file model.makefile .msun:
hostname% diff -Smode1.makefi1e.msun macros new
diff macros/model.makefile.msun new/model.makefile.msun
3,7c3
< The
< .I Makefile
< below is the
< .I Makefile
< used to actually make this document:

> The Makefile below is the Makefile used to actually make this document:
Only in macros: process.pic
Only in macros: test.tr

Three Files -

di f f 3

If you have three versions of a file that you want to compare at once, use the
diff3 command. The synopsis for the diff3 command is:

]

( 141
· cu (continuously underline) request, 29

o
\0 (digit-size space) function, 134

A
\a (leader character) function, 72
· a (post-line extra space) number register, 52
· ab (abort) request, 166

access format for number registers, 125
accessing strings, 98
· ad (adjust) request, 21
adjusting, 17
center, 21
flush left, ragged right, 21
flush right, ragged left, 21
justified, 21
· af (format of number register) request, 125
• am (append to a macro) request, 112
append to a
diversion, 114
macro, 112
string, 99
arguments to macros, 109
arithmetic expressions with number registers, 124
· as (append to string) request, 99
auto-incrementing number registers, 123
automatic hyphenation, 24

B
\b (bracket) function, 142
backslash - how to print it in troff, 9
basic request, 8
· bd (boldface) request, 60
begin page, 41
blank lines, 19
bold-face request, 60
box lines, 145
· bp (start new page) request, 41

D
\d (move down) function, 131
· d (vertical place in current diversion) number register, 114
· da (append to a diversion) request, 114
· de (define macro) request, 105

-201-

Index - Continued

defining troff objects
macros, 105
number registers, 121
strings, 98
deleting number registers, 127
device resolution, 10
· di (divert text) request, 114
diversion traps, 114, 116
diversions, 113, 114
divert text, 114
dl (width of last finished diversion) number register, 113
dn (height of last finished diversion) number register, 113
document preparation
formatters, 3 thru 13
nroff program, 3 Ihr" 13
text formatters, 3 Ihru 13
troff program, 3 Ihr" 13
drawing in troff
boxes, 145
brackets, 142
horizontal lines, 143
vertical lines, 143, 144
· ds (define string) request, 98
· dt (set a diversion trap) request, 116
dy (day of month) number register, 121

general number registers
%-page-number, 42,121
et - character type, 141
dl - width of last finished diversion, 113
dn - height of last finished diversion, 113
dy -day of month, 121
mo -month of year, 121
nl - vertical position of last baseline, 121, 113
sb - string depth below baseline, 140
s t - string height above baseline, 140
yr -last two digits of year, 121
get vertical space request, 47

H
\h (horizontal motion) function, 133
• h (text high-water mark) number register, 18, 114
half em-space, 136
half-line motions
\d (move down) function, 131
\ u (move up) function, 131
hanging indent, 39
hard blank, 17
• he (hyphenation character) request, 26
headers, 81, 85
horizontal lines, 143
horizontal motion, 133, 134, 136, 138
horizontal place marker, 141
• hw (hyphenate word) request, 25
· hy (hyphenate) request, 24,25
hyphenation, 24
automatic, 24
control,24
indicator, 25
indicator character, 26
special cases, 25
specuyinglocation, 25
tum on and off, 24

E
· ee (set escape character) request, 149
· el (else conditional) request, 159
• em (set the end-of-processing trap) request, 117
end-of-file, 19
end-of-processing traps, 117
end-of-sentence,18
environmentswioching, 169
· eo (set escape off) request, 149
escape character, 149
escape code for elM, 196
· ev (switch environment) request, 169
· ex (terminal message) request, 94
expressions with number registers, 124

I
· i (current indent) number register, 38, 40
· ie (if-else conditional) request, 159
· if (conditional processing) request, 157
· ig (ignore lines) request, 160

F
· f (current font) number register, 62

· fe (set field characters) request, 74
· fi (fill) request, 23

ignoring input lines, 160
· in (indent) request. 37
in-line functions
\ (unpaddable space) function, 136
\ & (zero-width non-printing) function, 137
(thin space) function, 136
\ I (thick space) function, 136
\ 0 (digit-size space) function, 134
\ a (leader character) function, 72
\b (bracket) function, 142
\e (continuation line) function, 20
\d (move down) function, 131
\h (horizontal motion) function, 133
\k (mark horizontal position) function, 141
\ 1 (horizontal line) function, 143
\L (vertical line) function, 144, 143
\ 0 (overstrike) function, 138

field character, 74
fields, 74
fill request, 23
filler character, 18
filling, 17
· fl (flush buffer) request, 166
flash code, 196, 196
flush output buffer, 166
font position request, 59
footers, 81, 85
force font size request, 59
· fp (change font position) request, 59
· ft (set font) request, 58
· f z (force font size) request, 59

-202-

Index - Continued

local motions, continued
(thin space) function, 136
\ I (thick space) function, 136
\0 (digit-size space) function, 134
\b (bracket) function, 142
\d (move down) function, 131
\h (horizontal motion) function, 133
\ 1 (horizontal line) function, 143
\L (vertical line) function, 144, 143
\0 (overstrike) function, 138
\r (reverse line) function, 143
\u (move up) function, 131
\ v (vertical motion) function, 132
\ z (zero motion) function, 139
long lines, 10
.1s (change line spacing) request, 51
· It (set length of title) request, 83

in-line functions, continued
\p (break and spread) function, 19
\r (reverse line) function, 143
\ u (move up) function, 131
\ v (vertical motion) function, 132
\w (width) function, 140
\x (get extra line space) function, 52
\ z (zero motion) function, 139
include
from file, 89
from standard input, 92
incrementing number registers, 123
indentation
first line of paragraph, 38
permanent, 37
temporary, 38
input-line-count traps, 114, 116
interpolating number registers, 121, 125
interrupted line, 20
· it (set an input-line-count trap) request, 116
italic correction, 136
itemized lists, 39

M
macros,9,105
append to, 112
arguments to, 109
copy mode, 112
defining, 105
embedded blanks, 111
invoking, 105
print names and sizes, 165
remove, 107
renaming, 108
margin character, 145
margins on a page
with nroff and troff, 21, 35
mark
horizontal position, 141
vertical position, 43, 114
• me (margin character) request, 145
measure, 35
• mk (mark vertical position) request, 43, 114
mo (month of year) number register, 121

J
· j (current adjustment indicator) number register, 21

K
\k (mark horizontal position) function, 141

L
\1 (horizontal line) function, 143
\L (vertical line) function, 144, 143
· 1 (line-length) number register, 36
large boxes, 145
.1c (set leader character) request, 73
leaders and leader characters, 71, 72
left margin, 35
length of title, 83
.1g (set ligature mode) request, 63
ligatures, 63
line adjusttnent indicators
both,21
center, 21
indentation, 37
left, 21
normal,21
right, 21
line drawing
functions, 143, 144
horizontal, 143
vertical, 143, 144
line numbering
start, 153
suspend,154
line spacing request, 51
line-length, 35
.11 (set line-length) request, 35
local motions, 132
\ (unpaddable space) function, 136
\ & (zero-width non-printing) function, 137

N
· n (text length) number register, 18
· na (no adjust) request, 22
· ne (need space) request, 42
need space, 42
newpage, 41
· nf (no fill) request, 23
· nh (no hyphenation) request, 25, 24
nl (vertical position of last baseline) number register, 121, 113
· nm (number lines) request, 153
· nn (no number) request, 154
no adjust request, 22
no fill request, 23
no hyphenation request, 24, 25
no space mode request, 53
no-break control character setting, 150
non-printing character, 137
· nr (set number register) request, 121
n roff command
exit from, 94
introduction to, 3, 13
-203-

Index - Continued

predefined number registers, continued
sb - string depth below baseline, 140
st - string height above baseline, 140
yr -last two digits of year, 121
print macros, 165
Procrustean mold, 23
. ps (change point size) request, 49

· n s (no space mode) request, 53
number registers, 121
access format, 125
auto-incrementing, 123
creating, 121
expressions, 124
interpolating, 121
removing, 127
setting, 121
numbering lines, 153, 154
· nx (next file) request, 91

R
\r (reverse line) function, 143
. rd (read standard input) request, 92
read-only number registers
• $ - number of arguments, 109
· a - post-line extra space, 52
· d - vertical place in current diversion, 114
· f - current font, 62
· h - text high-water mark, 18, 114
· i-current indent, 38, 40
· j - current adjustment indicator, 21
.1-line-Iength,36
· n - text length, 18
•0 page-offset, 35
· p - page-length, 41
· s - point-size, 49
· t - distance to next trap, 113, 115
· u - fill mode indicator, 23
· v - vertical spacing, 51
• z -name of current diversion, 114
reading from standard input, 92
referencing strings, 98
removing
macro definitions, 107
number registers, 127
string definitions, 107
renaming macros and strings, 108
requests, 8
· ab - abort, 166
· ad - adjust, 21
· af - format of number register, 125
· am - append to a macro, 112
· as - append to string, 99
· bd - break line, 60
· bp - begin page, 41
· br - break line, 20, 19
· e2 - set no-break control character, 150
· ee - set control character, 150
· ee - center lines, 28, 27 thru 28
· eh - change position of a trap, 116
· es - constant spacing, 54
· eu - continuously underline, 29
· da - append to a diversion, 114
· de - define macro, 105
· di - divert text, 114
· ds - define string, 98
· dt - set a diversion trap, 116
· ee - set escape character, 149
· el - else conditional, 159
· em - set the end-of-processing trap, 117
· eo - set escape off, 149
· ev - switch environment, 169
· ex - exit from nroff or troff, 94
· fe - set field characters, 74
· fi - fill, 23

o
(overstrike) function, 138
.0 (page-offset) number register, 35
one-twelfth em-space, 136
orphans, 43
· os (output saved vertical space) request, 53
output saved vertical request, 53
overstriking, 138
\ 0

P
\p (break and spread) function, 19
· p (page-length) number register, 41
padding indicators, 74
page length changes, 41
page number, 42, 84
page traps, 114
page-offset, 35
· pc (set page number character) request, 84
· pi (pipe to program) request, 91
pipe to program, 91
· pI (set page length) request, 41
· pm (print macros) request, 165
· pn (set page number) request, 42
· po (set page-offset) request, 35
point size request, 49
predefined number registers
% -page-number, 42,121
• $ - number of arguments, 109
· a - post-line extra space, 52
· d - vertical place in current diversion, 114
• f - current font, 62
· h - text high-water mark, 18, 114
· i-current indent, 38, 40
· j - current adjustment indicator, 21
· I -line-length, 36
· n - text length, 18
• 0 page-offset, 35
· p - page-length, 41
· s - point-size, 49
· t - distance to next trap, 113, 115
· u - fill mode indicator, 23
· v - vertical spacing, 51
· z - name of current diversion, 114
ct - character type, 141
d l - width of last finished diversion, 113
dn - height of last finished diversion, 113
dy - day of month, 121
mo - month of year, 121
n I - vertical position of last baseline, 121, 113
-204-

Index - Coruinued

requests, continued
• f1-flush buffer, 166
· fp - font position, 59
· ft - set font, 58
· f z - force font size, 59
• he - hyphenation character, 26
· hw - hyphenate word, 25
.hy-hyphenate, 24, 25
· ie - if-else conditional, 159
• if - conditional processing, 157
· ig - ignore lines, 160
• in - indent, 37
· it - set an input-line-count trap, 116
.1e - set leader character, 73
· 19 - set ligature mode, 63
.11- set line-length, 35
.15 -line spacing, 51
· It - set length of title, 83
· me - margin character, 145
• mk - mark vertical position, 43, 114
· na - no adjust, 22
.ne -need space, 42
· nf - no fill, 23
· nh - no hyphenation, 25, 24
· nm - number lines, 153
· nn - no numbering, 154
· nr - set number register, 121
· ns - no space mode, 53
· nx - read next source file, 91
· os - output saved vertical space, 53
· pc - set page number character, 84
· pi - pipe to program, 91
· pI - set page length, 41
· pm - print macros, 165
· pn - set page number, 42
· po - set page-offset, 35
· ps -point size, 49
· rd - read from standard input, 92
removing, 107
renaming, 108
· rm - remove request, macro, or string, 107
· rn - rename request, macro, or string, 108
· rr - remove number register, 127
· rs - restore space mode, 53
· rt - return to position, 44, 114
· so - switch source file, 89
· sp - space, 47
· s s - set space size, 54
• sv - save vertical space, 52
· ta - set tab stops, 67
· tc - set tab character, 69
· t i-temporary indent, 38
· t 1 - define title, 85
· tm - tenninal message, 94
· tr - translate characters, 150
· uf -underline font, 29
· u1 - underline, 28
· vs - vertical spacing, 51
· wh - when something, lIS, 82
resolution, 10
restore space mode request, 53
return to marked vertical position, 114
return to vertical position, 44

reverse line function, 143
revision bars, 145
right-adjusted tabs, 68
· rm (remove request, macro, or string) request, 107
· rn (rename request, macro, or string) request, 108
· rr (remove number register) request, 127
· rs (restore space mode) request, 53
· rt (return to position) request, 44, 114
rules
horizontal,143
vertical, 143, 144
running headers and footers, 81, 85

s
· s (point-size) number register, 49
save vertical space request, 52
saving state, 169
sb (string depth below baseline) number register, 140
sentence endings, 18
set font request, 58
set ligature mode request, 63
set page number, 42
set space-character size request, 54
setting line-length, 35
setting number registers, 121
setting tabs, 67
skipping input lines, 160
· so (switch source) request, 89
· sp (get vertical space) request, 47
space request, 47
spaces, 19
· s s (set space-character size) request, 54
st (string height above baseline) number register, 140
standard input
reading t ro f f input from, 92
start line numbering, 153
start new page, 41
strings, 97
accessing, 98
appending to, 99
beginning with blanks, 98
defining, 98
removing, 107
renaming, 108
substituting characters, 150
suspend line numbering, 154
· sv (save vertical space) request, 52
switch source file, 89

T
· t (distance to next trap) number register, 113, 115
· ta (set tab stops) request, 67
tabs
absolute, 68
centered, 68
relative, 68
replacement character, 69
right-adjusted, 68
setting, 67

-205-

Index - Continued

· t c (set tab character) request, 69
temporary indent of one line, 38
text lines
as trof f input, 8
ignoring, 160
words in, 17
thick space, 136
thin space, 136
three-part titles, 85
· ti (temporary indent) request, 38
title length, 83
titles, 81
· t l (title) request, 85
• tm (terminal message) request, 94
· tr (translate characters) request, 150
translating characters, 150
transparent throughput, 10
traps
change position of, 116
diversion, 116
end-of-processing, 117
input-line-count, 116
page, 114
troff command
exit from, 94
introductionto,3,13
turn escape mechanism on and off, 149

\x (get extra line space) function, 52

y
yr (last two digits of year) number register, 121

Z
\ z (zero motion) function, 139
. z (name of current diversion) number register, 114
zero motion function, 139
zero-width character, 18, 137

U
\u (move up) function, 131
· u (fill mode indicator) number register, 23
· uf (underline font) request, 29
· u 1 (underline) request, 28
underline font request, 29
underline request, 28
units, 10
unpaddable space, 17

V
\ v (vertical motion) function, 132
· v (vertical spacing) number register, 51

vertical lines, 143, 144
vertical motion, 132
vertical position
mark,43
return to, 44
vertical spacing request, 51
· vs (change vertical spacing) request, 51

W
\w (width) function, 140
• wh (when something) request, 115, 82
when something request, 82, 115
width function, 140
word,17

-206-

~"sun®
•

microsystems

Formatting Documents

Part Number: 800-1756-10
Revision A, of 9 May 1988

UNIX is a registered trademark of AT&T.
SunOS is a trademark of Sun Microsystems, Inc.
Sun Workstation is a registered trademark of Sun Microsystems, Inc.
Material in this manual comes from a number of sources: Typing Documents on
the UNIX System: Using the -ms Macros with Troff and Nroff, M. E. Lesk, Bell
Laboratories, Murray Hill, New Jersey; A Guide to Preparing Documents with
-ms, M. E. Lesk, Bell Laboratories, Murray Hill, New Jersey; Document Formatting on UNIX Using the -ms Macros, Joel Kies, University of California, Berkeley, California; Tbl-A Program to Format Tables, M. E. Lesk, Bell Laboratories, Murray Hill, New Jersey; A Systemfor Typesetting Mathematics, Brian W.
Kernighan, Lorinda L. Cherry, Bell Laboratories, Murray Hill, New Jersey;
Typesetting Mathematics - User's Guide, Brian W. Kernighan, Lorinda L.
Cherry, Bell Laboratories, Murray Hill, New Jersey; Updating Publications Lists,
M. E. Lesk, Bell Laboratories, Murray Hill, New Jersey; Some Applications of
Inverted Indexes on the UNIX System, M. E. Lesk, Bell Laboratories, Murray
Hill, New Jersey; Writing Papers with Nroff Using -me, Eric P. Allman, University of California, Berkeley; The -me Reference Manual, Eric P. Allman, University of California, Berkeley; and Introducing the UNIX System, Henry McGilton,
Rachel Morgan, McGraw-Hill Book Company, 1983. These materials are gratefully acknowledged.

Copyright © 1987, 1988 by Sun Microsystems, Inc.
This publication is protected by Federal Copyright L~w, with all rights reseIVed.
No part of this publication may be reproduced, stored in a retrieval system,
translated, transcribed, or transmitted, in any form, or by any means manual,
electric, electronic, electro-magnetic, mechanical, chemical, optical, or otherwise, without prior explicit written permission from Sun Microsystems.

Contents

Chapter 1 Introduction to Document Preparation ............................................

1.1. What Do Text Formatters Do? .................................................................................

1.2. What is a Macro Package? .........................................................................................

1.3. What is a Preprocessor? ...............................................................................................

1.4. Typesetting Jargon ..........................................................................................................

1.5. Hints for Typing in Text ..............................................................................................

1.6. Types of Paragraphs .......................................................................................................

Paragraph Illustrations ...............................................................................................

1.7. Quick References .............................................................................................................

Displaying and Printing Documents ..................................................................

Technical Memorandum ...........................................................................................

Section Headings for Documents ........................................................................

Changing Fonts ..............................................................................................................

Making a Simple List .................................................................................................

Multiple Indents for Lists and Outlines ...........................................................

Displays ..............................................................................................................................

Footnotes

Keeping Text Together - Keeps .......................................~.•.. ;",+~ ... ,..... ~~ .....:"."..,..
Double-Column Format .................................................... ,.;" .. ~ ..... ;;.... ~~ ......;::.:;~" .......... ,.;~~<
Sample Tables ..................................................................;•...~ ........ ;;; . . . . . . ,.......................;:':;;::''''';'.«<
Writing Mathematical Equations .......................,;; . .;.;.; .....,.........:•. ;.:....."".:.;....•..:.:...........;.:::
Registers You Can Change ...................................................."......,.':...;" ....:.:.:.:.......:..:.:':':....;..

Chapter 2 Formatting Documents with the -ms Macros ....... .:,:.:;;;.: ..............

- iii-

Contents -

Continued

2.1. Changes in the New -ms Macro Package .........................................................

2.2. Displaying and Printing Documents with -ms ..............................................

2.3. What Can Macros Do? .................................................................................................

2.4. Formatting Requests ......................................................................................................

Paragraphs .........................................................................................................................

. PP ..............................................................................

. LP ..........................................................................

Indented Paragraph -

. IP ...............................................................................

Nested Indentation -

. RS and . RE ...........................................................

Quoted Paragraph -

. QP ..................................................................................

. SHand . NH ....................................................................

Standard Paragraph Left-Block Paragraph -

Section Headings -

Cover Sheets and Title Pages -

. TL and . AU ..........................................

LH, CH, RH .........................................................

.OH, . EH, . OF, and . EF ................

. 2C and . MC .......................................................

. FS and . FE .....................................................................................

Endnotes ........................................................................................................ ~...................

Displays and Tables -

Running Heads and Feet -

Custom Headers and Footers Multi-Column Formats Foomotes -

. DS and . DE ..............................................................

Keeping Text Together -

. KS, . KE and . KF ..........................................

Boxing Words or Lines -

. BX and . Bland . B 2 ..................................

. I, . B, . Rand. UL ........................................................

Changing Fonts -

Changing the Type Size -

. LG, . SM and . NL .........................................

Dates- .DA and .ND ..............................................................................................

Thesis Format Mode -

. TM .................................................................................

. XP ..................................................................................................

Bibliography -

Table of Contents -

. XS, . XE, . XA, . PX .................................................

Defining Quotation Marks .......................................................................................

Accent Marks ..................................................................................................................

2.5. Modifying Default Features ......................................................................................

Dimensions .......................................................................................................................

2.6. Using nroff and troff Requests ....................................................................

2.7. Using -ms with eqn to Typeset Mathematics ................................................

2.8. Using -ms with tbl to Fonnat Tables ..............................................................

-iv-

Contents -

Continued

2.9. Register Names .................................................................................................................

2.10. Order of Requests in Input .......................................................................................

2.11. -ms Request Summary .............................................................................................

Chapter 3 The -man Macro Package .......................................................................

3.1. Parts of a Manual Page .................................................................................................

3.2. Coding Conventions ......................................................................................................

The Header and Footer Line ( . TH) -

Identifying the Page ...............

The NAME Line ...........................................................................................................

The SYNOPSIS Section ..........................................................................................

The DESCRIPTION Section ...............................................................................

The OPTIONS Section ............................................................................................

The FILES Section .....................................................................................................

The SEE ALSO Section ..........................................................................................

The BUGS Section ......................................................................................................

3.3. New Features of the -man Macro Package ......................................................

New Num1:>er Registers ..............................................................................................

Using the Num1:>er Registers ...................................................................................

3.4. How to Fonn.at a Manual Page ................................................................................

Chapter 4 Formatting Documents with the -me Macros ...........................

4.1. Using -me ...........................................................................................................................

4.2. Basic -me Requests .......................................................................................................

Paragraphs .........................................................................................................................

Standard Paragraph -

. pp ..............................................................................

.lp ........................................................................

. i p and . n p ........................................................

Paragraph Reference ..............................................................................................

Left Block Paragraphs -

Indented Paragraphs 4.3. Headers and Footers -

. he and . fa ................................................................

Headers and Footers Reference ............................................................................

Double Spacing -

. Is 2 .....................................................................................

Page Layout .....................................................................................................................

Underlining -

-v-

. ul ....................................................................................................

Contents -

Continued

Displays ..............................................................................................................................
Major Quotes -

. (q and .) q ......................................................................

Lists -

. (1 and . ) 1 ..........................................................................................

Keeps -

. (b and .) b, . (z and .) z ......................................................

4.4. Fancy Displays ..................................................................................................................

Display Reference ........................................................................................................

Annotations ......................................................................................................................

Footnotes -

. (f and . ) f .....................................................................................

Delayed Text ...................................................................................................................

Indexes- . (x .) x and . xp ..............................................................................

Annotations Reference ...............................................................................................

4.5. Fancy Features ..................................................................................................................

Section Headings -

. sh and . uh ....................................................................

Section Heading Reference ...............................................................................

Parts of the Standard Pa{>er .....................................................................................

Standard Paper Reference ...................................................................................

Two-Column Output -

. 2 c .................................................................................

Column Output Reference ..................................................................................

Defining Macros -

. de ..........................................................................................

Annotations Inside Keeps ........................................................................................

4.6. Using traff for Phototypesetting .......................................................................

Fonts .....................................................................................................................................

Point Sizes -

. s z ......................................................................................................

Fonts and Sizes Reference .................................................................................

* (lq and \ * (rq ..............................................................................

4.7. Adjusting Macro Parameters .....................................................................................

4.8.

raff Support ..................................................................................................................

4.9. Preprocessor Support .....................................................................................................

4.10. Predefined Strings .........................................................................................................

4.11. Miscellaneous Requests ............................................................................................

4.12. Special Characters and Diacritical Marks -

. sc ....................................

4.13. -me Request Summary .............................................................................................

Quotes -

-vi-

Contents -

Chapter 5 refer -

Continued

A Bibliography System .................................................... 103

5.1. Introduction .........................................................................................................................

103

5.2. Features .................................................................................................................................

103

5.3. Data Entry with addbib ...........................................................................................

105

5.4. Printing the Bibliography ...........................................................................................

106

5.5. Citing Papers with. refer .........................................................................................

107

5.6. refer Command Line Options ...........................................................................

108

5.7. Making an Index ..............................................................................................................

109

5.8. refer Bugs and Some Solutions .......................................................................

110

BlaI1k.s at Ends of Lines .............................................................................................

110

Interpolated Strings ......................................................................................................

111

Interpreting Foreign Surnames ..............................................................................

111

Footnote Num1:>ers ........................................................................................................

111

5.9. Internal Details of refer ..........................................................................................

112

5.10. Changing the refer Macros ................................................................................

114

Chapter 6 Formatting Tables with tbl ................................................................... 119
6.1. Running tbl ......................................................................................................................

121

6.2. Input Commands ..............................................................................................................

122

Options That Affect the Whole Table ...............................................................

123

Key Letters - Fonnat Describing Data Items ............................................

123

Optional Features of Key Letters .........................................................................

125

Data to 1:>e Fonnatted in the Table .......................................................................

127

Changing the Format of a Table ...........................................................................

128

6.3. Examples ..............................................................................................................................

129

6.4. tbl Commands ..............................................................................................................

140

Chapter 7 Typesetting Mathematics with eqn .................................................. 143
7.1. Displaying Equations -

. EQ and . EN .............................................................

144

7.2. Running eqn and neqn ..............................................................................................

145

7.3. Putting Spaces in the Input Text .............................................................................

146

7.4. Producing Spaces in the Output Text ...................................................................

147

7.5. Symbols, Special Names, and Greek Letters ...................................................

147

-vii-

Contents - Continued

7.6. Subscripts and Superscripts -

sub and sup ....................................,...........

148

{ and } ....................................................................

149

7.8. Fractions - over ..........................................................................................................

150

7.9. Square Roots -

sqrt .................................................................................................

151

7.10. Summation, Integral, and Other Large Operators ......................................

152

7.11. Size and Font Changes ...............................................................................................

153

7.12. Diacritical Marks ..........................................................................................................

154

7.13. Quoted Text .....................................................................................................................

155

7.14. Lining Up Equations - mark and lineup ...............................................

156

7.15. Big Brackets .....................................................................................................................

156

7.16. Piles-pile .................................................................................................................

157

7.17. Matrices-matrix ..................................................................................................

158

7.18. Shorthand for In-line Equations - delim ..................................................

159

7.19. Definitions - define .............................................................................................

159

7.20. Tuning th.e Spacing ......................................................................................................

161

7.21. Troubleshooting .............................................................................................................

161

7.22. Precedences and Keywords .....................................................................................

162

7.23. Several Examples ..........................................................................................................

166

7.7. Grouping Equation Parts -

Chapter 8 Verification Tools ............................................................................................ 173
8.1. spell .................................................................................................................................

173

8.2. checknr ...........................................................................................................................

173

8.3. soelim ..............................................................................................................................

173

8.4. deroff ..............................................................................................................................

173

8.5. fmt ........................................................................................................................................

173

8.6. col ........................................................................................................................................

173

8.7. colcrt ..............................................................................................................................

173

8.8. ul ...........................................................................................................................................

173

Index .......................................................................................................................................................

175

- viii-

Tables

Table 1-1 How to Display and Print Documents ..........................................................

Table 1-2 Registers You Can Change .................................................................................

Table 2-1 Display Macros .........................................................................................................

Table 2-2 Old Accent Marks ....................................................................................................

Table 2-3 Accent Marks .............................................................................................................

Table 2-4 Units of Measurement in nroff and traff ........................................

Table 2-5 Summary of -ms Number Registers ............................................................

Table 2-6 Bell Laboratories Macros Deleted From -ms .........................................

Table 2-7 New -ms Requests ..................................................................................................

Table 2-8 New String Definitions .........................................................................................

Table 2-9 -ms Macro Request Summary .........................................................................

Table 2-10 -ms String Definitions .......................................................................................

Table 2-11 Printing and Displaying Documents ...........................................................

Table 3-1 Summary of the -man Macro Requests .....................................................

Table 4-1 Special Characters and Diacritical Marks

Table 4-2 -me Request Summary .......................................................... ,.,.:,:,:,:•...;.•~...,.;,,:''':,:,:~.~.;..•••..: :-.

Table 7-1 Character Sequence Translation ................................ ;.,.;.....i.:.;.;.;; •.•• ;·.;.............:.:,;,... ,,::-:..
Table 7-2 Greek Letters ......................................... ".................................. "..... ;.O:;;+,.;;:;:;.:;:+~.;;;'H;;;••••••

164

Table 7-3 eqn Keywords ............ ".............................................. "..................................; ,.................

165

-ix-

Figures

Figure 2-1 Order of Requests in

Documents .......................................................

Figure 4-1 Outline of a Sample Paper ................................................................................

-xi-

-IDS

Preface
This manual provides user's guides and reference information for various document processing tools. We assume you are familiar with a terminal keyboard and
the Sun system. If you are not, see Getting Started with SunOS: Beginner's
Guide for infonnation on the basics, like logging in and the Sun file system. If
you are not familiar with text editing, read "An Introduction to Text Editing" in
the manual Editing Text Files, or" An Introduction to Document Preparation" in
this manual. Finally, we assume that you are using a Sun Workstation, although
specific terminal information is also provided.
If you choose to read one of the user's guides, sit down at your workstation and
try the exercises and examples. The reference sections provide additional explanations and examples on how to use certain facilities and can be dipped into as
necessary. For additional details on Sun system commands and programs, see
the SunOS Reference Manual.

Summary of Contents

This manual is divided into three sections:
o

Macro Packages

traff Preprocessors

Verification and Reformatting Programs

Introduction to Document Preparation - Describes the basics of text processing, macros and macro packages, provides a guide to the available tools
and several simple examples after which to pattern your pa~rs~d documents. Newcomers to the Sun document fonnatters shoulClrid·4Ocllmep.ts.<· ..
Includes new -ms macros.
. ... ... ..... ......
....

.........

. ............ « ..

............ -:::».

".:<-:.:.'

.';<';',"

-::';::":":.. "," ..:::::"<:"

The -man Macro Package - User's guide and referer1cettlfortrtatidJl>f6r the
-man macros for formatting manual pages (man pages). 1)$
.TE

Output:

Definition

Name

Ff"t Z- e- dt
t

Gamma

r(z

Sine

sin(x)= 2i (eIX-e- lX )

Error

erf(z)=~ rZe-t'dt

.,JiJ>

Bessel

J rl..z F1t"! cos(z sinG)d G

Zeta

~(s)=

I:k-

(Re s > 1)

1=1

Writing Mathematical
Equations

A displayed equation is marked with an equation number at the right margin by
adding an argument to the . EQ line:
Input:
.EO (1.3)
x sup 2 over a sup 2
.EN

sqrt {p z sup 2 +qz+r}

A displayed equation is marked with an equation number at the right margin by
adding an argument to the . EQ line:
Output:
(1.3)

Revision A, of 9 May 1988

Formatting Documents

Input:
.EQ (2.2a)
bold V bar sub nu-=-left [ pile {a above b above
c } right ] + left [ matrix { col { A(ll) above .
above. } col { . above. above .} col {. above.
above A(33) }} right] cdot left [ pile { alpha
above beta above gamma } right ]
.EN

OUtpUt:

--[1 [
Vv -

b + A (11).
. . ..
C
• • A (33)

(2.2a)

Input:
.EQ I '"' 2. 75i
F hat ( chi ) - mark
I del V I sup 2
.EN
.EQ I '"' 2. 75i
lineup =- {left ( {partial V} over {partial x} right ) } sup 2
+ { left ( {partial V} over {partial y} right ) } sup 2
lambda -> inf
.EN

Output:

Input:
$ a dot $,

$ b dotdot$,

$ rho tilde-times-y vec$.

Output:

a, b", pxy.
(with delim $$ on).

Revision A, of 9 May 1988

Chapter 1 - Introduction to Document Preparation

Registers You Can Change
Table 1-2

Registers You Can Change

Controls

Default Setting

Command to
Change

Takes Effect
Next

Line length of text

6 inches (6i)

.nr LL 7.Si

paragraph

Length of titles

.nr LT Si

page

Line length of footnotes

5.5i

.nr FL LL

.FS request

Footnote indent

5 ens (5n)

.nr FI 2n

.FS request

Point size

.nr PS 11

paragraph

Vertical spacing

.nr VS 13

paragraph

Column width

LL.7/15

.nr CW 3i

· 2C or • MC request

Intercolurnn spacing

LL.l/15

.nr GW .Si

• 2 C or . MC request

Header margin

.nr HM .7Si

page

Footer margin

.nr FM .7Si

page

Paragraph indent

5 ens (5n)

.nr PI 2n

paragraph

Paragraph depth

.3 vertical space

.nr PD 0

paragraph

Left and right indent for
quote paragraph ( . Qp)

.nr QI 8n

.QP request

Vertical distance around
displays

.5v

.nr DD 1v

· DS request

Page offset

.nr PO O.Si

page

(.3v)

Left page header

null

.ds LH Sun

page

Center page header

null

.ds CH Confidential

page

Right page header

null

.ds RH Software

page

Left page footer

null

.ds LF Do Not Copy

page

Center page footer

page number register

.ds CF Draft

page

Right page footer

null

.ds RF %

page

.nr % 3

page

(-'nPN-)

Page number

Revision A, of 9 May 1988

2
Fonnatting Documents with the -ms
Macros
Fonnatting Documents with the -ms Macros ........................................................
2.1. Changes in the New

Macro Package .........................................................

-IDS

27
27

-IDS ..............................................

2.3. What Can Macros Do? .................................................................................................

2.4. Fonnatting Requests ......................................................................................................

Paragraphs .........................................................................................................................

2.2. Displaying and Printing Documents with

Standard Paragraph -

. p p ..............................................................................

. LP ..........................................................................

Indented Paragraph -

. IP ...............................................................................

Nested Indentation -

. RS and . RE ...........................................................

Quoted Paragraph -

. QP ..................................................................................

. SHand . NH ....................................................................

Left-Block Paragraph -

Section Headings -

Cover Sheets and Title Pages -

. TL and . AU ..........................................

LH, CH, RH .........................................................

.OH, . EH, . OF, and . EF ................

. 2C and .MC .......................................................

. F S and . FE .....................................................................................

Endnotes .............................................................................................................................

. D Sand . DE ..............................................................

Keeping Text Together -

. KS, . KE and . KF ..........................................

Boxing Words or Lines -

. BX and . Bl and . B2 ..................................

. I, . B, . Rand. UL ........................................................

Running Heads and Feet -

Custom Headers and Footers Multi-Column Formats Footnotes -

Displays and Tables -

Changing Fonts -

Changing the Type Size -

. LG, . SM and . NL .........................................

Dates -

. DA aIld . ND ..............................................................................................

Thesis Fonnat Mode Bibliography -

. TM .................................................................................

. XP ..................................................................................................

. XS, • XE, • XA, • PX .................................................

Defining Quotation Marks .......................................................................................

Accent Marks ..................................................................................................................

2.5. Modifying Default Features ......................................................................................

Dimension3 .......................................................................................................................

2.6. Using nroff aIld troff Requests ....................................................................

2.7. Using -ms with eqn to Typeset Mathematics ...............................................

2.8. Using -ms with tbl to Fonnat Tables ..............................................................

2.9. Register Names .................................................................................................................

2.10. Order of Requests in Input .......................................................................................

2.11. -ms Request Summary .............................................................................................

Table of Contents -

2
Formatting Documents with the -IDS
Macros
This chapter describes the -IDS macro package for preparing documents with
nroff and troff on the Sun system. 1 The -IDS Request Summary at the end
of this chapter provides a quick reference for all the -ms macros and for useful
displaying and printing commands. If you are acquainted with -IDS, there is a
quick reference for the new requests and string definitions as well. The differences between the new and the old -IDS macro packages are described in the section entitled "Changes in the New -ms Macro Package." The section "Displaying and Printing Documents with -IDS" describes how you can produce documents on either your workstation, printer, or phototypesetter without changing
the text and formatting request input.

2.1. Changes in the New ms Macro Package

The old -ms macro package has been revised, and the new macro package
assumes the name -IDS. There are some extensions to previous -IDS macros and
a number of new macros, but all the previously documented -IDS macros still
work exactly as they did before, and have the same names as before. The new
-ms macro package includes several bug fixes, including a problem with the
single-column . 1 C 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 bibliographic citation macros. Macros used only at
Bell Laboratories have been removed from the new version. We list them at the
end of this chapter in the

2.2. Displaying and
Printing Documents
with -ms

After you have prepared your document with text and -IDS formatting requests
and stored it in a file, you can display it on your workstation screen or print it
with nroff or troff with the -ms option to use the -IDS macro package. A
good way to start is to pipe your file through IDO re for viewing:
( hostname% nroff -ms ji/ennme ...

I more

If you forget the -IDS option, you get continuous, justified, unpaginated output in
which -IDS requests are ignored. You can format more than one file on the
1 The material in this chapler is derived from A Revised Version of -ms, B. Tuthill, University of California,
Berkeley; Typing DocUlTU!ntson the UNIX System: Using tM -ms Macros with traff and nraff, M.E. Lesk,
Bell Laboratories, Murray Hill, New Jersey; and Document Formatting on UNIX: Using the -ms Macros, Joel
Kies, University of California, Berkeley.

Revision A, of9 May 1988

Formatting Documents

command line at a time, in which case nroff simply processes all of them in
the order they appear, as if they were one file. There are other options to use
with nroff and troff; see the SunOS Reference Manual for details.
You can get preview and final output of various sorts with the following commands. To send nroff output to the line printer, type:
(......h_o_s_t_n_a_m_e_%_n_r_O_f_f_-_mB
__
fi_le_name
___1_l_p_r_-_p_p_r_in_te_r_____________J

To produce a file with tables, use:
hostname% tbl filename I nroff -ms I Ipr -printer

To produce a file with equations, type:
hostname% neqn filename I nroff -ms I Ipr -printer

To produce a file with tables and equations, use the following order:
hostname% tbl filename I neqn I nroff -ms I Ipr -printer

To print your document with troff, use:
hostname % troff -ms filename I Ipr -t -printer

See Ipr(l) in the SunOS Reference Manual for details on printing.

2.3. What Can Macros Do?

Macros can help you produce paragraphs, lists, sections (optionally with
automatic numbering), page titles, footnotes, equations, tables, two-column format, a table of contents, endnotes, running heads and feet, and cover pages for
papers. As with other fonnatting utilities such as nroff and troff, you
prepare text interspersed with fonnatting requests. However, the macro package,
which itself is written in traff commands, provides higher-level commands
than those provided with the basic traff program. In other words, you can do
a lot more with just one macro than with one t ra f f request.

2.4. Formatting Requests

An -ms request usually consists of one or two upper-case characters, and usually
in the form . XX.

The easiest way to produce simple fonnatted text is to put a . LP request on a
line by itself at the beginning of the document. Add your text, on the following
lines, leaving just a blank line to separate paragraphs. The . LP request produces
a left-blocked paragraph, as we used throughout this chapter. Your output will
have paragraphs and be paginated with right and left-justified margins.
When you use a macro package, you type in text as you nonnally do and intersperse it with formatting requests. For example, instead of spacing in with the
space bar or typing a tab to indent paragraphs, put a . PP request on a line by

Revision At of 9 May 1988

Chapter 2 -

Formatting Documents with the -ros Macros

itself before each paragraph. When formatted, this indents the first line of the
following paragraph.

Note: You cannot just begin a document with a line of text. You must include
an -ms request before any text input. When in doubt, use . LP to properly initialize the file, although any of the requests. PP, . LP, . TL, . SH, . NH is good
enough. See the section "Cover Sheets and Title Pages" later in this chapter for
the correct arrangement of requests at the start of a document.
Paragraphs

Standard Paragraph -

You can produce several different kinds of paragraphs with the -ms macro package: standard, left-block, indented, labeled, and quoted.
.p P

To get an ordinary paragraph, use the . PP request, followed on subsequent lines
by the text of the paragraph. For example, you type:
.PP
Tom appeared on the sidewalk with a bucket of whitewash and a long-handled
brush.
He surveyed the fence, and all gladness left him and a deep melancholy
settled down upon his spirit.
Thirty yards of board fence nine feet high.
Life to him seemed hollow, and
existence but a burden.

to produce:
Tom appeared on the sidewalk with a bucket of whitewash and a longhandled brush. He surveyed the fence, and all gladness left him and a deep
melancholy settled down upon his spirit. Thirty yards of board fence nine feet
high. Life to him seemed hollow, and existence but a burden.
Left-Block Paragraph -

. LP

You can also produce a left-block paragraph, like those in this manual, with . LP.
The first line is not indented as it is with the . PP request. For example, you
type:

[~ _·~_~

__a_p_p_e_a_r_e_d_________________________________________________

to produce:
Tom appeared on the sidewalk with a bucket of whitewash and a long-handled
brush. He surveyed the fence, and all gladness left him and a deep melancholy
settled down upon his spirit. Thirty yards of board fence nine feet high. Life to
him seemed hollow, and existence but a burden.
There are default values for the vertical spacing before paragraphs and for the
width of the indentation. To change the paragraph spacing, see the section
"Modifying Default Features."

Revision A. of 9 May 1988

Formatting Documents

Indented Paragraph -

. IP

Another kind of paragraph is the indented paragraph, produced by the . I P
request. These paragraphs can have hanging numbers or labels. For example:
. IP

[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,
. LP

...

produces
[1] Text for first paragraph, typed normally for as long as you would like on as
many lines as needed.
[2] Text for second paragraph, ...
A series of indented paragraphs must be followed by an ordinary paragraph
beginning with . P P or . LP, depending on whether you wish indenting" or not
Here we used the . LP request.
More sophisticated uses of . IP are also possible. If the label is omitted, for
example, you get a plain block indent:
Torn appeared on the sidewalk with a bucket of whitewash and a long-handled
brush .
. IP
He surveyed the fence, and all gladness left him and a deep melancholy
settled down upon his spirit.
Thirty yards of board fence nine feet high.
Life to him seemed hollow, and
existence but a burden .

. LP

which produces
Tom appeared on the sidewalk with a bucket of whitewash and a long-handled
brush.
He surveyed the fence, and all gladness left him and a deep melancholy settled down upon his spirit. Thirty yards of board fence nine feet high. Life to
him seemed hollow, and existence but a burden.
If a non-standard amount of indenting is required, specify it after the label in
character positions. It remains in effect until the next . PP or . LP. Thus, the
general form of the . IP request contains two additional fields: the label and the
indenting length. For example,

Revision A, of 9 May 1988

Chapter 2 -

Formatting Documents with the -ms Macros

.IP "Example one:" 15
Notice the longer label, requ1r1ng larger
indenting for these paragraphs .
. IP "Example two:"
And so forth .
. LP

produces this:
Example one:

Notice the longer label, requiring larger indenting for these
paragraphs.

Example two:

And so forth.

Notice that you must enclose the label in double quote marks because it contains
a space; otherwise, the space signifies the end of the argument. The indentation
request above is in the number of ens, a unit of dimension used in typesetting.
An en is approximately the width of a lowercase 'n' in the particular point size
you are using.
The . IP macro adjusts properly by causing a break to the next line if you type in
a label longer than the space you allowed for. For example, if you have a very
long label and have allowed 10 en-spaces for it, your input looks like:
.IP
And
And
And
And
And

"A very, very,
now here's the
now here's the
now here's the
now here's the
now here's the

long
text
text
text
text
text

and verbose label" 10
that you want.
that you want.
that you want.
that you want.
that you want.

And your output is adjusted accordingly with a break between the label and the
text body:
A very, very, long and verbose label
And now here's the text that you want. And now here's the text that
you want. And now here's the text that you want. And now here's
the text that you want. And now here's the text that you want.
Nested Indentation oRE

RS and

It is also possible to produce multiple (or relative) nested indents; the . RS
request indicates that the next IP starts its indentation from the current indentation leve1. Each RE undoes one level of indenting, so you should balance RS
and RE requests. Think of the RS request as 'move right' and the RE request
as 'move left'. As an example:
0

Revision A, of 9 May 1988

Formatting Documents

.IP I.
South Bay Area Restaurants
.RS
.IP A.
Palo Alto
.RS
.IP 1.
La Terrasse
.RE

.IP B.
Mountain View
.RS
. IP 1.
Grand China
.RE

.IP C.
Menlo Park
.RS
. IP 1.
Late for the Train
.IP 2.
Flea Street Cafe
.RE
.RE

.LP

results in:
I.

South Bay Area Restaurants
A. Palo Alto

La Terrasse

B. Mountain View

Grand China

C. Menlo Park

Late for the Train

2. Flea Street Cafe
Note the two . RE requests in a row at the end of the list. Remember that you
need one end for each start.
Quoted Paragraph -

. QP

All of the variations on . LP leave the right margin untouched. Sometimes, you
need a a paragraph indented on both right and left sides. To set off a quotation as
such, use:

Revision A, of 9 May 1988

Chapter 2 -

Formatting Documents with the -ms Macros

.QP
Precede each paragraph that you want offset as a quotation
with a .QP. This produces a paragraph like this.
Notice that the right edge is also indented from the right margin.

to produce
Precede each paragraph that you want offset as a quotation with a
• QP. This produces a paragraph like this. Notice that the right edge
is also indented from the right margin.
Section Headings .NH

. SHand

There are two varieties of section headings, unnumbered with. SH and numbered
with . NH. In either case, type the text of the section heading on one or more
lines following the request. End the section heading by typing a subsequent
paragraph request or another section heading request. When printed, one line of
vertical space precedes the heading, which begins at the left margin. nra f f
offsets the heading with blank lines, while traff sets it in boldface type. . NH
section headings are numbered automatically. The macro takes an argument
number representing the level-number of the heading, up to 5. A third-level section number is one like' 1.2.1'. The macro adds one to the section number at the
requested level, as shown in the following example:
.NH
Bay Area Recreation

.NH 2
Beaches

.NH 3
San Gregorio

.NH 3
Half Moon Bay

.NH 2
Parks
.NH 3
Wunderlich
.NH 3
Los Trancos

.NH 2
Amusement Parks

.NH 3
Marine World/Africa USA

generates:

Revision A, of 9 May 1988

Formatting Documents

2. Bay Area Recreation
2.1 Beaches
2.1.1 San Gregorio
2.1.2 Half Moon Bay
2.2 Parks
2.2.1 Wunderlich
2.2.2 Los Trancos
2.3 Amusement Parks
2.3.1 Marine World/Africa USA
• NH without a level-number means the same thing as . NH 1, and . NH 0 cancels
the numbering sequence in effect and produces a section heading numbered 1.

Cover Sheets and Title Pages
. TL and .AU

-InS provides a group of macros to format items that typically appear on the
cover sheet or title page ofa formally laid-out paper. You can use them selectively, but if you use several, you must put them in the order shown below, normally at or near the beginning of the input file.

The first line of a document signals the general fonnat of the first page. In particular, if it is . RP (released paper), a cover sheet with title and abstract is prepared.
The default fonnat is useful for scanning drafts.

Revision A, of9 May 1988

Chapter 2 -

Formatting Documents with the -ms Macros

Sample input is:
• RP
(Optional; usefor released paper format)
.TL
Title of document (one or more lines)
.AU
Author(s)
(may also be several lines)
.AI
Author's institution(s)
.AB
Abstract; to be placed on the cover sheet of a paper.
Line length is 5/6 of normal; use .11 here to change .
• AE
(abstract end)
text ...
(begins with. pp)

(See Order of Requests in Input for a quick example of this scheme.)
If the . RP request precedes. TL, the title, author, and abstract material are
printed separately on a cover sheet. The title and author information (not the
abstract) is then repeated automatically on page one (the title page) of the paper,
without your having to type it again. If you do not include an . RP request, all of
this material appears on page one, followed on the same page by the main text of
the paper.
To omit some of the standard headings (such as no abstract, or no author's institution)' just omit the corresponding fields and command lines. To suppress the
word ABSTRACf type . AB no rather than . AB. You can intersperse several
• AU and . AI lines to format for multiple authors.
These macros are optional; you may begin a paper simply with a section heading
or paragraph request. When you do precede the main text with cover sheet and
title page material, include a paragraph or section heading between the last title
page request and the beginning of the main text. Don't forget that some -ms
request must precede any input text.

Running Heads and Feet LH,CH,RH

The -ms macros, by default, print a page heading containing a page number (if
greater than 1). You can make minor adjustments to the page headings and 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 nroff output, there are two default values: CH is the current page number surrounded on
either side by hyphens, and CF contains the current date as supplied by the computer. For t r 0 f f CH also contains the page number, but CF is empty. The
other four registers are empty by default for both nroff and troff. You can
use the . ds request to assign a value to a string register. For example:
( .ds RF Draft Only \ (em Do Not Distribute

)

This prints the character string

Revision At of 9 May 1988

Formatting Documents

Draft Only -

Do Not Distribute

at the bottom right of every page. You do not need to enclose the string in double quote marks. To remove the contents of a string register, simply redefine it
as empty. For instance, to clear string register CH, and make the center header
blank on the following pages, use the request:
(____
odS _CH_ _ _ _ _ _ _]

To put the page number in the right header, use:

]

( ods RH %

In a string definition, '%' is a special symbol referring to nro f f 's automatic
page counter. If you want hyphens on either side of the page number, place them
on either side of the '%' in the command, that is:
( ods RH -%-

]

Remember that putting the page number in the right header as shown above does
not remove it from the default CH; you still have to clear out CH.
If you want requests that set the values of string and number registers to take
effect on the first page of output, put them at or near the beginning of the input
file, before the initializing macro, which in turn must precede the first line of text.
Among other functions, the initializing macro causes a 'pseudo page break' onto
page one of the paper, including the top-of-page processing for that page. Be
sure to put requests that change the value of the PO (page offset), HM (top or
head margin), and PM (bottom or foot margin) number registers and the page
header string registers before the transition onto the page where they are to take
effect.

For more complex fonnats, you can redefine the macros Pf (page top) and BT
(page bottom), which are invoked respectively at the top and bottom of each
page. The margins (taken from registers HM and PM for the top and bottom
margin respectively) are nonnally 1 inch; the page header/footer are in the middle of that space. If you redefine these macros, be careful not to change parameters such as point size or font without resetting them to default values.

Custom Headers and Footers
.OH, • EH, • OF, and . EF

You can also produce custom headers and footers that are different on even and
odd pages. The . OR 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 the nrof f . tl, that is, there are three fields (left, center and
right), each separated by a single apostrophe. For example, to get odd-page
headers with the chapter name followed by the page number and the reverse on
even pages, use:

Revision A, of 9 May 1988

Chapter 2 -

.OH
.EH

Formatting Documents with the -ms Macros

' For Whom the Bell Tolls' , Page %'
' Page %' , For Whom the Bell Tolls'

Note that it is an error to have an apostrophe in the header text; if you need an
apostrophe, use a backslash and apostrophe (') or a delimiter other than apostrophe 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
.OR, .ER, .OF,or .EF.

You can use the . PI (dot-P-one) macro to print the header on page 1. If you
want roman numeral page numbering, use an . af PN i request.
Multi-Column Formats . 2C and .MC

If you place the request . 2 C in your document, the document will be printed in
double column fonnat beginning at that point. This is often desirable on the
typesetter. Each column will have a width 7/15 that of the text line length in
single-column fonnat, and a gutter (the space between the columns) of 1/15 of
the fu11line length. Remember that when you use the two-column . 2 C request,
either pipe the nroff output through col or make the first line of the input .pi
/usr /bin/ col.
The . 2 C request is actually a special case of the . MC request that produces formats of more than two spaces:

( .Me [column width [gutter width 1 1

This formats output in as many columns of column width as will fit across the
page with a gap of gutter width. You can specify the column width in any unit of
scale, but if you do not specify a unit, the setting defaults to ens. . Me without
any column width is the same thing as . 2 C. For example:
.Me
Tom appeared on the sidewalk with a bucket of whitewash and a long-handled
brush.
He surveyed the fence, and all gladness left him and a deep melancholy
settled down upon his spirit.

To return to single-column output, use . 1 C. Switching from double to singlecolumn always causes a skip to a new page.

Revision A, of 9 May 1988

Formatting Documents

Footnotes -

. F Sand . FE

Material placed between lines with the commands. FS (footnote start) and . FE
(footnote end) is collected, remembered, and placed at the bottom of the current
page. * The formatting of the footnote is:
... at the bottom of the current page.*
.FS
* Like this .
. FE

By default, footnotes are 1l/12th the length of normal text, but you can modify
this by changing the FL register (see the "Modifying Default Features" section).
When typeset, footnotes appear in smaller size type.
Because the macros only save a passage of text for printing at the bottom of the
page, you have to mark the footnote reference in some way, both in the text
preceding the footnote and again as part of the footnote text. We use a simple
asterisk, but you can use anything you want.
You can also produce automatically-numbered footnotes. Footnote numbers are
printed by a predefined string (\ **), which you invoke separately from. FS and
. FE. Each time this string is used, it increases the footnote number by one,
whether or not you use . F S and . FE in your text. Footnote numbers are superscripted on the phototypesetter and on daisy-wheel terminals, but on lowresolution devices (such as the line printer and a treminal), they are bracketed. If
you use \ * * to indicate numbered footnotes, the . F S macro automatically
includes the footnote number at the bottom of the page. This footnote, for example, was produced as follows: 2
This footnote, for example, was produced as follows:\**
.FS
If you never use the ...
. FE

If you are using \ * * to number footnotes, but want a footnote of the same style
marked with an asterisk or dagger, give that mark as the first argument to . FS:t
give that mark as the first argument to .FS:\(dg
.FS \ (dg
In the footnote, the dagger
.FE

Footnote numbering is temporarily suspended, because the \ ** string is not
used. Instead of a dagger, you could use an asterisk * or double dagger
represented as \ (dd.

* Like this.
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, the old -ms macro package.
2

In the footnote, the dagger will appear where the footnote number would otherwise appear, as shown here.

+~t!!

Revision A, of 9 May 1988

Chapter 2 -

Endnotes

Displays and Tables and. DE

Fonnatting Documents with the -rns Macros

If you want 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 conventional typewriter. Note that you can use automatic footnote numbering without actually having the . F S 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 gives you numbers at the left-hand margin. With some styles of endnotes,
you would want to use . PP rather than . IP macros, and specify \** before the
reference begins.

. DS

To prepare displays of lines, such as tables, in which the lines should not be rearranged or broken between pages, enclose them in the requests . D S and . DE:
.DS
lines, like the
examples here, are placed
between .DS and .DE macros
.DE

which produces:
lines, like the
examples here, are placed
between .DS and .DE macros
By default, lines between. DS and . DE are indented from the left margin.
If you don't want the indentation, use . DS L to begin and . DE to produce a
left-justified display:

to get
something like
this
You can also center lines with the . DS C and . DE requests:
This is an
example
of a centered display.
Note that each line is centered individually.
A plain. DS is equivalent to . DS I, which indents and left-adjusts. An extra
argument to the . DS I or . DS request is taken as an amount to indent. For
example, . DS I 3 or . DS 3 begins a display to be indented 3 ens from the
margin.
There is a variant. DS B that makes the display into a left-adjusted block of
text, and then centers that entire block.
Nonnally a display is kept together on one page. If you wish to have a long
display which may be split across page boundaries, use. CD, • LD, and . BD in
place of the requests. DS C, . DS L, and . DS B respectively. Use. ID for
either a plain . DS or . DS I. You can also specify the amount of indentation
with the . ID macro. Use the following table as a quick reference:
Revision A, of 9 May 1988

Fonnatting Documents

Table 2-1

Display Macros

Macro with Keep
.DS
.DS
.DS
.DS
.DS

Macro without Keep

.ID

L
C

.LD
.CD

.BD

.ID

Note: It is tempting to assume that. DS R will right-adjust lines, but it doesn't.

Keeping Text Together .KS, .KE and .KF

It you wish to keep a table or other block of lines together on a page, there are
'keep - release' requests. Ita block of lines preceded by . KS and followed by
• KE does not fit on the remainder of the current page, it will begin on a new
page. There is also a 'keep floating' request. If the block to be kept together is
preceded by . KF instead of . KS and does not fit on the current page, it will be
moved down through the text to the top of the next page. nroff fills in the
current page with the ordinary text that follows the keep in the input file to avoid
leaving blank space at the bottom of the page preceding the keep. Thus, no large
blank space will be introduced in the document
In multi-column output, the keep macros attempt to place all the kept material in

the same column. If the material enclosed in a keep requires more than one page,
or more than a column in multi-column fonnat, it will start on a new page or
column and simply run over onto the following page or column.

Boxing Words or Lines -

To draw rectangular boxes around words, use the request

.BX and .BI and. B2

)

( .BX word

to print 1W0rd las shown. You can box longer pieces of text by enclosing them
with. BI and . B2:
.Bl
Tom appeared on the sidewalk with a bucket of whitewash
and a long-handled brush.
He surveyed the fence, and all gladness left him and a deep melancholy
settled down upon his spirit.
Thirty yards of board fence nine feet high.
Life to him seemed hollow, and
existence but a burden .

. B2

This produces:
Tom appeared on the sidewalk with a bucket of whitewash and a long-handled
brush. He sUlVeyed the fence, and all gladness left him and a deep melancholy
settled down upon his spirit. Thirty yards of board fence nine feet high. Life to
him seemed hollow, and existence but a burden.

Revision A, of 9 May 1988

Chapter 2 - Formatting Documents with the -ms Macros

Changing Fonts and UL

To get italics on the typesetter or reverse display on the workstation, say:

as much text as you want
can be typed here
oR

as was done for these three words. The R request restores the nonnal (usually
Roman) font. If only one word is to be italicized, you can put it on the line with
the . I request:
0

(oI word

and in this case you do not need to use an . R to restore the previous font.
You can print boldface font by
.B
Text to be set in boldface
goes here
.R

As with . I, you can place a single word in boldface font by putting it on the
same line as the . B request. Also, when . I or . B is used with a word as an
argument, it can take as a second argument any trailing punctuation to be printed
immediately after the word but set in normal typeface. For example:
( oB word

prints
word)
that is, the word in boldface and the closing parenthesis in nonnal Roman
directly adjacent to the word.
If you want actual underlining as opposed to italicizing on the typesetter, use the

request

(,,---oUL_word_

_ _ _ _

to underline a word. There is no way to underline multiple words on the
typesetter.
Changing the Type Size • LG, SM and NL
0

You can specify a few size changes in troff output with the requests. LG
(make larger), . SM (make smaller), and . NL (return to nonnal size). The size
change is two points (see the "Dimensions" section for a discussion of point
size); you can repeat the requests for increased effect (here one NL canceled two
• SM requests). These requests are primarily useful for temporary size changes
0

Revision ~ of 9 May 1988

Formatting Documents

for a small number of words. They do not affect vertical spacing of lines of text.
See the section on "Modifying Default Features" for other techniques for changing the type size and vertical spacing of longer passages.
Dates -

When you use -ms, nroff prints the date at the bottom of each page, but
troff does not Both nroff and troff print it on the cover sheet if you
have requested one with . RP .. To make t ro f f print the date as the center page
footer, say. DA (date). To suppress the date, say. ND (no date). To lie about the
date, type • DA July 4, 1776, which puts the specified date at the bottom
of each page. The request:

. DA and . ND

]

( .ND September 16, 1959

in . RP fonnat places the specified date on the cover sheet and nowhere else.
Place either . ND or . DA before the . RP Notice this is one instance that you do
not need to put double quote marlcs around the arguments.
Thesis Format Mode -

Bibliography -

. XP

. TM

To fonnat a paper as a thesis, use the . TM macro (thesis mode). It is much like
the . th macro in the -me macro package. It puts page numbers in the upper
right-hand comer, numbers the first page, suppresses the date, and doublespaces
everything except quotes, displays, and keeps. Use it at the top of each file making up your thesis. Calling . TM defines the . CT macro for chapter titles, which
skips to a new page and moves the page number to the center footer. You can
use the . P 1 (p one) macro even without thesis mode to print the header on page
one, which is suppressed except in thesis mode. If you want roman numeral page
numbering, use an . af PN i request
To fonnat bibliography entries, use the . XP macro, which stands for exdented
paragraph. It exdents the first line of the paragraph by \n(pI units, usually 5n,
the same as the indent for the first line of a . PP. An example of exdented paragraphs is:
.XP

Lumley, Lyle S., \fISex in Crustaceans: Shell Fish Habits,\fp\~
Harbinger Press, Tampa Bay and San Diego, October 1979.
243 pages.
The pioneering work in this field .
• XP

Leffadinger, Harry A., ~Mollusk Mating Season: 52 Weeks, or All Year?"
in \fIActa Biologica,\fP\~ vol. 42, no. 11, November 1980.
A provocative thesis, but the conclusions are wrong.

which produces:
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.
Revision A, of 9 May 1988

Chapter 2 -

Formatting Documents with the -ms Macros

You do have to italicize the book andjoumal titles and quote the title of the journal article. You can change the indentation and exdentation by setting the value
of number register PI.

Table of Contents . XE, .XA, .PX

. XS,

There are four macros that produce a table of contents. Enclose table of contents
entries 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.
A final . P X macro prints out the table of contents. A sample of typical input and
output text is:

.xs ii
Introduction
.XA 1
Chapter 1: Review of the Literature
.XA 23
Chapter 2: Experimental Evidence
.XE

.px

Table of Contents
Introduction ....................... ............. ........... ..............................................................
Chapter 1: Review of the Literature ........................................................................
Chapter 2: Experimental Evidence ............................................... ..... ............. .........

ii
1
23

You can also use the . xs and . XE pairs 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
make the table of contents after finishing your document. To print out the table
of contents, use the . P X macro or nothing will happen.

Defining Quotation Marks

To produce quotation marks and dashes that fonnat correctly with both nroff
and troff, there are some string definitions for each of the formatting programs. The \*- string yields two hyphens in nroff, and produces an em-dash
-like this one in troff. The \*Q and \*u strings produce" and" in troff,
but" in nroff.

Accent Marks

To simplify typing certain foreign words, the -ms macro package defines strings
representing common accent marks. There are a large number of optional
foreign accent marks defined by the -ms macros. All the accent marks available
in -mos are present, and they all work just as they always did.
For the old accent marks, type the string before the letter over which the mark is
to appear. For example, to print 't'el'qtxne with the old macros, you type:
(t\*'el\*'ePhone

J
Revision A, of9 May 1988

Formatting Documents

Unlike the old accent marks, the new accent strings should be placed after the
letter being accented. Place . AM (accent mark) at the beginning of your document, and type the accent strings after the letter being accented. A list of both
sets of diacritical marks and examples of what they look like follows. Note: Do
not use the tbl macros. TS and . TE with any of the accent marks as the marks
do not line up correctly.
Table 2-2

Old Accent Marks
Accent Name
acute
grave
umlaut
circumflex
tilde
haeek
cedilla

Table 2-3

Input
\*'e
\*'e
\*:u
\* . . e
\*-a
\*Cr
\*,c

Output

e
e
ti
~

av
r
c

AccentMarks
Accent Name
acute
grave
circumflex
cedilla
tilde
question
exclamation
umlaut
digraphes
harek
macron
o-slash
yogh
angstrom
Thorn
thorn
Eth
eth
hooked 0
ae ligature
AEligature
oe ligature
OEligature

Input
e\* '
e\*'
0\* . .
c\*,
n\*\*?
\*!
u\*:
\*8
c\*v
a\* 0\*/
kni\*3t
a\*o
\*(Th
\*(th
\* (D\*(d\*q
\*(ae
\* (Ae
\*(oe
\*(Oe

Output

e
e
6
C
fi.

J
I

ii
J3
v
c

a
r/J

kni3t
~

P
p
D

a
Q
3!

.IE
re
(E

If you want to use these new diacritical marks, don't forget the . AM at the top of
your file. Without it, some of these marks will not print at all, and others will be
placed on the wrong letter.

Revision A, of9 May 1988

Chapter 2 -

2.5. Modifying Default
Features

Formatting Documents with the -ros Macros

The -ms macro package supplies a standard page layout style. The text line has
a default length of six inches; the indentation of the first line of a paragraph is
five ens; the page number is printed at the top center of every page after page
one; and so on for standard papers. You can alter many of these default features
by changing the values that control them.
The computer memory locations where these values are stored are called number
registers and string registers. Number and string registers have names like those
of requests, one or two characters long. For instance, the value of the line length
is stored in a number register named LL. Unless you give a request to change the
value stored in register LL, it will contain the standard or default value assigned
to it by -ms. The "Summary of -ms Number Registers" table lists the number
registers you can change along with their default values.

Dimensions

To change a dimension like the line length from its default value, reset the associated number register with the troff request. nr (number register):
[ .nr

The first argument, LL, is the name of a number register, and the second, 5 i is
the value being assigned to it In the case above, the line length is adjusted from
the default six inches to five inches. As another example, consider:
( .nr PS 9

which makes the default point size 9 point.
The value may be expressed as an integer or may contain a decimal fraction.
When setting the value of a number register, it is almost always necessary to
include a unit of scale immediately after the value. In the example above, the 'i'
as the unit of scale lets troff know you mean five inches and not five of some
other unit of distance. But the point size cPS) and vertical spacing (VS) registers
are exceptions to this rule; ordinarily they should be assigned a value as a
number of points without indicating the unit of scale. For example, to set the
vertical spacing to 24 points, or one-third of an inch (double-spacing), use the
request:
( .nr VS 24

In the unusual case where you want to set the vertical spacing to more than half
an inch (more than 36 points), include a unit of scale in setting the VS register.
The "Units of Measurement in nrof f and trof f" table explains the units of
measurement

+~t!!

Revision A, of 9 May 1988

Formatting Documents

Table 2-4

Units o/Measurement in nroff and troff
Unit
point
pica
em

Abbr
p
p
m

en
vertical space

n
v

inch
centimeter
machine unit

i
u

nroff

troff

1n2 inch
1/6 inch
width of one character

1n2 inch
1/6 inch
distance equal
to number of
points in the
current typesize
half an em
same

width of one character
amount of space in
which each line of
text is set, measured
baseline to baseline
inch
centimeter
1/240 inch

inch
centimeter
1/432 inch

The units point, pica, em, and en are units of measurement used by tradition in
typesetting. The vertical space unit also corresponds to the typesetting tenn
leading, which refers to the distance from the baseline of one line of type to the
baseline of the next. Em and en are particularly interesting in that they are proportional to the type size currently in use (normally expressed as a number of
points). An em is the distance equal to the number of points in the type size
(roughly the width of the letter 'm' in that point size), while an en is half that
(about the width of the letter en'). These units are convenient for specifying
dimensions such as indentation. In t r 0 f f, em and en have their traditional
meanings, that is one em of distance is equal to two ens. For nroff, on the
other hand, em and en both mean the same quantity of distance, the width of one
typewritten character.
The machine unit is a special unit of dimension used by nroff and troff
internally. This is the unit to which the programs convert almost all dimensions
when storing them in memory, and is included here primarily for completeness.
In using the features of -ms, it is sufficient to know that such a unit of measure
exists.
Note that a change to a number register such as LL does not immediately change
the related dimension at that point in the output. Instead, in the case of the line
length for example, the change takes place at the beginning of the next paragraph, where -ms resets various dimensions to the current values of the related
number registers.
If you need the effect immediately, use the nonna! troff command in addition
to changing the number register. For example, to control the vertical spacing
immediately, use:

]

( .vs

This takes effect at the place where it occurs in your input file. Since it does not
Revision A, of 9 May 1988

Chapter 2 -

Formatting Documents with the -ms Macros

change the VS register, however, its effect lasts only until the beginning of the
next paragraph. As a general rule, to make a pennanent change, or one that will
last for several paragraphs until you want to change it again, alter the value of the
-ms register. If the change must happen immediately, somewhere other than the
point shown in the table, use the t r a f f request. If you want the change to be
both immediate and lasting, do both.
Table 2-5

Summary of -ms Number Registers

Controls

point size
line spacing
line length
title length
para. spacing
para. indent
footnote length
column width
intercolumn gap
page offset
top margin
bottom margin

Takes
Effect
next para.
next para.
next para.
next para.
next para.
next para.
next. FS
next.2C
next.2C
next page
next page
next page

Default
10
12 pts
6"
6"
0.3 VS
S ens
11/12 LL
7/15 LL
1/15 LL
26/27"
1"
I"

You may also alter the strings and which are the left, center, and right headings
respectively; and similarly and which are strings in the page footer. Use the
traff . ds (define string) request to alter the string registers, as you use the
· nr request for number registers. The page number on output is taken from
register to pennit changing its output style. For more complicated headers and
footers, you can redefine the macros and as explained earlier. See the "Register
Names" section for a full list.

2.6. Using nroff and
troff Requests

You can use a small subset of the t r a f f requests to supplement the -ms macro
package.
.
Use. nr and . ds requests to manipulate the -ms number and string registers as
described in the "Modifying Default Features" section. You can also freely use
the other following requests in a file for processing with the -ms macro package.
They all work with both typesetter and workstation or tenninal output.
· ad b

Adjust both margins. This is the default adjust mode.

· bp

Begin new page.

· br

'Break' line; start a new output line whether or not the current one
has been completely filled with text.

· ce n

~), sun
~

microsystems

Center the following n input text lines individually in the output. If n
is omitted, only the next (one) line of text is centered.

Revision A. of 9 May 1988

Formatting Documents

Define string register named XX.

• ds XX

· na

Tum off adjusting of right margins to produce ragged right.

xx.

· nr XX

Define number register named

· sp n

Insert n blank lines. If n is omitted, one blank line is produced (the
current value of the unit v). You can attach a unit of dimension to n
to specify the quantity in units other than a number of blank lines.

Note: The macro package executes sequences of troff requests on its own, in

a manner invisible to you. By inserting your own troff requests, you run the
risk of introducing errors. The most likely result is simply for your troff
requests to be ignored, but in some cases the results can include fatal troff
errors and garbled typesetter output.
As a simple example, if you try to produce a centered heading with the input:
[ .ce

.SH
Text of section heading

you will discover that the heading comes out left-adjusted; the . SH macro,
appearing after the . ce request overrules it and forces left-adjusting. But consider the following sequence:
.sp
.ce
.B
Line of text

which successfully produces a centered, boldface heading preceded by one line
of vertical space. There are lots of tricks like this, so be careful.
To learn more about troff see the chapter on "Formatting Documents with
nroff and troff."

2.7. Using -ms with eqn to
Typeset Mathematics

If you have to print Greek letters or mathematical equations, see the chapter
''Typesetting Mathematics with eqn" for equation setting. To aid eqn users, rns provides definitions of . EQ and . EN which nonnally center the equation and
set it off slightly. An argument to . EQ is taken to be an equation number and
placed in the right margin near the equation. In addition, there are three special
arguments to . EQ: the letters C, I, and L indicate centered (default), indented,
and left adjusted equations, respectively. If there is both a format argument and
an equation number, give the fonnat argument first, as in
( • EQ L

(1. 3a)

]

for a left-adjusted equation numbered (1.3a).

Revision A, of 9 May 1988

Chapter 2 -

Formatting Documents with the -ms Macros

2.8. Using -ms with tbl to
Format Tables

Similar to the eqn macros are the macros. TS and . TE defined to separate
tables from text with a little space (see the chapter "Formatting Tables with
tbl"). A very long table with a heading may be broken across pages by beginning it with . T S H instead of . T S, and placing the line . THin the table data
after the heading. If the table has no heading repeated from page to page, just
use the ordinary . T S and . TE macros.

2.9. Register Names

The -ms macro package uses the following register names internally. Independent use of these names in your own macros may produce incorrect output. Note
that there are no lower case letters in any -ms internal name.

..
#T
T.
IT
AV
CW

,
...
'"

,
lC
2C
Al
A2
A3
A4

DW
EF
FC
FL
FM
FP

AS
AB
AE
AI
AU
B
BG
BT
C
C1
C2
CA

GW
HI
H2
H3
H4
H5

CB
CC
CD
CF
CH
CM
CS
CT
D
DA
DE
DS

2.10. Order of Requests in
Input

HM
HT

IF
IK
1M
IP

DW
DY
E1
E2
E3
E4
E5
EE
EL
EM
EN
EQ

Number Registers Used in -ms
IQ
NA
LL
IR
LT
NC
IT
MF
ND
KI
MM
NF
LI
MN
NS
LE
MO
01

String Registers Used in -ms
I
EZ
KF
KQ
FA
11
FE
12
KS
FJ
13
LB
14
FK
LD
FN
15
LG
FO
ID
LP
FQ
IE
ME
FS
1M
MF
FV
IP
MH
FY
IZ
MN
HO
MO
KE

OJ
PD
PE
PF
PI
PN

MR
ND
NH
NL
NP
OD
OK
PP
Pf
PY
QF
R

PO
PQ
PS
PX
RO
ST

Rl
R2
R3
R4
R5
RC
RE
RF
RH
RP
RQ
RS

T.
TB
TC
TD

TN
TQ

RT
SO
SI
S2
SG
SH
SM
SN
SY
TA
TE
TH

TV
VS
WF
YE
YY
ZN

TL
TM
TQ
TS

TT
UL
WB
WH

WT
XD
XF
XK

The following diagram provides a quick reference for how to order macro
requests when using the -IDS macro package to format documents. The central
arrow indicates that the minimum formatting requests you need with -ms are the
paragraph macros. These initialize certain quantities and are necessary to obtain
predictable results when you use other macros.
The double-edged arrows indicate optional requests. The single-edged arrows
indicate dependencies. For example, if you use a . AB request, you need a . AE
request. If you use a . AU request, you don't need a . AI request, but if you use a
. AI request, you have to use a . AU request first. The locations of the side
arrows relative to the other requests indicate the relative locations of the requests
in the document source.

Revision A, of 9 May 1988

Formatting Documents

For simpler documents, use just a . LP initializing request and just leave blank
lines between paragraphs.
Figure 2-1

Order of Requests in -ms Documents

.AM

.NO

...

• RP

...

• TM

...

.nrXX

-...

. dsXX

...

.EH .0 H .EF

.na

.1sN

.OF~

.TL

.AU

.AI
.AB

.AE

SH .NH

...

. LP .PP
!IE--':- - - ; . . . : ; .

. nh

text

Revision A, of9 May 1988

Chapter 2 -

2.11. -ms Request
Summary

Formatting Documents with the -ms Macros

This section includes tables of the old Bell Laboratories that have been removed
from the new -ms package, of new -ms requests and string definitions, and of
useful printing and displaying commands. It also includes a complete -ms
request and string summary for easy reference.
Table 2-6

Bell Laboratories Macros Deleted From -ms

Macro Request
.CS
.EG
.HO
.IH
.1M
.MF
.MH
.MR
.ND
.OK
.py

.SG
.TM
.TR
.WH
Table 2-7

Explanation
Cover sheet
BTL Engineer's Notes
Bell Labs, Holmdel, N.J.
Bell Labs, Naperville, Ill .
BTL internal memo
BTL file memo
Bell Labs, Murray Hill, N.J .
BTL record memo
BTL date
BTL keywords for tech memo
Bell Labs, Piscataway, N.J .
Signatures for tech memo
BTL technical memo
BTL report format
Bell Labs, Whippany, N.J .

New -ms Requests

Macro Request
.AM

.cr
.EH
.EF

.FE
.FS
.IP\**
.IX
.OF
.OH
.PI
.PX
.TM
.XS
.XE
.XA
.PX
.XP

Explanation
New accent mark definitions .
Chapter title in . TM format.
Define even three-part page header.
Define even three-part page footer.
End automatically numbered footnote .
Begin automatically numbered footnote .
Endnotes with automatic numbering.
Index words .
Define odd three-part page footer .
Define odd three-part page header.
Put header on page one in . TM format .
Print table of contents .
Thesis mode format.
Start table of contents entry.
End table of contents entry .
Additional table of contents entry .
Prints table of contents .
Exdented paragraph.

Revision A, of 9 May 1988

Formatting Documents

Table 2-8

New String Definitions

Definition
\*-

\*Q
\*U

Table 2-9

In nroff
Two dashes -Open quote "
Oose quote"

In troff
Em dashOpen quote"
Close quote "

-ms Macro Request Summary

Macro
Request

Initial
Value

Cause
Break?

yes
no
no

.AT

yes
yes
yes
yes
yes
no
yes

. AU
.B x

no
no

yes
no

. BI
.B2
.BT

no
no
date

yes
yes
no

. BX x
.CM

no
no

. 1C
.2C
.AB
.AE
. AI

.AM

yes

. CT
.DA x
. DE
.DS x

.EF x
.EN

date

yes
yes

no
yes

Explanation

One column fonnat on a new page .
Two column fonnat.
Begin abstract.
End abstract.
Author's institution follows .
New accent mark definitions
Print ' ...Attached' and turn off line
filling.
Author's name follows .
Print x in boldface; if no argument
switch to boldface.
Begin text to be enclosed in a box .
End text to be boxed and print it.
Bottom title, automatically invoked
at foot of page. May be redefined.
Print x in a box .
Cut mark between pages (only if
troff).
Chapter title in thesis mode only .
Page number moved to CF.
'Date line' at bottom of page is x
(only in nroff). Default is today.
End displayed text. Implies . KE .
Start of displayed text to appear verbatim line-by-line. x=I for
indented display (default), x=L for
left-adjusted on the page, x=C for
centered, s=B for make left-justified
block, then center whole block.
Implies . KS.
Even three-part page footer x
Space after equation produced by
eqn or neqn.

Revision A, of 9 May 1988

Chapter 2 -

Table 2-9

Formatting Documents with the

-InS

Macros

-ms Macro Request Summary- Continued

Macro
Request

Initial
Value

Cause
Break?

.EQ xy

yes

. FE
.FS x

yes
no

.1 x

.IP xy

yes

.KE

yes

.KF

yes

. KS
. LG
. LP
.ND date

no
no
yes

yes
yes
yes
no

.NH n

. NL
.IX xy

yes

. OF x
.OH header
.Pl

no
no
no

.PP

.PT

pg#

+~~t!!

no
yes

yes

Explanation

Precede equation; break out and add
space. Equation number is y. The
optional argument x may be I to
indent equation (default), L to
left-adjust the equation, or C to
center it.
End footnote .
Start footnote. x is optional footnote label. The note will be printed
at the bottom of the page.
Italicize x; if x is missing, italic text
follows.
Start indented paragraph, with hanging tag x. Indentation is y ens
(default 5).
End keep. Put kept text on next
page if not enough room.
Start floating keep. If the kept text
must be moved to the next page,
float later text back to this page.
Start keeping following text.
Make letters larger.
Start left-blocked paragraph .
Use date supplied if any as page
footer; only in special format positions.
Same as . S H with section number
supplied automatically. Numbers
are multilevel, like 1.2.3, where n
tells what level is wanted (default is
1).
Make letters normal size .
Index entries wand y and so on up
to 5 levels. Make letters normal
size.
Odd three-part page footer .
Odd three-part page header.
Print header on first page (only in
thesis mode).
Begin paragraph. First line
indented.
Page title, automatically invoked at
top of page. May be redefined.

Revision A, of 9 May 1988

Formatting Documents

Table 2-9

-ms Macro Request Summa~ Continued

Macro
Request

Initial
Value

.PX x

yes

.QP

yes

.R
.RE
.RP

yes

no
yes

. RS

yes

. SH

yes

. SM
. TA x ...
. TE
. TH
. TL
.TM
.TS x

.UL x

no
5...

no
off

Explanation

Cause
Break?

no
no
yes
yes
yes
no
yes

yes

Print table of contents; x=no
suppresses title.
Begin single paragraph which is
indented and shorter.
Roman text follows .
End relative indent leve1.
Cover sheet and first page for
released paper. Must precede other
requests.
Start level of relative indentation.
Following. IPs are measured from
current indentation.
Section head follows, font automatically bold.
Make letters smaller.
Set tabs in ens. Default is 5 10 15 ...
End table.
End heading section of table.
Title follows .
Thesis mode fonnat.
Begin table; if x is H, table has
repeated heading on subsequent
pages.
Underline argument, even in
troff.

.XA xy

yes

.XE

yes

.XS xy

yes

.UL x

yes

Another index entry; x=page for no
for none, y=indent.
End index entry or series of . IX
entries.
Begin index entry; x=page or no for
none, y=indent.
Underline argument, even in
troff.

Revision A. of 9 May 1988

Chapter 2 -

Table 2-10

Formatting Documents with the -ms Macros

-ms String Definitions

Name

Definition

In nroff

In troff

quote
unquote
dash
month of year
current date
numbered footnote

\*Q
\*U
\*\*(MO
\*(DY
\**

"
"

March
6 March 1988
[1 ]footnote

March
6 March 1988
1ootnote

The following table summarizes command lines you use to print and display
documents. Use the same order with troff for preprocessing files with tbl
and eqn.
If you use the two-column. 2C request, either pipe the nroff output through
col or make the first line of the input. pi /usr /bin/ col.

Table 2-11

Printing and Displaying Documents

What You Want to Do

How to Do it

Display file on screen

nroff -ms file(s)

Print file on line printer

nroff -ms file(s)

l.pr

Print file with tables

tbl. file(s) I nro£f -ms I 1pr

Print file with equations

neqn file(s) I nroff -ms I 1pr

Print file with both

tb1 file(s) I neqn i nroff -ms I 1pr

Print file using t r 0 f f

troff -ms file(s) I 1pr -t

Revision A, of 9 May 1988

3
The -man Macro Package
The -man Macro Package ....................................................................................................

3.1. Parts of a Manual Page .................................................................................................

3.2. Coding Conventions ......................................................................................................

The Header and Footer Line (. TH) -