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

[Alejandro Colomar]

Hi Branden,

On 12/17/22 17:08, G. Branden Robinson wrote:
> 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/

:D

BTW, how is the status of 1.23.0?  How many RC bugs are there?  Are they growing 
faster than they are eaten by birds?  :P

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

BTW, I've seen in groff really bad cases of broken indentation where some lines 
use tabs, others use spaces, and others use a mix.  What's the coding style 
regarding tabs in groff source code?  I want to know in case I send a patch some 
day.

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

Yep.  Probably I'll do that; but (probably) not soon.

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

But if the intro(*) page references _everything_, then it would be a huge page 
(there are thousands of pages in the Linux man-pages).  Although, in the PDF, 
I'd like to have an index.  That might help.

> Unofficial patch attached.

Do you like the patch?  Should I apply it, or is it just a draft?

> Regards,
> Branden

Cheers,

Alex

--
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature