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