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