Re: [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...))

[G. Branden Robinson]

Hi Alex,

At 2022-12-17T14:19:55+0100, Alejandro Colomar wrote:
> Another bug report (but not about the script; this seems to be about
> tbl(1) interaction with gropdf(1), I guess):
> 
> <http://chuzzlewit.co.uk/LinuxManBook.pdf#pdf%3Abm11813>

The suffixes(7) page, which I've managed to never see in 25 years as a
GNU/Linux user!  Ah, well.

Dude, I'm friggin' _trying_ to get groff ready for 1.23.0.rc2 and you
nerd-snipe me with this huge list of things that hasn't been updated in
twenty years and has all kinds of fiddly little things wrong with it--
this of course constitutes an OCD emergency for me!

https://xkcd.com/356/

> Running all the linters I know doesn't trigger any warnings on the
> page source:

That tbl(1) source isn't invalid but it is pretty weird.

I tend to agree that there is a gropdf(1) bug here, as grops(1) handles
the same input fine.  But Deri is the real expert and I will let him
speak to that.

I'm attaching a patch that does three things:

1. Removes the hack to shut up warnings from grotty(1).  This was indeed
   a bug, it's been around forever (possibly since ~1990), and it is
   fixed in groff Git.  Expect that in 1.23.0.  man-db man(1) conceals
   these diagnostic messages anyway.

   https://savannah.gnu.org/bugs/index.php?63449

2. Stops using leading spaces in table entries.  This is a kind of weird
   thing to do.  The likely reason is that the table author(s) had a ton
   of entries that started with dots (the *roff control character) and
   didn't know to prefix them with the *roff dummy character (`\&`) to
   keep them from being interpreted as requests or macro calls.  The
   tbl(1) page in groff 1.23.0 explicitly documents this use (the old
   one seems to have expected the reader to have access to CSTR #49 by
   Lesk).

    Rows of table entries can be interleaved with groff control lines;
    these do not count as table data.  On such lines the default control
    character (.) must be used (and not changed); the no‐break control
    character is not recognized.  To start the first table entry in a
    row with a dot, precede it with the token \&.

3. I added the dummy character even on "continuation" lines where a
   description overran.  This does no damage since the tab character
   remains there as an entry separator and the dummy character by itself
   is harmless as a marker of an empty table entry.  I even recommend
   this in the GNU tbl 1.23.0 man page; it's much nicer for people whose
   text editors don't visibly highlight tabs.

A _more_ idiomatic thing to do would be to use a spanning table
entry `\^` for rows where the description get continued, but that makes
no practical difference for a simple table layout like this one.

More idiomatic still, and well worth considering for the future, is
setting _all_ of these descriptions in text blocks.  This table looks to
me like it was laid out for an 80-column terminal with the excessively
long descriptions manually broken.  This looks suboptimal when typeset
and will look ridiculous on a wide terminal.

Also, use of a text block enables the employment of man(7) macros
instead of font selection escape sequences to change the typeface, and,
importantly for the near Linux man-pages future, use of the new `MR`
macro to cross reference the many pages referred to in these
descriptions.

I didn't pursue further revision along either of these lines because the
as I look at these the entries, the intensity of my urge to do a
top-to-bottom revision fixing the many infelicities and a few outright
errors increases exponentially with time.  There is even at least one
unescaped hyphen!  🤯

Regrettably, if a moderately experienced GNU/Linux user has gone 25
years without seeing this page, likely many others will go 25 more
without seeing it.  A good intro(1) page would cross reference it,
aiding the novice.

Unofficial patch attached.

Regards,
Branden

suffixes.7.diff
Description: Text Data

signature.asc
Description: PGP signature