Re: Unexpected behaviour when using linenumbering and tbl

[G. Branden Robinson]

Hi Hans,

At 2022-11-24T19:47:35+0100, hbezemer--- via wrote:
> When I make exams I sometimes use linenumbering so I can refer to a
> specific line of a source.  I noticed some unexpected behaviour when
> having a table after the part that has linenumbers.  The table also
> gets linenumbers added, which should not be the case of course.  I can
> reproduce the behaviour with the example below.

Tadziu was swift to the rescue with good advice, so I'll cover the
broader issue.

I think the formatter's line numbering feature and the tbl preprocessor
interact in unexpected ways, and apparently always have.

First let me offer an example input and then I will show how it behaves
with Unix Version 7 troff (1979), Heirloom Doctools troff (2019), groff
1.22.4 (2018) and groff Git HEAD.

$ cat ~/tmp/line-numbered-table.roff
.nm 1
Here is a line of output.
Sic transit adispicing meatballs.
Let's pad it out with more content to ensure the line breaks.
.TS
L.
This is my table.
There are many like it but this one is mine.
T{
My table is my best exhibit;
I will guard it as I guard my life.
Even as it requires multiple output lines for an entry.
T}
.TE
What is the line number now?

Unix Version 7 on a SIMH PDP-11/45:

  1 Here is a line of  output.   Sic  transit  adispicing  meatballs.
  2 Let's pad it out with more content to ensure the line breaks.
  6 This is my table.
  7 There are many like it but this one is mine.
  8
  9   3 My table is my best exhibit; I will guard it
 10   4 as  I  guard  my  life.  Even as it requires
 11   5 multiple output lines for an entry.
 12 What is the line number now?

Heirloom Doctools troff:

  1 Here is a line of  output.   Sic  transit  adispicing  meatballs.
  2 Let's pad it out with more content to ensure the line breaks.
  6 This is my table.
  7 There are many like it but this one is mine.
  8
  9   3 My table is my best exhibit; I will guard it
 10   4 as  I  guard  my  life.  Even as it requires
 11   5 multiple output lines for an entry.
 12 What is the line number now?

groff 1.22.4:

  1 Here  is  a  line  of  output.  Sic transit adispicing meatballs.
  2 Let’s pad it out with more content to ensure the line breaks.
  6 This is my table.
  7 There are many like it but this one is mine.
  8   3 My table is my best exhibit; I will guard it
  9   4 as  I  guard  my  life.  Even as it requires
 10   5 multiple output lines for an entry.
What is the line number now?

groff Git HEAD:

  1 Here  is  a  line  of  output.  Sic transit adispicing meatballs.
  2 Let’s pad it out with more content to ensure the line breaks.
This is my table.
There are many like it but this one is mine.
  3 My table is my best exhibit; I will guard it
  4 as I guard my life.   Even  as  it  requires
  5 multiple output lines for an entry.
What is the line number now?

Observations:

1.  I think the original behavior may have been considered buggy at
    Murray Hill.  I checked the entire corpus of Version 7's _Unix
    Programmer's Manual_, Volume 2, and could not find a single place
    where line numbering and tbl(1) tables were combined.  (I did this
    by scanning the pages visually and by grepping for `TS` calls and
    `nm` invocations.)

2.  Heirloom Doctools troff seems quite faithful to its lineal ancestors
    of Ossanna troff and Lesk tbl.  Good!  That's less time I have to
    spend dealing with the painful Unix V7 TTY driver and the Spartan
    original Bourne shell.

3.  Nevertheless these golden masters behave quite perversely when you
    set a text block in a table entry.  You get two sets of line
    numbers.  This is so perverse that I have to regard it as a bug.
    Anyone care to argue?

4.  Also, the line numbers of the text block are counted before any
    preceding lines of the table, so the line numbers are not even
    monotonically increasing, let alone strictly increasing.  I find
    this incredibly dubious and hereby dare Ralph Corderoy to defend its
    correctness.

5.  AT&T/Heirloom troff/tbl also seems to add unasked-for vertical space
    prior to the start of the table.  groff doesn't, and I don't think
    it should.  I looked briefly at the tbl output on Unix V7, but not
    long enough to see if this was a hack in nroff mode to avoid
    overprinting other output when tables were boxed.  groff's
    implementation has had headaches with this too; see
    <https://savannah.gnu.org/bugs/?62471>.

6.  groff has an apparently long-standing bug where the state of output
    line numbering does not get properly restored after a table region.
    That just ain't right and should be fixed.

7.  groff Git shuts off line numbering when beginning a table.  I think
    this is what people want most of the time, so I propose to retain it
    as the default.  But I should probably document it in NEWS.

    Also see <https://savannah.gnu.org/bugs/?59812>.

8.  However my fix for Savannah #59812 was not complete.  I didn't
    suppress line numbering in the diversion/environment used to format
    text blocks.  We see above that it rises from the grave.  We don't
    get double numbering like old-school troff but it's still likely a
    shock to users unaccustomed to the old system.

9.  Another aspect of my incomplete fix was, I think, introducing only
    an .nm register.  I probably should have introduced one for .nn as
    well.  (This Ossanna troff request suspends line numbering for the
    next N lines, default 1. )  I'm thinking what I want to do is save
    the states of _both_ of these when a table begins, and restore them
    at the table's end, so that the lines of the table, even text
    blocks, effectively don't count for incrementation or suspension
    purposes.

10. What if someone _wants_ numbered table lines?  Or wants to number
    certain regions of the table?  This should be possible; I think I
    have seen some standards documents maintain numbering even in
    tabular contexts.  In that event they should be able to use `nm` and
    `nn` requests between table rows just as they can invoke other
    requests.  These requests should also work within text blocks.  I
    propose however that any such requests not override the post-table
    restoration of line numbering and numbering suspension states.  The
    user can also assign arbitrary values to the `nl` register.  That's
    a little trickier.  I propose that, when starting a table region,
    the line number `nl` be remembered by tbl, and if it has been
    changed by the user during the course of the table, we _don't_
    restore it.  If it hasn't, we do, so that line numbering "picks up
    where it left off".

11. If all that is too hard, a better approach might be to simply warn
    that tables get their lines numbered if numbering was on when they
    started.  But the double-numbering of text block lines should be
    fixed in any case.

12. Another possibility is to have a new region option (like "box" or
    "center"), perhaps called "numbering", which retains line numbering.
    A variant of this would be to add "nonumbering" and flip the default
    for slavish AT&T compatibility.

Because there are several changes here, and some are AT&T-incompatible,
I propose to proceed in the following order.

A. Implement the `.nn` register.  This should be a piece of observable
   state in the formatter, and it isn't (cf. \n[.ce], \n[.hlc],
   \n[.rj]).

B. Fix the text block numbering bug by forcing line numbering off when
   starting a text block diversion.

C. Update tbl(1) to advise the user about line numbering and tell them
   how to defeat it.  (Save `nl` and do ".nm" before the table, then
   ".nm \n[saved-register]" afterward.)

D. See what folks on this list think about my more radical ideas.

Thoughts?

Regards,
Branden

signature.asc
Description: PGP signature