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