[bug #62036] [PATCH] Document how environments are initialized

[G. Branden Robinson]

Follow-up Comment #12, bug #62036 (project groff):


[comment #11 comment #11:]
> I had been screwing around with the code in env.cpp because it annoyed me
that the existence of `env_stack` (technically, the non-nullity of it, a
pointer)

..."was not an invariant" is how I wanted to end that sentence.

Anyway, after my trip through Wonderland, simply deleting the long footnote in
the paragraph previous to my additions seems to suffice.

Here's a new patch for your consideration.


diff --git a/doc/groff.texi b/doc/groff.texi
index b71fe16dd..5d2622462 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14670,22 +14670,26 @@ 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.
+
+Strictly, @emph{names} of environments are what is stacked.  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.
 
 @itemize @bullet
 @item
-font parameters (size, family, style, glyph height and slant, inter-word
-and and inter-sentence space sizes)
+typeface parameters (size, family, style, glyph height and slant,
+inter-word and inter-sentence space sizes)
 
 @item
 page parameters (line length, title length, vertical spacing, line


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?62036>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/