[bug #55060] [me] behavior of .ll does not match documentation

[G. Branden Robinson]

Follow-up Comment #8, bug #55060 (project groff):


[comment #6 comment #6:]
> [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.

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.

    _______________________________________________________

Reply to this item at:

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

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