/share/doc/usd/21.troff/m4

https://bitbucket.org/freebsd/freebsd-head/ · #! · 416 lines · 416 code · 0 blank · 0 comment · 0 complexity · 115a75d9d7c4ae7058c8d254b8d7c3ff MD5 · raw file

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