From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: Alejandro Colomar <alx@kernel.org>
Cc: linux-man@vger.kernel.org
Subject: using the TQ macro
Date: Wed, 25 Oct 2023 09:11:03 -0500 [thread overview]
Message-ID: <20231025141103.savwphtepufpget4@illithid> (raw)
[-- Attachment #1: Type: text/plain, Size: 3303 bytes --]
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]
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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next reply other threads:[~2023-10-25 14:11 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-10-25 14:11 G. Branden Robinson [this message]
2023-10-25 15:08 ` using the TQ macro Alejandro Colomar
2023-10-28 13:13 ` groff 1.23.0 stability (was: using the TQ macro) G. Branden Robinson
2023-10-31 4:38 ` Sam James
2023-10-31 12:13 ` Alejandro Colomar
2023-11-13 23:48 ` Sam James
2023-11-14 0:25 ` Alejandro Colomar
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=20231025141103.savwphtepufpget4@illithid \
--to=g.branden.robinson@gmail.com \
--cc=alx@kernel.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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).