GNU Info

(groff)Diversions

---

Next: Environments Prev: Traps Up: gtroff Reference

---

Enter node , (file) or (file)node

Diversions
==========

   In `gtroff' it is possible to "divert" text into a named storage
area.  Due to the similarity to defining macros it is sometimes said to
be stored in a macro.  This is used for saving text for output at a
later time, which is useful for keeping blocks of text on the same
page, footnotes, tables of contents and indices.

 - Request: .di macro
 - Request: .da macro
     Begins a diversion.  Like the `de' request, it takes an argument
     of a macro name to divert subsequent text into.  The `da' macro
     appends to an existing diversion.

     `di' or `da' without an argument ends the diversion.


 - Register: \n[.z]
 - Register: \n[.d]
     Diversions may be nested.  The read-only number register `.z'
     contains the name of the current diversion (this is a string-valued
     register).  The read-only number register `.d' contains the current
     vertical place in the diversion.  If not in a diversion it is the
     same as the register `nl'.

 - Register: \n[.h]
     The "high-water mark" on the current page.  It corresponds to the
     text baseline of the lowest line on the page.  This is a read-only
     register.

 - Register: \n[dn]
 - Register: \n[dl]
     After completing a diversion, the read-write number registers `dn'
     and `dl' contain the vertical and horizontal size of the diversion.

          .\" Center text both horizontally & vertically
          .de (c
          .br
          .nf
          .di @c
          ..
          .de )c
          .br
          .di
          .nr @s (((\\n(.tu-\\n(dnu)/2u)-1v)
          .sp \\n(@su
          .ce 1000
          .nf
          ..br
          .ce 0
          .sp \\n(@su
          .br
          .fi
          .rr @s
          ..

 - Escape: \!
 - Escape: \?ANYTHING\?
     Prevents requests, macros and escapes from being interpreted when
     read into a diversion.  This takes the given text and
     "transparently" embeds it into the diversion.  This is useful for
     macros which shouldn't be invoked until the diverted text is
     actually output.

     The `\!' escape transparently embeds text up to and including the
     end of the line.  The `\?' escape transparently embeds text until
     the next occurrence of the `\?' escape.  For example:


          \?ANYTHING\?

     ANYTHING may not contain newlines; use `\!'  to embed newlines in
     a diversion.  The escape sequence `\?' is also recognized in copy
     mode and turned into a single internal code; it is this code that
     terminates anything.  Thus the following example prints 4.


          .nr x 1
          .nf
          .di d
          \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
          .di
          .nr x 2
          .di e
          .d
          .di
          .nr x 3
          .di f
          .e
          .di
          .nr x 4
          .f


 - Request: .asciify div
     "Unformats" the diversion specified by DIV in such a way that
     ASCII and space characters that were formatted and diverted are
     treated like ordinary input characters when the diversion is
     reread.  It can be also used for gross hacks; for example, the
     following sets register `n' to 1.


          .tr @.
          .di x
          @nr n 1
          .br
          .di
          .tr @@
          .asciify x
          .x

     Note: Copy-in Mode.