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