Hi Branden, On Wed, Oct 25, 2023 at 09:11:03AM -0500, G. Branden Robinson wrote: > 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] Thanks :) > > 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. Heh, I guessed it would :p BTW, I just checked and Gentoo still doesn't consider 1.23.0 stable enough <https://packages.gentoo.org/packages/sys-apps/groff>. :| Although with word from Ingo that he has urgent plans to implement MR, I may merge the MR patch earlier. Cheers, Alex > > 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 -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
