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