![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to m5 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 m5 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 24.troff |
1.1 root 1: .\" @(#)m5 6.1 (Berkeley) 4/17/86
2: .\"
3: .pn 28
4: .ds H T
5: .tr |
6: .tr ~|
7: .de x1
8: .xx
9: .ftB
10: .in .2i
11: .nf
12: .ne 2.1
13: .ta 1i
14: ..
15: .de x2
16: .fi
17: .in0
18: .ftR
19: .xx
20: ..
21: .br
22: .ce
23: .ftB
24: .rs
25: .sp 0.5i
26: TUTORIAL EXAMPLES
27: .ftR
28: .sp2
29: .nr p 0
30: .2C
31: .ns
32: .mh
33: .mk
34: Introduction
35: .pg
36: Although \*(NR and \*(TR
37: have by design a syntax reminiscent
38: of earlier text processors*
39: .fn
40: .xx
41: *For example:
42: P.|A.|Crisman, Ed.,
43: .ul
44: The Compatible Time-Sharing System,
45: MIT Press, 1965, Section|AH9.01
46: (Description of RUNOFF program on MIT's CTSS system).
47: .ef
48: with the intent of easing their use,
49: it is almost always necessary to
50: prepare at least a small set of macro definitions
51: to describe most documents.
52: Such common formatting needs
53: as page margins and footnotes
54: are deliberately not built into \*(NR and \*(TR.
55: Instead,
56: the macro and string definition, number register, diversion,
57: environment switching, page-position trap, and conditional input mechanisms
58: provide the basis for user-defined implementations.
59: .pg
60: The examples to be discussed are intended to be useful and somewhat realistic,
61: but won't necessarily cover all relevant contingencies.
62: Explicit numerical parameters are used
63: in the examples
64: to make them easier to read and to
65: illustrate typical values.
66: In many cases, number registers would really be used
67: to reduce the number of places where numerical
68: information is kept,
69: and to concentrate conditional parameter initialization
70: like that which depends on whether \*(TR or \*(NR is being used.
71: .mh
72: Page Margins
73: .pg
74: As discussed in \(sc3,
75: \fIheader\fR and \fIfooter\fR macros are usually defined
76: to describe the top and bottom page margin areas respectively.
77: A trap is planted at page position 0 for the header, and at
78: \fI\-N\fR (\fIN\fR from the page bottom) for the footer.
79: The simplest such definitions might be
80: .x1
81: &de hd \e"define header
82: \'sp 1i
83: && \e"end definition
84: &de fo \e"define footer
85: \'bp
86: && \e"end definition
87: &wh 0 hd
88: &wh \-1i fo
89: .x2
90: which provide blank 1|inch top and bottom margins.
91: The header will occur on the \fIfirst\fR page,
92: only if the definition and trap exist prior to
93: the initial pseudo-page transition (\(sc3).
94: In fill mode, the output line that springs the footer trap
95: was typically forced out because some part or whole word didn't fit on it.
96: If anything in the footer and header that follows causes a \fIbreak\fR,
97: that word or part word will be forced out.
98: In this and other examples,
99: requests like \fBbp\fR and \fBsp\fR that normally cause breaks are invoked using
100: the \fIno-break\fR control character \fB\'\fR
101: to avoid this.
102: When the header\(slfooter design contains material
103: requiring independent text processing, the
104: environment may be switched, avoiding
105: most interaction with the running text.
106: .pg
107: A more realistic example would be
108: .x1
109: &de hd \e"header
110: &if t .tl \'\|\e(rn\'\'\e(rn\' \e"troff cut mark
111: &if \e\en%>1 \e{\e
112: \'sp ~\|0.5i\-1 \e"tl base at 0.5i
113: &tl \'\'\- % \-\'\' \e"centered page number
114: &ps \e"restore size
115: &ft \e"restore font
116: &vs \e} \e"restore vs
117: \'sp ~\|1.0i \e"space to 1.0i
118: &ns \e"turn on no-space mode
119: &&
120: &de fo \e"footer
121: &ps 10 \e"set footer\(slheader size
122: &ft R \e"set font
123: &vs 12p \e"set base-line spacing
124: &if \e\en%=1 \e{\e
125: \'sp ~\|\e\en(.pu\-0.5i\-1 \e"tl base 0.5i up
126: &tl \'\'\- % \-\'\' \e} \e"first page number
127: \'bp
128: &&
129: &wh 0 hd
130: &wh \-1i fo
131: .x2
132: which sets the size, font, and base-line spacing for the
133: header\(slfooter material, and ultimately restores them.
134: The material in this case is a page number at the bottom of the
135: first page and at the top of the remaining pages.
136: If \*(TR is used, a \fIcut mark\fR is drawn in the form
137: of \fIroot-en\fR's at each margin.
138: The \fBsp\fR's refer to absolute positions to avoid
139: dependence on the base-line spacing.
140: Another reason for this in the footer
141: is that the footer is invoked by printing a line whose
142: vertical spacing swept past the trap position by possibly
143: as much as the base-line spacing.
144: The \fIno-space\fR mode is turned on at the end of \fBhd\fR
145: to render ineffective
146: accidental occurrences of \fBsp\fR at the top of the running text.
147: .pg
148: The above method of restoring size, font, etc. presupposes
149: that such requests (that set \fIprevious\fR value) are \fInot\fR
150: used in the running text.
151: A better scheme is save and restore both the current \fIand\fR
152: previous values as shown for size in the following:
153: .x1
154: &de fo
155: &nr s1 \e\en(.s \e"current size
156: &ps
157: &nr s2 \e\en(.s \e"previous size
158: & --- \e"rest of footer
159: &&
160: &de hd
161: & --- \e"header stuff
162: &ps \e\en(s2 \e"restore previous size
163: &ps \e\en(s1 \e"restore current size
164: &&
165: .x2
166: Page numbers may be printed in the bottom margin
167: by a separate macro triggered during the footer's
168: page ejection:
169: .x1
170: &de bn \e"bottom number
171: &tl \'\'\- % \-\'\' \e"centered page number
172: &&
173: &wh \-0.5i\-1v bn \e"tl base 0.5i up
174: .x2
175: .mh
176: Paragraphs and Headings
177: .pg
178: The housekeeping
179: associated with starting a new paragraph should be collected
180: in a paragraph macro
181: that, for example,
182: does the desired preparagraph spacing,
183: forces the correct font, size, base-line spacing, and indent,
184: checks that enough space remains for \fImore than one\fR line,
185: and
186: requests a temporary indent.
187: .x1
188: &de pg \e"paragraph
189: &br \e"break
190: &ft R \e"force font,
191: &ps 10 \e"size,
192: &vs 12p \e"spacing,
193: &in 0 \e"and indent
194: &sp 0.4 \e"prespace
195: &ne 1+\e\en(.Vu \e"want more than 1 line
196: &ti 0.2i \e"temp indent
197: &&
198: .x2
199: The first break in \fBpg\fR
200: will force out any previous partial lines,
201: and must occur before the \fBvs\fR.
202: The forcing of font, etc. is
203: partly a defense against prior error and
204: partly to permit
205: things like section heading macros to
206: set parameters only once.
207: The prespacing parameter is suitable for \*(TR;
208: a larger space, at least as big as the output device vertical resolution, would be
209: more suitable in \*(NR.
210: The choice of remaining space to test for in the \fBne\fR
211: is the smallest amount greater than one line
212: (the \fB.V\fR is the available vertical resolution).
213: .pg
214: A macro to automatically number section headings
215: might look like:
216: .x1
217: &de sc \e"section
218: & --- \e"force font, etc.
219: &sp 0.4 \e"prespace
220: &ne 2.4+\e\en(.Vu \e"want 2.4+ lines
221: .lg 0
222: &fi
223: .lg
224: \e\en+S.
225: &&
226: &nr S 0 1 \e"init S
227: .x2
228: The usage is \fB.sc\fR,
229: followed by the section heading text,
230: followed by \fB.pg\fR.
231: The \fBne\fR test value includes one line of heading,
232: 0.4 line in the following \fBpg\fR, and
233: one line of the paragraph text.
234: A word consisting of the next section number and a period is
235: produced to begin the heading line.
236: The format of the number may be set by \fBaf\fR (\(sc8).
237: .pg
238: Another common form is the labeled, indented paragraph,
239: where the label protrudes left into the indent space.
240: .x1
241: &de lp \e"labeled paragraph
242: &pg
243: &in 0.5i \e"paragraph indent
244: &ta 0.2i 0.5i \e"label, paragraph
245: &ti 0
246: \et\e\e$1\et\ec \e"flow into paragraph
247: &&
248: .x2
249: The intended usage is "\fB.lp\fR \fIlabel\fR\|";
250: \fIlabel\fR will begin at 0.2\|inch, and
251: cannot exceed a length of 0.3\|inch without intruding into
252: the paragraph.
253: The label could be right adjusted against 0.4\|inch by
254: setting the tabs instead with \fB.ta|0.4iR|0.5i\fR.
255: The last line of \fBlp\fR ends with \fB\ec\fR so that
256: it will become a part of the first line of the text
257: that follows.
258: .mh
259: Multiple Column Output
260: .pg
261: The production of multiple column pages requires
262: the footer macro to decide whether it was
263: invoked by other than the last column,
264: so that it will begin a new column rather than
265: produce the bottom margin.
266: The header can initialize a column register that
267: the footer will increment and test.
268: The following is arranged for two columns, but
269: is easily modified for more.
270: .x1
271: &de hd \e"header
272: & ---
273: &nr cl 0 1 \e"init column count
274: &mk \e"mark top of text
275: &&
276: &de fo \e"footer
277: &ie \e\en+(cl<2 \e{\e
278: &po +3.4i \e"next column; 3.1+0.3
279: &rt \e"back to mark
280: &ns \e} \e"no-space mode
281: &el \e{\e
282: &po \e\enMu \e"restore left margin
283: & ---
284: \'bp \e}
285: &&
286: &ll 3.1i \e"column width
287: &nr M \e\en(.o \e"save left margin
288: .x2
289: Typically a portion of the top of the first page
290: contains full width text;
291: the request for the narrower line length,
292: as well as another \fB.mk\fR would
293: be made where the two column output was to begin.
294: .mh
295: Footnote Processing
296: .pg
297: The footnote mechanism to be described is used by
298: imbedding the footnotes in the input text at the
299: point of reference,
300: demarcated by an initial \fB.fn\fR and a terminal \fB.ef\fR:
301: .x1
302: &fn
303: \fIFootnote text and control lines...\fP
304: &ef
305: .x2
306: In the following,
307: footnotes are processed in a separate environment and diverted
308: for later printing in the space immediately prior to the bottom
309: margin.
310: There is provision for the case where the last collected
311: footnote doesn't completely fit in the available space.
312: .x1
313: &de hd \e"header
314: & ---
315: &nr x 0 1 \e"init footnote count
316: &nr y 0\-\e\enb \e"current footer place
317: &ch fo \-\e\enbu \e"reset footer trap
318: &if \e\en(dn .fz \e"leftover footnote
319: &&
320: &de fo \e"footer
321: &nr dn 0 \e"zero last diversion size
322: &if \e\enx \e{\e
323: &ev 1 \e"expand footnotes in ev1
324: &nf \e"retain vertical size
325: &FN \e"footnotes
326: &rm FN \e"delete it
327: &if "\e\en(.z"fy" .di \e"end overflow diversion
328: &nr x 0 \e"disable fx
329: &ev \e} \e"pop environment
330: & ---
331: \'bp
332: &&
333: &de fx \e"process footnote overflow
334: &if \e\enx .di fy \e"divert overflow
335: &&
336: &de fn \e"start footnote
337: &da FN \e"divert (append) footnote
338: &ev 1 \e"in environment 1
339: &if \e\en+x=1 .fs \e"if first, include separator
340: .lg0
341: &fi \e"fill mode
342: .lg
343: &&
344: &de ef \e"end footnote
345: &br \e"finish output
346: &nr z \e\en(.v \e"save spacing
347: &ev \e"pop ev
348: &di \e"end diversion
349: &nr y \-\e\en(dn \e"new footer position,
350: &if \e\enx=1 .nr y \-(\e\en(.v\-\e\enz) \e
351: \e"uncertainty correction
352: &ch fo \e\enyu \e"y is negative
353: &if (\|\e\en(nl+1v)>(\|\e\en(.p+\e\eny) \e
354: &ch fo \e\en(nlu+1v \e"it didn't fit
355: &&
356: &de fs \e"separator
357: \el\'\|1i\' \e"1 inch rule
358: &br
359: &&
360: &de fz \e"get leftover footnote
361: &fn
362: &nf \e"retain vertical size
363: &fy \e"where fx put it
364: &ef
365: &&
366: &nr b 1.0i \e"bottom margin size
367: &wh 0 hd \e"header trap
368: &wh 12i fo \e"footer trap, temp position
369: &wh \-\e\enbu fx \e"fx at footer position
370: &ch fo \-\e\enbu \e"conceal fx with fo
371: .x2
372: The header \fBhd\fR initializes a footnote count register \fBx\fR,
373: and sets both the current footer trap position register \fBy\fR and
374: the footer trap itself to a nominal position specified in
375: register \fBb\fR.
376: In addition, if the register \fBdn\fR indicates a leftover footnote,
377: \fBfz\fR is invoked to reprocess it.
378: The footnote start macro \fBfn\fR begins a diversion (append) in environment 1,
379: and increments the count \fBx\fR; if the count is one, the footnote separator \fBfs\fR
380: is interpolated.
381: The separator is kept in a separate macro to permit user redefinition.
382: The footnote end macro \fBef\fR restores
383: the previous environment and ends the diversion after saving the spacing size in register \fBz\fR.
384: \fBy\fR is then decremented by the size of the footnote, available in \fBdn\fR;
385: then on the first footnote, \fBy\fR is further decremented by the difference
386: in vertical base-line spacings of the two environments, to
387: prevent the late triggering the footer trap from causing the last
388: line of the combined footnotes to overflow.
389: The footer trap is then set to the lower (on the page) of \fBy\fR or the current page position (\fBnl\fR)
390: plus one line, to allow for printing the reference line.
391: If indicated by \fBx\fR, the footer \fBfo\fR rereads the footnotes from \fBFN\fR in nofill mode
392: in environment 1,
393: and deletes \fBFN\fR.
394: If the footnotes were too large to fit, the macro \fBfx\fR will be trap-invoked to redivert
395: the overflow into \fBfy\fR,
396: and the register \fBdn\fR will later indicate to the header whether \fBfy\fR is empty.
397: Both \fBfo\fR and \fBfx\fR are planted in the nominal footer trap position in an order
398: that causes \fBfx\fR to be concealed unless the \fBfo\fR trap is moved.
399: The footer then terminates the overflow diversion, if necessary, and
400: zeros \fBx\fR to disable \fBfx\fR,
401: because the uncertainty correction
402: together with a not-too-late triggering of the footer can result
403: in the footnote rereading finishing before reaching the \fBfx\fR trap.
404: .pg
405: A good exercise for the student is to combine the multiple-column and footnote mechanisms.
406: .mh
407: The Last Page
408: .pg
409: After the last input file has ended, \*(NR and \*(TR
410: invoke the \fIend macro\fR (\(sc7), if any,
411: and when it finishes, eject the remainder of the page.
412: During the eject, any traps encountered are processed normally.
413: At the \fIend\fR of this last page, processing terminates
414: \fIunless\fR a partial line, word, or partial word remains.
415: If it is desired that another page be started, the end-macro
416: .x1
417: &de en \e"end-macro
418: \ec
419: \'bp
420: &&
421: &em en
422: .x2
423: will deposit a null partial word,
424: and effect another last page.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.