bugGNU roff - Bugs: bug #62036, [PATCH] Document how environments...

 
 

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

Submitter:  Dave <barx>
Submitted:  Sat 12 Feb 2022 03:13:18 AM UTC
   
 
Category:  Core Severity:  1 - Wish
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Fri 18 Mar 2022 04:47:15 AM UTC, comment #15: 


commit 971f0055267aaa016a7593cd2274b3c7d5b8ead8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   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>.


G. Branden Robinson <gbranden>
Group administrator
Tue 15 Mar 2022 10:54:32 PM UTC, comment #14: 


comment #13:

> Yes, after following along on your side trip that contained more plot twists than a Christopher Nolan film, I think the text from comment #12 captures everything accurately and succinctly.


Thanks, Dave!  I'll proceed, and use this material to populate an "Environments" section in groff(7) as well.

> For completeness, I'll record here that remedying "Environments cannot be renamed or deleted" is the subject of bug #60954.


I started cogitating on this after my exploration of env.cpp last night and wrote something up, then it occurred to me that the material is better placed at the ticket you just cited.  See you there.  :)

G. Branden Robinson <gbranden>
Group administrator
Tue 15 Mar 2022 05:38:20 PM UTC, comment #13: 

Yes, after following along on your side trip that contained more plot twists than a Christopher Nolan film, I think the text from comment #12 captures everything accurately and succinctly.

For completeness, I'll record here that remedying "Environments cannot be renamed or deleted" is the subject of bug #60954.

Dave <barx>
Group Member
Tue 15 Mar 2022 01:15:17 PM UTC, comment #12: 


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


G. Branden Robinson <gbranden>
Group administrator
Tue 15 Mar 2022 01:07:49 PM UTC, comment #11: 


comment #10:

> comment #9:
> > Maybe label them with the adjustment mode...wait, except there's no .j in V7 *roff, either.
>
> That's wrong. .j is there.  Enough environments to play Towers of Hanoi suffices to reveal stack behavior.
>
> And the news is bad.  New bug forthcoming.


Double false alarm.  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).  I got started refactoring, ran into a problem, reverted my changes...

...but forgot to rebuild.

G. Branden Robinson <gbranden>
Group administrator
Tue 15 Mar 2022 12:58:13 PM UTC, comment #10: 

comment #9:

> Maybe label them with the adjustment mode...wait, except there's no .j in V7 *roff, either.


That's wrong. .j is there.  Enough environments to play Towers of Hanoi suffices to reveal stack behavior.

And the news is bad.  New bug forthcoming.

G. Branden Robinson <gbranden>
Group administrator
Tue 15 Mar 2022 12:48:03 PM UTC, comment #9: 

It appears we may have a problem.

If we add the line ".cp 0" to the top of the document in comment #8, we can then run it through Heirloom Doctools troff.


$ ./heirloom/bin/nroff src/GIT/groff/EXPERIMENTS/stack-pusher.groff
4=4
2=2
3=3
2=2
1=1
0=0


That appears to be the behavior you were describing, Dave.

This seems faintly ominous for groff, but I'll check V7 nroff just to be sure.  (Of course, there we have only 3 environments, and no .ev register to disclose their names, but I'll come up with something.  Maybe label them with the adjustment mode...wait, except there's no .j in V7 *roff, either.  Hmmm.)

G. Branden Robinson <gbranden>
Group administrator
Tue 15 Mar 2022 12:24:18 PM UTC, comment #8: 


> And the footnote as written in this attachment isn't entirely accurate, saying "switching to an environment with an existing name moves it from its place in the stack to the top."  The word "moves" indicates that it's removed from its position in the stack, which is not the case.  An environment can be in the stack multiple times, even adjacently.


This does not appear to be true.


$ cat EXPERIMENTS/stack-pusher.groff
.ev 1
.ev 2
.ev 3
.ev 2
.ev 4
.tm 4=\n[.ev]
.ev
.tm 2=\n[.ev]
.ev
.tm 3=\n[.ev]
.ev
.tm 2=\n[.ev]
.ev
.tm 1=\n[.ev]
.ev
.tm 0=\n[.ev]
.ev
$ ./build/test-groff -b -ww -Tutf8 EXPERIMENTS/stack-pusher.groff
4=4
2=3
3=2
2=1
1=0
0=0
troff: backtrace: file 'EXPERIMENTS/stack-pusher.groff':17
troff:EXPERIMENTS/stack-pusher.groff:17: error: environment stack underflow


G. Branden Robinson <gbranden>
Group administrator
Tue 15 Mar 2022 10:35:28 AM UTC, comment #7: 

Whoops, disregard, I forgot to edit the paragraph before my additions, which contains multiple claims you (rightly) objected to.

G. Branden Robinson <gbranden>
Group administrator
Tue 15 Mar 2022 10:26:13 AM UTC, comment #6: 

Hi Dave,

What do you think of this?


diff --git a/doc/groff.texi b/doc/groff.texi
index b71fe16dd..3f7029ef5 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14680,12 +14680,22 @@ 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.}

+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


G. Branden Robinson <gbranden>
Group administrator
Fri 25 Feb 2022 01:41:21 PM UTC, comment #5: 

The patch attached to comment #1 (now live as commit 3671aaa6) also contains a repeated word:

+font parameters (size, family, style, glyph height and slant, inter-word
+and and inter-sentence space sizes)


Dave <barx>
Group Member
Mon 14 Feb 2022 06:53:52 AM UTC, comment #4: 

Still in progress, however...


commit 32727130384ffbf60b3f8dfd3805a1759c97d316
Author: Dave Kemper <saint.snit@gmail.com>
Date:   Sat Feb 12 03:13:18 2022 +0000

    doc/groff.texi: Fix content nits.

    * (Tabs and Fields): Add cross reference to "Environments" node.
    * (Environments): Describe how a new environment is initialized.

    Fixes initial issue reported in <https://savannah.gnu.org/bugs/?62036>.


...the foregoing has been pushed.

G. Branden Robinson <gbranden>
Group administrator
Sun 13 Feb 2022 08:18:55 AM UTC, comment #3: 

These are excellent points.  :-O

I'm going to rescope this ticket to include your comment #2 before resolving it.  It's been about a week since I pushed, so I want to go ahead and do one, but addressing the issues you've raised here is going to demand some thought.

G. Branden Robinson <gbranden>
Group administrator
Sun 13 Feb 2022 06:18:23 AM UTC, comment #2: 

comment #1:

> We had revisions that passed like ships in the night;


I did notice that the .ev section hadn't yet been Brandenified, but since I didn't know when in your Texinfo slog it might get hit, I thought it was worth supplying some missing information in the meantime.

> see attachment.


I realize this is a work in progress, but I wonder if the new text would be clearer by more strongly differentiating between active environments, which do operate as a stack, and the pool of defined environments, which are indexed by identifier.  That is, saying "The current environment is at the top of the stack" is true, but maybe "The current environment is at the top of the active-environment stack" wouldn't then need to be partially walked back in a footnote.

And the footnote as written in this attachment isn't entirely accurate, saying "switching to an environment with an existing name moves it from its place in the stack to the top."  The word "moves" indicates that it's removed from its position in the stack, which is not the case.  An environment can be in the stack multiple times, even adjacently.

For that matter, the stack doesn't contain environments so much as environment identifiers.  That is, if an environment is in multiple places in the stack, and you switch to it and change some of its parameters, you're changing them throughout the stack.  If the stack contained environments themselves, they should be immune to change until at the top.  But the stack is just of their names.

It's a little confusing because the .ev request is always a push operation but only sometimes a create operation.

> After applying, I plan to migrate us to "startup";


That's actually what I originally wrote in my modification, but changed it after checking the rest of the manual's usage. #PointlessTrivia

Dave <barx>
Group Member
Sat 12 Feb 2022 09:26:25 AM UTC, comment #1: 

Hi Dave!

We had revisions that passed like ships in the night; see attachment.  I'll hand-apply yours.  Thanks for catching the inconsistency stragglers.

After applying, I plan to migrate us to "startup"; seeing the hyphen always jars me, and we don't generally say "shut-down", but "shutdown".

(file #52847)

G. Branden Robinson <gbranden>
Group administrator
Sat 12 Feb 2022 03:13:18 AM UTC, original submission:  

Classical troff lacked the ability to create new environments.  Three were established at the outset, and CSTR #54 explicitly stated, "All environments are initialized with default parameter values."

Groff starts up with only one environment ("0"), but users can create an unlimited number of environments as needed.  However, its documentation fails to mention how environments are populated upon creation.

The attached patch remedies this.  It says the environment "is created using GNU troff's start-up defaults for all environment-specific parameters," which appears to be accurate for the cases I tested.  But if there are other cases where this is not accurate, let me know and I'll adjust this wording.

Other notes


The overall manual inconsistently uses both "start-up" (23 instances) and "startup" (3 instances), whether in noun or adjective context.  I went with the majority spelling in this patch.  American Heritage Dictionary says both are valid (http://ahdictionary.com/word/search.html?q=startup).

Everywhere the manual says something "is associated with the environment," this is followed by "(@pxref{Environments})."  This was missing in one place; as a bonus fix, the patch corrects this.

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #52847:  branden-environment.diff added by gbranden (8KiB - text/x-patch)
file #52846:  62036.patch added by barx (1KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-03-18 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2022-02-12 gbranden Attached File- Added branden-environment.diff, #52847
        StatusNone In Progress
        Assigned toNone gbranden
    2022-02-12 barx Attached File- Added 62036.patch, #52846

    Back to the top

    Powered by Savane 3.13-bb6a.
    Corresponding source code