Commit | Line | Data |
---|---|---|
035eb8bc C |
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. |