/share/doc/usd/21.troff/m5

https://bitbucket.org/freebsd/freebsd-head/ · #! · 462 lines · 462 code · 0 blank · 0 comment · 0 complexity · ff14cfcbde0cfe9741ca22e94f45edcc 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. .\" @(#)m5 8.1 (Berkeley) 8/14/93
  38. .\"
  39. .\" $FreeBSD$
  40. .ds H T
  41. .tr |
  42. .tr ~|
  43. .de x1
  44. .xx
  45. .ft B
  46. .in .2i
  47. .nf
  48. .ne 2.1
  49. .ta 1i
  50. ..
  51. .de x2
  52. .fi
  53. .in 0
  54. .ft R
  55. .xx
  56. ..
  57. .br
  58. .ce
  59. .ft B
  60. .rs
  61. .sp 0.5i
  62. TUTORIAL EXAMPLES
  63. .ft R
  64. .sp 2
  65. .nr p 0
  66. .2C
  67. .ns
  68. .mh
  69. .mk
  70. Introduction
  71. .pg
  72. Although \*(NR and \*(TR
  73. have by design a syntax reminiscent
  74. of earlier text processors*
  75. .fn
  76. .xx
  77. *For example:
  78. P.|A.|Crisman, Ed.,
  79. .ul
  80. The Compatible Time-Sharing System,
  81. MIT Press, 1965, Section|AH9.01
  82. (Description of RUNOFF program on MIT's CTSS system).
  83. .ef
  84. with the intent of easing their use,
  85. it is almost always necessary to
  86. prepare at least a small set of macro definitions
  87. to describe most documents.
  88. Such common formatting needs
  89. as page margins and footnotes
  90. are deliberately not built into \*(NR and \*(TR.
  91. Instead,
  92. the macro and string definition, number register, diversion,
  93. environment switching, page-position trap, and conditional input mechanisms
  94. provide the basis for user-defined implementations.
  95. .pg
  96. The examples to be discussed are intended to be useful and somewhat realistic,
  97. but won't necessarily cover all relevant contingencies.
  98. Explicit numerical parameters are used
  99. in the examples
  100. to make them easier to read and to
  101. illustrate typical values.
  102. In many cases, number registers would really be used
  103. to reduce the number of places where numerical
  104. information is kept,
  105. and to concentrate conditional parameter initialization
  106. like that which depends on whether \*(TR or \*(NR is being used.
  107. .mh
  108. Page Margins
  109. .pg
  110. As discussed in \(sc3,
  111. \fIheader\fR and \fIfooter\fR macros are usually defined
  112. to describe the top and bottom page margin areas respectively.
  113. A trap is planted at page position 0 for the header, and at
  114. \fI\-N\fR (\fIN\fR from the page bottom) for the footer.
  115. The simplest such definitions might be
  116. .x1
  117. &de hd \e"define header
  118. \'sp 1i
  119. && \e"end definition
  120. &de fo \e"define footer
  121. \'bp
  122. && \e"end definition
  123. &wh 0 hd
  124. &wh \-1i fo
  125. .x2
  126. which provide blank 1|inch top and bottom margins.
  127. The header will occur on the \fIfirst\fR page,
  128. only if the definition and trap exist prior to
  129. the initial pseudo-page transition (\(sc3).
  130. In fill mode, the output line that springs the footer trap
  131. was typically forced out because some part or whole word didn't fit on it.
  132. If anything in the footer and header that follows causes a \fIbreak\fR,
  133. that word or part word will be forced out.
  134. In this and other examples,
  135. requests like \fBbp\fR and \fBsp\fR that normally cause breaks are invoked using
  136. the \fIno-break\fR control character \fB\'\fR
  137. to avoid this.
  138. When the header\(slfooter design contains material
  139. requiring independent text processing, the
  140. environment may be switched, avoiding
  141. most interaction with the running text.
  142. .pg
  143. A more realistic example would be
  144. .x1
  145. &de hd \e"header
  146. &if t .tl \'\|\e(rn\'\'\e(rn\' \e"troff cut mark
  147. &if \e\en%>1 \e{\e
  148. \'sp ~\|0.5i\-1 \e"tl base at 0.5i
  149. &tl \'\'\- % \-\'\' \e"centered page number
  150. &ps \e"restore size
  151. &ft \e"restore font
  152. &vs \e} \e"restore vs
  153. \'sp ~\|1.0i \e"space to 1.0i
  154. &ns \e"turn on no-space mode
  155. &&
  156. &de fo \e"footer
  157. &ps 10 \e"set footer\(slheader size
  158. &ft R \e"set font
  159. &vs 12p \e"set base-line spacing
  160. &if \e\en%=1 \e{\e
  161. \'sp ~\|\e\en(.pu\-0.5i\-1 \e"tl base 0.5i up
  162. &tl \'\'\- % \-\'\' \e} \e"first page number
  163. \'bp
  164. &&
  165. &wh 0 hd
  166. &wh \-1i fo
  167. .x2
  168. which sets the size, font, and base-line spacing for the
  169. header\(slfooter material, and ultimately restores them.
  170. The material in this case is a page number at the bottom of the
  171. first page and at the top of the remaining pages.
  172. If \*(TR is used, a \fIcut mark\fR is drawn in the form
  173. of \fIroot-en\fR's at each margin.
  174. The \fBsp\fR's refer to absolute positions to avoid
  175. dependence on the base-line spacing.
  176. Another reason for this in the footer
  177. is that the footer is invoked by printing a line whose
  178. vertical spacing swept past the trap position by possibly
  179. as much as the base-line spacing.
  180. The \fIno-space\fR mode is turned on at the end of \fBhd\fR
  181. to render ineffective
  182. accidental occurrences of \fBsp\fR at the top of the running text.
  183. .pg
  184. The above method of restoring size, font, etc. presupposes
  185. that such requests (that set \fIprevious\fR value) are \fInot\fR
  186. used in the running text.
  187. A better scheme is save and restore both the current \fIand\fR
  188. previous values as shown for size in the following:
  189. .x1
  190. &de fo
  191. &nr s1 \e\en(.s \e"current size
  192. &ps
  193. &nr s2 \e\en(.s \e"previous size
  194. & --- \e"rest of footer
  195. &&
  196. &de hd
  197. & --- \e"header stuff
  198. &ps \e\en(s2 \e"restore previous size
  199. &ps \e\en(s1 \e"restore current size
  200. &&
  201. .x2
  202. Page numbers may be printed in the bottom margin
  203. by a separate macro triggered during the footer's
  204. page ejection:
  205. .x1
  206. &de bn \e"bottom number
  207. &tl \'\'\- % \-\'\' \e"centered page number
  208. &&
  209. &wh \-0.5i\-1v bn \e"tl base 0.5i up
  210. .x2
  211. .mh
  212. Paragraphs and Headings
  213. .pg
  214. The housekeeping
  215. associated with starting a new paragraph should be collected
  216. in a paragraph macro
  217. that, for example,
  218. does the desired preparagraph spacing,
  219. forces the correct font, size, base-line spacing, and indent,
  220. checks that enough space remains for \fImore than one\fR line,
  221. and
  222. requests a temporary indent.
  223. .x1
  224. &de pg \e"paragraph
  225. &br \e"break
  226. &ft R \e"force font,
  227. &ps 10 \e"size,
  228. &vs 12p \e"spacing,
  229. &in 0 \e"and indent
  230. &sp 0.4 \e"prespace
  231. &ne 1+\e\en(.Vu \e"want more than 1 line
  232. &ti 0.2i \e"temp indent
  233. &&
  234. .x2
  235. The first break in \fBpg\fR
  236. will force out any previous partial lines,
  237. and must occur before the \fBvs\fR.
  238. The forcing of font, etc. is
  239. partly a defense against prior error and
  240. partly to permit
  241. things like section heading macros to
  242. set parameters only once.
  243. The prespacing parameter is suitable for \*(TR;
  244. a larger space, at least as big as the output device vertical resolution, would be
  245. more suitable in \*(NR.
  246. The choice of remaining space to test for in the \fBne\fR
  247. is the smallest amount greater than one line
  248. (the \fB.V\fR is the available vertical resolution).
  249. .pg
  250. A macro to automatically number section headings
  251. might look like:
  252. .x1
  253. &de sc \e"section
  254. & --- \e"force font, etc.
  255. &sp 0.4 \e"prespace
  256. &ne 2.4+\e\en(.Vu \e"want 2.4+ lines
  257. .lg 0
  258. &fi
  259. .lg
  260. \e\en+S.
  261. &&
  262. &nr S 0 1 \e"init S
  263. .x2
  264. The usage is \fB.sc\fR,
  265. followed by the section heading text,
  266. followed by \fB.pg\fR.
  267. The \fBne\fR test value includes one line of heading,
  268. 0.4 line in the following \fBpg\fR, and
  269. one line of the paragraph text.
  270. A word consisting of the next section number and a period is
  271. produced to begin the heading line.
  272. The format of the number may be set by \fBaf\fR (\(sc8).
  273. .pg
  274. Another common form is the labeled, indented paragraph,
  275. where the label protrudes left into the indent space.
  276. .x1
  277. &de lp \e"labeled paragraph
  278. &pg
  279. &in 0.5i \e"paragraph indent
  280. &ta 0.2i 0.5i \e"label, paragraph
  281. &ti 0
  282. \et\e\e$1\et\ec \e"flow into paragraph
  283. &&
  284. .x2
  285. The intended usage is "\fB.lp\fR \fIlabel\fR\|";
  286. \fIlabel\fR will begin at 0.2\|inch, and
  287. cannot exceed a length of 0.3\|inch without intruding into
  288. the paragraph.
  289. The label could be right adjusted against 0.4\|inch by
  290. setting the tabs instead with \fB.ta|0.4iR|0.5i\fR.
  291. The last line of \fBlp\fR ends with \fB\ec\fR so that
  292. it will become a part of the first line of the text
  293. that follows.
  294. .mh
  295. Multiple Column Output
  296. .pg
  297. The production of multiple column pages requires
  298. the footer macro to decide whether it was
  299. invoked by other than the last column,
  300. so that it will begin a new column rather than
  301. produce the bottom margin.
  302. The header can initialize a column register that
  303. the footer will increment and test.
  304. The following is arranged for two columns, but
  305. is easily modified for more.
  306. .x1
  307. &de hd \e"header
  308. & ---
  309. &nr cl 0 1 \e"init column count
  310. &mk \e"mark top of text
  311. &&
  312. &de fo \e"footer
  313. &ie \e\en+(cl<2 \e{\e
  314. &po +3.4i \e"next column; 3.1+0.3
  315. &rt \e"back to mark
  316. &ns \e} \e"no-space mode
  317. &el \e{\e
  318. &po \e\enMu \e"restore left margin
  319. & ---
  320. \'bp \e}
  321. &&
  322. &ll 3.1i \e"column width
  323. &nr M \e\en(.o \e"save left margin
  324. .x2
  325. Typically a portion of the top of the first page
  326. contains full width text;
  327. the request for the narrower line length,
  328. as well as another \fB.mk\fR would
  329. be made where the two column output was to begin.
  330. .mh
  331. Footnote Processing
  332. .pg
  333. The footnote mechanism to be described is used by
  334. imbedding the footnotes in the input text at the
  335. point of reference,
  336. demarcated by an initial \fB.fn\fR and a terminal \fB.ef\fR:
  337. .x1
  338. &fn
  339. \fIFootnote text and control lines...\fP
  340. &ef
  341. .x2
  342. In the following,
  343. footnotes are processed in a separate environment and diverted
  344. for later printing in the space immediately prior to the bottom
  345. margin.
  346. There is provision for the case where the last collected
  347. footnote doesn't completely fit in the available space.
  348. .x1
  349. &de hd \e"header
  350. & ---
  351. &nr x 0 1 \e"init footnote count
  352. &nr y 0\-\e\enb \e"current footer place
  353. &ch fo \-\e\enbu \e"reset footer trap
  354. &if \e\en(dn .fz \e"leftover footnote
  355. &&
  356. &de fo \e"footer
  357. &nr dn 0 \e"zero last diversion size
  358. &if \e\enx \e{\e
  359. &ev 1 \e"expand footnotes in ev1
  360. &nf \e"retain vertical size
  361. &FN \e"footnotes
  362. &rm FN \e"delete it
  363. &if "\e\en(.z"fy" .di \e"end overflow diversion
  364. &nr x 0 \e"disable fx
  365. &ev \e} \e"pop environment
  366. & ---
  367. \'bp
  368. &&
  369. &de fx \e"process footnote overflow
  370. &if \e\enx .di fy \e"divert overflow
  371. &&
  372. &de fn \e"start footnote
  373. &da FN \e"divert (append) footnote
  374. &ev 1 \e"in environment 1
  375. &if \e\en+x=1 .fs \e"if first, include separator
  376. .lg 0
  377. &fi \e"fill mode
  378. .lg
  379. &&
  380. &de ef \e"end footnote
  381. &br \e"finish output
  382. &nr z \e\en(.v \e"save spacing
  383. &ev \e"pop ev
  384. &di \e"end diversion
  385. &nr y \-\e\en(dn \e"new footer position,
  386. &if \e\enx=1 .nr y \-(\e\en(.v\-\e\enz) \e
  387. \e"uncertainty correction
  388. &ch fo \e\enyu \e"y is negative
  389. &if (\|\e\en(nl+1v)>(\|\e\en(.p+\e\eny) \e
  390. &ch fo \e\en(nlu+1v \e"it didn't fit
  391. &&
  392. &de fs \e"separator
  393. \el\'\|1i\' \e"1 inch rule
  394. &br
  395. &&
  396. &de fz \e"get leftover footnote
  397. &fn
  398. &nf \e"retain vertical size
  399. &fy \e"where fx put it
  400. &ef
  401. &&
  402. &nr b 1.0i \e"bottom margin size
  403. &wh 0 hd \e"header trap
  404. &wh 12i fo \e"footer trap, temp position
  405. &wh \-\e\enbu fx \e"fx at footer position
  406. &ch fo \-\e\enbu \e"conceal fx with fo
  407. .x2
  408. The header \fBhd\fR initializes a footnote count register \fBx\fR,
  409. and sets both the current footer trap position register \fBy\fR and
  410. the footer trap itself to a nominal position specified in
  411. register \fBb\fR.
  412. In addition, if the register \fBdn\fR indicates a leftover footnote,
  413. \fBfz\fR is invoked to reprocess it.
  414. The footnote start macro \fBfn\fR begins a diversion (append) in environment 1,
  415. and increments the count \fBx\fR; if the count is one, the footnote separator \fBfs\fR
  416. is interpolated.
  417. The separator is kept in a separate macro to permit user redefinition.
  418. The footnote end macro \fBef\fR restores
  419. the previous environment and ends the diversion after saving the spacing size in register \fBz\fR.
  420. \fBy\fR is then decremented by the size of the footnote, available in \fBdn\fR;
  421. then on the first footnote, \fBy\fR is further decremented by the difference
  422. in vertical base-line spacings of the two environments, to
  423. prevent the late triggering the footer trap from causing the last
  424. line of the combined footnotes to overflow.
  425. The footer trap is then set to the lower (on the page) of \fBy\fR or the current page position (\fBnl\fR)
  426. plus one line, to allow for printing the reference line.
  427. If indicated by \fBx\fR, the footer \fBfo\fR rereads the footnotes from \fBFN\fR in nofill mode
  428. in environment 1,
  429. and deletes \fBFN\fR.
  430. If the footnotes were too large to fit, the macro \fBfx\fR will be trap-invoked to redivert
  431. the overflow into \fBfy\fR,
  432. and the register \fBdn\fR will later indicate to the header whether \fBfy\fR is empty.
  433. Both \fBfo\fR and \fBfx\fR are planted in the nominal footer trap position in an order
  434. that causes \fBfx\fR to be concealed unless the \fBfo\fR trap is moved.
  435. The footer then terminates the overflow diversion, if necessary, and
  436. zeros \fBx\fR to disable \fBfx\fR,
  437. because the uncertainty correction
  438. together with a not-too-late triggering of the footer can result
  439. in the footnote rereading finishing before reaching the \fBfx\fR trap.
  440. .pg
  441. A good exercise for the student is to combine the multiple-column and footnote mechanisms.
  442. .mh
  443. The Last Page
  444. .pg
  445. After the last input file has ended, \*(NR and \*(TR
  446. invoke the \fIend macro\fR (\(sc7), if any,
  447. and when it finishes, eject the remainder of the page.
  448. During the eject, any traps encountered are processed normally.
  449. At the \fIend\fR of this last page, processing terminates
  450. \fIunless\fR a partial line, word, or partial word remains.
  451. If it is desired that another page be started, the end-macro
  452. .x1
  453. &de en \e"end-macro
  454. \ec
  455. \'bp
  456. &&
  457. &em en
  458. .x2
  459. will deposit a null partial word,
  460. and effect another last page.
  461. .1C
  462. 'bp