bug in new curs_inopts(3x) table

[G. Branden Robinson]

[CCing Ingo to confirm resolution of mandoc 1.14.6 bug]

Hi Thomas,

Documenter's Workbench 3.3 tbl throws diagnostics and truncates the
curs_inopts(3x) page upon encountering its new table.

$ DWBHOME=. ./bin/tbl /tmp/branden/curs_inopts.3x.orig | less
File /tmp/branden/curs_inopts.3x.orig, line 306: Tried to widen table after 
first row
tbl quits

Other implementations that are close to AT&T tbl will, I expect, have
the same problem.  GNU tbl, Heirloom Doctools tbl, and mandoc are all
fine with it.  They do not complain even though the table format syntax
might be suspect.  (GNU tbl "rectangularizes" the shape of the table
after reading its format, and my understanding of Lesk's original tbl
paper is that AT&T tbl did too.  Maybe a bug, or maybe I misunderstand.)

Here is a patch.

--- /tmp/branden/curs_inopts.3x.orig    2023-08-13 07:59:40.964704089 -0500
+++ /tmp/branden/curs_inopts.3x 2023-08-13 08:00:13.624651014 -0500
@@ -302,10 +302,9 @@
 This implementation provides four functions which may be used to detect
 if the corresponding flags were set or reset:
 .TS
-l l l
-_ _ _ _
-l l l .
+l l l.
 \fBQuery\fP    \fBSet\fP       \fBReset\fP
+_
 is_cbreak      cbreak  nocbreak
 is_echo        echo    noecho
 is_nl  nl      nonl

Your table format is uniformly three columns, so it can be simplified as
shown.  And when you want to draw a rule across a table, you can do that
at any point after the format definition, in other words amid the rows
of entries.

GNU tbl(1) says:

   Column classifiers
     The L, R, and C classifiers are the easiest to understand and use.
[...]
     _, -  Replace table entry with a horizontal rule.  An empty table
           entry is expected to correspond to this classifier; if data
           are found there, tbl issues a diagnostic message.
[...]
   Table data
[...]
     Several forms of table entry are interpreted specially.

     •  If a table row contains only an underscore or equals sign (_ or
        =), a single or double horizontal rule (line), respectively, is
        drawn across the table at that point.

Usually, it seems, people want the latter application of '_', not the
former.

Also, if you are expecting a blank line before the table, Heirloom
Doctools troff/man and groff do not produce one.[1]  mandoc 1.14.6 (and
probably older versions) do, but this is expected to change in the next
release.[2]

Finally, purely as an esthetic point, I think the table would look
better if indented.  I would put it in a relative inset with `RS`/`RE`.

So an omnibus patch to do all of the above is as follows.

--- /tmp/branden/curs_inopts.3x.orig    2023-08-13 07:59:40.964704089 -0500
+++ /tmp/branden/curs_inopts.3x 2023-08-13 08:21:44.463722022 -0500
@@ -301,16 +301,18 @@
 .SH EXTENSIONS
 This implementation provides four functions which may be used to detect
 if the corresponding flags were set or reset:
+.PP
+.RS
 .TS
-l l l
-_ _ _ _
-l l l .
+l l l.
 \fBQuery\fP    \fBSet\fP       \fBReset\fP
+_
 is_cbreak      cbreak  nocbreak
 is_echo        echo    noecho
 is_nl  nl      nonl
 is_raw raw     noraw
 .TE
+.RE
 .PP
 In each case, the function returns
 .TP 5

Full disclosure: mandoc 1.14.6 puts _two_ blank lines before the table
in my patched version.  I suppose the combination of `PP` with the
relative inset confuses it.  I believe this is incorrect behavior, and
may already be fixed in mandoc CVS, but I am attaching my altered
version of the page and CCing mandoc maintainer Ingo Schwarze so he can
confirm.

DWB 3.3, Heirloom Doctools, and groff all render my altered version of
the page correctly.

N.B. I do not recommend DWB 3.3 as a daily driver.  Its value lies in
its status as an exemplar of AT&T device-independent troff.  As far as I
know it is representative of the troff on all Unix System V
installations, excepting any that switched to groff (as Solaris 11 did).

Regards,
Branden

[1] The details are somewhat complex.  For me, groff 1.22.4 doesn't, but
    it "should have", per a commit in 2002.  It nevertheless does not--I
    am guessing due to other bugs in groff man(7) and tbl(1).  For groff
    1.23.0 and the foreseeable future, `TS` and `TE` calls will _not_
    put vertical space on the output.

    https://savannah.gnu.org/bugs/?62841

    Once the table format is fixed per the above, DWB 3.3 nroff/man
    doesn't put a blank line on the output either, so I believe this to
    be authentic behavior.  Let me know if a data point from Unix
    Version 7 would help, and I'll fire up the simulator.  I know you
    want your man pages to be portable, but I don't know if you support
    ncurses on Unix Version 7.

[2] https://marc.info/?l=mandoc-source&m=166168038326866

curs_inopts.3x
Description: Text document

signature.asc
Description: PGP signature