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