/share/doc/usd/21.troff/m5

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