bugGNU roff - Bugs: bug #55060, [me] behavior of .ll does not...

 
 

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

Submitter:  Dave <barx>
Submitted:  Mon 19 Nov 2018 11:25:30 PM UTC
   
 
Category:  Macro me Severity:  3 - Normal
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

Sun 25 Jun 2023 01:39:37 AM UTC, comment #13: 

For the archaeologists, this bug was first reported in http://lists.gnu.org/r/bug-groff/2011-05/msg00003.html

Dave <barx>
Group Member
Wed 18 Aug 2021 01:07:54 PM UTC, comment #12: 

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.

Dave <barx>
Group Member
Wed 18 Aug 2021 10:37:00 AM UTC, comment #11: 

comment #10:

> I certainly don't mind restoring meref.me readers' innocence
> of the "environment" concept


It's less "restoring" it than it is initiating it, since the .xl and .ll descriptions under discussion predate groff.  But even in the -Me Reference Manual of yore, this explanation was somewhat misplaced, since it was meaningful only if you knew how the code used troff environments.

> But that will require a more considered rewrite than the
> band-aid of commit a61cd74ad38b7948f63784ae1373e572fcf12292.


OK, I've opened bug #61054 for this.  (This seemed cleaner than reopening this one, as the problem originally reported in this bug is fixed now.)

Dave <barx>
Group Member
Mon 16 Aug 2021 06:54:37 PM UTC, comment #10: 

Hi, Dave!

comment #9:

> comment #8:
> > Can we treat this as a fresh bug?  Its scope is much greater,
>
> Yes, that was my intent with that sentence, for that very reason.  Sorry if that was unclear.


No worries!

> The committed change disregards the recommendation in comment #6 and continues defining .xl and .ll in terms of environments (a troff concept meref.me neither defines nor expects the user to know) rather than in terms of their effects on the output.  The explanation is at least correct now, but I'm wondering what the rationale is for retaining that terminology.


The only reason for the disregard was that I already had the patch written by that point and had moved on to other tasks.  (I push in batches...my working tree and branch go through much churn between pushes, with copious interactive rebases and use of the git stash.)

I certainly don't mind restoring meref.me readers' innocence of the "environment" concept, especially since as a term it collides with other uses in operating system contexts.

But that will require a more considered rewrite than the band-aid of commit a61cd74ad38b7948f63784ae1373e572fcf12292.

G. Branden Robinson <gbranden>
Group administrator
Sun 15 Aug 2021 02:00:27 AM UTC, comment #9: 

comment #8:

> Can we treat this as a fresh bug?  Its scope is much greater,


Yes, that was my intent with that sentence, for that very reason.  Sorry if that was unclear.

The committed change disregards the recommendation in comment #6 and continues defining .xl and .ll in terms of environments (a troff concept meref.me neither defines nor expects the user to know) rather than in terms of their effects on the output.  The explanation is at least correct now, but I'm wondering what the rationale is for retaining that terminology.

Dave <barx>
Group Member
Fri 13 Aug 2021 03:22:02 PM UTC, comment #8: 


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.

G. Branden Robinson <gbranden>
Group administrator
Fri 13 Aug 2021 02:09:26 PM UTC, comment #7: 


commit a61cd74ad38b7948f63784ae1373e572fcf12292
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Aug 13 10:22:43 2021 +1000

    [me]: Clarify breadth of application of `ll` macro.

    * doc/meref.me: Document application of .ll macro only to the 3
      environments that me(7) uses, not any the user might create.
    * tmac/e.tmac (@C, xl, ll): Update comments.

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


G. Branden Robinson <gbranden>
Group administrator
Fri 13 Aug 2021 03:26:51 AM UTC, 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.

Dave <barx>
Group Member
Thu 12 Aug 2021 11:51:01 PM UTC, comment #5: 

I think it's easiest just to call this a documentation issue, in code comments and meref.me.

I'm updating the wording accordingly.  me(7) users can create their own named environments if they choose, and can use .evc to copy from a desired one to get the "global" line length instead of assuming that this will happen by some other means.

G. Branden Robinson <gbranden>
Group administrator
Mon 25 Jan 2021 01:17:23 PM UTC, comment #4: 

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.

Dave <barx>
Group Member
Fri 25 Dec 2020 02:52:06 PM UTC, comment #3: 

  I do not remember exactly what I meant,
but 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".

  The line length in me-files is '$l' not '.l'.

  The register '$l' is thus global to all environments, but each
environment must set its own line length if it differs from the default
'.l' value.

  Or

the register '$l' can be used in all environments once set.

The register '.l' is an environmental register.

Bjarni Ingi Gislason <bjarniig>
Sun 25 Nov 2018 02:00:59 AM UTC, comment #2: 


> 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.

Dave <barx>
Group Member
Tue 20 Nov 2018 11:05:26 PM UTC, comment #1: 

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

  The file "e.tmac-e" shows:

.rn ll xl \" * special line length (local)
.de ll \" * line length (global to environments)

  Get the documentation for troff, "Troff User's Manual", on paper.
The path to the PostScript file is found under "CSTR #54" in the
manuals "groff(7)", "groff_diff(7)", and "groff_out(5)".

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

Bjarni Ingi Gislason <bjarniig>
Mon 19 Nov 2018 11:25:30 PM UTC, original submission:  

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.

Dave <barx>
Group Member

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

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 bjarniig (Posted a comment)
  • -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 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-08-13 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2021-08-12 gbranden Item GroupIncorrect behaviour Documentation
        StatusNone In Progress
        Assigned toNone gbranden
    2021-06-04 barx Summaryme: behavior of .ll does not match documentation [me] behavior of .ll does not match documentation
    2020-07-25 gbranden CategoryMacro - others/general Macro me

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code