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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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

Attachment: OpenPGP_signature
Description: OpenPGP digital signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux