![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to u3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 01.begin|
Return to u3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 01.begin |
1.1 root 1: .\" @(#)u3 6.1 (Berkeley) 5/22/86
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
181: detect possible spelling mistakes in a document.\(dg
182: .FS
183: \(dg "typo" is not provided with Berkeley Unix.
184: .FE
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.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.