From: Alejandro Colomar <alx.manpages@gmail.com>
To: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Deri <deri@chuzzlewit.myzen.co.uk>, groff <groff@gnu.org>,
linux-man <linux-man@vger.kernel.org>
Subject: Re: [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...))
Date: Sun, 18 Dec 2022 12:46:59 +0100 [thread overview]
Message-ID: <5439523a-4fd1-e0c7-9116-6fd8c2a65c67@gmail.com> (raw)
In-Reply-To: <20221217160830.rcvgr65axz4hpcge@illithid>
[-- Attachment #1.1: Type: text/plain, Size: 5051 bytes --]
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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2022-12-18 11:47 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20220906191320.447t5awx3rcb5d5b@illithid>
[not found] ` <a7b8c6b3-a8e8-6ab7-6cf4-118446849a9c@gmail.com>
[not found] ` <dca0e251-7481-7f1e-4077-0ddee070a357@gmail.com>
[not found] ` <20220906204245.hzhq2s7yha6zzgrh@illithid>
[not found] ` <30e80fe0-f0ce-d6cd-ee40-28692e5a5f82@gmail.com>
[not found] ` <5c1e8620-e4ff-c79a-1d4e-11f797276726@gmail.com>
[not found] ` <20221116234049.GA1229865@if>
[not found] ` <f306a83a-306d-e3d0-5d25-bf07da3da59f@gmail.com>
2022-11-17 0:28 ` Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty) Alejandro Colomar
2022-12-11 16:40 ` Ping^1: " Alejandro Colomar
2022-12-11 19:05 ` Michael Haardt
2022-12-11 19:21 ` Alejandro Colomar
2022-12-11 21:10 ` Michael Haardt
2022-12-12 0:34 ` Douglas McIlroy
2022-12-12 11:39 ` Alejandro Colomar
2022-12-12 8:58 ` Ralph Corderoy
2022-12-12 13:19 ` G. Branden Robinson
2022-12-12 13:57 ` Andries E. Brouwer
2022-12-12 13:39 ` Colin Watson
2022-12-12 13:48 ` Alejandro Colomar
[not found] ` <1719285.QkHrqEjB74@pip>
[not found] ` <01989003-349f-fb6b-f460-89106b82bc34@gmail.com>
[not found] ` <2176657.1BCLMh4Saa@pip>
2022-12-17 11:51 ` Ping^1: " Alejandro Colomar
2022-12-17 13:19 ` [BUG] gropdf, tbl: Completely broken table (was: Ping^1: Chapters of the manual (was: Bug#1018737: ...)) Alejandro Colomar
2022-12-17 16:08 ` G. Branden Robinson
2022-12-17 21:26 ` Deri
2022-12-18 11:25 ` Alejandro Colomar
2022-12-18 5:49 ` [BUG] gropdf, tbl: Completely broken table Ralph Corderoy
2022-12-18 11:01 ` Alejandro Colomar
2022-12-18 11:46 ` Alejandro Colomar [this message]
2022-12-19 5:32 ` groff 1.23.0.rc2 status report (was: [BUG] gropdf, tbl: Completely broken table) G. Branden Robinson
2022-12-19 12:58 ` Deri
2022-12-19 16:39 ` Alejandro Colomar
2022-12-19 16:59 ` patching suffixes(7) (was: groff 1.23.0.rc2 status report) G. Branden Robinson
2022-12-19 19:10 ` Alejandro Colomar
2022-12-19 19:54 ` prehistory branch (was: patching suffixes(7) (was: groff 1.23.0.rc2 status report)) Alejandro Colomar
2022-12-19 20:05 ` Alejandro Colomar
2022-12-20 3:40 ` patching suffixes(7) (was: groff 1.23.0.rc2 status report) G. Branden Robinson
2022-12-20 10:12 ` Alejandro Colomar
2022-12-19 16:51 ` groff 1.23.0.rc2 status report (was: [BUG] gropdf, tbl: Completely broken table) G. Branden Robinson
2022-12-17 21:37 ` Ping^1: Chapters of the manual (was: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty) Deri
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5439523a-4fd1-e0c7-9116-6fd8c2a65c67@gmail.com \
--to=alx.manpages@gmail.com \
--cc=deri@chuzzlewit.myzen.co.uk \
--cc=g.branden.robinson@gmail.com \
--cc=groff@gnu.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.