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

  1. .tr |
  2. .mh
  3. Hyphenation.
  4. .pg
  5. The automatic hyphenation may be switched off and on.
  6. When switched on with \fBhy\fR,
  7. several variants may be set.
  8. A \fIhyphenation indicator\fR character may be imbedded in a word to
  9. specify desired hyphenation points,
  10. or may be prepended to suppress hyphenation.
  11. In addition,
  12. the user may specify a small exception word list.
  13. .pg
  14. Only words that consist of a central alphabetic string
  15. surrounded by (usually null) non-alphabetic strings
  16. are considered candidates for automatic hyphenation.
  17. Words that were input containing hyphens
  18. (minus),
  19. em-dashes (\fB\e(em\fR),
  20. or hyphenation indicator characters\
  21. \(emsuch as mother-in-law\(em\
  22. are \fIalways\fR subject to splitting after those characters,
  23. whether or not automatic hyphenation is on or off.
  24. .h1
  25. .bt
  26. \fB&nh\fR    hyphenate    -    E    \
  27. Automatic hyphenation is turned off.
  28. .bt
  29. \fB&hy\fIN\fR    on,\fIN=\fR1    on,\fIN=\fR1    E    \
  30. Automatic hyphenation is turned on
  31. for \fIN\fR\|\(>=1, or off for \fIN=\fR\|0.
  32. If \fIN=\fR\|2, \fIlast\fR lines (ones that will cause a trap)
  33. are not hyphenated.
  34. For \fIN=\fR\|4 and 8, the last and first two characters
  35. respectively of a word are not split off.
  36. These values are additive;
  37. i.|e. \fIN=\fR\|14 will invoke all three restrictions.
  38. .bt
  39. \fB&hc\fI|c\fR    \fB\e%    \e%\fR    E    Hyphenation indicator character is set
  40. to \fIc\fR or to the default \fB\e%\fR.
  41. The indicator does not appear in the output.
  42. .bt
  43. \fB&hw\fI|word1|...\fR    ignored    -    Specify hyphenation points in words
  44. with imbedded minus signs.
  45. Versions of a word with terminal \fIs\fR are implied;
  46. i.|e. \fIdig\-it\fR implies \fIdig\-its\fR.
  47. This list is examined initially \fIand\fR after
  48. each suffix stripping.
  49. The space available is small\(emabout 128 characters.
  50. .mh
  51. Three Part Titles.
  52. .pg
  53. The titling function \fBtl\fR provides for automatic placement
  54. of three fields at the left, center, and right of a line
  55. with a title-length
  56. specifiable with \fBlt\fR.
  57. \fBtl\fR may be used anywhere, and is independent of the
  58. normal text collecting process.
  59. A common use is in header and footer macros.
  60. .h1
  61. .bt
  62. \fB&tl\fI|\'left\|\'center\|\'right\|\'\fR    -    -    \
  63. The strings \fIleft\fR, \fIcenter\fR, and \fIright\fR are
  64. respectively left-adjusted, centered, and right-adjusted
  65. in the current title-length.
  66. Any of the strings may be empty,
  67. and overlapping is permitted.
  68. If the page-number character (initially \fB%\fR) is found within any of the fields it is replaced
  69. by the current page number having the format assigned to register \fB%\fR.
  70. Any character may be used as the string delimiter.
  71. .bt
  72. \fB&pc\fI|c\fR    \fB%\fR    off    -    The page number character is set to \fIc\fR,
  73. or removed.
  74. The page-number register remains \fB%\fR.
  75. .bt
  76. \fB<\fI|\(+-N\fR    6.5\|in    previous    E,\fBm\fR    Length of title set to \fI\(+-N\fR.
  77. The line-length and the title-length are \fIindependent\fR.
  78. Indents do not apply to titles; page-offsets do.
  79. .mh
  80. Output Line Numbering.
  81. .pg
  82. .ll -\w'0000'u
  83. .nm 1 3
  84. Automatic sequence numbering of output lines may be
  85. requested with \fBnm\fR.
  86. When in effect,
  87. a three-digit, arabic number plus a digit-space
  88. is prepended to output text lines.
  89. The text lines are thus offset by four digit-spaces,
  90. and otherwise retain their line length;
  91. a reduction in line length may be desired to keep the right margin
  92. aligned with an earlier margin.
  93. Blank lines, other vertical spaces, and lines generated by \fBtl\fR
  94. are \fInot\fR numbered.
  95. Numbering can be temporarily suspended with \fBnn\fR,
  96. or with an \fB.nm\fR followed by a later \fB.nm|+0\fR.
  97. In addition,
  98. a line number indent \fII\fR, and the number-text separation \fIS\fR
  99. may be specified in digit-spaces.
  100. Further, it can be specified that only those line numbers that are
  101. multiples of some number \fIM\fR are to be printed (the others will appear
  102. as blank number fields).
  103. .br
  104. .nm
  105. .ll
  106. .h1
  107. .bt
  108. \fB&nm\fI|\(+-N|M|S|I\fR    off    E    \
  109. Line number mode.
  110. If \fI\(+-N\fR is given,
  111. line numbering is turned on,
  112. and the next output line numbered is numbered \fI\(+-N\fR.
  113. Default values are \fIM=\fR\|1, \fIS=\fR\|1, and \fII=\fR\|0.
  114. Parameters corresponding to missing arguments are unaffected;
  115. a non-numeric argument is considered missing.
  116. In the absence of all arguments, numbering is turned off;
  117. the next line number is preserved for possible further use
  118. in number register \fBln\fR.
  119. .bt
  120. \fB&nn\fI|N\fR    -    \fIN=\fR1    E    The next \fIN\fR text output lines are not
  121. numbered.
  122. .pg
  123. .ll -\w'0000'u
  124. .nm +0
  125. As an example, the paragraph portions of this section
  126. are numbered with \fIM=\fR\|3:
  127. \&\fB.nm|1|3\fR was placed at the beginning;
  128. \&\fB.nm\fR was placed at the end of the first paragraph;
  129. and \fB.nm|+0\fR was placed in front of this paragraph;
  130. and \fB.nm\fR finally placed at the end.
  131. Line lengths were also changed (by \fB\ew\'0000\'u\fR) to keep the right side aligned.
  132. Another example is
  133. \&\fB.nm|+5|5|x|3\fR which turns on numbering with the line number of the next
  134. line to be 5 greater than the last numbered line,
  135. with \fIM=\fR\|5, with spacing \fIS\fR untouched, and with the indent \fII\fR set to 3.
  136. .br
  137. .ll
  138. .nm
  139. .mh
  140. Conditional Acceptance of Input
  141. .pg
  142. In the following,
  143. \fIc\fR is a one-character, built-in \fIcondition\fR name,
  144. \fB!\fR signifies \fInot\fR,
  145. \fIN\fR is a numerical expression,
  146. \fIstring1\fR and \fIstring2\fR are strings delimited by any non-blank, non-numeric character \fInot\fR in the strings,
  147. and
  148. \fIanything\fR represents what is conditionally accepted.
  149. .h1
  150. .bt
  151. \fB&if\fI|c|anything\fR        -    -    If condition \fIc\fR true, accept \fIanything\fR as input;
  152. in multi-line case use \fI\e{anything\|\e}\fR.
  153. .bt
  154. \fB&if|!\fIc|anything\fR    -    -    If condition \fIc\fR false, accept \fIanything\fR.
  155. .bt
  156. \fB&if\fI|N|anything\fR    -    \fBu\fR    If expression \fIN\fR > 0, accept \fIanything\fR.
  157. .bt
  158. \fB&if|!\fIN|anything\fR    -    \fBu\fR    If expression \fIN\fR \(<= 0, accept \fIanything\fR.
  159. .bt
  160. \fB&if\fI|\|\'string1\|\'string2\|\'|anything\fR    -    If \fIstring1\fR identical to \fIstring2\fR,
  161. accept \fIanything\fR.
  162. .bt
  163. \fB&if|!\fI\|\'string1\|\'string2\|\'|anything\fR    -    If \fIstring1\fR not identical to \fIstring2\fR,
  164. accept \fIanything\fR.
  165. .bt
  166. \fB&ie\fI|c|anything\fR    -    \fBu\fR    If portion of if-else; all above forms (like \fBif\fR).
  167. .bt
  168. \fB&el\fI|anything\fR        -    -    Else portion of if-else.
  169. .pg
  170. The built-in condition names are:
  171. .TS
  172. center box;
  173. c2|c2
  174. c2|c2
  175. c2|l2.
  176. Condition
  177. Name    True If
  178. _
  179. \fBo\fR    Current page number is odd
  180. \fBe\fR    Current page number is even
  181. \fBt\fR    Formatter is \*(TR
  182. \fBn\fR    Formatter is \*(NR
  183. .TE
  184. If the condition \fIc\fR is \fItrue\fR, or if the number \fIN\fR is greater than zero,
  185. or if the strings compare identically (including motions and character size and font),
  186. \fIanything\fR is accepted as input.
  187. If a \fB!\fR precedes the condition, number, or string comparison,
  188. the sense of the acceptance is reversed.
  189. .pg
  190. Any spaces between the condition and the beginning of \fIanything\fR are skipped over.
  191. The \fIanything\fR can be either a single input line (text, macro, or whatever)
  192. or a number of input lines.
  193. In the multi-line case,
  194. the first line must begin with a left delimiter \fB\e{\fR and
  195. the last line must end with a right delimiter \fB\e}\fR.
  196. .pg
  197. The request \fBie\fR (if-else) is identical to \fBif\fR
  198. except that the acceptance state is remembered.
  199. A subsequent and matching \fBel\fR (else) request then uses the reverse sense of that state.
  200. \fBie\fR|-|\fBel\fR pairs may be nested.
  201. .pg
  202. Some examples are:
  203. .x1
  204. .ftB
  205. .ne 1
  206. &if e .tl \'\|Even Page %\'\'\'
  207. .ftR
  208. .x2
  209. which outputs a title if the page number is even; and
  210. .x1
  211. .ftB
  212. .ne 3.1
  213. &ie \en%>1 \e{\e
  214. \&\'sp 0.5i
  215. &tl \'\|Page %\'\'\'
  216. \&\'sp ~\|1.2i|\e}
  217. &el .sp ~\|2.5i
  218. .ftR
  219. .x2
  220. which treats page 1 differently from other pages.
  221. .mh
  222. Environment Switching.
  223. .pg
  224. A number of the parameters that
  225. control the text processing are gathered together into an
  226. \fIenvironment\fR, which can be switched by the user.
  227. The environment parameters are those associated
  228. with requests noting E in their \fINotes\fR column;
  229. in addition, partially collected lines and words are in the environment.
  230. Everything else is global; examples are page-oriented parameters,
  231. diversion-oriented parameters, number registers, and macro and string definitions.
  232. All environments are initialized with default parameter values.
  233. .h1
  234. .bt
  235. \fB&ev\fI|N\fR    \fIN\(eq\fR0    previous    -    Environment switched to
  236. environment 0\(<=\fIN\fR\(<=2.
  237. Switching is done in push-down fashion so that
  238. restoring a previous environment \fImust\fR be done with \fB.ev\fR
  239. rather than specific reference.
  240. .mh
  241. Insertions from the Standard Input
  242. .pg
  243. The input can be temporarily switched to the system \fIstandard input\fR
  244. with \fBrd\fR,
  245. which will switch back when \fItwo\fR newlines
  246. in a row are found (the \fIextra\fR blank line is not used).
  247. This mechanism is intended for insertions in form-letter-like documentation.
  248. On \s-1UNIX\s+1, the \fIstandard input\fR can be the user's keyboard,
  249. a \fIpipe\fR, or a \fIfile\fR.
  250. .h1
  251. .bt
  252. \fB&rd\fI|prompt\fR    -    \fIprompt=\fR\s-1BEL\s+1    -    \
  253. Read insertion from the standard input until two newlines in a row are found.
  254. If the standard input is the user's keyboard, \fIprompt\fR (or a \s-1BEL\s+1)
  255. is written onto the user's terminal.
  256. \fBrd\fR behaves like a macro,
  257. and arguments may be placed after \fIprompt\fR.
  258. .bt
  259. \fB&ex\fR    -    -    -    Exit from \*(NR\(sl\*(TR.
  260. Text processing is terminated exactly as if all input had ended.
  261. .pg
  262. If insertions are to be
  263. taken from the terminal keyboard \fIwhile\fR output is being printed
  264. on the terminal, the command line option \fB\-q\fR will turn off the echoing
  265. of keyboard input and prompt only with \s-1BEL\s+1.
  266. The regular input and insertion input \fIcannot\fR
  267. simultaneously come from the standard input.
  268. .pg
  269. As an example,
  270. multiple copies of a form letter may be prepared by entering the insertions
  271. for all the copies in one file to be used as the standard input,
  272. and causing the file containing the letter to reinvoke itself using \fBnx\fR (\(sc19);
  273. the process would ultimately be ended by an \fBex\fR in the insertion file.
  274. .mh
  275. Input\(slOutput File Switching
  276. .h1
  277. .bt
  278. \fB&so\fI|filename\fR        -    -    Switch source file.
  279. The top input (file reading) level is switched to \fIfilename\fR.
  280. The effect of an \fBso\fR encountered in a macro
  281. is not felt until the input level returns to the file level.
  282. When the new file ends,
  283. input is again taken from the original file.
  284. \fBso\fR's may be nested.
  285. .bt
  286. \fB&nx\fI|filename\fR        end-of-file    -    Next file is \fIfilename\fR.
  287. The current file is considered ended, and the input is immediately switched
  288. to \fIfilename\fR.
  289. .bt
  290. \fB&pi\fI|program\fR        -    -    Pipe output to \fIprogram\fR (\*(NR only).
  291. This request must occur \fIbefore\fR any printing occurs.
  292. No arguments are transmitted to \fIprogram\fR.
  293. .mh
  294. Miscellaneous
  295. .pg
  296. .h1
  297. .bt
  298. .mc \s12\(br\s0
  299. \fB&mc\fI|c|N\fR    -    off    E,\fBm\fR    \
  300. Specifies that a \fImargin\fR character \fIc\fR appear a distance
  301. \fIN\fR to the right of the right margin
  302. after each non-empty text line (except those produced by \fBtl\fR).
  303. If the output line is too-long (as can happen in nofill mode)
  304. the character will be appended to the line.
  305. If \fIN\fR is not given, the previous \fIN\fR is used; the initial \fIN\fR is
  306. 0.2|inches in \*(NR and 1\|em in \*(TR.
  307. The margin character used with this paragraph was a 12-point box-rule.
  308. .br
  309. .mc
  310. .bt
  311. \fB&tm\fI|string\fR    -    newline    -    \
  312. After skipping initial blanks, \fIstring\fR (rest of the line) is read in \fIcopy mode\fR
  313. and written on the user's terminal.
  314. .bt
  315. \fB&ig\fI|yy\fR    -    \fI.yy=\fB..\fR    -    Ignore \
  316. input lines.
  317. \fBig\fR behaves exactly like \fBde\fR (\(sc7) except that the
  318. input is discarded.
  319. The input is read in \fIcopy mode\fR, and any auto-incremented
  320. registers will be affected.
  321. .bt
  322. \fB&pm\fI|t\fR    -    all    -    \
  323. Print macros.
  324. The names and sizes of all of the defined macros and strings are printed
  325. on the user's terminal;
  326. if \fIt\fR is given, only the total of the sizes is printed.
  327. The sizes is given in \fIblocks\fR
  328. of 128 characters.
  329. .bt
  330. .lg0
  331. \fB&fl\fR    -    -    B    \c
  332. .lg
  333. Flush output buffer.
  334. Used in interactive debugging to force output.
  335. .mh
  336. Output and Error Messages.
  337. .pg
  338. The output from \fBtm\fR, \fBpm\fR, and the prompt from \fBrd\fR,
  339. as well as various \fIerror\fR messages are written onto
  340. \s-1UNIX\s+1's \fIstandard message\fR output.
  341. The latter is different from the \fIstandard output\fR,
  342. where \*(NR formatted output goes.
  343. By default, both are written onto the user's terminal,
  344. but they can be independently redirected.
  345. .pg
  346. Various \fIerror\fR conditions may occur during
  347. the operation of \*(NR and \*(TR.
  348. Certain less serious errors having only local impact do not
  349. cause processing to terminate.
  350. Two examples are \fIword overflow\fR, caused by a word that is too large
  351. to fit into the word buffer (in fill mode), and
  352. \fIline overflow\fR, caused by an output line that grew too large
  353. to fit in the line buffer;
  354. in both cases, a message is printed, the offending excess
  355. is discarded,
  356. and the affected word or line is marked at the point of truncation
  357. with a \(** in \*(NR and a \(lh in \*(TR.
  358. The philosophy is to continue processing, if possible,
  359. on the grounds that output useful for debugging may be produced.
  360. If a serious error occurs, processing terminates,
  361. and an appropriate message is printed.
  362. Examples are the inability to create, read, or write files,
  363. and the exceeding of certain internal limits that
  364. make future output unlikely to be useful.
  365. .pg
  366. .bp
  367.