File: groff.info,  Node: Environments,  Next: Suppressing Output,  Prev: Diversions,  Up: GNU troff Reference

5.31 Environments
=================

As discussed in *note Deferring Output::, environments store most of the
parameters that determine the appearance of text.  A default environment
named '0' exists when GNU 'troff' starts up; it is modified by
formatting-related requests and escape sequences.

   You can create new environments and switch among them.  Only one is
current at any given time.  Active environments are managed using a
"stack", a data structure supporting "push" and "pop" operations.  The
current environment is at the top of the stack.  The same environment
name can be pushed onto the stack multiple times, possibly interleaved
with others.  Popping the environment stack does not destroy the current
environment; it remains accessible by name and can be made current again
by pushing it at any time.  Environments cannot be renamed or deleted,
and can only be modified when current.  To inspect the environment
stack, use the 'pev' request; see *note Debugging::.

   Environments store the following information.

   * a partially collected line, if any

   * data about the most recently output glyph and line (registers
     '.cdp', '.cht', '.csk', '.n', '.w')

   * typeface parameters (size, family, style, height and slant,
     inter-word and inter-sentence space sizes)

   * page parameters (line length, title length, vertical spacing, line
     spacing, indentation, line numbering, centering, right-alignment,
     underlining, hyphenation parameters)

   * filling enablement; adjustment enablement and mode

   * tab stops; tab, leader, escape, control, no-break control,
     hyphenation, and margin characters

   * input line traps

   * stroke and fill colors

 -- Request: .ev [ident]
 -- Register: \n[.ev]
     Enter the environment IDENT, which is created if it does not
     already exist, using the same parameters as for the default
     environment used at startup.  With no argument, GNU 'troff'
     switches to the previous environment.

     Invoking 'ev' with an argument puts environment IDENT onto the top
     of the environment stack.  (If it isn't already present in the
     stack, this is a proper push.)  Without an argument, 'ev' pops the
     environment stack, making the previous environment current.  It is
     an error to pop the environment stack with no previous environment
     available.  The read-only string-valued register '.ev' contains the
     name of the current environment--the one at the top of the stack.

          .ev footnote-env
          .fam N
          .ps 6
          .vs 8
          .ll -.5i
          .ev

          ...

          .ev footnote-env
          \[dg] Observe the smaller text and vertical spacing.
          .ev

     We can familiarize ourselves with stack behavior by wrapping the
     'ev' request with a macro that reports the contents of the '.ev'
     register to the standard error stream.

          .de EV
          .  ev \\$1
          .  tm environment is now \\n[.ev]
          ..
          .
          .EV foo
          .EV bar
          .EV
          .EV baz
          .EV
          .EV
          .EV

              error-> environment is now foo
              error-> environment is now bar
              error-> environment is now foo
              error-> environment is now baz
              error-> environment is now foo
              error-> environment is now 0
              error-> error: environment stack underflow
              error-> environment is now 0

 -- Request: .evc environment
     Copy the contents of ENVIRONMENT to the current environment.

     The following environment data are not copied.

        * a partially collected line, if present;

        * the interruption status of the previous input line (due to use
          of the '\c' escape sequence);

        * the count of remaining lines to center, to right-justify, or
          to underline (with or without underlined spaces)--these are
          set to zero;

        * the activation status of temporary indentation;

        * input line traps and their associated data;

        * the activation status of line numbering (which can be
          reactivated with '.nm +0'); and

        * the count of consecutive hyphenated lines (set to zero).

 -- Register: \n[.w]
 -- Register: \n[.cht]
 -- Register: \n[.cdp]
 -- Register: \n[.csk]
     The '\n[.w]' register contains the width of the last glyph
     formatted in the environment.

     The '\n[.cht]' register contains the height of the last glyph
     formatted in the environment.

     The '\n[.cdp]' register contains the depth of the last glyph
     formatted in the environment.  It is positive for glyphs extending
     below the baseline.

     The '\n[.csk]' register contains the "skew" (how far to the right
     of the glyph's center that GNU 'troff' should place an accent) of
     the last glyph formatted in the environment.

 -- Register: \n[.n]
     The '\n[.n]' register contains the length of the previous output
     line emitted in the environment.