156 lines
5.0 KiB
Plaintext
156 lines
5.0 KiB
Plaintext
.\" This module is believed to contain source code proprietary to AT&T.
|
|
.\" Use and redistribution is subject to the Berkeley Software License
|
|
.\" Agreement and your Software Agreement with AT&T (Western Electric).
|
|
.\"
|
|
.\" @(#)tt14 8.1 (Berkeley) 6/8/93
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.NH
|
|
Diversions
|
|
.PP
|
|
There are numerous occasions in page layout when it is necessary to store some text
|
|
for a period of time without actually printing it.
|
|
Footnotes are the most obvious example:
|
|
the text of the footnote usually appears in the input well before the place
|
|
on the page where it is to be printed is reached.
|
|
In fact,
|
|
the place where it is output normally depends on how big it is,
|
|
which implies that there must be a way
|
|
to process the footnote at least
|
|
enough to decide its size
|
|
without printing it.
|
|
.PP
|
|
.UL troff
|
|
provides a mechanism called a diversion
|
|
for doing this processing.
|
|
Any part of the output may be diverted into a macro instead
|
|
of being printed,
|
|
and then at some convenient time the macro may be put back into
|
|
the input.
|
|
.PP
|
|
The command
|
|
.BD .di\ xy
|
|
begins a diversion _ all subsequent output is collected into the macro
|
|
.BD xy
|
|
until the command
|
|
.BD .di
|
|
with no arguments is encountered.
|
|
This terminates the diversion.
|
|
The processed text is available at any time thereafter, simply
|
|
by giving the command
|
|
.P1
|
|
^xy
|
|
.P2
|
|
The vertical size of the last finished diversion is contained in
|
|
the built-in number register
|
|
.BD dn .
|
|
.PP
|
|
As a simple example,
|
|
suppose we want to implement a `keep-release'
|
|
operation,
|
|
so that text between the commands
|
|
.BD .KS
|
|
and
|
|
.BD .KE
|
|
will not be split across a page boundary
|
|
(as for a figure or table).
|
|
Clearly, when a
|
|
.BD .KS
|
|
is encountered, we have to begin diverting
|
|
the output so we can find out how big it is.
|
|
Then when a
|
|
.BD .KE
|
|
is seen, we decide
|
|
whether the diverted text will fit on the current page,
|
|
and print it either there if it fits, or at the top of the next page if it doesn't.
|
|
So:
|
|
.P1 2
|
|
.ta .6i
|
|
^de KS \e" start keep
|
|
^br \e" start fresh line
|
|
^ev 1 \e" collect in new environment
|
|
^fi \e" make it filled text
|
|
^di XX \e" collect in XX
|
|
^^
|
|
.P2
|
|
.P1 2
|
|
.ta .6i
|
|
^de KE \e" end keep
|
|
^br \e" get last partial line
|
|
^di \e" end diversion
|
|
^if \e\en(dn>=\e\en(.t .bp \e" bp if doesn't fit
|
|
^nf \e" bring it back in no-fill
|
|
^XX \e" text
|
|
^ev \e" return to normal environment
|
|
^^
|
|
.P2
|
|
Recall that number register
|
|
.BD nl
|
|
is the current position
|
|
on the output page.
|
|
Since output was being diverted, this remains
|
|
at its value when the diversion started.
|
|
.BD dn
|
|
is the amount of text in the diversion;
|
|
.BD .t
|
|
(another built-in register)
|
|
is the distance to the next trap,
|
|
which we assume is at the bottom margin of the page.
|
|
If the diversion is large enough to go past the trap,
|
|
the
|
|
.BD .if
|
|
is satisfied, and
|
|
a
|
|
.BD .bp
|
|
is issued.
|
|
In either case, the diverted output is then brought back with
|
|
.BD .XX .
|
|
It is essential to bring it back in no-fill mode so
|
|
.UL troff
|
|
will do no further processing on it.
|
|
.PP
|
|
This is not the most general keep-release,
|
|
nor is it robust in the face of all conceivable inputs,
|
|
but it would require more space than we have here to write it
|
|
in full generality.
|
|
This section is not intended
|
|
to teach everything about diversions,
|
|
but to sketch out enough that you can read
|
|
existing macro packages with some comprehension.
|