[prev in list] [next in list] [prev in thread] [next in thread]
List: linux-man
Subject: Re: using the TQ macro
From: Alejandro Colomar <alx () kernel ! org>
Date: 2023-10-25 15:08:19
Message-ID: ZTkvY8egIrf9pcxF () debian
[Download RAW message or body]
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/>
["signature.asc" (application/pgp-signature)]
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic