1 .\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions are
7 .\" Redistributions of source code and documentation must retain the above
8 .\" copyright notice, this list of conditions and the following
11 .\" Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
18 .\" This product includes software developed or owned by Caldera
19 .\" International, Inc. Neither the name of Caldera International, Inc.
20 .\" nor the names of other contributors may be used to endorse or promote
21 .\" products derived from this software without specific prior written
24 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
25 .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
27 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
28 .\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
32 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
33 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
34 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
35 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 .\" @(#)m5 8.1 (Berkeley) 8/14/93
72 Although \*(NR and \*(TR
73 have by design a syntax reminiscent
74 of earlier text processors*
80 The Compatible Time-Sharing System,
81 MIT Press, 1965, Section|AH9.01
82 (Description of RUNOFF program on MIT's CTSS system).
84 with the intent of easing their use,
85 it is almost always necessary to
86 prepare at least a small set of macro definitions
87 to describe most documents.
88 Such common formatting needs
89 as page margins and footnotes
90 are deliberately not built into \*(NR and \*(TR.
92 the macro and string definition, number register, diversion,
93 environment switching, page-position trap, and conditional input mechanisms
94 provide the basis for user-defined implementations.
96 The examples to be discussed are intended to be useful and somewhat realistic,
97 but won't necessarily cover all relevant contingencies.
98 Explicit numerical parameters are used
100 to make them easier to read and to
101 illustrate typical values.
102 In many cases, number registers would really be used
103 to reduce the number of places where numerical
105 and to concentrate conditional parameter initialization
106 like that which depends on whether \*(TR or \*(NR is being used.
110 As discussed in \(sc3,
111 \fIheader\fR and \fIfooter\fR macros are usually defined
112 to describe the top and bottom page margin areas respectively.
113 A trap is planted at page position 0 for the header, and at
114 \fI\-N\fR (\fIN\fR from the page bottom) for the footer.
115 The simplest such definitions might be
117 &de hd \e"define header
120 &de fo \e"define footer
126 which provide blank 1|inch top and bottom margins.
127 The header will occur on the \fIfirst\fR page,
128 only if the definition and trap exist prior to
129 the initial pseudo-page transition (\(sc3).
130 In fill mode, the output line that springs the footer trap
131 was typically forced out because some part or whole word didn't fit on it.
132 If anything in the footer and header that follows causes a \fIbreak\fR,
133 that word or part word will be forced out.
134 In this and other examples,
135 requests like \fBbp\fR and \fBsp\fR that normally cause breaks are invoked using
136 the \fIno-break\fR control character \fB\'\fR
138 When the header\(slfooter design contains material
139 requiring independent text processing, the
140 environment may be switched, avoiding
141 most interaction with the running text.
143 A more realistic example would be
146 &if t .tl \'\|\e(rn\'\'\e(rn\' \e"troff cut mark
148 \'sp ~\|0.5i\-1 \e"tl base at 0.5i
149 &tl \'\'\- % \-\'\' \e"centered page number
152 &vs \e} \e"restore vs
153 \'sp ~\|1.0i \e"space to 1.0i
154 &ns \e"turn on no-space mode
157 &ps 10 \e"set footer\(slheader size
159 &vs 12p \e"set base-line spacing
161 \'sp ~\|\e\en(.pu\-0.5i\-1 \e"tl base 0.5i up
162 &tl \'\'\- % \-\'\' \e} \e"first page number
168 which sets the size, font, and base-line spacing for the
169 header\(slfooter material, and ultimately restores them.
170 The material in this case is a page number at the bottom of the
171 first page and at the top of the remaining pages.
172 If \*(TR is used, a \fIcut mark\fR is drawn in the form
173 of \fIroot-en\fR's at each margin.
174 The \fBsp\fR's refer to absolute positions to avoid
175 dependence on the base-line spacing.
176 Another reason for this in the footer
177 is that the footer is invoked by printing a line whose
178 vertical spacing swept past the trap position by possibly
179 as much as the base-line spacing.
180 The \fIno-space\fR mode is turned on at the end of \fBhd\fR
181 to render ineffective
182 accidental occurrences of \fBsp\fR at the top of the running text.
184 The above method of restoring size, font, etc. presupposes
185 that such requests (that set \fIprevious\fR value) are \fInot\fR
186 used in the running text.
187 A better scheme is save and restore both the current \fIand\fR
188 previous values as shown for size in the following:
191 &nr s1 \e\en(.s \e"current size
193 &nr s2 \e\en(.s \e"previous size
194 & --- \e"rest of footer
197 & --- \e"header stuff
198 &ps \e\en(s2 \e"restore previous size
199 &ps \e\en(s1 \e"restore current size
202 Page numbers may be printed in the bottom margin
203 by a separate macro triggered during the footer's
206 &de bn \e"bottom number
207 &tl \'\'\- % \-\'\' \e"centered page number
209 &wh \-0.5i\-1v bn \e"tl base 0.5i up
212 Paragraphs and Headings
215 associated with starting a new paragraph should be collected
218 does the desired preparagraph spacing,
219 forces the correct font, size, base-line spacing, and indent,
220 checks that enough space remains for \fImore than one\fR line,
222 requests a temporary indent.
231 &ne 1+\e\en(.Vu \e"want more than 1 line
232 &ti 0.2i \e"temp indent
235 The first break in \fBpg\fR
236 will force out any previous partial lines,
237 and must occur before the \fBvs\fR.
238 The forcing of font, etc. is
239 partly a defense against prior error and
241 things like section heading macros to
242 set parameters only once.
243 The prespacing parameter is suitable for \*(TR;
244 a larger space, at least as big as the output device vertical resolution, would be
245 more suitable in \*(NR.
246 The choice of remaining space to test for in the \fBne\fR
247 is the smallest amount greater than one line
248 (the \fB.V\fR is the available vertical resolution).
250 A macro to automatically number section headings
254 & --- \e"force font, etc.
256 &ne 2.4+\e\en(.Vu \e"want 2.4+ lines
264 The usage is \fB.sc\fR,
265 followed by the section heading text,
266 followed by \fB.pg\fR.
267 The \fBne\fR test value includes one line of heading,
268 0.4 line in the following \fBpg\fR, and
269 one line of the paragraph text.
270 A word consisting of the next section number and a period is
271 produced to begin the heading line.
272 The format of the number may be set by \fBaf\fR (\(sc8).
274 Another common form is the labeled, indented paragraph,
275 where the label protrudes left into the indent space.
277 &de lp \e"labeled paragraph
279 &in 0.5i \e"paragraph indent
280 &ta 0.2i 0.5i \e"label, paragraph
282 \et\e\e$1\et\ec \e"flow into paragraph
285 The intended usage is "\fB.lp\fR \fIlabel\fR\|";
286 \fIlabel\fR will begin at 0.2\|inch, and
287 cannot exceed a length of 0.3\|inch without intruding into
289 The label could be right adjusted against 0.4\|inch by
290 setting the tabs instead with \fB.ta|0.4iR|0.5i\fR.
291 The last line of \fBlp\fR ends with \fB\ec\fR so that
292 it will become a part of the first line of the text
295 Multiple Column Output
297 The production of multiple column pages requires
298 the footer macro to decide whether it was
299 invoked by other than the last column,
300 so that it will begin a new column rather than
301 produce the bottom margin.
302 The header can initialize a column register that
303 the footer will increment and test.
304 The following is arranged for two columns, but
305 is easily modified for more.
309 &nr cl 0 1 \e"init column count
310 &mk \e"mark top of text
313 &ie \e\en+(cl<2 \e{\e
314 &po +3.4i \e"next column; 3.1+0.3
316 &ns \e} \e"no-space mode
318 &po \e\enMu \e"restore left margin
322 &ll 3.1i \e"column width
323 &nr M \e\en(.o \e"save left margin
325 Typically a portion of the top of the first page
326 contains full width text;
327 the request for the narrower line length,
328 as well as another \fB.mk\fR would
329 be made where the two column output was to begin.
333 The footnote mechanism to be described is used by
334 imbedding the footnotes in the input text at the
336 demarcated by an initial \fB.fn\fR and a terminal \fB.ef\fR:
339 \fIFootnote text and control lines...\fP
343 footnotes are processed in a separate environment and diverted
344 for later printing in the space immediately prior to the bottom
346 There is provision for the case where the last collected
347 footnote doesn't completely fit in the available space.
351 &nr x 0 1 \e"init footnote count
352 &nr y 0\-\e\enb \e"current footer place
353 &ch fo \-\e\enbu \e"reset footer trap
354 &if \e\en(dn .fz \e"leftover footnote
357 &nr dn 0 \e"zero last diversion size
359 &ev 1 \e"expand footnotes in ev1
360 &nf \e"retain vertical size
363 &if "\e\en(.z"fy" .di \e"end overflow diversion
364 &nr x 0 \e"disable fx
365 &ev \e} \e"pop environment
369 &de fx \e"process footnote overflow
370 &if \e\enx .di fy \e"divert overflow
372 &de fn \e"start footnote
373 &da FN \e"divert (append) footnote
374 &ev 1 \e"in environment 1
375 &if \e\en+x=1 .fs \e"if first, include separator
380 &de ef \e"end footnote
382 &nr z \e\en(.v \e"save spacing
385 &nr y \-\e\en(dn \e"new footer position,
386 &if \e\enx=1 .nr y \-(\e\en(.v\-\e\enz) \e
387 \e"uncertainty correction
388 &ch fo \e\enyu \e"y is negative
389 &if (\|\e\en(nl+1v)>(\|\e\en(.p+\e\eny) \e
390 &ch fo \e\en(nlu+1v \e"it didn't fit
393 \el\'\|1i\' \e"1 inch rule
396 &de fz \e"get leftover footnote
398 &nf \e"retain vertical size
399 &fy \e"where fx put it
402 &nr b 1.0i \e"bottom margin size
403 &wh 0 hd \e"header trap
404 &wh 12i fo \e"footer trap, temp position
405 &wh \-\e\enbu fx \e"fx at footer position
406 &ch fo \-\e\enbu \e"conceal fx with fo
408 The header \fBhd\fR initializes a footnote count register \fBx\fR,
409 and sets both the current footer trap position register \fBy\fR and
410 the footer trap itself to a nominal position specified in
412 In addition, if the register \fBdn\fR indicates a leftover footnote,
413 \fBfz\fR is invoked to reprocess it.
414 The footnote start macro \fBfn\fR begins a diversion (append) in environment 1,
415 and increments the count \fBx\fR; if the count is one, the footnote separator \fBfs\fR
417 The separator is kept in a separate macro to permit user redefinition.
418 The footnote end macro \fBef\fR restores
419 the previous environment and ends the diversion after saving the spacing size in register \fBz\fR.
420 \fBy\fR is then decremented by the size of the footnote, available in \fBdn\fR;
421 then on the first footnote, \fBy\fR is further decremented by the difference
422 in vertical base-line spacings of the two environments, to
423 prevent the late triggering the footer trap from causing the last
424 line of the combined footnotes to overflow.
425 The footer trap is then set to the lower (on the page) of \fBy\fR or the current page position (\fBnl\fR)
426 plus one line, to allow for printing the reference line.
427 If indicated by \fBx\fR, the footer \fBfo\fR rereads the footnotes from \fBFN\fR in nofill mode
429 and deletes \fBFN\fR.
430 If the footnotes were too large to fit, the macro \fBfx\fR will be trap-invoked to redivert
431 the overflow into \fBfy\fR,
432 and the register \fBdn\fR will later indicate to the header whether \fBfy\fR is empty.
433 Both \fBfo\fR and \fBfx\fR are planted in the nominal footer trap position in an order
434 that causes \fBfx\fR to be concealed unless the \fBfo\fR trap is moved.
435 The footer then terminates the overflow diversion, if necessary, and
436 zeros \fBx\fR to disable \fBfx\fR,
437 because the uncertainty correction
438 together with a not-too-late triggering of the footer can result
439 in the footnote rereading finishing before reaching the \fBfx\fR trap.
441 A good exercise for the student is to combine the multiple-column and footnote mechanisms.
445 After the last input file has ended, \*(NR and \*(TR
446 invoke the \fIend macro\fR (\(sc7), if any,
447 and when it finishes, eject the remainder of the page.
448 During the eject, any traps encountered are processed normally.
449 At the \fIend\fR of this last page, processing terminates
450 \fIunless\fR a partial line, word, or partial word remains.
451 If it is desired that another page be started, the end-macro
459 will deposit a null partial word,
460 and effect another last page.