UNIX Programmers Manual Vol 4 Preparation 1986
UNIX_Programmers_Manual_Vol_4__Preparation_1986 UNIX_Programmers_Manual_Vol_4__Preparation_1986
UNIX_Programmers_Manual_Vol_4__Preparation_1986 UNIX_Programmers_Manual_Vol_4__Preparation_1986
User Manual: manual pdf -FilePursuit
Open the PDF directly: View PDF 
.
Page Count: 374
| Download | |
| Open PDF In Browser | View PDF |
AT8.T
VOLUME 4
PREPARATION
DOCUMENTATION
UNIX*
programmer's manual
CBS COLLEGE PUBLISHING'S
UNIX SYSTEM LIBRARY
* Trademark of AT&T.
AlIaT
VOLUME 4
PREPARATION
DOCUMENTATION
UNIX*
programmer's manual
CBS COLLEGE PUBLISHING'S
UNIX SYSTEM LIBRARY
Steven V. Earhart: Editor
HOLT, RINEHART AND WINSTON
New York Chicago San Francisco Philadelphia
Montreal Toronto London Sydney Tokyo
Mexico City Rio de Janeiro Madrid
* Trademark of AT&T.
IMPORTANT NOTE TO USERS
While every effort has been made to ensure the accuracy of all information in this document, AT&T assumes
no liability to any party for any loss or damage caused by errors or omissions or statements of any kind in the
UNIX* Programmer's Manual, its updates, supplements, or special editions, whether such errors are
omissions or statements resulting from negligence, accident, or any other cause. AT&T further assumes no
liability arising out of the application or use of any product or system described herein; nor any liability for
incidental or consequential damages arising from the use of this document. AT&T disclaims all warranties
regarding the information contained herein, whether expressed, implied or statutory, including implied
warranties or merchantability or fitness for a particular purpose.
AT&T reserves the right to make changes without further notice to any products herein to improve
reliability, function or design.
This document was set on an AUTOLOGIC, Inc. APS-5 phototypesetter driven by the TROFF formatter
operating under the UNIX system on an AT&T 3B20 computer.
* Trademark of AT&T.
Copyright© 1986 AT&T
All rights reserved.
Address correspondence to:
383 Madison Avenue
New York, NY 10017
No part of this publication may be reproduced, transmitted or used in any form or by any means-graphic,
electronic, mechanical or chemical, including photocopying, recording in any medium, taping, by any
computer or information storage and retrieval systems, etc. without prior permission in writing from
AT&T.
Library of Congress Cataloging-in-Publication Data
UNIX programmer's manual.
At head of title: AT&T
Inclues index.
Contents: v. 1. Commands and utilities-v. 2.
System calls and library routines-v. 3. System
administration facilities.-v. 4. Document Preparation.
1. UNIX (Computer operating system) I. Earhart,
Steven V. ll. American Telephone and Telegraph Company.
QA76.76.063U548
1986
005.4'3
86-311
Select Code 320-034
ISBN 0-03-011207-9
Printed in the United States of America
Published simultaneously in Cariada
678 090 98765432
CBS COLLEGE PUBLISHING
Holt, Rinehart and Winston
The Dryden Press
Saunders College Publishing
PREFACE
The UNIX Programmer's Manual describes most of the features of the UNIX
System V. It does not provide a general overview of the UNIX system nor
details of the implementation of the system.
Not all commands, features, or facilities described in this series are available in
every UNIX system implementation. For specific questions on a machine
implementation of the UNIX system, consult your system administrator.
The UNIX Programmer's Manual is available in several volumes.
• Volume 1 contains the Commands and Utilities (sections 1 and 6)
• Volume 2 contains the System Calls and Library Routines (sections 2,3,4,
and 5).
• Volume 3 contains the System Administration Facilities (sections 1M, 7,
and 8).
• Volume 4 contains the Document Preparation Facilities (mm, tbl, etc.).
• Volume 5 contains the Languages and Support Tools (C language, lex,
make, etc.).
UNIX Programmer's Manual
Document Preparation-i
INTRODUCTION
An important feature of the UNIX* operating system is to provide a method of
document preparation and generation. This manual provides information
needed to make optimum use of the system. The following sections delve into
text editing features of the UNIX operating system and describe programs that
are used to format a document in a user controlled style.
The Document Preparation section contains three parts:
• UNIX System Facilities
• Advanced Editing
• Stream Editor
The Advanced Editing part describes text editing functions which include
special characters, line addressing, global commands, commands for cut and
paste operations, and text editor-based programs. The Stream Editor part
describes the noninteractive context editor. The UNIX System Facilities part
outines some other tools that aid in document preparation.
The Formatting Facilities section contains three parts:
• NROFF and TROFF User's Manual
• Table Formatting Program
• Mathematics Typesetting Program.
The NROFF and TROFF User's Manual part presents information to enable
the user to do simple formatting tasks and to make incremental changes to
existing packages of troff formatter commands. The UNIX operating system
formatter, nroff, is identical to the troff formatter in most respects. The Table
Formatting Program part describes the tbl program usage and the input
commands used to generate documents that contain tables. The Mathematics
Typesetting Program part describes the eqn program usage and language for
obtaining text with mathematical expressions. The language interfaces directly
..
Trademark of AT&T.
UNIX Programmer's Manual
Document Preparation-iii
with the troff processor so mathematical expressions can be embedded in the
running text of a manuscript and the entire document produced in one process.
The Memorandum Macros section is a user's guide and reference manual for
the Memorandum Macros (MM) package. These macros provide a general
purpose package of text formatting macros used with the nroff and troff
formatters. The macros provide users of the UNIX operating system a unified,
consistent, and flexible tool for producing many common types of documents.
Although the UNIX operating system provides other macro packages for
various specialized formats, MM is the standard general purpose macro
package for most documents such as letters, reports, technical memoranda,
released papers, manuals, books, design proposals, and user guides. Uses of
MM range from single-page letters to documents of several hundred pages in
length.
The Viewgraphs and Slides Macros section describes the MV package of
macros. These macros provide users a method of preparing viewgraphs and
slides using the troff formatter. Included is a discussion on the use of the
macros and a philosophy of how a viewgraph or slide should appear.
iv-Document Preparation
UNIX Programmer's Manual
TABLE OF CONTENTS
DOCUMENT PREPARATION
DOCUMENT PREPARATION . • . . • . •
UNIX SYSTEM FACILITIES. .
ADV ANCED EDITING
. • . • • .
Introduction • • . • • • . •
Special Characters • . • . •
Print and List Commands
Substitute Commands •
Undo Command . • • . .
Metacharacters .
Period . .
Backslash
Dollar Sign
Circumflex
Star
Brackets • • • • .
Ampersand
Operating On Lines
Substituting Newline Characters .
Joining Lines . . • • • • . .
Rearranging Lines • • • • .
Line Addressing in the Editor. •
Address Arithmetic • • . . • . •
Repeated Searches . • •
Default Line Numbers . • . • . •
Semicolon • • • • •
Interrupting the Editor .
. • . • . •
Global Commands.
Basic. • •••
Multiline • . • • •
Cut and Paste
...•••
Command Functions • . • . • • •
Change Name of Files
• . . • •
Copy Files. . . . .
• .•••
Combine Files . . •
• . • • •
Remove Files
. . • •
Text Editor Functions
File Names • . . .
Insert One File Into Another •
Write Out Part of a File ••
Move Lines Around .
Copy Lines
Marks • . • • •
Temporary Escape .
. . . . .
Supporting Tools . . • • • . • . • . •
Global Printing From a Set of Files (grep)
Editing Scripts . . • • • . •
STREAM EDITOR.
. •...
Introduction. • •
Overall Operation
Command Line . • . • . • .
Order of Application of Editing Commands
Pattern Space . • . . • . • . • . • • •
UNIX Programmer's Manual
•1
•1
•
•
•
•
·
•
•
•
•
·
·
·
·
•
·
·
·
. . . • .
•
•
. . . • . . . . . .
.
• . • • . .
•
•
•
•
•
•
•
·
.
.4
.4
.5
•5
.6
.7
.7
.8
.9
• 12
• 13
• 14
• 17
• 19
.20
.20
• 21
.22
.23
.23
.25
.26
.29
• 31
• 31
• 31
. 33
.34
.34
• 35
• 35
.36
• 37
• 38
• 38
• 39
.40
• 41
.42
.43
.44
.44
.44
.45
.47
.47
.48
.48
.48
.49
Document Preparation-v
Examples • • • . . . •.
•.•.•
..• . .
. • • 49
• . • . •
.• • 50
Selecting Lines for Editing
Line Number Addresses.
. . • . • • •
. •. 50
Context Addresses . . • . • •
. . • . • . .
• . 50
Number of Addresses . .
• . • • • • . . . . . • . .
• . 51
Functions. • • . . • .
• . • • • • . . . . . • . .
. 52
Whole Line Oriented Functions • . • • •
.. • . • . .
• • 52
..•.•.••••.....•..
. 55
Substitute Function
Pattern . . • .
. . • . • • • • • • • • . . . • . .
. • 55
Replacement. . .
. . • . • .
. . . • . . . . . . . 55
Flags . . . • . .
. . • • . . . . • .
. . • . • . . . 56
. . . . . .
. . 56
Examples . • . .
Input/Output Functions . . • . • • . • .
. 57
Multiple Input Line Functions
. . . • .
. . • . .
. 59
Hold and Get Functions • .
. . . • .
. . • . • . . . 59
Flow of Control Functions .
. . . . . • . .
. 60
Miscellaneous Functions • .
. . • . • . . . 62
FORMATTING FACILITIES
FORMATTING FACILITIES . • • . . • .
• .63
NROFF AND TROFF USER'S MANUAL • • • • .
• .63
INTRODUCTION . • . . . • . • . • •
• .63
USAGE . . . . . . • . . . • . • . . .
· .64
.68
NROFF/TROFF REFERENCE MANUAL
GENERAL EXPLANATION . . . • . . .
· . • . • . . . 68
Form of Input • . . • . • . • .
.68
Formatter and Device Resolution
• • • • • • • • 69
Numerical Parameter Input . . .
• • • • 69
Numerical Expressions •• . .•
. . . 70
Notation . . . . • . . . • .
• •• 71
Font and Character Size Control.
. 71
Fonts . . . •
• • 71
Character Set . . • . • •
• .72
Character Size .
· .73
Page Control • .
• .73
Text Filling, Adjusting, and Centering . . . . • . . • . •
• .74
Filling and Adjusting
• .74
Interrupted Text .
· .74
.75
Vertical Spacing . . • .
Base-line Spacing. . .
• .75
Extra Line Space . . .
.75
•.•••
Blocks of Vertical Space..
· . • . • . • • 76
Line Length and Indenting . . . • .
• . . • 76
Macros, Strings, Diversions, and Position Traps • . . • .
• .76
Macros and Strings • . • . . . •
· .76
Copy Mode Input Interpretation
• .77
Arguments
.78
.79
Diversions . . . .
Traps . • . . . . • . • . • •
· .80
Number Registers
..••.
· .80
Tabs, Leaders, and Fields . . . . . .
• . 81
Tabs and Leaders
• • 81
Fields. . . • • . • .
· .82
• 83
Input/Output Conventions and Character Translations
Input Character Translations. • . • . • •
• • • • .g3
vi-Document Preparation
UNIX Programmer's Manual
Ligatures . . . • . • . • . . . . . • . . .
• ••• 83
Backspacing, Underlining, and Overstriking
· .83
Control Characters . • . •
• • 83
Output Translation . • . • . . • . . • . . • . . .
• • 83
Transparent Throughput . • • . . • • . • .
· . . . 84
Comments and Concealed Newline Characters
· .84
Local Horizontal/Vertical Motion and Width Function
· • 85
Local Motion
· .85
Width Function • . • . • . . . . • • . • . . . . . . • . • · . • • 85
Mark Horizontal Place . • . . . . . • . . . . . .
· .86
Overstrike, Zero-Width, Bracket, and Line Drawing Functions
· .86
Overstrike • • . • . •
• ••• 86
Zero-Width Characters
· .87
Large Brackets. •
· .87
Line Drawing . • . •
· . . • 87
Hyphenation • • . . • .
• •• 89
Three-Part Titles
• .89
Output Line Numbering
• . . . . 90
Conditional Acceptance of Input .
· .90
Environment Switching . . • . .
.92
Insertions From Standard Input
· •• 92
Input/Output File Switching . • • • .
• •• 92
Miscellaneous . . . . . . .
.92
Output and Error. Messages • •
• ••• 92
Compacted Macros
• •• 93
Building a Compacted Macro Package
· .94
Produce Compacted Files • . • •
· .94
Install Compacted Files • • . • .
• •• 95
Install Noncompactible Segment
.95
TROFF TUTORIAL . . . . • . . . .
• •• 96
OVERVIEW • . • . . . • • . . •
• •• 96
POINT SIZES AND LINE SPACING
.97
FONTS AND SPECIAL CHARACTERS
• ••• 99
INDENTS AND LINE LENGTHS
• • 101
TABS • . • . . . . . • . • •
• • 103
LOCAL MOTIONS
• • 104
Vertical Motions .
• 104
Horizontal Motions
• • 105
Overstrikes • • . • . • . • • . • • . • • .
• • 107
Drawing Lines . .
. . . . . .
· 107
STRINGS . . . .
• . 107
INTRODUCTION TO MACROS . . • . • .
• • 108
TITLES, PAGES, AND PAGE NUMBERING
• 110
NUMBER REGISTERS AND ARITHMETIC
• • 114
MACROS WITH ARGUMENTS .
• • 117
CONDITIONALS .
. • . • • • .
• • 120
ENVIRONMENTS . . . . . • .
• • 122
DIVERSIONS . . . . • . • • • • • . •
• • 123
NROFF/TROFF TUTORIAL EXAMPLES.
• 125
PAGE MARGINS . . . . . • • .
• • 12~
PARAGRAPHS AND HEADINGS
• • 127
MULTIPLE COLUMN OUTPUT.
• 129
FOOTNOTE PROCESSING • • •
· .130
LAST PAGE • • • . . . . • • •
• .132
TABLE FORMATTING PROGRAM
. . • • 133
UNIX Programmer's Manual
Document Preparation-vii
INTRODUCTION. . • • . • 0 • 0 0 • •
0 0
USAGE o. 0 • • • • 0
0 • 0 • •
0 0
INPUT COMMANDS.
• 0 • 0 • • • •
Global Options • • •
. • • • 0 • • • • • • • • • 0
Format Section • • •
. • . • • • 0
• • • • 0 0 •
Data To Be Printed • • . . • . • . • .
.
ADDITIONAL COMMAND LINES
. . .• 0 0 •
EXAMPLES . . • • • • . • . • •
. . . . • . 0 •
MATHEMATICS TYPESETTING PROGRAM
.•.•• 0 •
INTRODUCTION.
. • . • . • . • • . • •.•• 0
USAGE
0 0 • 0 • 0 • 0
0 • 0 • 0
LANGUAGE 0 •
0 0 • 0 •
0 •
Design
• 0 • 0 • 0 • •
0 0 0 • 0
Structure • 0
0 • 0 • 0
0 0 0 • 0 0 •
Mode of Operation
• 0 • 0 • 0 • 0 •• 0 0
USER'S GUIDE 0 • • • • 0 • 0 • 0 •
Delimiters • 0 • 0
• 0 • 0 • 0 • 0
• 0 •
Spaces and New Lines • 0 • 0 • 0
Input Spaces 0 0 • • 0 0 • 0 • 0 • 0
0 • 0 • • 0
Output Spaces
Symbols, Special Names, and Greek Alphabet 0 • • • • • 0
Subscripts and Superscripts
• 0 • 0 •
o. 0 • • 0
Braces
Fractions • 0 • 0 • • • 0
0 0 • • • 0 • • 0 •
Square Roots 0 0 0 0 • • 0 • 0 0 • 0 0
0 • 0 • • 0
Summations, Integrals, and Similar Constructions
0
Size and Font Changes
Diacritical Marks 0
• 0 • • 0
0 0 •
Quoted Text 0 0 0
Aligning Equations
• 0 • 0 • • •
Big Brackets • • 0 •
0 • 0 • •
0 •
Piles • 0 0 ••• 0
0 • 0 • 0 • 0 •• 0 0 0 0 • 0
Matrices. • • • •
0 • 0 • 0 • 0 •• 0
0 • 0 0 •
In-Line Equations
0 • 0 • 0 •• 0 0
Defines •• 0
0 • 0 • 0 • 0
• 0 •• 0
Local Motions • •
0 • 0 •••• 0 • • • • • •
0
Precedence
• 0 • 0 • 0
••• 0 •• 0
TROUBLESHOOTING
0 • • • • •
FORMATTING FACILITIES EXAMPLES. 0
0 •
Figure 1 - Font Style Examples ••• 0 0 0 • 0 • • • • 0 0
Figure 2 - Example of Output Line Numbering •
Figure 3 - Table Using "box" Option •• 0 • •
0 •
Figure 4 - Table Using "allbox" Option • • 0 •
0 •
Figure 5 - Table Using "vertical bar" Key Letter Feature
•
Figure 6 - Table Using Horizontal Lines In Place Of Key Letters
Figure 7 - Table Using Additional Command Lines 0
0 0
Figure 8 - Table Using Text Blocks 0 •
0
Table A 0
0 0 0 • 0 0 • 0 • 0 • 0 0
•
Table B o o • 0 •• 0 •• 0 •
0 • 0 ••
Table C o o • 0 •• 0 • •
Table D •
0 • 0 • • • •
Table E 0
0 • 0 • 0
Table F
••••• 0
0 0 • 0 •• 0
Table G •. 0 • • • • • 0
• 0 • • •
• • 0 •• 0
Table H
• 0 ••••• 0 • 0 0
viii-Document Preparation
0 0 • 0 • 133
0 0 0 0 .133
• •• 135
• • 136
0 • • 0 • 137
0 • • • • 141
0 • • • 0 143
0 • • • 0 144
0 ••• 0 145
0 145
• 0146
0 0 • 0 0147
• 0 147
0 0 • • 0 148
••• 148
0 149
0 • 0 • • 149
0 150
• 0 150
0 0 • 0 150
0 0 • 0 151
0 0 • 0 152
0 0 • 0 154
0 0 0 • 0 155
0 0 155
0 0 0 • 0 156
0 0 157
0 00 0 0 159
0 • 0 • 159
• 0 • 160
0 0 • 0 • 161
0 • 162
0 0 • 0 • 163
0 164
0 0 • 0 165
0 0 0 • 0 167
0 0 • 0 167
0 0 168
0 0 0 • 0170
• 0 0 • 0 170
0 0 172
0 0 • 0 0 173
0 0 • 0 0 174
0 0 • 0 • 175
0 0 • 0 • 177
0 0 0 0 • 178
• 0 0 • 0 180
0 0 • 0 0 182
0 0 • 0 0 184
0 • 186
0 • 188
0 193
0 195
0 0 • 0 198
•• 200
UNIX Programmer's Manual
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
I
J
K
L
M
N
0
P
.•
..
.
.•.
••
.
.
.•
·
Q ..
R
S
T
U
V
W
X
Y
Z
.
.
..
•
.•.
.
.
•..
·
. . . . • •
·
.202
.203
• .206
.207
.209
.210
• • . 212
· 214
· 215
. • • 217
· 218
· 219
.220
• 221
.222
• • . 223
• .225
· .226
MEMORANDUM MACROS
MEMORANDUM MACROS
INTRODUCTION . . . . • . .
... .
Purpose . . . • . • .
. • . • . . • .
Conventions . . . .
. • • .
Document Structure
. . . •
Input Text Structure
. . . • .
Definitions . • • .•
...• • .
....
USAGE . . . . . . . .
The mm Command . . . • . .
The -cm or -mm Flag .
. . . .
Typical Command Lines . . . . • . .
.
Parameters Set From Command Line
.
Omission of -cm or -mm Flag. • • . . . . • . •
FORMATTING CONCEPTS . . • • . . . . . . .
Basic Terms . • . . . . • • .
.
Arguments and Double Quotes . . • .
Unpaddable Spaces . . . . • .
Hyphenation . . . . . . . • . . . • • .
Tabs . • . . . . . . . . . .
BEL Character. . . . . . • .
Bullets . • . . • . . . . • . .
Dashes, Minus Signs, and Hyphens
Trademark String . • . • • . . . . . . . . • .
Use of Formatter Requests . • • .
PARAGRAPHS AND HEADINGS.
Paragraphs . . • . • • . . . . . . . • .
Paragraph Indention • . . • • . . . • . .
Numbered Paragraphs • . . .
Spacing Between Paragraphs . . . .
Numbered Headings • . . . •
Normal Appearance . • . • . . • . . . . • • •
Altering Appearance. • • • .
Pres pacing and Page Ejection •
Spacing After Headings
Centered Headings
UNIX Programmer's Manual
. . . .
. . .
. . .
. ..•
.229
.229
· 229
.229
.230
• 231
• 231
• • 232
• 233
• 234
.235
.237
• 240
.241
.241
• 241
.242
• 243
• 244
.244
• 244
• 245
.245
• 246
• 247
• 247
.247
• 248
.249
.249
• 250
• • 251
.251
• 252
.253
Document Preparation-ix
Bold, Italic, and Underlined Headings
.253
Control by Level: . . • • • • . • •
.253
NROFF Underlining Style: • • • . •
• 253
Heading Point Sizes: • • • • • . • • . •
.254
Marking StylesNumerals and Concatenation
.255
Unnumbered Headings • • • • • . • . . • •
.255
Headings and Table of Contents • • • . • • • • • •
.256
First-Level Headings and Page Numbering Style
. • • .
.257
User Exit Macros. • • • • • . • • • .
.257
Hints for Large Documents • • • • • . • • •
• 259
LISTS . . • . . • • • • • • • • • • • • . • •
.260
.260
List Macros . . • • . • • • • • . • • . . .
List-Initialization Macros. • . . . • . . • • • . . • • .
.261
Automatically Numbered or Alphabetized List
· 261
.262
Bullet List • •.
.• • • . • • .
Dash List • • . •
• • • .
• 262
Marked List . . • • .
.263
.263
Reference List
Variable-Item List.
.264
List-Item Macro ••
.265
List-End Macro • • . •
.267
Example of Nested Lists • . • • . • •
• 267
List-Begin Macro and Customized Lists
.269
User-Defined List Structures • • • . • • . • • • . • • . . • • · 271
MEMORANDUM & RELEASED-PAPER STYLE DOCUMENTS .275
Sequence of Beginning Macros • • • • •
.275
Title . . . . .
. • • • •
.276
.277
Authors • • . •
• • . •
.278
TM Numbers .
Abstract. . • . .
• 278
Other Keywords .
• 279
Memorandum Types
.279
Date Changes • . • . . • •
· 281
.282
Alternate First-Page Format
.282
Example • . . . • . • . . • •
End of Memorandum Macros
.283
Signature Block • • . • • . •
• 283
"Copy to" and Other Notations
.284
Approval Signature Line
.• ••
.285
One-Page Letter . • .•
.•• •
• 286
DISPLAYS . • . .
• 286
Static Displays . .
• 287
Floating Displays .
• 289
Tables . . • • .
. .••.
• 291
.292
Equations . . • . • . . • • . • • • . • •
.293
Figure, Table, Equation, and Exhibit Titles . .
List of Figures, Tables, Equations, and Exhibits
• 294
.294
FOOTNOTES . . • • . • • . • •
.294
Automatic Numbering of Footnotes
Delimiting Footnote Text . • • •
.295
.296
Format Style of Footnote Text • •
.297
Spacing Between Footnote Entries •
.297
PAGE HEADERS AND FOOTERS
Default Headers and Footers • • • • • .
.298
Header and Footer Macros •
.298
x- Document
Preparation
UNIX Programmer's Manual,
Page Header . . . . .
.298
Even-Page Header.
.299
Odd-Page Header
.299
Page Footer
• . . . . . . . • .
. . • • • • . . • . . 299
Even-Page Footer • . . • . .
.299
Odd-Page Footer . . .
. .•.
· .300
First Page Footer • . . • • . • . . . . • . . . . . .
.300
Default Header and Footer With Section-Page Numbering .
.300
Strings and Registers in Header and Footer Macros
.300
Header and Footer Example • . . . . •
· 301
Generalized Top-of-Page Processing . . . . .
• 301
Generalized Bottom-of-Page Processing . . . . . . .
.303
Top and Bottom (Vertical) Margins . . • . . . . . .
.303
Proprietary Marking . . . . . . . . . . .
.304
Private Documents . . . . . . . . . • . .
.304
TABLE OF CONTENTS AND COVER SHEET.
.305
Table of Contents. . . . . . . . . . .
· .305
Cover Sheet . . . . • . . . . . .
.308
REFERENCES. . . . . . . . . . .
.308
Automatic Numbering of References
.308
Delimiting Reference Text . . .
· .308
Subsequent References . . . .
.309
Reference Page. . . . . . . .
.309
MISCELLANEOUS FEATURES . . . •
· .310
Bold, Italic, and Roman Fonts .
. ...
· 310
Justification of Right Margin . .
. • . . . . . .
• . 312
SCCS Release Identification . .
.•..
. . • .
• 312
Two-Column Output • . . . . . . . .
· 313
Column Headings for Two-Column Output.
· .314
Vertical Spacing . . • . . . . . . .
· • 315
Skipping Pages . . . . . . . . . . . . . • . . . . . . . . • • 315
Forcing an Odd Page . . . . . . . . .
.316
Setting Point Size and Vertical Spacing
• 316
Reducing Point Size of a String.
• 317
Producing Accents . . . .
• 318
Inserting Text Interactively . .
· • 318
ERRORS AND DEBUGGING . .
· • 319
Error Terminations . . . . . .
• • 319
Disappearance of Output
. . . . . . . .
· .320
EXTENDING AND MODIFYING MM MACROS . . . .
• 320
Naming Conventions . . . . . . . .
• 320
Names Used by Formatters . . . . .
• . 321
Names Used by MM . . . . . . . . . • .
• • 321
Names Used by cw, eqn/neqn, and tbl
.322
Names Defined by User . . .
· • 322
Sample Extensions . . . . . .
. . . •
• 322
Appendix Headings . . . . •
. • • . • • 322
Hanging Indent With Tabs . . .
• . • . . • • 323
SUMMARY •.
• • 325
Table AA . . . .
. •• 326
Table BB
· • 333
Table CC
• .335
UNIX Programmer's Manual
Document Preparation-xi
VIEWGRAPHS AND SLIDES MACROS
VIEWGRAPHS AND SLIDES MACROS • • .
• • • . . • • 341
INTRODUCTION .
• . • .
.341
MACROS • . . .
.341
Foil-Start Macros
• 341
Level Macros • .
• 343
The .A Level. . . . •
• 343
The .B Level . . ' . • .
• 344
The .C Level. .
• • • .
. • ••
• 345
The .D Level .
• • • • . • ••
• 345
Titles . • . . . . . .
• • • • 345
Global Indents
• • . • .
• • • • . • • 345
Point Sizes and Line Lengths . • . •
• 346
Default Fonts • . . . •
• 346
Default Vertical Space •
. . • • . .
• 347
Underlining • . . . .
. . • • • .
• 347
Synonyms . • . . . .
. ••.
• 348
Breaks . . . • . • . . . • • • . • .
• 348
Text Filling, Adjusting, and Hyphenation . . • . .
· ••• 348
THE TROFF PREPROCESSORS . .
· • • • 348
Tables . • . . . . . • . • • . • .
. • • 348
Mathematical Expressions • • • • .
• 349
Constant-Width Program Examples ••
. • 349
FINISHED PRODUCT • . . . . . •
• 349
Phototypesetter Output. . • . • .~ •
• 349
Output Approximation on a Terminal
• 350
Making Actual Viewgraphs and Slides
• 350
SUGGESTIONS FOR USE •.
•• • .
• • • . . • • • 351
WARNINGS • . • . . . • .
. • • 353
Use of troff Formatter Requests .
• • • . . • • 353
Reserved Names • . . . • •
· • • • 353
Miscellaneous. . . . . . • .
· • • • 353
. . • •
DIMENSIONAL DETAILS • •
. • • 354
Table DD
• • • . . • • 354
Table EE . . . . . . . • .
• . • • • • • 355
xii-Document Preparation
UNIX Programmer's Manual
LIST OF FIGURES AND TABLES
Figure 1 - Font Style Examples . . . . . . . . . . . • . . . · •. 170
Figure 2 - Example of Output Line Numbering . . . . • .
· 172
Figure 3 - Table Using "box" Option . • . . .
. • . . · • • 173
Figure 4 - Table Using "allbox" Option • . . . • . • .
• 174
Figure 5 - Table Using "vertical bar" Key Letter Feature •.
• . 175
Figure 6 - Table Using Horizontal Lines In Place Of Key Letters
· 177
Figure 7 - Table Using Additional Command Lines
• 178
Figure 8 - Table Using Text Blocks • . • . . . . . .
· 180
.•. • • .
Table A
. . • • • .
• 182
Table B
• • • • • • •
•. 184
Table C
. . . . . • . . . • • • 186
Table D
• • • • • •
. • • 188
Table E
• • • • • • • . . • • . . . • • 193
Table F
· • • • .
• 195
Table G
• • • • • . • • • ••
. 198
Table H
• • • • • . • •
• 200
Table I
.202
Table J
• • • • . • • .
. 203
Table K
• • • • • • •
• 206
Table L
• . • • . . . . . . . . • • • • 207
Table M .
. 209
• • • • • • • • • • • .
Table N
• • • • • •
• . 210
Table 0
• • • • . • • • • • • •
•. 212
Table P
· • • • .
• • . • • • • • 214
Table Q
. . • • • • • • . 215
Table R
· •• 217
Table S
• • • • • • •.
• . • • 218
Table T
. • . . • . • . 219
Table U
. . . • . • . . ..
. 220
Table V
• . • • 221
Table W .
• . • • 222
Table X
.223
Table Y
• ••• 225
Table Z
.226
Table AA
• • • • • • • • • • • • • • 326
Table BB
· . . . . . . • . • • 333
Table CC
• . . • . . •
• • • • 335
Table DD
. • • • • • • • • 354
Table EE
. • • • • • • • 355
UNIX Programmer's Manual
Document Preparation-xiii
DOCUMENT PREPARATION
The following section deals with the basics of document preparation. The
sections covered are:
• UNIX SYSTEM FACILITIES
• ADVANCED EDITING
• STREAM EDITOR
UNIX SYSTEM FACILITIES
Several miscellaneous facilities exist (via UNIX operating system commands) to
aid in the development of documentation. These facilities are easy to access
and are very effective. Their use is beneficial in documentation development.
Some available miscellaneous facilities are described briefly in the following
list. The UNIX Programmer's M anual- Volume 1: Commands and Utilities
has a more detailed list.
bdiff
The bdiff facility is used in a manner analogous to diff to find
which lines must be changed in two files to bring them into
agreement. Its purpose is to allow processing of files which
are too large for diff.
cat
The cat facility reads each file in sequence and writes it on
the standard output. Thus:
cat file
prints the file named file, and
cat file 1 file2
>file3
concatenates filel and file2 and places the result in file3 .
UNIX Programmer's Manual
Document Preparation-l
DOCUMENT PREPARATION
cmp
The cmp facility compares two files. Under default options,
cmp makes no comment if the files are the same; if they
differ, it announces the byte and line number at which the
difference occurred.
comm
The comm facility selects or rejects lines common to two
sorted files. It reads filel and file2 and produces a 3-column
output as follows: lines only in filel , lines only in file2, and
lines in both files.
diff
The diff facility is a differential file comparator. It tells
what lines must be changed in two files to bring them into
agreement.
diff3
The diff3 facility is a 3-way differential file (files up to 64K)
comparator. It compares three versions of a file and
publishes disagreeing ranges of text flagged with special
codes.
diffmk
The diffmk facility marks the differences between files. It
compares two versions of a file and creates a third file that
includes "change mark" commands for the nroff or troff
formatter.
grep
Commands of the grep facility search the input files for lines
matching a pattern. Normally, each line found is copied to
the standard output. The grep patterns are limited regular
expressions in the style of ed. The egrep patterns are full
regular expressions. The fgrep patterns are fixed strings.
pr
The pr facility prints the named files on the standard output.
If file is - or if no files are specified, the standard input is
assumed.
sdiff
The sdiff facility uses the output of diff to produce a sideby-side listing of two files indicating those lines that are
different. Each line of the two files are printed with a blank
gutter between them if the lines are identical, a > in the
gutter if the line exists only in filel, a < in the gutter if the
line exists only in file2, and a I for lines that are different.
sort
The sort facility sorts lines of all the named files together
and writes the results on the standard output.
2-Document Preparation
UNIX Programmer's Manual
spell
The spell facility collects words from the named files and
looks them up in a spelling list. Words that do not occur in
the spelling list nor can be derived from them are printed on
the standard output. The spellin and spellout programs are
two additional subroutines of spell.
split
The split facility splits a file into pieces.
typo
The typo facility searches through a document for unusual
words, typographical errors, and hapax legomena and prints
them on the standard output.
uniq
The uniq facility reports repeated lines in a file. It reads the
input file comparing adjacent lines. In the normal case, the
second and succeeding copies of repeated lines are removed;
the remainder is written on the output file.
UNIX Programmer's Manual
Document Preparation-3
DOCUMENT PREPARATION
ADVANCED EDITING
Introduction
The advanced editing part is meant to help UNIX operating system users
(secretaries, typists, programmers, etc.) make effective use of facilities for
preparing and editing documents, text, programs, files, etc. It provides
. explanations and examples of:
• special characters, operating on lines, line addressing, and global commands
in the text editor (ed)
• commands for "cut and paste" operations on files and parts of files, including
mv, cp, cat, and rm commands, and r, W, m, and t commands of the text editor
(ed)
• editing scripts and text editor-based programs like grep and sed {7}.
Examples are based on experience and observations of users and the difficulties
encountered.
Although this document is written for non-programmers, new UNIX operating
system users with any background should find helpful hints on how to get their
jobs done more easily. The UNIX operating system provides tools for text
editing, but that by itself is no guarantee that everyone will make the most
effective use of them. In particular, users who are not computer specialists
(typists, secretaries, casual users) often use the UNIX operating system less
effectively than they could.
The next paragraphs discuss shortcuts and labor-saving devices. Not all will be
instantly useful (some will) and others should provide ideas for future use.
A document like this should provide ideas about what to try. There is only one
way to learn to use something, and that is to use it. Reading a description is
no substitute for hands-on use.
The reader should be familiar with the HOW TO GET STARTED section of the
UNIX Programmer's Manual-Volume 1: Commands and Utilities before
using the text editor. Further information on all commands discussed here can
be found in:
4-Document Preparation
UNIX Programmer's Manual
• UNIX Programmer's Manual-Volume 1: Commands and Utilities
• UNIX
Programmer's Manual-Volume 2: System
Calls and Library
Routines
• UNIX Programmer's M anual-Volume 3: System Administration Facilities
Special Characters
The ed program is the primary interface to the system, so it is worthwhile to
know how to get the most out of it with the least effort.
Print and List Commands
Two commands are provided for printing contents of lines being edited. Most
users are familiar with the print command (p) in combinations like
1,$p
to print all lines that are being edited, or
sl a bcl def! p
to change the first "abc" to "def' on the current line and print the results.
Less familiar is the list command 0) which gives slightly more information
than p. In particular, I makes characters visible that are normally invisible,
such as tabs and backspaces. If a line contains some of these, the I command
will print each tab as '~>" and each backspace as "<". This makes it easier
to correct typing mistakes that insert extra spaces adjacent to tabs or a
backspace followed by a space.
The I command also "folds" long lines for display purposes. Any line that
exceeds 72 characters is printed on multiple lines. Each printed line except the
last is automatically terminated by a backslash (\) to indicate that the line was
folded. A "$" character is appended to the real end of line. This is useful for
printing long lines on terminals having output line capability of only 72
characters per line.
UNIX Programmer's Manual
Document Preparation-5
DOCUMENT PREPARATION
Occasionally, the I command will print a string of numbers preceded by a
backslash, such as "\07" or "\16". These combinations are used to make
characters visible that normally do not print, e.g., form feed, vertical tab, or
bell. Each such combination is interpreted as a single character. When such
characters are detected, they may have surprising meanings when printed on
some terminals. Often their presence means that a finger slipped while typing.
Substitute Commands
The substitute command (s) is used for changing the contents of individual
lines. It is probably the most complex and effective of any ed command.
The meaning of a trailing global command (g) after a substitute command is
illustrated in the next two commands:
s/this/thatl
and
sl thisl tha tl g
The first form replaces the first "this" on the line with "that". If there is more
than one occurrence of "this" on the line, the second form (with the trailing g)
changes all of them. Either of the two forms of the s command can be
followed by p or I to print or list the contents of the line:
sl thisl tha tl p
slthisl thatIl
slthislthatl gp
slthislthatlgl
All are legal and have slightly different meanings.
An s command can be preceded by one or two line numbers to specify that the
substitution is to take place on a group of lines specified by the line numbers.
Thus:
6-Document Preparation
UNIX Programmer's Manual
1,$sl mispelll misspelll
changes the first occurrence of "mispell" to "misspell" on every line of the file.
The following command changes every occurrence on every line:
l,$s/mispell/misspell/g
By adding a p or I to the end of any of these substitute commands, only the last
line that was changed will be printed, not all lines. How to print all the lines
that were changed is described in a later section.
Any character can be used to delimit pieces of an s command. There is
nothing sacred about slashes (but slashes must be used for context searching).
For instance, for a line that contains a lot of slashes already, e.g.:
II exec f Isys. fort. go f f etc ...
a colon could be used as the delimiter. To delete all the slashes, the command
is
sf: I::g
Undo Command
Occasionally, an erroneous substitution is made in a line. The undo command
(u) negates the last command so that data is restored to its previous state.
This command is especially useful after executing a global command if it is
discovered the command did things that are undesirable.
Metacharacters
When using ed, certain characters have special meanings when they occur in
the left side of a substitute command or in a search for a particular line. These
are called "metacharacters" which are:
• Period.
• Backslash \
UNIX Programmer's Manual
Document Preparation-7
DOCUMENT PREPARATION
• Dollar Sign $
• Circumflex "
• Star
*
• Brackets [
• Ampersand &
Even though metacharacters are discussed separately in the following text, they
can be combined.
Period
The period (.) on the left side of a substitute command or in a search stands
for any single character. Thus the search
Ix. yl
finds any line where "x" and "y" occur separated by a single character, as in
x+y
x-y
xy
x.y
The" " stands for a space character whenever needed to make it visible.
Since the period matches any single character, a way to deal with the
"invisible" characters printed by I is available. For instance, if there is a line
that when printed with the I command, appears as
... th\07is ...
and it is desired to get rid of the "\07" (the bell character), the most obvious
solution is to try
8-Document Preparation
UNIX Programmer's Manual
s/\ 071 I
This will fail. Retyping the entire line is a reasonable tactic if the line in
question is not too long. However, for a very long line, retyping could result in
additional errors. Since "\07" really represents a single character, the
command
slth . islthisl
gets the job done. The period matches the mysterious character between the
"h" and the "i".
Since the period matches any single character, the command
s/.l,!
converts the first character on the line into a " , ".
As is true of many characters in ed, the period has several meanings depending
on its context. In the line
.s/./. I
• The first period is the line number of the line being edited, which is called
"dot" .
• The second period is a metacharacter that matches any single character on
that line (in this instance the first character of the line).
• The third period is the only one that really is a literal period. On the right
side of a substitution, the period is not special.
Backslash
Since a period means "any character", the question arises of what to do when a
period is really needed. For example, to convert the line:
N ow is the time.
UNIX Programmer's Manual
Document Prepara tion-9
DOCUMENT PREPARATION
into
N ow is the time?
the backslash (\) is used. A backslash turns off any special meaning that the
next character might have. In particular, "~~' .. converts the period from a
"match anything" into a "match the pedod" statement. The" \." pair of
characters is considered by ed to be a single literal period. To replace the
period with a question mark, the following command is used:
s/\. /? /
The backslash can also be used when searching for lines that contain a special
character. If a search is made to look for a line that contains
.PP
the search
/.PP/
is not adequate. It will find a line like
THE APPLICATION OF ...
The period matches the letter "A". But if the command
/\.PP/
is used, only the lines that contain ".PP" are found.
The backslash can also be used to turn off special meanings for characters
other than the period. For example, to find a line that contains a backslash,
the search
10-Document Preparation
UNIX Programmer's Manual
1\1
will not work because the" \ " is not a literal backslash, but instead means that
the second "I" no longer delimits the search. A search can be made for a
literal backslash by preceding a backslash with another" \ ":
1\\1
Similarly, searches can be made for a slash (/) with
1\11
The backslash turns off the meaning of the immediately following" /" so that
it does not terminate the search prematurely.
Some substitute commands, each of which will convert the line
\x\ .\y
into the line
\x\y
are
s/\\\. I I
s/x .. /xl
s/ .. y/yl
The user's erase character and the line kill character (# and @ by default)
must also be used with a backslash to turn off their special meaning. When
adding text with append (a), insert 0), or change (c) commands, the backslash
is special only for the erase and line kill characters, and only one backslash
should be used for each one needed.
UNIX Programmer's Manual
Document Preparation-II
DOCUMENT PREPARATION
Dollar Sign
In the left side of a substitute command or in a search command the dollar
sign ($) stands for "the end of line". The word "time" is added to the end of
the following phrase:
Now is the
with the following command:
s/$1 timel
The result is
N ow is the time
A space is needed before "time" in the substitute command, otherwise, the
following will be printed:
N ow is thetime
The second comma in the following line can be replaced with a period without
altering the first:
N ow is the time, for all good men,
The needed command is
s/, $1.1
The "$" provides context to indicate which specific comma. Without it the s
command would operate on the first comma to produce
N ow is the time. for all good men,
To convert
12-Document Preparation
UNIX Programmer's Manual
N ow is the time.
into
N ow is the time?
that was previously done with the backslash, the following command is used:
s/.$I?1
The "$" has multiple meanings depending on context. In the line
$s/$ 1$ 1
• The first $ refers to the last line of the file.
• The second $ refers to the end of the line.
• The third $ is a literal dollar sign to be added to that line.
Circumflex
The circumflex ("), alias "hat" or "caret", stands for the beginning of the line.
For example, if a search is made for a line that begins with "the", the
command
Ithel
will probably find several lines that contain "the" before arriving at the line
that was wanted. But the command
1 "thel
narrows the context, and thus arrives at the desired line more quickly.
The other use of the circumflex is to enable text to be inserted at the beginning
of a line. For example:
UNIX Programmer's Manual
Document Preparation-13
DOCUMENT PREPARATION
sl AI 1
places a space at the beginning of the current line.
Metacharacters can be combined. For example, to search for a line that
contains only the characters
.PP
the command
I A\ .PP$I
can be used.
Star
The star (*) is useful to replace all spaces between x and y with a single
space, as in the following example:
text x
y text
where text stands for lots of text, and there are an indeterminate number of
spaces between x and y. The line is too long to retype, and there are too many
spaces to count.
A regular expression (typically a single character) followed by a star stands for
as many consecutive occurrences of that regular expression as possible. To
refer to all the spaces at once, the following command is used:
sIx *y/x yl
The construction * means "as many spaces as possible". Thus
x < sp > *y means: "an x, followed by as many spaces as possible, and then a
y".
The star can be used with any character, not just space. If the original
example was
14-Document Preparation
UNIX Programmer's Manual
text x--------y text
then all "-" characters can be replaced by a single space with the command
s/x-*y/xyl
If the original line was
text x ......... y text
and if the following command was typed:
sIx. *y/x yl
what happens depends upon the occurrence of other x's or y's on the line. If
there are no other x's or y's, then everything works, but it is blind luck, not
good management. Since a period matches any single character, then •*
matches as many single characters as possible. Unless the user is careful the
star can eat up a lot more of the line than expected. If the line was
text x text x ......... y text y text
then the command will take everything from the first "x" to the last "y",
which, in this example, is undoubtedly more than wanted. The proper way is
to turn off the special meaning of period with "\. ".
s/x\. *y/x yl
Now everything works since "\. *" means "as many periods as possible".
There are times when the pattern " *" is exactly what is wanted.
example, to change
For
N ow is the time for all good men ...
into
UNIX Programmer's Manual
Document Preparation-I 5
DOCUMENT PREPARATION
Now is the time.
the following deletes everything after the word "time":
sl for. * 1,/
There are a couple of additional pitfalls associated with * to be aware of. Most
notable is that "as many as possible" means zero or more. The fact that zero
is a legitimate possibility is sometimes rather surprising. For example, if a line
contains
text xy text x
y text
and the command is
sIx *y/x yl
the first "xy" matches this pattern, for it consists of an "x", zero spaces, and a
"y". The result is that the substitute acts on the first "xy" and does not touch
the later one that actually contains some intervening spaces. The proper way is
to specify a pattern like
Ix *yl
which says "an x, a space, as many more spaces as possible, and then a y" (in
other words, one or more spaces).
The other startling behavior of * is also related to the zero being a legitimate
number of occurrences of something followed by a star. The command
s/x*/y/g
when applied to the line
abcdef
16-Document Preparation
UNIX Programmer's Manual
produces
yaybycydyeyfy
which is almost certainly not what was intended. The reason for this behavior
is that zero is a legal number of matches, and there is no "x" at the beginning
of the line (so that gets converted into a "y"), nor between the "a" and the "b"
(so that gets converted into a "y"), etc. The following command:
s/xx*/y/g
where "xx*" is "one or more x's", when applied to the line
abcdefxghi
produces
abcdefyghi
Brackets
Should a number that appears at the beginning of all lines of a file need to be
deleted, a first thought might be to perform a series of commands like:
I,$sl "I *11
I,$s/" 2*11
I,$s/" 3*11
This is going to take forever if the numbers are long. Unless it is desired to
repeat the commands over and over until finally all numbers are gone, the
digits can be deleted on one pass. This is the purpose of brackets ([]).
The construction
[0123456789]
UNIX Programmer's Manual
Document Preparation-I7
DOCUMENT PREPARATION
matches any single digit. The whole thing is called a "character class". With
a character class, the job is easy. The pattern "[0123456789]*" matches zero
or more digits (an entire number), so
1,$s/" [0123456789]* II
deletes all digits from the beginning of all lines.
Any characters can appear within a character class; and just to confuse the
issue, there are essentially no special characters inside the brackets. Even the
backslash does not have a special meaning. The following command searches
for special characters within the brackets:
1[,\ $ "[ ]1
Within a character class, the "[" is not special. To get a "]" into a character
class, it should be placed as the first character in the class. For example:
1 [ 1.\$ "[ ] 1
It is a nuisance to have to spell out the digits. They can be abbreviated as
[0-9]; similarly, [a-z] stands for the lowercase letters and [A-Z] for
uppercase letters.
The user can specify a character class that means "none of the following
characters". This is done by beginning the class with a circumflex.
[" 0 - 9]
which stands for "any character except a digit". The following search finds the
first line that does not begin with a tab or space:
I" [ " (space) (tab) ] 1
Within a character class, the circumflex has a special meaning only if it occurs
at the beginning. For example:
18-Document Preparation
UNIX Programmer's Manual
1"['''']1
finds a line that does not begin with a circumflex.
Ampersand
The ampersand (&), is used primarily to save typing. For example, if the
following is the original line:
N ow is the time
and it needs to be
Now is the best time
the command
s/the/the bestl
can be used, but it is unnecessary to repeat the "the". The & is used to
eliminate the repetition. On the right-hand side of a substitute command, the
ampersand means "whatever was just matched", so in the command
s/thel & bestl
the & represents "the". This is not much of a saving if the thing matched is
just "the"; but if it is something long or complicated or if it is something (such
as .*) which matches a lot of text, the & can save some tedious typing. There
is also much less chance of making a typing error in the replacement text. For
example, to parenthesize a line, regardless of its length:
s/. * I (&) I
The ampersand can occur more than once on the right side.
s/thel & best and & worst/
UNIX Programmer's Manual
Document Preparation- ~ 9
DOCUMENT PREPARATION
makes the original line
N ow is the best and the worst time
and
sf. */ &? &!!/
converts the original line into
Now is the time? Now is the time!!
To get a literal ampersand, the backslash is used to turn off the special
meaning.
s/ampersand/\& /
converts the word into the symbol. The & is not special on the left-hand side
of a substitute, only on the right.
Operating On Lines
Substituting Newline Characters
The ed program provides a facility for splitting a single line into two or more
lines by substituting in a newline character. If a line is unmanageably long
because of editing or merely because of the way it is typed, it can be divided as
follows:
text xy text
can be broken between the "x" and the "y" with the following substitute
command:
20-Document Preparation
UNIX Programmer's Manual
s/xy/x\
y/
This is actually a single command although it is typed on two lines. Since the
" \" turns off special meanings, a "\" at the end of a line makes the new line
character there no longer special. When a new line is substituted in, dot is left
pointing at the last line created.
A single line can be made into several lines with this same mechanism. The
word "very" in the following example can be put on a separate line preceded
with the nrofT formatter underline command CuI):
text a very big text
The commands
s/ very /\
.ul\
very\
/
convert the line into four shorter lines:
text a
.ul
very
big text
The word "very" is preceded by the line containing the" .ul" and spaces around
"very" are eliminated at the same time.
Joining Lines
Lines maybe connected with the join command (j). Given the lines
Now is
the time
and if dot is set to the first line, then the j command joins them together. No
UNIX Programmer's Manual
Document Preparation-21
DOCUMENT PREPARATION
spaces are added which is why a space is shown at the beginning of the second
line.
All by itself, a j command joins dot to dot+ 1. Any contiguous set of lines can
be joined by specifying the starting and ending line numbers. For example:
1,$jp
joins all the lines into a big one and prints it.
Rearranging Lines
The & metacharacter stands for whatever was matched by the left side of an s
command. Similarly, several pieces can be captured of what was matched; the
only difference is it must be specified on the left side just what pieces the user
is interested in. For instance, if there is a file of lines that consist of names in
the form
Smith, A. B.
Jones, C.
etc., and it was intended to have the initials to precede the name, as in:
A. B. Smith
C. Jones
It is possible to do this with a series of tedious and error-prone editing
commands. The alternative is to "tag" the pieces of the pattern (in this case,
the last name and the initials) and then rearrange the pieces. On the left side
of a substitution if part of the pattern is enclosed between "\ (" and "\)",
whatever matched that part is remembered and available for use on the right
side. On the right side, the symbol "\1 " refers to whatever matched the first
" \ (. .. \) " pair, "\2" to the second "\ (. .. \) " pair, etc.
The command
1,$s/"\ ([",]*\),*\ (.*\)/\2\ 11
22-Document Preparation
UNIX Programmer's Manual
although hard to read, does the job. The first "\ ( ... \)" matches the last
name, which is any string up to the comma; this is referred to on the right side
with "\1". The second "\{ ... \)" is whatever follows the comma and any
spaces and is referred to as "\2 ".
With any complicated editing sequence, it is foolhardy to run it and hope.
Global commands provide a way to print those lines affected by the substitute
command.
Line Addressing in the Editor
Line addressing in ed specifies the lines to be affected by editing commands.
Previous constructions like
1,$s/x/y/
were used to specify a change on all lines. Most users are familiar with using a
single newline character (or return) to print the next line and with
/string/
to find a line that contains "string". Less familiar is the use of
?string?
to scan backwards for the previous occurrence of "string". This is handy when
the user realizes that the string to be operated on is back up the page (file)
from the current line being edited. The slash and question mark are the only
characters that can be used to delimit a context search. '
Address Arithmetic
It is possible to combine line numbers like ".", "$", "/ ... / ", and "?.?"
with "+" and "-". Thus:
$-1
UNIX Programmer's Manual
Document Preparation-23
DOCUMENT PREPARATION
is a command. to print the next to last line of the current file (i.e., one line
before line $). For example:
$-5,$p
prints the last six lines. If there are not six lines, an error message will be
indicated.
As another example:
.-3,. +3p
prints from three lines before the current line to three lines after. The" +"
can be omitted:
.-3,.3p
is identical in meaning.
Another area in which to save typing effort in specifying lines is by using" -"
and" +" as line numbers by themselves. For instance, a
by itself is a command to move back up one line in the file. Several minus
signs can be strung together to move back up that many lines:
moves up three lines, as does" -3". Thus:
-3,+3p
is also identical to the examples above.
24-Document Preparation.
UNIX Programmer's Manual
Since "-" is shorter than ".-1", constructions like
- , . s/badl goodl
are useful. This changes the first occurrence of "bad" to "good" on both the
previous line and the current line.
The "+" and "-" can be used in combination with searches using
" Istring/", "?string?", and" $". The search
Istring/-finds the line containing "string" and positions dot two lines before it.
Repeated Searches
When the search command is
Ihorrible stringl
and when the line is printed, it is discovered that it is not the "horrible string"
that was wanted. It is necessary to repeat the search again, but it is not
necessary to retype it. The construction
II
is a shorthand for "the string that was previously searched for", whatever it
was. This can be repeated as many times as necessary. This also applies to the
backwards search
??
which searches for the same string but in the reverse direction.
Not only can the search be repeated, but the / / construction can be used. on
the left side of a substitute command to mean "the most recent pattern":
UNIX Programmer's Manual
Document Preparation-25
DOCUMENT PREPARATION
Ihorrible stringl
--- ed prints line with "horrible string"
sllgood/p
--- ed prints the corrected line
To search backwards and change a line, the following command is used:
??sllgoodl
Of course, the & on the right-hand side of a substitute can still be used to
stand for whatever got matched:
I lsI 1& &/p
finds the next occurrence of whatever was searched for last, replaces it by two
copies of itself, and then prints the line to verify that it worked.
Default Line Numbers
One of the most effective ways to speed editing is by knowing which lines are
affected by a command with no address and where dot will be positioned when
a command finishes. Editing without specifying unnecessary line numbers can
save a lot of typing. As the most obvious example, the search command
Istringl
puts dot at the next line that contains "string". No address is required with
commands like:
•. p to print the current line
• I to list the current line
• d to delete the current line
• a to append text after the current line
• c to change the current line
26-Document Preparation
UNIX Programmer's Manual
• i to insert text before the current line .
• s to make a substitution on the current line
If there was no "string" detected, dot stays on the line where it was. This is
also true if it was sitting on the only "string" when the command was issued.
The same rules hold for searches that use" ?string?"; the only difference is
direction of search.
The delete command (d) leaves dot at the line following the last deleted line.
However, dot points to the new last line when the last line is deleted.
Line-changing commands a, c, and i affect (by default) the current line if no
line number is specified. They behave identically in one respect - after
appending, changing, or inserting, dot points at the last line entered. For
example, the following can be done without specifying any line number for the
substitute command or for the second append command:
a
--- text
--- botch
s/botch/ correct/
a
--- more text
(minor error)
(fix botched line)
The following overwrites the major error and permits continuation of entering
information:
a
--- text
--- horrible botch
(major error)
c
--- fixed up line
--- more text
(replace entire line)
The read command (r) will read a file into the text being edited, either at the
end if no address is given or after the specified line if an address is given. In
either case, dot points at the last line read in. The Or command can be used to
read in a file at the beginning of the text and the Oa or Ii commands can be
used to start adding text at the beginning.
UNIX Programmer's Manual
Document Preparation-27
DOCUMENT PREPARATION
The write command (w) writes out the entire file. If the command is preceded
by one line number, that line is written. Preceding the command by two line
numbers causes a range of lines to be written. The w command does not
change dot, therefore, the current line remains the same regardless of what
lines are written. This is true even if a command like
/ A\ .AB/, / A\ .AE/w abstract
is made which involves a context search. Since the w command is easy to use,
the text being edited should be saved regularly just in case the system crashes
or a file being edited is clobbered.
The command with the least intuitive behavior is the s command. The dot
remains at the last line that was changed. If there were no changes, then dot is
unchanged. To illustrate, if there are three lines in the buffer and dot is sitting
. on the middle one:
xl
x2
x3
the command
-,+s/x/y /p
prints the third line, which is the last one changed. But if the three lines had
been:
xl
y2
y3
and the same command issued while dot pointed at the second line, then the
result would be to change and print only the first line and. that is where dot
would be set.
28-Document Preparation
UNIX Programmer's Manual
Semicolon
Searches with" I . .. I" and" ? .. ?" start at the current line and move forward
or backward, respectively, until they either find the pattern or get back to the
current line. Sometimes this is not what is wanted. Suppose, for example, that
the buffer contains lines like
ab
bc
Starting at line 1, one would expect that the command
la/,/b/p
prints all the lines from the "ab" to the "bc", inclusive. This is not what
happens. Both searches (for "a" and for "b") start from the same point, and
thus they both find the line that contains "ab". The result is to print a single
line. If there had been a line with a "b" in it before the "ab" line, then the
print command would be in error since the second line number would be less
than the first; and it is illegal to try to print lines in reverse order. This is
because the comma separator for line numbers does not set dot while each
address is processed. Each search starts from the same place.
In ed, the semicolon (;) can be used just like comma with the single difference
that use of a semicolon forces dot to be set at that point while line numbers are
being evaluated. In effect, the semicolon "moves" dot. Thus in the example
above, the command
la I; Ib/p
prints the range of lines from "ab" to "bc" because after the "a" is found dot
is set to that line, and then "b" is searched for starting beyond that line. This
UNIX Programmer's Manual
Document Preparation-29
DOCUMENT PREPARATION
property is most often useful in a very simple situation. If the need is to find
the second occurrence of "string", then the commands
Istringl
II
print the first occurrence as well as the second. The command
Istring 1;/1
finds the first occurrence of "string" and sets dot there. Then it finds the
second occurrence and prints only that line.
Searching for the second previous occurrence of "string", as in
?string?;??
is similar. Printing the third, fourth, etc. occurrence in either direction is left
as an exercise.
When searching for the first occurrence of a character string in a file where dot
is positioned at an arbitrary place within the file, the command
1; Istringl
will fail if "string" occurs on line 1. It is possible to use the command
0; Istring I
(one of the few places where 0 is a legal line number) to start the search at
line 1.
.
3D-Document Preparation
UNIX Programmer's Manual
Interrupting the Editor
If the user interrupts ed while performing a command by depressing the
BREAK key, the INTERRUPT key, or the user interrupt character (RUB
OUT or DEL CHAR keys by default), the file is put back together again. The
file state is restored as much as possible to what it was before the command
began. Naturally, some changes are irrevocable. If the file is being read from
or written into, substitutions are being made, or lines are being deleted, these
will be stopped in some clean but unpredictable state in the middle of the
command execution (which is why it is not usually wise to stop them). Dot
mayor may not be changed.
Printing is more clear cut. Dot is not changed until the printing is done. Thus
if a user interrupts ed while some printing is being done, dot is not sitting on
the last printed line or even near it. Dot is returned to where it was when the p
command was started.
Global Commands
Basic
Global commands (g and v) are used to perform one or more editing commands
on all lines of a file. The g command operates on those lines that contain a
specified string. As the simplest example, the command
g/THIS/p
prints all lines that contain the string "THIS". The string that goes between
the slashes can be anything that could be used in a line search or in a
substitute command; exactly the same rules and limitations apply. As another
example:
gl "\.Ip
prints all lines that begin with period.
The v command (there is no mnemonic significance to the letter "v") is
identical to g, except that it operates on those lines that do not contain an
occurrence of the string. So
UNIX Programmer's Manual
Document Preparation-31
DOCUMENT PREPARATION
v/"\./p
prints the lines that do not begin with period.
The command that follows g or v can be almost any command. For example:
g/"\./d
deletes all lines that begin with period, and
g/"$/d
deletes all empty (blank) lines.
Probably the most useful command that can follow a global command is the
substitute command since this can be used to make a change and print each
affected line for verification. For example, to change the word "This" to
"THIS" everywhere in a file and verify that it really worked, the command is
g/This/sllTHIS/gp
The use of "1/" in the substitute command means "the previous pattern", in
this case, "This". The p command is done on every line that matches the
pattern, not just those on which a substitution took place.
Global commands operate by making two passes over the file. On the first
pass, all lines that match the pattern are marked. On the second pass, each
marked line in turn is examined, dot is set to that line, and the command
executed. This means that it is possible for the command that follows a g or v
to use. addresses, set dot, etc., quite freely. For example:
gl "\.PP 1+
prints the line that follows each ".PP" macro (the signal for a new paragraph
in some formatting packages). The" +" means "one line past dot", and
32-Document Preparation
UNIX Programmer's Manual
g /topic I?
A
\
.SH? 1
searches for each line that contains "topic", scans backwards until it finds a
line that begins ".sH" (a section heading) and prints the line that follows, thus
showing the section headings under which "topic" is mentioned. Finally:
gl A\ .EQ 1+, 1 A\ .EN/- p
prints all the lines that lie between lines beginning with the ".EQ" and ".EN"
formatting macros.
The g and v commands can also be preceded by line numbers, in which case
the lines searched are only those in the range specified.
Multiline
It is possible to do more than one command under the control of a global
command although the syntax for expressing the operation is not especially
natural or easy. As an example, suppose the task is to change "x" to "y" and
"a" to "b" on all lines that contain "string". Then:
g/string/s/x/y/\
s/a/bl
is sufficient. The backslash signals the g command that the set of commands
continues on the next line. It terminates on the first line that does not end with
"\ ". A substitute command can not be used to insert a newline character
within a g command.
The command
g/x/slly/\
s/a/bl
does not work as expected. The remembered pattern is the last pattern that
was actually executed, so sometimes it will be "x" (as expected) and sometimes
it will be "a" (not expected). The desired pattern should be spelled out:
UNIX Programmer's Manual
Document Preparation-33
DOCUMENT PREPARATION
g/x/s/x/y/\
s/a/bl
It is also possible to execute a, c, and i commands {append, change, and insert}
under a global command. As with other multiline constructions, all that is
needed is to add a "\" at the end of each line except the last. Thus to add a
.nf and .sp command before each ".EQ" line, the following is typed:
gl A\ .EQI i\
.nf\
.sp
There is no need for a final line containing a period to terminate the i
command unless there are further commands being done under the global. On
the other hand, it does no harm to put it in.
It is good practice, after each global command, to check that the command did
only what was desired. Surprises sometimes happen. When they do occur, the
u command {undo} is useful to negate what was done by the last command.
Cut and Paste
There are two editing areas in which "cut and paste" operations can be
performed.
• Command functions
• Text editor functions
Most operations are actually easy if the task is defined and precautions are
taken when entering the commands.
Command Functions
The UNIX operating system command functions perform the following:
• Change name of files
34-Document Preparation
UNIX Programmer's Manual
• Copy files
• Combine files
• Remove files
Change Name of Files
If there is a file named oldname and if it needs to be renamed to newname, the
move command (mv) will do the job. It moves the file from one name to
another (the target file), for example:
mv oldname newname
Note: If there is already a file with the new name, its contents will be
overwritten with information from the other (oldname) file. The one exception
is that a file cannot be moved to itself, therefore, the following command is
illegal.
mv oldname oldname
Copy Files
Sometimes a copy of a file is needed while retaining
might be because a file needs to be worked on and yet
something happens to the file. In any case, the copy
command (cp). To make a copy of a file named good,
will place a copy in a file named savegood:
the original file. This
have a back up in case
is made with the copy
the following command
cp good savegood
Two identical copies of the file good exist. If savegood previously contained
something, it is overwritten.
To get the file savegood back to its original filename, good, the following
commands are used:
mv savegood good
UNIX Programmer's Manual
Document Preparation-35
DOCUMENT PREPARATION
if savegood is not needed anymore or
cp savegood good
to retain a copy of savegood.
In summary, mv renames a file; cp makes a duplicate copy. Both commands
overwrite the target file if one already exists unless write permission is denied
by the mode of the file.
Combine Files
A familiar requirement is that of collecting two or more files into one big file,
bigfile. This is needed, for example, when the author of a paper decides that
several sections are to be combined. There are several ways to do this; the
cleanest is a command called cat (not all commands have 2-letter names). The
word cat is short for "concatenate" which is exactly what is desired. The
command
cat file
prints the contents of the file on the terminal. The command
cat file] file2
causes the contents of filel and file2 to be printed on the terminal, in that
order, but does not place them in bigfile.
There is a way to tell the system to put the same information in a file instead
of printing on the terminal. The way to do it is to add to the command line the
">" character and the name of the file where the output is to go. The
command
cat filel file2
> bigfile
is used and the job is done. As with cp and mv, when something is put into
bigfile, anything already there is destroyed. The ability to capture the output
of a program can be used with any command that prints on a terminal.
/
36-Document Preparation
UNIX Programmer's Manual
Several files can be combined, not just two:
cat file] file2 file3 ...
> bigfile
collects many individual files.
Sometimes a file needs to be appended to the end of another file. For example:
cat good good] >temp
mv temp good
is the most direct way. The following command:
cat good good] > good
does not work because the ">" empties good before the cat program begins.
The easiest way is to use a variant of ">", called "> >". In fact, "> >" is
identical to ">" except that instead of clobbering the old file it adds something
to the end. Thus the command
cat good] > > good
adds good] to the end of good. If good does not exist, this makes a copy of
good] called good.
Remove Files
If a file is not needed, it can be removed. The rm command
rm savegood
irrevocably deletes the file called savegood if the user has write permission.
Several files can be removed with one command.
rm save*
UNIX Programmer's Manual
Document Preparation-37
DOCUMENT PREPARATION
removes all files that begin with "save". The command
rm savel save2 save3
removes three files.
Text Editor Functions
The text editor (ed) function performs the following operations:
• Insert one file into another
• Write out part of a file
• Move lines around
• Copy lines
• Marks
File Names
It is important to know the editor (ed) commands for reading and writing files.
Equally useful is the edit command (e). Within ed, the command
e newfile
says "edit a new file call~d newfile without leaving the text editor". The e
command discards whatever is being worked on and starts over on newfile.
This is the same as if one had quit with the q command and reentered ed with
a new file name except that if a pattern has been remembered, a command like
"//" will still work.
When entering ed with the command
ed fileed remembers the name of the file, and any subsequent e, r, or w commands
38-Document Preparation
UNIX Programmer's Manual
that do not contain a file name will refer to this remembered file. Thus:
ed filel
w
e file2
w
(editing)
(writes back in file1 )
(edit different file without leaving ed)
(editing on file2)
(writes back in file2)
etc. does a series of edits on various files without leaving ed and without typing
the name of any file more than once. By examining the sequence of commands
in this example, it can be seen why many operating systems use e as a synonym
for ed.
The current file name can be found at any time with the f command by typing
f without a file name. Also, the name of a remembered file can be changed
with f. A useful sequence is
ed precious
fjunk
(editing)
This obtains a copy of the file precious and guarantees that a subsequent w
command without a filename will write to junk and will not overwrite the
original file.
Insert One File Into Another
When a file is to be inserted into another, the r command can be used. For
example, if the file table is to be inserted just after the reference to "Table 1",
the following can be used:
/ Table 1/
Table 1 shows that ...
.r table
(response from ed)
The critical line is the last one. The.r command reads a file in after dot. An r
command without any address adds lines to the end of the file, so it is
equivalent to the $r command.
UNIX Programmer's Manual
Document Preparation-39
DOCUMENT PREPARATION
Write Out Part of a File
Another feature is writing to another file part of the document that is being
edited. For example, it is possible to split into a separate file the table from the
previous example, so it can be formatted or tested separately. If in the file
being edited, there is
--- text
.TS
--- data for table
.TE
--- text
(which is the way a table is set up as explained in the TABLE FORMATTING.
PROGRAM section) to isolate the table information in a separate file called
table. First the start of the table (the .TS line) is found, and then the desired
part is written on file table:
/A\.TS/
.TS
(response from ed)
.,/ A\ .TE/w table
The same job can be accomplished with the single command
/ A\ .TS/; / A\ .TE/w table
The point is that the w command can write out a group of lines instead of the
whole file. A single line can be written by using one line number instead of
two. For example, if a complicated line was just typed and it will be needed
again, it should be saved and read in later rather than retyped:
40-Document Preparation
UNIX Programmer's Manual
a
--- lots of stuff
--- stuff to repeat
.w temp
a
--- more stuff
.r temp
a
--- more stuff
Move Lines Around
Moving a paragraph from its present position in a paper to the end can be done
several ways. For example, it is assumed that each paragraph in the paper
begins with the" .PP" formatting macro. The brute force way (not necessarily
bad) is to write the paragraph onto a temporary file, delete it from its current
position, and then read in the temporary file at the end. If dot is at the ".PP"
macro that begins the paragraph, this is the sequence of commands:
.,I"\.PP/-w temp
.,I/-d
$r temp
This states that from where dot is now until one line before the next ".PP"
write onto file temp. The same lines are deleted and the file temp is read in at
the end of the working file.
An easier way is to use the move command (m) that ed provides. This does the
whole set of operations at one time without a temporary file. The m command
is like many other ed commands in that it takes up to two line numbers in front
to tell which lines are to be affected. It is also followed by a line number that
tells where the lines are to go. Thus:
line 1,line2m line3
says "move all the lines from Iinel through Iine2 to after Iine3". Any of
"line1", etc., can be line numbers, strings between slashes or dollar signs, or
other line specifications. If dot is at the first line of the paragraph, the
UNIX Programmer's Manual
Document Preparation-41
DOCUMENT PREPARATION
command
.,I"\.PP/-m$
will also accomplish this task.
As another example of a frequent operation, the order of two adjacent lines can
be reversed by moving the first one after the second. If dot is positioned at the
first line, then
m+
does it. It says to move the line to after the dot. If dot is positioned on the
second line:
m-does the interchange.
The m command is more concise and direct than writing, deleting, and
rereading. The main difficulty with the m command is that if patterns are used
to specify both the line being moved and the target line, they must be specified
properly or the wrong lines may be moved. The result of a botched m
command can be a costly mistake. Doing the job a step at a time makes it
easier to verify that each step accomplished what was wanted. It is also a good
idea to issue a w command before doing anything complicated; then if an error
is made, it is easy to back up.
Copy Lines
The ed program provides a transfer command (t) for making a copy of a group
of one or more lines at any point. This is often easier than writing and
reading. The t command is identical to the m command except instead of
moving lines it duplicates them at the place referenced. Thus:
1,$t$
duplicates the entire contents that is being edited. A more common use for t is
42-Document· Preparation
UNIX Programmer's Manual
creating a series of lines that differ only slightly. For example:
a
--- long line of stuff
t.
s/x/yl
t.
s/y/zl
(make a copy)
(change it a bit)
(make third copy)
(change it a bit)
Marks
The ed program provides for marking a line with a particular name so that the
line can be referenced .later by its name regardless of its line number. This can
be useful for moving lines and for keeping track of them as they move. The
mark command is k. The mark name must be a single lowercase letter. The
command
kx
marks the current line with the name "x". If a line number precedes the k,
that line is marked. The marked line can then be referred to with the address
'x
Marks are most useful for moving things around. The first line of the block to
be moved is found and marked with ka. Then the last line of the block is
found and marked with kb. Dot is then positioned at the place where the lines
are to go and the following command is performed:
'a,'bm
Note: Only one line can have a particular mark name associated with it at any
given time.
UNIX Programmer's Manual
Document Preparation-43
DOCUMENT PREPARATION
Temporary Escape
Sometimes it is convenient to temporarily escape from the text editor to do
some UNIX operating system command without leaving the text editor. The
escape command (0 provides a way to do this. If the command
!
is entered, the current editing state is suspended; and the command asked for is
executed. When the command finishes, ed will return a signal by printing
another "!" and editing can be resumed.
Any UNIX operating system command may be performed including another ed
(this is quite common). In this case, another "!" can be done.
Supporting Tools
There are several related tools and techniques which are relatively easy to learn
after ed has been learned because they are based Qn ed. Examples of these
techniques are shown, more to indicate their existence than to provide a
complete tutorial.
Global Printing From a Set of Files (grep)
Sometimes all occurrences of some word or pattern in a set of files need to be
found in order to edit them or perhaps to verify their presence or absence. It
may be possible to edit each file separately and look for the pattern of interest.
If there are many files, this can be tedious; and if the files are really big, it may
be impossible because of limits in ed.
The grep program was written to get around these limitations. Search patterns
are often called "regular expressions", and "grep" stands for
g/re/p
This describes what grep does - it prints every line in a set of files that contains
a particular pattern. Thus:
44-Document Preparation
UNIX Programmer's Manual·
grep 'string' filel file2 file3 ...
finds "string" wherever it occurs in any of the files filel, file2, etc. The grep
program also indicates the file in which the line was found, so it can be edited
later if needed.
The pattern represented by "string" can be any pattern that can be used in the
text editor since grep and ed use the same mechanism for pattern searching. It
is wisest to enclose the pattern in the single quotes ('string') if it contains any
nonalphabetic characters since many such characters also mean something
special to the UNIX operating system command interpreter (the "shell").
Without single quotes, the command interpreter will try to interpret them
before grep has the opportunity.
There is also a way to find lines that do not contain a pattern:
grep -v 'string' filel file2 ...
finds all lines that do not contain "string". The -v option must occur in the
position shown. Given grep and grep -v, it is possible to select all lines that
contain some combination of patterns. For example, to obtain all lines that
contain "x" but not "y":
grep x file ... I grep -v y
The pipe notation (I) causes the output of the first command to be used as
input to the second command.
Editing Scripts
If a fairly complicated set of editing operations is to be performed on an entire
set of files, the easiest thing to do is to make a script file, i.e., a file that
contains the operations to be performed and then apply this script to each file
in turn. For example, if every instance of "This" needs to be changed to
"THIS" and every instance of "That" needs to be changed to "THAT" in a
large number of files, a file script is made with the following contents:
UNIX Programmer's Manual
Document Preparation-45
DOCUMENT PREPARATION
g/Thisl sllTHISIg
g/That/sllTHAT I g
w
q
The following is done:
ed filel