Follow-up Comment #6, bug #55060 (project groff): [comment #5 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. _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?55060> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/