1 files changed, 152 insertions, 0 deletions
diff --git a/share/doc/usd/22.trofftut/tt14 b/share/doc/usd/22.trofftut/tt14
new file mode 100644
index 000000000000..962fb4a21553
--- /dev/null
+++ b/share/doc/usd/22.trofftut/tt14
@@ -0,0 +1,152 @@
+.\" 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).
+.\" 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.
+.\" 
+.\"
+.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.