Re: using the TQ macro

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3960 bytes --]

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@kernel.org>
> 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@kernel.org>
> 
> 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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]