summaryrefslogtreecommitdiff
path: root/share/doc/usd/01.begin/u3
blob: 096405ce904f24d5b0d00edb85cd5e9af347df56 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
.\"	$NetBSD: u3,v 1.1 2007/11/29 12:35:06 mjf Exp $
.\"
.\" Copyright (C) Caldera International Inc.  2001-2002.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code and documentation must retain the above
.\"    copyright notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed or owned by Caldera
.\"	International, Inc.
.\" 4. Neither the name of Caldera International, Inc. nor the names of other
.\"    contributors may be used to endorse or promote products derived from
.\"    this software without specific prior written permission.
.\"
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\"	@(#)u3	8.1 (Berkeley) 6/8/93
.\"
.sp
.SH
III. DOCUMENT PREPARATION
.PP
.UC UNIX
systems are used extensively for document preparation.
There are two major 
formatting
programs,
that is,
programs that produce a text with
justified right margins, automatic page numbering and titling,
automatic hyphenation,
and the like.
.UL nroff
is designed to produce output on terminals and
line-printers.
.UL troff
(pronounced ``tee-roff'')
instead drives a phototypesetter,
which produces very high quality output
on photographic paper.
This paper was formatted with
.UL troff .
.SH
Formatting Packages
.PP
The basic idea of
.UL nroff 
and 
.UL troff
is that the text to be formatted contains within it
``formatting commands'' that indicate in detail
how the formatted text is to look.
For example, there might be commands that specify how long
lines are, whether to use single or double spacing,
and what running titles to use on each page.
.PP
Because
.UL nroff
and
.UL troff
are relatively hard to learn to use effectively,
several
``packages'' of canned formatting requests are available
to let you specify
paragraphs, running titles, footnotes, multi-column output,
and so on, with little effort
and without having to learn
.UL nroff
and
.UL troff .
These packages take a modest effort to learn,
but the rewards for using them are so great
that it is time well spent.
.PP
In this section,
we will provide a hasty look at the ``manuscript'' 
package known as
.UL \-ms .
Formatting requests typically consist of a period and two upper-case letters,
such as
.UL .TL ,
which is used to introduce a title,
or
.UL .PP
to begin a new paragraph.
.PP
A document is typed so it looks something like this:
.P1
\&.TL
title of document
\&.AU
author name
\&.SH
section heading
\&.PP
paragraph ...
\&.PP
another paragraph ...
\&.SH
another section heading
\&.PP
etc.
.P2
The lines that begin with a period are the formatting requests.
For example,
.UL .PP
calls for starting a new paragraph.
The precise meaning of
.UL .PP
depends on what output device is being used
(typesetter or terminal, for instance),
and on what publication the document will appear in.
For example,
.UL \-ms
normally assumes that a paragraph is preceded by a space
(one line in
.UL nroff ,
\(12 line in
.UL troff ),
and the first word is indented.
These rules can be changed if you like,
but they are changed by changing the interpretation
of
.UL .PP ,
not by re-typing the document.
.PP
To actually produce a document in standard format
using
.UL \-ms ,
use the command
.P1
troff -ms files ...
.P2
for the typesetter, and
.P1
nroff -ms files ...
.P2
for a terminal.
The
.UL \-ms
argument tells
.UL troff
and
.UL nroff
to use the manuscript package of formatting requests.
.PP
There are several similar packages;
check with a local expert to determine which ones
are in common use on your machine.
.SH
Supporting Tools
.PP
In addition to the basic formatters,
there is
a host of supporting programs
that help with document preparation.
The list in the next few paragraphs
is far from complete,
so browse through the manual
and check with people around you for other possibilities.
.PP
.UL eqn
and
.UL neqn
let you integrate mathematics
into the text of a document,
in an easy-to-learn language that closely resembles the way
you would speak it aloud.
For example, the
.UL eqn
input
.P1
sum from i=0 to n x sub i ~=~ pi over 2
.P2
produces the output
.EQ
sum from i=0 to n x sub i ~=~ pi over 2
.EN
.PP
The program
.UL tbl
provides an analogous service for preparing tabular material;
it does all the computations necessary to align complicated columns
with elements of varying widths.
.PP
.UL refer
prepares bibliographic citations from a data base,
in whatever style is defined by the formatting package.
It looks after all the details of numbering references in sequence,
filling in page and volume numbers,
getting the author's initials and the journal name right,
and so on.
.PP
.UL spell
and
.UL typo
detect possible spelling mistakes in a document.\(dg
.FS
\(dg "typo" is not provided with Berkeley Unix.
.FE
.UL spell
works by comparing the words in your document
to a dictionary,
printing those that are not in the dictionary.
It knows enough about English spelling to detect plurals and the like,
so it does a very good job.
.UL typo
looks for words which are ``unusual'',
and prints those.
Spelling mistakes tend to be more unusual,
and thus show up early when the most unusual words
are printed first.
.PP
.UL grep
looks through a set of files for lines
that contain a particular text pattern 
(rather like the editor's context search does,
but on a bunch of files).
For example,
.P1
grep \(fming$\(fm chap*
.P2
will find all lines that end with
the letters
.UL ing
in the files
.UL chap* .
(It is almost always a good practice to put single quotes around
the pattern you're searching for,
in case it contains characters like
.UL *
or
.UL $
that have a special meaning to the shell.)
.UL grep
is often useful for finding out in which of a set of files
the misspelled words detected by
.UL spell
are actually located.
.PP
.UL diff
prints a list of the differences between
two files,
so you can compare
two versions of something automatically
(which certainly beats proofreading by hand).
.PP
.UL wc
counts the words, lines and characters in a set of files.
.UL tr
translates characters into other characters;
for example it will convert upper to lower case and vice versa.
This translates upper into lower:
.P1
tr A-Z a-z <input >output
.P2
.PP
.UL sort
sorts files in a variety of ways;
.UL sed
provides many of the editing facilities
of
.UL ed ,
but can apply them to arbitrarily long inputs.
.UL awk
provides the ability to do both pattern matching and numeric computations,
and to conveniently process fields within lines.
These programs are for more advanced users,
and they are not limited to document preparation.
Put them on your list of things to learn about.
.PP
Most of these programs are either independently documented
(like
.UL eqn
and
.UL tbl ),
or are sufficiently simple that the description in
the
.ul 2
.UC UNIX
Programmer's Manual
is adequate explanation.
.SH
Hints for Preparing Documents
.PP
Most documents go through several versions (always more than you expected) before they
are finally finished.
Accordingly, you should do whatever possible to make
the job of changing them easy.
.PP
First, when you do the purely mechanical operations of typing,
type so that subsequent editing will be easy.
Start each sentence on a new line.
Make lines short,
and break lines at natural places,
such as after commas and semicolons,
rather than randomly.
Since most people change documents by rewriting phrases
and adding, deleting and rearranging sentences,
these precautions simplify any editing
you have to do later.
.PP
Keep the individual files of a document down
to modest size,
perhaps ten to fifteen thousand characters.
Larger files edit more slowly,
and of course if you make a dumb mistake
it's better to have clobbered a small file than a big one.
Split into files at natural boundaries in the document,
for the same reasons that you start each sentence
on a new line.
.PP
The second aspect of making change easy
is to not commit yourself to formatting details too early.
One of the advantages of formatting packages like
.UL \-ms
is that they permit you to delay decisions
to the last possible moment.
Indeed,
until a document is printed,
it is not even decided whether it will be typeset
or put on a line printer.
.PP
As a rule of thumb, for all but the most trivial jobs,
you should type a document in terms of a set of requests
like
.UL .PP ,
and then define them appropriately,
either by using one of the canned packages
(the better way)
or by defining your own
.UL nroff
and
.UL troff
commands.
As long as you have entered the text in some systematic way,
it can always be cleaned up and re-formatted
by a judicious combination of
editing commands and request definitions.