Return to tt14 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 25.trofftut

Annotation of 43BSDReno/share/doc/usd/25.trofftut/tt14, revision 1.1

1.1     ! root        1: .\"    @(#)tt14        6.1 (Berkeley) 5/23/86
        !             2: .\"
        !             3: .NH
        !             4: Diversions
        !             5: .PP
        !             6: There are numerous occasions in page layout when it is necessary to store some text
        !             7: for a period of time without actually printing it.
        !             8: Footnotes are the most obvious example:
        !             9: the text of the footnote usually appears in the input well before the place
        !            10: on the page where it is to be printed is reached.
        !            11: In fact,
        !            12: the place where it is output normally depends on how big it is,
        !            13: which implies that there must be a way
        !            14: to process the footnote at least
        !            15: enough to decide its size
        !            16: without printing it.
        !            17: .PP
        !            18: .UL troff
        !            19: provides a mechanism called a diversion
        !            20: for doing this processing.
        !            21: Any part of the output may be diverted into a macro instead
        !            22: of being printed,
        !            23: and then at some convenient time the macro may be put back into
        !            24: the input.
        !            25: .PP
        !            26: The command
        !            27: .BD .di\ xy
        !            28: begins a diversion _ all subsequent output is collected into the macro
        !            29: .BD xy
        !            30: until the command
        !            31: .BD .di
        !            32: with no arguments is encountered.
        !            33: This terminates the diversion.
        !            34: The processed text is available at any time thereafter, simply
        !            35: by giving the command
        !            36: .P1
        !            37: ^xy
        !            38: .P2
        !            39: The vertical size of the last finished diversion is contained in
        !            40: the built-in number register
        !            41: .BD dn .
        !            42: .PP
        !            43: As a simple example,
        !            44: suppose we want to implement a `keep-release'
        !            45: operation,
        !            46: so that text between the commands
        !            47: .BD .KS 
        !            48: and
        !            49: .BD .KE
        !            50: will not be split across a page boundary
        !            51: (as for a figure or table).
        !            52: Clearly, when a
        !            53: .BD .KS
        !            54: is encountered, we have to begin diverting
        !            55: the output so we can find out how big it is.
        !            56: Then when a
        !            57: .BD .KE
        !            58: is seen, we decide
        !            59: whether the diverted text will fit on the current page,
        !            60: and print it either there if it fits, or at the top of the next page if it doesn't.
        !            61: So:
        !            62: .P1 2
        !            63: .ta .6i
        !            64: ^de KS \e" start keep
        !            65: ^br    \e" start fresh line
        !            66: ^ev 1  \e" collect in new environment
        !            67: ^fi    \e" make it filled text
        !            68: ^di XX \e" collect in XX
        !            69: ^^
        !            70: .P2
        !            71: .P1 2
        !            72: .ta .6i
        !            73: ^de KE \e" end keep
        !            74: ^br    \e" get last partial line
        !            75: ^di    \e" end diversion
        !            76: ^if \e\en(dn>=\e\en(.t .bp   \e" bp if doesn't fit
        !            77: ^nf    \e" bring it back in no-fill
        !            78: ^XX    \e" text
        !            79: ^ev    \e" return to normal environment
        !            80: ^^
        !            81: .P2
        !            82: Recall that number register
        !            83: .BD nl
        !            84: is the current position
        !            85: on the output page.
        !            86: Since output was being diverted, this remains
        !            87: at its value when the diversion started.
        !            88: .BD dn
        !            89: is the amount of text in the diversion;
        !            90: .BD .t
        !            91: (another built-in register)
        !            92: is the distance to the next trap,
        !            93: which we assume is at the bottom margin of the page.
        !            94: If the diversion is large enough to go past the trap,
        !            95: the
        !            96: .BD .if
        !            97: is satisfied, and
        !            98: a
        !            99: .BD .bp
        !           100: is issued.
        !           101: In either case, the diverted output is then brought back with
        !           102: .BD .XX .
        !           103: It is essential to bring it back in no-fill mode so
        !           104: .UL troff
        !           105: will do no further processing on it.
        !           106: .PP
        !           107: This is not the most general keep-release,
        !           108: nor is it robust in the face of all conceivable inputs,
        !           109: but it would require more space than we have here to write it
        !           110: in full generality.
        !           111: This section is not intended
        !           112: to teach everything about diversions,
        !           113: but to sketch out enough that you can read
        !           114: existing macro packages with some comprehension.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.