home *** CD-ROM | disk | FTP | other *** search
/ minnie.tuhs.org / unixen.tar / unixen / PDP-11 / Trees / V7 / usr / doc / beginners / u3 < prev    next >
Encoding:
Text File  |  1979-01-10  |  7.8 KB  |  324 lines

  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.
  324.