Hi Alex,
I pulled man-pages Git and saw this.
commit 6fdb1c03075b31364968bcccf472a4d4a86952a6 (origin/master, origin/HEAD)
Author: Alejandro Colomar <alx@xxxxxxxxxx>
Date: Sun Oct 22 14:57:46 2023 +0200
man*/: ffix (Use '.TQ' where appropriate)
When there are multiple tags for a paragraph, using a single TP and
separating the tags with commas makes the man(7) source more complex.
It also has a disadvantage: when searching through a manual page,
heuristics such as " --option" don't work so well.
By using GNU's TQ, we simplify the source of the pages, and improve the
ability to search them.
Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>
I wanted to offer my support for it, in part since Ingo was so critical
over on the groff list.[1]
Your use of `TQ` seems entirely idiomatic here. You're right that it
makes the man(7) source less complex, but it also emphasizes even to the
casual reader the parallel syntax of `TP` and `TQ`, which inexpert man
page authors will surely appreciate.
Another advantage is that if people get carried away with the former
approach, creating a lengthy paragraph tag, they might overrun the line
length, which would be really ugly.
I don't share Ingo's concern that this style of stacking paragraphing
tags is inherently wasteful of screen real estate. Man pages are, and
have always been--going back to the 1971 First Edition Unix
manual--pretty sparse in their use of text on the page.[2] In part,
this helps the eye of the reader to navigate the content.
Ingo would have more of a point if someone had a dozen tags stacked up
for one paragraph, but doing so would suggest other problems; either
your interface doesn't need that many ways to say the same thing and you
should retire and de-document some forms of expression; something should
be parameterized (i.e., turned into a hyphenated noun phrase in
italics); or you're packing too many different things into one item's
presentation. Not everything can be solved with markup: sometimes we
have to do the dirty work of writing clearly in natural language.
But I don't see any problem like that in the Linux man-pages, so I think
his criticism was not entirely apropos. Also, as I noted on the groff
list, he seems to have forgotten that `TQ` takes no arguments, so a
formatter that doesn't support it won't throw any text away.
I also like your suggestion that if we really want to economize on
space, we could present a command's long option form before its short,
old-style Unix synonym, which will work well when the short option (plus
its argument, if any) fits within the space for the paragraph tag. This
might be a good idea for another reason; in GNU user space, the long
option is the much more self-documenting form, and the single-character
option name a kind of "expert mode" alternative. As a general rule,
when presenting technical material, one should not lead with "expert
mode".
Another benefit of this commit was that it made my "prepare for MR"
commit simpler. So I reckon this is a good time to re-submit that (and
the big sed-driven MR migration humdinger; you can look for that soon.
Regards,
Branden
[1] https://lists.gnu.org/archive/html/groff/2023-10/msg00024.html
[2] https://www.bell-labs.com/usr/dmr/www/1stEdman.html
Attachment:
signature.asc
Description: PGP signature
