463 lines
14 KiB
Plaintext
463 lines
14 KiB
Plaintext
.\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are
|
|
.\" met:
|
|
.\"
|
|
.\" Redistributions of source code and documentation must retain the above
|
|
.\" copyright notice, this list of conditions and the following
|
|
.\" disclaimer.
|
|
.\"
|
|
.\" Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\"
|
|
.\" This product includes software developed or owned by Caldera
|
|
.\" International, Inc. Neither the name of Caldera International, Inc.
|
|
.\" nor the names of other contributors may be used to endorse or promote
|
|
.\" products derived from this software without specific prior written
|
|
.\" permission.
|
|
.\"
|
|
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
|
|
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
|
|
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
|
|
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
|
|
.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
|
|
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)m5 8.1 (Berkeley) 8/14/93
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.ds H T
|
|
.tr |
|
|
.tr ~|
|
|
.de x1
|
|
.xx
|
|
.ft B
|
|
.in .2i
|
|
.nf
|
|
.ne 2.1
|
|
.ta 1i
|
|
..
|
|
.de x2
|
|
.fi
|
|
.in 0
|
|
.ft R
|
|
.xx
|
|
..
|
|
.br
|
|
.ce
|
|
.ft B
|
|
.rs
|
|
.sp 0.5i
|
|
TUTORIAL EXAMPLES
|
|
.ft R
|
|
.sp 2
|
|
.nr p 0
|
|
.2C
|
|
.ns
|
|
.mh
|
|
.mk
|
|
Introduction
|
|
.pg
|
|
Although \*(NR and \*(TR
|
|
have by design a syntax reminiscent
|
|
of earlier text processors*
|
|
.fn
|
|
.xx
|
|
*For example:
|
|
P.|A.|Crisman, Ed.,
|
|
.ul
|
|
The Compatible Time-Sharing System,
|
|
MIT Press, 1965, Section|AH9.01
|
|
(Description of RUNOFF program on MIT's CTSS system).
|
|
.ef
|
|
with the intent of easing their use,
|
|
it is almost always necessary to
|
|
prepare at least a small set of macro definitions
|
|
to describe most documents.
|
|
Such common formatting needs
|
|
as page margins and footnotes
|
|
are deliberately not built into \*(NR and \*(TR.
|
|
Instead,
|
|
the macro and string definition, number register, diversion,
|
|
environment switching, page-position trap, and conditional input mechanisms
|
|
provide the basis for user-defined implementations.
|
|
.pg
|
|
The examples to be discussed are intended to be useful and somewhat realistic,
|
|
but won't necessarily cover all relevant contingencies.
|
|
Explicit numerical parameters are used
|
|
in the examples
|
|
to make them easier to read and to
|
|
illustrate typical values.
|
|
In many cases, number registers would really be used
|
|
to reduce the number of places where numerical
|
|
information is kept,
|
|
and to concentrate conditional parameter initialization
|
|
like that which depends on whether \*(TR or \*(NR is being used.
|
|
.mh
|
|
Page Margins
|
|
.pg
|
|
As discussed in \(sc3,
|
|
\fIheader\fR and \fIfooter\fR macros are usually defined
|
|
to describe the top and bottom page margin areas respectively.
|
|
A trap is planted at page position 0 for the header, and at
|
|
\fI\-N\fR (\fIN\fR from the page bottom) for the footer.
|
|
The simplest such definitions might be
|
|
.x1
|
|
&de hd \e"define header
|
|
\'sp 1i
|
|
&& \e"end definition
|
|
&de fo \e"define footer
|
|
\'bp
|
|
&& \e"end definition
|
|
&wh 0 hd
|
|
&wh \-1i fo
|
|
.x2
|
|
which provide blank 1|inch top and bottom margins.
|
|
The header will occur on the \fIfirst\fR page,
|
|
only if the definition and trap exist prior to
|
|
the initial pseudo-page transition (\(sc3).
|
|
In fill mode, the output line that springs the footer trap
|
|
was typically forced out because some part or whole word didn't fit on it.
|
|
If anything in the footer and header that follows causes a \fIbreak\fR,
|
|
that word or part word will be forced out.
|
|
In this and other examples,
|
|
requests like \fBbp\fR and \fBsp\fR that normally cause breaks are invoked using
|
|
the \fIno-break\fR control character \fB\'\fR
|
|
to avoid this.
|
|
When the header\(slfooter design contains material
|
|
requiring independent text processing, the
|
|
environment may be switched, avoiding
|
|
most interaction with the running text.
|
|
.pg
|
|
A more realistic example would be
|
|
.x1
|
|
&de hd \e"header
|
|
&if t .tl \'\|\e(rn\'\'\e(rn\' \e"troff cut mark
|
|
&if \e\en%>1 \e{\e
|
|
\'sp ~\|0.5i\-1 \e"tl base at 0.5i
|
|
&tl \'\'\- % \-\'\' \e"centered page number
|
|
&ps \e"restore size
|
|
&ft \e"restore font
|
|
&vs \e} \e"restore vs
|
|
\'sp ~\|1.0i \e"space to 1.0i
|
|
&ns \e"turn on no-space mode
|
|
&&
|
|
&de fo \e"footer
|
|
&ps 10 \e"set footer\(slheader size
|
|
&ft R \e"set font
|
|
&vs 12p \e"set base-line spacing
|
|
&if \e\en%=1 \e{\e
|
|
\'sp ~\|\e\en(.pu\-0.5i\-1 \e"tl base 0.5i up
|
|
&tl \'\'\- % \-\'\' \e} \e"first page number
|
|
\'bp
|
|
&&
|
|
&wh 0 hd
|
|
&wh \-1i fo
|
|
.x2
|
|
which sets the size, font, and base-line spacing for the
|
|
header\(slfooter material, and ultimately restores them.
|
|
The material in this case is a page number at the bottom of the
|
|
first page and at the top of the remaining pages.
|
|
If \*(TR is used, a \fIcut mark\fR is drawn in the form
|
|
of \fIroot-en\fR's at each margin.
|
|
The \fBsp\fR's refer to absolute positions to avoid
|
|
dependence on the base-line spacing.
|
|
Another reason for this in the footer
|
|
is that the footer is invoked by printing a line whose
|
|
vertical spacing swept past the trap position by possibly
|
|
as much as the base-line spacing.
|
|
The \fIno-space\fR mode is turned on at the end of \fBhd\fR
|
|
to render ineffective
|
|
accidental occurrences of \fBsp\fR at the top of the running text.
|
|
.pg
|
|
The above method of restoring size, font, etc. presupposes
|
|
that such requests (that set \fIprevious\fR value) are \fInot\fR
|
|
used in the running text.
|
|
A better scheme is save and restore both the current \fIand\fR
|
|
previous values as shown for size in the following:
|
|
.x1
|
|
&de fo
|
|
&nr s1 \e\en(.s \e"current size
|
|
&ps
|
|
&nr s2 \e\en(.s \e"previous size
|
|
& --- \e"rest of footer
|
|
&&
|
|
&de hd
|
|
& --- \e"header stuff
|
|
&ps \e\en(s2 \e"restore previous size
|
|
&ps \e\en(s1 \e"restore current size
|
|
&&
|
|
.x2
|
|
Page numbers may be printed in the bottom margin
|
|
by a separate macro triggered during the footer's
|
|
page ejection:
|
|
.x1
|
|
&de bn \e"bottom number
|
|
&tl \'\'\- % \-\'\' \e"centered page number
|
|
&&
|
|
&wh \-0.5i\-1v bn \e"tl base 0.5i up
|
|
.x2
|
|
.mh
|
|
Paragraphs and Headings
|
|
.pg
|
|
The housekeeping
|
|
associated with starting a new paragraph should be collected
|
|
in a paragraph macro
|
|
that, for example,
|
|
does the desired preparagraph spacing,
|
|
forces the correct font, size, base-line spacing, and indent,
|
|
checks that enough space remains for \fImore than one\fR line,
|
|
and
|
|
requests a temporary indent.
|
|
.x1
|
|
&de pg \e"paragraph
|
|
&br \e"break
|
|
&ft R \e"force font,
|
|
&ps 10 \e"size,
|
|
&vs 12p \e"spacing,
|
|
&in 0 \e"and indent
|
|
&sp 0.4 \e"prespace
|
|
&ne 1+\e\en(.Vu \e"want more than 1 line
|
|
&ti 0.2i \e"temp indent
|
|
&&
|
|
.x2
|
|
The first break in \fBpg\fR
|
|
will force out any previous partial lines,
|
|
and must occur before the \fBvs\fR.
|
|
The forcing of font, etc. is
|
|
partly a defense against prior error and
|
|
partly to permit
|
|
things like section heading macros to
|
|
set parameters only once.
|
|
The prespacing parameter is suitable for \*(TR;
|
|
a larger space, at least as big as the output device vertical resolution, would be
|
|
more suitable in \*(NR.
|
|
The choice of remaining space to test for in the \fBne\fR
|
|
is the smallest amount greater than one line
|
|
(the \fB.V\fR is the available vertical resolution).
|
|
.pg
|
|
A macro to automatically number section headings
|
|
might look like:
|
|
.x1
|
|
&de sc \e"section
|
|
& --- \e"force font, etc.
|
|
&sp 0.4 \e"prespace
|
|
&ne 2.4+\e\en(.Vu \e"want 2.4+ lines
|
|
.lg 0
|
|
&fi
|
|
.lg
|
|
\e\en+S.
|
|
&&
|
|
&nr S 0 1 \e"init S
|
|
.x2
|
|
The usage is \fB.sc\fR,
|
|
followed by the section heading text,
|
|
followed by \fB.pg\fR.
|
|
The \fBne\fR test value includes one line of heading,
|
|
0.4 line in the following \fBpg\fR, and
|
|
one line of the paragraph text.
|
|
A word consisting of the next section number and a period is
|
|
produced to begin the heading line.
|
|
The format of the number may be set by \fBaf\fR (\(sc8).
|
|
.pg
|
|
Another common form is the labeled, indented paragraph,
|
|
where the label protrudes left into the indent space.
|
|
.x1
|
|
&de lp \e"labeled paragraph
|
|
&pg
|
|
&in 0.5i \e"paragraph indent
|
|
&ta 0.2i 0.5i \e"label, paragraph
|
|
&ti 0
|
|
\et\e\e$1\et\ec \e"flow into paragraph
|
|
&&
|
|
.x2
|
|
The intended usage is "\fB.lp\fR \fIlabel\fR\|";
|
|
\fIlabel\fR will begin at 0.2\|inch, and
|
|
cannot exceed a length of 0.3\|inch without intruding into
|
|
the paragraph.
|
|
The label could be right adjusted against 0.4\|inch by
|
|
setting the tabs instead with \fB.ta|0.4iR|0.5i\fR.
|
|
The last line of \fBlp\fR ends with \fB\ec\fR so that
|
|
it will become a part of the first line of the text
|
|
that follows.
|
|
.mh
|
|
Multiple Column Output
|
|
.pg
|
|
The production of multiple column pages requires
|
|
the footer macro to decide whether it was
|
|
invoked by other than the last column,
|
|
so that it will begin a new column rather than
|
|
produce the bottom margin.
|
|
The header can initialize a column register that
|
|
the footer will increment and test.
|
|
The following is arranged for two columns, but
|
|
is easily modified for more.
|
|
.x1
|
|
&de hd \e"header
|
|
& ---
|
|
&nr cl 0 1 \e"init column count
|
|
&mk \e"mark top of text
|
|
&&
|
|
&de fo \e"footer
|
|
&ie \e\en+(cl<2 \e{\e
|
|
&po +3.4i \e"next column; 3.1+0.3
|
|
&rt \e"back to mark
|
|
&ns \e} \e"no-space mode
|
|
&el \e{\e
|
|
&po \e\enMu \e"restore left margin
|
|
& ---
|
|
\'bp \e}
|
|
&&
|
|
&ll 3.1i \e"column width
|
|
&nr M \e\en(.o \e"save left margin
|
|
.x2
|
|
Typically a portion of the top of the first page
|
|
contains full width text;
|
|
the request for the narrower line length,
|
|
as well as another \fB.mk\fR would
|
|
be made where the two column output was to begin.
|
|
.mh
|
|
Footnote Processing
|
|
.pg
|
|
The footnote mechanism to be described is used by
|
|
imbedding the footnotes in the input text at the
|
|
point of reference,
|
|
demarcated by an initial \fB.fn\fR and a terminal \fB.ef\fR:
|
|
.x1
|
|
&fn
|
|
\fIFootnote text and control lines...\fP
|
|
&ef
|
|
.x2
|
|
In the following,
|
|
footnotes are processed in a separate environment and diverted
|
|
for later printing in the space immediately prior to the bottom
|
|
margin.
|
|
There is provision for the case where the last collected
|
|
footnote doesn't completely fit in the available space.
|
|
.x1
|
|
&de hd \e"header
|
|
& ---
|
|
&nr x 0 1 \e"init footnote count
|
|
&nr y 0\-\e\enb \e"current footer place
|
|
&ch fo \-\e\enbu \e"reset footer trap
|
|
&if \e\en(dn .fz \e"leftover footnote
|
|
&&
|
|
&de fo \e"footer
|
|
&nr dn 0 \e"zero last diversion size
|
|
&if \e\enx \e{\e
|
|
&ev 1 \e"expand footnotes in ev1
|
|
&nf \e"retain vertical size
|
|
&FN \e"footnotes
|
|
&rm FN \e"delete it
|
|
&if "\e\en(.z"fy" .di \e"end overflow diversion
|
|
&nr x 0 \e"disable fx
|
|
&ev \e} \e"pop environment
|
|
& ---
|
|
\'bp
|
|
&&
|
|
&de fx \e"process footnote overflow
|
|
&if \e\enx .di fy \e"divert overflow
|
|
&&
|
|
&de fn \e"start footnote
|
|
&da FN \e"divert (append) footnote
|
|
&ev 1 \e"in environment 1
|
|
&if \e\en+x=1 .fs \e"if first, include separator
|
|
.lg 0
|
|
&fi \e"fill mode
|
|
.lg
|
|
&&
|
|
&de ef \e"end footnote
|
|
&br \e"finish output
|
|
&nr z \e\en(.v \e"save spacing
|
|
&ev \e"pop ev
|
|
&di \e"end diversion
|
|
&nr y \-\e\en(dn \e"new footer position,
|
|
&if \e\enx=1 .nr y \-(\e\en(.v\-\e\enz) \e
|
|
\e"uncertainty correction
|
|
&ch fo \e\enyu \e"y is negative
|
|
&if (\|\e\en(nl+1v)>(\|\e\en(.p+\e\eny) \e
|
|
&ch fo \e\en(nlu+1v \e"it didn't fit
|
|
&&
|
|
&de fs \e"separator
|
|
\el\'\|1i\' \e"1 inch rule
|
|
&br
|
|
&&
|
|
&de fz \e"get leftover footnote
|
|
&fn
|
|
&nf \e"retain vertical size
|
|
&fy \e"where fx put it
|
|
&ef
|
|
&&
|
|
&nr b 1.0i \e"bottom margin size
|
|
&wh 0 hd \e"header trap
|
|
&wh 12i fo \e"footer trap, temp position
|
|
&wh \-\e\enbu fx \e"fx at footer position
|
|
&ch fo \-\e\enbu \e"conceal fx with fo
|
|
.x2
|
|
The header \fBhd\fR initializes a footnote count register \fBx\fR,
|
|
and sets both the current footer trap position register \fBy\fR and
|
|
the footer trap itself to a nominal position specified in
|
|
register \fBb\fR.
|
|
In addition, if the register \fBdn\fR indicates a leftover footnote,
|
|
\fBfz\fR is invoked to reprocess it.
|
|
The footnote start macro \fBfn\fR begins a diversion (append) in environment 1,
|
|
and increments the count \fBx\fR; if the count is one, the footnote separator \fBfs\fR
|
|
is interpolated.
|
|
The separator is kept in a separate macro to permit user redefinition.
|
|
The footnote end macro \fBef\fR restores
|
|
the previous environment and ends the diversion after saving the spacing size in register \fBz\fR.
|
|
\fBy\fR is then decremented by the size of the footnote, available in \fBdn\fR;
|
|
then on the first footnote, \fBy\fR is further decremented by the difference
|
|
in vertical base-line spacings of the two environments, to
|
|
prevent the late triggering the footer trap from causing the last
|
|
line of the combined footnotes to overflow.
|
|
The footer trap is then set to the lower (on the page) of \fBy\fR or the current page position (\fBnl\fR)
|
|
plus one line, to allow for printing the reference line.
|
|
If indicated by \fBx\fR, the footer \fBfo\fR rereads the footnotes from \fBFN\fR in nofill mode
|
|
in environment 1,
|
|
and deletes \fBFN\fR.
|
|
If the footnotes were too large to fit, the macro \fBfx\fR will be trap-invoked to redivert
|
|
the overflow into \fBfy\fR,
|
|
and the register \fBdn\fR will later indicate to the header whether \fBfy\fR is empty.
|
|
Both \fBfo\fR and \fBfx\fR are planted in the nominal footer trap position in an order
|
|
that causes \fBfx\fR to be concealed unless the \fBfo\fR trap is moved.
|
|
The footer then terminates the overflow diversion, if necessary, and
|
|
zeros \fBx\fR to disable \fBfx\fR,
|
|
because the uncertainty correction
|
|
together with a not-too-late triggering of the footer can result
|
|
in the footnote rereading finishing before reaching the \fBfx\fR trap.
|
|
.pg
|
|
A good exercise for the student is to combine the multiple-column and footnote mechanisms.
|
|
.mh
|
|
The Last Page
|
|
.pg
|
|
After the last input file has ended, \*(NR and \*(TR
|
|
invoke the \fIend macro\fR (\(sc7), if any,
|
|
and when it finishes, eject the remainder of the page.
|
|
During the eject, any traps encountered are processed normally.
|
|
At the \fIend\fR of this last page, processing terminates
|
|
\fIunless\fR a partial line, word, or partial word remains.
|
|
If it is desired that another page be started, the end-macro
|
|
.x1
|
|
&de en \e"end-macro
|
|
\ec
|
|
\'bp
|
|
&&
|
|
&em en
|
|
.x2
|
|
will deposit a null partial word,
|
|
and effect another last page.
|
|
.1C
|
|
'bp
|