[groff] 16/41: [docs]: Expand explanation of environments.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 971f0055267aaa016a7593cd2274b3c7d5b8ead8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Mar 16 18:24:44 2022 +1100

    [docs]: Expand explanation of environments.
    
    * doc/groff.texi (Environments): Clarify environment handling.
    * man/groff.7.man (Environments): Add new section.
    
    Fixes <https://savannah.gnu.org/bugs/?62036>.
---
 ChangeLog       |   7 ++++
 doc/groff.texi  |  22 +++++++-----
 man/groff.7.man | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 128 insertions(+), 9 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index fc072ed5..5fce792e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2022-03-16  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (Environments): Clarify environment handling.
+       * man/groff.7.man (Environments): Add new section.
+
+       Fixes <https://savannah.gnu.org/bugs/?62036>.
+
 2022-03-15  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/e.tmac (initialization): Define `@b` as empty if
diff --git a/doc/groff.texi b/doc/groff.texi
index 9e4c33e1..4997d044 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14659,6 +14659,7 @@ space width, and so on) is retained.
 
 @c =====================================================================
 
+@c BEGIN Keep parallel with section "Environments" of groff(7).
 @node Environments, Suppressing Output, Diversions, gtroff Reference
 @section Environments
 @cindex environments
@@ -14670,15 +14671,17 @@ formatting-related requests and escape sequences.
 
 @cindex stack
 You can create new environments and switch among them.  Only one is
-active at any given time.  Environments are managed using a @dfn{stack},
-a data structure supporting ``push'' and ``pop''
-operations.  The current environment is at the top of the
-stack.@footnote{In a stack as strictly defined, only the ``top''
-item---the one most recently pushed---is accessible.  In @code{roff}
-systems, switching to an environment with an existing name moves it from
-its place in the stack to the top.  Further, when environments are
-popped, they are not lost; in fact, there is no mechanism for deleting
-environments.}
+current at any given time.  Active environments are managed using a
+@dfn{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
+@code{pev} request; see @ref{Debugging}.
 
 Environments store the following information.
 
@@ -14708,6 +14711,7 @@ input traps
 @item
 stroke and fill colors
 @end itemize
+@c END Keep parallel with section "Environments" of groff(7).
 
 @DefreqList {ev, [@Var{ident}]}
 @DefregListEndx {.ev}
diff --git a/man/groff.7.man b/man/groff.7.man
index 0ecf3e7d..79717130 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5686,6 +5686,114 @@ with its corresponding amount of motion
 .
 .
 .\" ====================================================================
+.SH Environments
+.\" ====================================================================
+.
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Environments".
+Environments store most of the parameters that control text processing.
+.
+A default environment named
+.RB \[lq] 0 \[rq]
+exists when
+.I @g@troff
+starts up;
+it is modified by formatting-related requests and escape sequences.
+.
+.
+.P
+You can create new environments and switch among them.
+.
+Only one is current at any given time.
+.
+Active environments are managed using a
+.I stack,
+a data structure supporting \[lq]push\[rq] and \[lq]pop\[rq] 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.
+.
+.
+.P
+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
+.B pev
+request;
+see section \[lq]Debugging\[rq] below.
+.
+.
+.P
+Environments store the following information.
+.
+.
+.IP \[bu] 2n
+typeface parameters
+(size,
+family,
+style,
+glyph height and slant,
+inter-word and inter-sentence space sizes)
+.
+.
+.IP \[bu]
+page parameters
+(line length,
+title length,
+vertical spacing,
+line
+spacing,
+indentation,
+line numbering,
+centering,
+right-justifying,
+underlining,
+hyphenation data)
+.
+.
+.IP \[bu]
+filling enablement,
+adjustment enablement and mode
+.
+.
+.IP \[bu]
+tab stops; tab and leader characters; escape,
+control,
+no-break control,
+hyphenation control,
+and margin characters
+.
+.
+.IP \[bu]
+partially collected lines
+.
+.
+.IP \[bu]
+input traps
+.
+.
+.IP \[bu]
+stroke and fill colors
+.
+.
+.P
+The
+.B ev
+request pushes to and pops from the environment stack,
+while
+.B evc
+copies a named environment's contents to the current one.
+.\" END Keep (roughly) parallel with groff.texi node "Environments".
+.
+.
+.\" ====================================================================
 .SH Underlining
 .\" ====================================================================
 .