5.31 Environments

As discussed in 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 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.