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