comment #8:

> comment #6:
> > But meref.me would need a larger overhaul to address this,
>
> Can we treat this as a fresh bug?

Freshly filed in bug #61055.

comment #6:

> comment #5:
> > I think it's easiest just to call this a documentation issue
>
> I agree with this, and on further thought, I believe the problem is that the -Me Reference Manual describes .xl/.ll in terms of "environments" when it never defines this term or explains how -me uses them.
>
> Looking at this through a historical lens, where there were exactly three environments and -me claimed them for its own use, what the problematic sentence is trying to communicate is that .xl changes the line length only for running text while .ll changes it globally.  Using the word "environments" here requires the reader to have some knowledge of (a) the troff concept of environments, and (b) how the macro set uses them internally.
>
> (Regarding (a): the manual's opening paragraph tells what general troff knowledge it presumes: "the reader should understand breaks, fonts, point sizes, the use and definition of number registers and strings, how to define macros, and scaling factors for ens, points, v's (vertical line spaces), etc."  So knowledge of environments is explicitly not expected of the reader, making the -Me Reference Manual's one passing reference to them inappropriate.
>
> Further, the manual's index includes, in addition to all the macros -me defines, "selected troff requests," and further states, "those listed can generally be used with impunity."  The .ev request is not listed, suggesting the user should avoid it in (classical) -me documents -- which is in line with -me's internal usage of these (limited number of) environments.
>
> Regarding (b): maybe this was a fair assumption to make of readers in 1985; it isn't today.)
>
> So what the manual should do is define .xl and .ll in terms of their effect, not their implementation mechanism.  Remove mention of environments from their descriptions, and the whole discussion in this bug report about whether and how .ll should affect arbitrary created-on-the-fly environments becomes moot.
>
> That is, .ll changes the line length in running text, headers, and footers; .xl affects only running text.
>
> Today, because groff expands the number of environments from three to infinity, perhaps -me users have the freedom to define and use their own environments without colliding with those -me uses internally.  But meref.me would need a larger overhaul to address this, and I don't think that's necessary or appropriate to resolve this bug.  The fix for this bug should be to stop explaining -me behavior in terms of undocumented implementation details.

Can we treat this as a fresh bug?  Its scope is much greater, and it's going to take more effort--a more probing revision of the document--to resolve.

comment #5:

> I think it's easiest just to call this a documentation issue

I agree with this, and on further thought, I believe the problem is that the -Me Reference Manual describes .xl/.ll in terms of "environments" when it never defines this term or explains how -me uses them.

Looking at this through a historical lens, where there were exactly three environments and -me claimed them for its own use, what the problematic sentence is trying to communicate is that .xl changes the line length only for running text while .ll changes it globally.  Using the word "environments" here requires the reader to have some knowledge of (a) the troff concept of environments, and (b) how the macro set uses them internally.

(Regarding (a): the manual's opening paragraph tells what general troff knowledge it presumes: "the reader should understand breaks, fonts, point sizes, the use and definition of number registers and strings, how to define macros, and scaling factors for ens, points, v's (vertical line spaces), etc."  So knowledge of environments is explicitly not expected of the reader, making the -Me Reference Manual's one passing reference to them inappropriate.

Further, the manual's index includes, in addition to all the macros -me defines, "selected troff requests," and further states, "those listed can generally be used with impunity."  The .ev request is not listed, suggesting the user should avoid it in (classical) -me documents -- which is in line with -me's internal usage of these (limited number of) environments.

Regarding (b): maybe this was a fair assumption to make of readers in 1985; it isn't today.)

So what the manual should do is define .xl and .ll in terms of their effect, not their implementation mechanism.  Remove mention of environments from their descriptions, and the whole discussion in this bug report about whether and how .ll should affect arbitrary created-on-the-fly environments becomes moot.

That is, .ll changes the line length in running text, headers, and footers; .xl affects only running text.

Today, because groff expands the number of environments from three to infinity, perhaps -me users have the freedom to define and use their own environments without colliding with those -me uses internally.  But meref.me would need a larger overhaul to address this, and I don't think that's necessary or appropriate to resolve this bug.  The fix for this bug should be to stop explaining -me behavior in terms of undocumented implementation details.

comment #3:

> I think the "translation" of the meaning of line length in 'me'
> files or the macro package,
> did not succeed in the statement "global to environments".

OK.  That statement appears in -me's source code comments, not in the documentation, so I think it's OK.  -me comments are generally terse.  Still, this comment was written at a time when "environments" meant exactly three, not an arbitrarily large number, so an extra couple words of clarification wouldn't hurt (e.g., "global to the 3 classical roff environments").

> the register '$l' can be used in all environments once set.
>
> The register '.l' is an environmental register.

Good advice.  If the resolution of this bug ends up being to change the documentation, this could be mentioned.

> There is a translation error in the manual ("meref.me").

I don't know what this means.  I'm reading meref.me in its original language, English.  I have no evidence it has ever been translated out of and then back into English.  Do you mean "transcription error"?  If so, from what source was the passage in question transcribed, and what is the error that was introduced?

> Get the documentation for troff, "Troff User's Manual", on paper.

I have this document in PDF form.  What would a paper version reveal that I can't see on-screen?

It's also not clear what this manual has to do with the current bug report: the manual documents raw troff, and the bug I'm reporting concerns a macro package.  Can you be more specific about what you think I should be looking at in this manual?

> How does the macro ".ll" influence the line length
> in a new environment (it is issued outside it)?

It doesn't, which is what this bug is reporting.  But if you mean how could it, that's an interesting question that has been discussed on the mailing list, in the post I linked to directly below, and in other posts linked to from there.  Please see the email threads for a fuller answer, but briefly, note that (a) meref.me was originally written when only three environments were available in troff, and this part of meref.me is unchanged since at least 1988; (b) if we decide to change the code to match the documentation, this would almost certainly entail having -me define its own .ev macro (to replace the low-level groff request) that sets line length appropriately upon environment creation.

doc/meref.me describes the macro .ll as "Set line length in all environments."  This is not what it does:

groff -me -a <<EOF
.ll 2i
The quick brown fox
jumped over a quick brown fox which
jumped over a quick brown fox which
.ev foo
jumped over a quick brown fox which
jumped over a quick brown fox which
jumped over a quick brown fox which
jumped over a quick brown fox which
.ev
jumped over a quick brown fox which...
EOF

This has been discussed a couple times over the years on the groff email list.  The last post on the topic was mine, which left unresolved questions:

http://lists.gnu.org/archive/html/groff/2013-09/msg00025.html

No clear solution has emerged from these discussions, and I have no further input; I'm just creating this bug report so the issue doesn't get forgotten.