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

  1. .tr |
  2. .rm mx
  3. .br
  4. .mh
  5. Line Length and Indenting
  6. .pg
  7. The maximum line length for fill mode may be set with \fBll\fR.
  8. The indent may be set with \fBin\fR;
  9. an indent applicable to \fIonly\fR the \fInext\fR output line may be set with \fBti\fR.
  10. The line length includes indent space but \fInot\fR
  11. page offset space.
  12. The line-length minus the indent is the basis for centering with \fBce\fR.
  13. The effect of \fBll\fR, \fBin\fR, or \fBti\fR
  14. is delayed, if a partially collected line exists,
  15. until after that line is output.
  16. In fill mode the length of text on an output line is less than or equal to
  17. the line length minus the indent.
  18. The current line length and indent are available in registers \fB.l\fR and \fB.i\fR respectively.
  19. The length of \fIthree-part titles\fR produced by \fBtl\fR
  20. (see \(sc14) is \fIindependently\fR set by \fBlt\fR.
  21. .h1
  22. .bt
  23. \fB&ll\fI|\(+-N\fR    6.5\|in    previous    E,\fBm\fR    Line length is set to \(+-\fIN\fR.
  24. In \*(TR the maximum (line-length)+(page-offset) is about 7.54 inches.
  25. .bt
  26. \fB&in\fI|\(+-N\fR    \fIN\(eq\^\fR0    previous    B,E,\fBm\fR    Indent is set to \fI\(+-N\fR.
  27. The indent is prepended to each output line.
  28. .bt
  29. \fB&ti\fI|\(+-N\fR    -    ignored    B,E,\fBm\fR    Temporary indent.
  30. The \fInext\fR output text line will be indented a distance \fI\(+-N\fR
  31. with respect to the current indent.
  32. The resulting total indent may not be negative.
  33. The current indent is not changed.
  34. .mh
  35. Macros, Strings, Diversion, and Position Traps
  36. .sc
  37. Macros and strings.
  38. A \fImacro\fR is a named set of arbitrary \fIlines\fR that may be invoked by name or
  39. with a \fItrap\fR.
  40. A \fIstring\fR is a named string of \fIcharacters\fR,
  41. \fInot\fR including a newline character,
  42. that may be interpolated by name at any point.
  43. Request, macro, and string names share the \fIsame\fR name list.
  44. Macro and string names
  45. may be one or two characters long and may usurp previously defined
  46. request, macro, or string names.
  47. Any of these entities may be renamed with \fBrn\fR
  48. or removed with \fBrm\fR.
  49. Macros are created by \fBde\fR and \fBdi\fR, and appended to by \fBam\fR and \fBda\fR;
  50. \fBdi\fR and \fBda\fR cause normal output to be stored in a macro.
  51. Strings are created by \fBds\fR and appended to by \fBas\fR.
  52. A macro is invoked in the same way as a request;
  53. a control line beginning \fB.\fIxx\fR will interpolate the contents of macro \fIxx\fR.
  54. The remainder of the line may contain up to nine \fIarguments\fR.
  55. The strings \fIx\fR and \fIxx\fR are interpolated at any desired point with
  56. \fB\e\(**\fIx\fR and \fB\e\(**(\fIxx\fR respectively.
  57. String references and macro invocations may be nested.
  58. .sc
  59. Copy mode input interpretation.
  60. During the definition and extension
  61. of strings and macros (not by diversion)
  62. the input is read in \fIcopy mode\fR.
  63. The input is copied without interpretation
  64. \fIexcept\fR that:
  65. .x1
  66. .ds + \v'-.1m'\s-4\(bu\s+4\v'+.1m'
  67. \*+ The contents of number registers indicated by \fB\en\fR are interpolated.
  68. \*+ Strings indicated by \fB\e\(**\fR are interpolated.
  69. \*+ Arguments indicated by \fB\e$\fR are interpolated.
  70. \*+ Concealed newlines indicated by \fB\e\fR(newline) are eliminated.
  71. \*+ Comments indicated by \fB\e"\fR are eliminated.
  72. \*+ \fB\et\fR and \fB\ea\fR are interpreted as \s-1ASCII\s+1 horizontal tab and \s-1SOH\s+1 respectively (\(sc9).
  73. \*+ \fB\e\e\fR is interpreted as \fB\e\fR.
  74. \*+ \fB\e.\fR is interpreted as "\fB.\fR".
  75. .x2
  76. These interpretations can be suppressed by
  77. prepending
  78. a \fB\e\fR.
  79. For example, since \fB\e\e\fR maps into a \fB\e\fR, \fB\e\en\fR will copy as \fB\en\fR which
  80. will be interpreted as a number register indicator when the
  81. macro or string is reread.
  82. .sc
  83. Arguments.
  84. When a macro is invoked by name, the remainder of the line is
  85. taken to contain up to nine arguments.
  86. The argument separator is the space character, and arguments
  87. may be surrounded by double-quotes to permit imbedded space characters.
  88. Pairs of double-quotes may be imbedded in double-quoted arguments to
  89. represent a single double-quote.
  90. If the desired arguments won't fit on a line,
  91. a concealed newline may be used to continue on the next line.
  92. .pg
  93. When a macro is invoked the \fIinput level\fR is \fIpushed down\fR and
  94. any arguments available at the previous level become unavailable
  95. until the macro is completely read and the previous level is restored.
  96. A macro's own arguments can be interpolated at \fIany\fR point
  97. within the macro with \fB\e$\fIN\fR, which interpolates the \fIN\fR\^th
  98. argument
  99. (1\(<=\fIN\fR\^\(<=9).
  100. If an invoked argument doesn't exist,
  101. a null string results.
  102. For example, the macro \fIxx\fR may be defined by
  103. .x1
  104. .ftB
  105. .ta .75i
  106. &de xx    \e"begin definition
  107. Today is \e\e$1 the \e\e$2.
  108. &.    \e"end definition
  109. .ftR
  110. .x2
  111. and called by
  112. .x1
  113. .ftB
  114. &xx Monday 14th
  115. .ftR
  116. .x2
  117. to produce the text
  118. .x1
  119. .ftB
  120. Today is Monday the 14th.
  121. .ftR
  122. .x2
  123. Note that the \fB\e$\fR
  124. was concealed in the definition with a prepended \fB\e\fR.
  125. The number of currently available
  126. arguments is in the \fB.$\fR register.
  127. .pg
  128. No arguments are available at the top (non-macro) level
  129. in this implementation.
  130. Because string referencing is implemented
  131. as a input-level push down,
  132. no arguments are available from \fIwithin\fR a string.
  133. No arguments are available within a trap-invoked macro.
  134. .pg
  135. Arguments are copied in \fIcopy mode\fR onto a stack
  136. where they are available for reference.
  137. The mechanism does not allow an argument to contain
  138. a direct reference to a \fIlong\fR string
  139. (interpolated at copy time) and it is advisable to
  140. conceal string references (with an extra \fB\e\fR\|)
  141. to delay interpolation until argument reference time.
  142. .sc
  143. Diversions.
  144. Processed output may be diverted into a macro for purposes
  145. such as footnote processing (see Tutorial \(scT5)
  146. or determining the horizontal and vertical size of some text for
  147. conditional changing of pages or columns.
  148. A single diversion trap may be set at a specified vertical position.
  149. The number registers \fBdn\fR and \fBdl\fR respectively contain the
  150. vertical and horizontal size of the most
  151. recently ended diversion.
  152. Processed text that is diverted into a macro
  153. retains the vertical size of each of its lines when reread
  154. in \fInofill\fR mode
  155. regardless of the current \fIV\fR.
  156. Constant-spaced (\fBcs\fR) or emboldened (\fBbd\fR) text that is diverted
  157. can be reread correctly only if these modes are again or still in effect
  158. at reread time.
  159. One way to do this is to imbed in the diversion the appropriate
  160. \fBcs\fR or \fBbd\fR requests with the \fItransparent\fR
  161. mechanism described in \(sc10.6.
  162. .pg
  163. Diversions may be nested
  164. and certain parameters and registers
  165. are associated
  166. with the current diversion level
  167. (the top non-diversion level may be thought of as the
  168. 0th diversion level).
  169. These are the diversion trap and associated macro,
  170. no-space mode,
  171. the internally-saved marked place (see \fBmk\fR and \fBrt\fR),
  172. the current vertical place (\fB.d\fR register),
  173. the current high-water text base-line (\fB.h\fR register),
  174. and the current diversion name (\fB.z\fR register).
  175. .sc
  176. Traps.
  177. Three types of trap mechanisms are available\(empage traps, a diversion trap, and
  178. an input-line-count trap.
  179. Macro-invocation traps may be planted using \fBwh\fR at any page position including the top.
  180. This trap position may be changed using \fBch\fR.
  181. Trap positions at or below the bottom of the page
  182. have no effect unless or until
  183. moved to within the page or rendered effective by an increase in page length.
  184. Two traps may be planted at the \fIsame\fR position only by first planting them at different
  185. positions and then moving one of the traps;
  186. the first planted trap will conceal the second unless and until the first one is moved
  187. (see Tutorial Examples \(scT5).
  188. If the first one is moved back, it again conceals the second trap.
  189. The macro associated with a page trap is automatically
  190. invoked when a line of text is output whose vertical size \fIreaches\fR
  191. or \fIsweeps past\fR the trap position.
  192. Reaching the bottom of a page springs the top-of-page trap, if any,
  193. provided there is a next page.
  194. The distance to the next trap position is available in the \fB.t\fR register;
  195. if there are no traps between the current position and the bottom of the page,
  196. the distance returned is the distance to the page bottom.
  197. .pg
  198. A macro-invocation trap effective in the current diversion may be planted using \fBdt\fR.
  199. The \fB.t\fR register works in a diversion; if there is no subsequent trap a \fIlarge\fR
  200. distance is returned.
  201. For a description of input-line-count traps, see \fBit\fR below.
  202. .h1
  203. .bt
  204. \fB&de\fI|xx|yy\fR    -    \fI.yy=\fB..\fR    -    Define or redefine the macro \fIxx\fR.
  205. The contents of the macro begin on the next input line.
  206. Input lines are copied in \fIcopy mode\fR until the definition is terminated by a
  207. line beginning with \fB.\fIyy\fR,
  208. whereupon the macro \fIyy\fR is called.
  209. In the absence of \fIyy\fR, the definition
  210. is terminated by a
  211. line beginning with "\fB..\fR".
  212. A macro may contain \fBde\fR requests
  213. provided the terminating macros differ
  214. or the contained definition terminator is concealed.
  215. \&"\fB..\fR" can be concealed as
  216. \fB\e\e..\fR which will copy as \fB\e..\fR and be reread as "\fB..\fR".
  217. .bt
  218. \fB&am\fI|xx|yy\fR    -    \fI.yy=\fB..\fR    -    Append to macro (append version of \fBde\fR).
  219. .bt
  220. \fB&ds\fI|xx|string\fR    -    ignored    -    Define a string
  221. \fIxx\fR containing \fIstring\fR.
  222. Any initial double-quote in \fIstring\fR is stripped off to permit
  223. initial blanks.
  224. .bt
  225. \fB&as\fI|xx|string\fR    -    ignored    -    Append
  226. \fIstring\fR to string \fIxx\fR
  227. (append version of \fBds\fR).
  228. .bt
  229. \fB&rm\fI|xx\fR    -    ignored    -    Remove
  230. request, macro, or string.
  231. The name \fIxx\fR is removed from the name list and
  232. any related storage space is freed.
  233. Subsequent references will have no effect.
  234. .bt
  235. \fB&rn\fI|xx|yy\fR    -    ignored    -    Rename request, macro, or string
  236. \fIxx\fR to \fIyy\fR.
  237. If \fIyy\fR exists, it is first removed.
  238. .bt
  239. \fB&di|\fIxx\fR    -    end    D    Divert output to macro \fIxx\fR.
  240. Normal text processing occurs during diversion
  241. except that page offsetting is not done.
  242. The diversion ends when the request \fBdi\fR or \fBda\fR is encountered without an argument;
  243. extraneous
  244. requests of this type should not appear when nested diversions are being used.
  245. .bt
  246. \fB&da|\fIxx\fR    -    end    D    Divert, appending to \fIxx\fR
  247. (append version of \fBdi\fR).
  248. .bt
  249. \fB&wh\fI|N|xx\fR    -    -    \fBv\fR    Install
  250. a trap to invoke \fIxx\fR at page position \fIN;\fR
  251. a \fInegative N\fR will be interpreted with respect to the
  252. page \fIbottom\fR.
  253. Any macro previously planted at \fIN\fR is replaced by \fIxx\fR.
  254. A zero \fIN\fR refers to the \fItop\fR of a page.
  255. In the absence of \fIxx\fR, the first found trap at \fIN\fR, if any, is removed.
  256. .bt
  257. \fB&ch\fI|xx|N\fR    -    -    \fBv\fR    Change
  258. the trap position for macro \fIxx\fR to be \fIN\fR.
  259. In the absence of \fIN\fR, the trap, if any, is removed.
  260. .bt
  261. \fB&dt\fI|N|xx\fR    -    off    D,\fBv\fR    Install a diversion trap
  262. at position \fIN\fR in the \fIcurrent\fR diversion to invoke
  263. macro \fIxx\fR.
  264. Another \fBdt\fR will redefine the diversion trap.
  265. If no arguments are given, the diversion trap is removed.
  266. .bt
  267. \fB&it\fI|N|xx\fR    -    off    E    Set an input-line-count trap
  268. to invoke the macro \fIxx\fR after \fIN\fR lines of \fItext\fR input
  269. have been read
  270. (control or request lines don't count).
  271. The text may be in-line text or
  272. text interpolated by inline or trap-invoked macros.
  273. .bt
  274. \fB&em\fI|xx\fR    none    none    -    The
  275. macro \fIxx\fR will be invoked
  276. when all input has ended.
  277. The effect is the same as if the contents of \fIxx\fR had been at the end
  278. of the last file processed.
  279. .mh
  280. Number Registers
  281. .pg
  282. A variety of parameters are available to the user as
  283. predefined, named \fInumber registers\fR (see Summary and Index, page 7).
  284. In addition, the user may define his own named registers.
  285. Register names are one or two characters long and \fIdo not\fR conflict
  286. with request, macro, or string names.
  287. Except for certain predefined read-only registers,
  288. a number register can be read, written, automatically
  289. incremented or decremented, and interpolated
  290. into the input in a variety of formats.
  291. One common use of user-defined registers is to
  292. automatically number sections, paragraphs, lines, etc.
  293. A number register may be used any time numerical input is expected or desired
  294. and may be used in numerical \fIexpressions\fR (\(sc1.4).
  295. .pg
  296. Number registers are created and modified using \fBnr\fR, which
  297. specifies the name, numerical value, and the auto-increment size.
  298. Registers are also modified, if accessed
  299. with an auto-incrementing sequence.
  300. If the registers \fIx\fR and \fIxx\fR both contain
  301. \fIN\fR and have the auto-increment size \fIM\fR,
  302. the following access sequences have the effect shown:
  303. .TS
  304. center box;
  305. c2|c2|c
  306. c2|c2|c2
  307. l2|c2|c2
  308. l2|c2|c2
  309. l2|l2|c2.
  310.     Effect on    Value
  311. Sequence    Register    Interpolated
  312. _
  313. \fB\en\fIx\fR    none    \fIN\fR
  314. \fB\en(\fIxx\fR    none    \fIN\fR
  315. \fB\en+\fIx\fR    \fIx\fR incremented by \fIM\fR    \fIN+M\fR
  316. \fB\en\-\fIx\fR    \fIx\fR decremented by \fIM\fR    \fIN\-M\fR
  317. \fB\en+(\fIxx\fR    \fIxx\fR incremented by \fIM\fR    \fIN+M\fR
  318. \fB\en\-(\fIxx\fR    \fIxx\fR decremented by \fIM\fR    \fIN\-M\fR
  319. .TE
  320. When interpolated, a number register is converted to
  321. decimal (default),
  322. decimal with leading zeros,
  323. lower-case Roman,
  324. upper-case Roman,
  325. lower-case sequential alphabetic,
  326. or
  327. upper-case sequential alphabetic
  328. according to the format specified by \fBaf\fR.
  329. .h1
  330. .bt
  331. \fB&nr\fI|R|\(+-N|M\fR    -    \fBu\fR    \
  332. The number register \fIR\fR is assigned the value \fI\(+-N\fR
  333. with respect to the previous value, if any.
  334. The increment for auto-incrementing is set to \fIM\fR.
  335. .bt
  336. \fB&af\fI|R|c\fR    arabic    -    -    Assign format \fIc\fR to register \fIR\fR.
  337. The available formats are:
  338. .TS
  339. center box;
  340. c2|c
  341. c2|c
  342. c2|l.
  343.     Numbering
  344. Format    Sequence
  345. _
  346. \fB1\fR    0,1,2,3,4,5,...
  347. \fB001\fR    000,001,002,003,004,005,...
  348. \fBi\fR    0,i,ii,iii,iv,v,...
  349. \fBI\fR    0,I,II,III,IV,V,...
  350. \fBa\fR    0,a,b,c,...,z,aa,ab,...,zz,aaa,...
  351. \fBA\fR    0,A,B,C,...,Z,AA,AB,...,ZZ,AAA,...
  352. .TE
  353. An arabic format having \fIN\fR digits
  354. specifies a field width of \fIN\fR digits (example 2 above).
  355. The read-only registers and the \fIwidth\fR function (\(sc11.2)
  356. are always arabic.
  357. .bt
  358. \fB&rr\fI|R\fR    -    ignored    -    Remove register \fIR\fR.
  359. If many registers are being created dynamically, it
  360. may become necessary to remove no longer used registers
  361. to recapture internal storage space for newer registers.
  362.