![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to m2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 24.troff|
Return to m2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 24.troff |
1.1 root 1: .\" @(#)m2 6.2 (Berkeley) 4/21/86
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.
203: For a description of input-line-count traps, see the \fBit\fR request below.
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
333: \fB&nr\fI|R|\(+-N|M\fR - - \fBu\fR \
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.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.