Radical reforms to line-numbered tables (was: Unexpected behaviour when using linenumbering and tbl)

[G. Branden Robinson]

I have an update on this.

At 2022-11-25T02:33:57-0600, G. Branden Robinson wrote:
> 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.
[...]
> 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

I added a "box;" region option to this; the result is shown below.

I do not recommend doing that on Unix Version 7 or Heirloom Doctools
nroff.  You will not be happy.

> 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?
[...]
> 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?

Here's what my working copy produces now.

$ ./build/test-groff -t -Tascii EXPERIMENTS/line-numbered-table.roff \
 | cat -s
  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. |
|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.          |
+---------------------------------------------+
  3 What is the line number now?

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

I have fixed this.

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

I had actually planned NOT to do this right away, by trying to pivot to
a bug-fixed AT&T tbl behavior first, but it turned out to be really easy
to just suppress all line numbering in tables while still correctly
restoring it afterward.  This also enabled me to remove a lot of code
from George Helffrich in 2011 that was complex and defeated all my
efforts to understand it.

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

This no longer happens.

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

I did indeed have to introduce an .nn register.  Also, if we are to
permit line numbering in tables, we're going to need 3 more registers
exposing troff environmental parameters: the increment, suffixed space,
and indentation of line numbering.  These are also not visible in the
groff(7) language present and are not in any other implementation I'm
aware of.  They therefore cannot be saved for restoration and any use of
`.nm` inside a tbl(1) table, whether produced by the preprocessor user,
will clobber them irrevocably.

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

As I noted after item #9, supporting this will mean we need more
interface registers.

>     The user can also assign arbitrary values to the `ln` register.
>     That's a little trickier.  I propose that, when starting a table
>     region, the line number `ln` 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".

I've corrected the above to say `ln`, not `nl`.  Who needs more than 2
characters in an identifier?

Picking up line numbering where it left off is now implemented.

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

Double-numbering is fixed but there is no reason to warn here, unless we
want an inverse warning that groff simply won't number tbl lines.

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

This remains a possibility.

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

Best-laid plans...

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

Done.

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

Done.

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

Not necessary.

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

Feedback still wanted.

See the attached diff for my changes to tbl(1).

Regards,
Branden

unhelffrich.diff
Description: Text Data

signature.asc
Description: PGP signature