From: Alejandro Colomar <colomar.6.4.3@gmail.com>
To: "G. Branden Robinson" <g.branden.robinson@gmail.com>,
mtk.manpages@gmail.com
Cc: linux-man@vger.kernel.org, libc-alpha@sourceware.org
Subject: Re: [PATCH v2 1/3] system_data_types.7: ffix
Date: Wed, 30 Sep 2020 23:32:20 +0200 [thread overview]
Message-ID: <f9871768-cc7a-fac0-3500-6a0ccaa78099@gmail.com> (raw)
In-Reply-To: <20200930104322.6ffed5lw3uqmlzph@localhost.localdomain>
Hi Branden & Michael,
On 2020-09-30 12:43, G. Branden Robinson wrote:
>> However, if using .br is a big headache, I would rather not use
>> workarounds (as you proposed in an earlier email),
>> and instead just live with the blank line. It's not much of a
>> problem.
>
> Was an actual decision taken on this? I see patches continuing to roll
> in containing this .br-based pattern. I think if the extra line is
> live-withable, it should be lived with (or one of my four proposed
> alternatives could be used :) ), in preference to setting the bad
> example of the "naked" .br requests.
No decision yet.
We continued with the patch,
considering that we might revert it
or change it to a different approach in the future.
Actually I thought Michael would have hold the patches until the decision,
but he merged them, and it may be easier this way...
we'll fix it when we decide.
For me, I can live with the extra blank line.
Michael, what are your thoughts?
>
> man page markup is highly prone to cargo-culting; on the groff list not
> too long ago, some sleuthing revealed an example of a typo that crept
> into the X Window System man pages over 30 years ago and was not only
> diligently retained there but faithfully copied elsewhere by people who
> didn't realize what they were copying[1].
As someone who has written man-pages only for about a month,
I completely ignore the problems about using .br.
I see it easy in my mind:
I want a line break (without fancy paragraph stuff), I write .br.
I guess it's somewhat more complicated than that :-)
You could probably convince me otherwise,
and in fact you may have already...
>
>> I leave it up to you to decide what to do, Michael.
>>
>> My proposals:
>> If you prefer consistency in the source, I'd rather not use
>> workarounds: I'd just leave .PP, and accept the blank line
>> I see those workarounds uglier than .br.
>
> Too bad for me. But I admit I'm not proud of that .TQ thing. :P
>
>> If you however prefer consistency in the visual page,
>
> That's not how it appears to me; I may be bringing too much insider
> knowledge to the question, but I know when I see them that the things
> you've termed section headings aren't true section headings. Primarily
> I can tell by the fact that their indentation is wrong for an .SH macro.
>
> But the knowledge isn't all that far inside. The worst hand-written man
> page I have ever seen in my life, or expect to see, was written by
> Albert Cahalan, who hated *roff with a passion I have reserved only for
> love affairs. He learned just enough of the language to subvert man-db
> and groff into accepting his plain-text document as a man page[2].
>
> I don't know what ever became of Mr. Cahalan, but I imagine that he is
> somewhere working on processing Markdown with XML:FO and enjoying
> himself immensely.
8-O
I'm curious as to how that man page displays...
>
> Regards,
> Branden
>
> [1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
> [2]
https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
>
I was writing about the different options and testing them,
when by accident I discovered that .RS alone, which I introduced lately,
already fixed the problem we had in the beginning:
.RS forces a line break after the tag
(so .br is actually redundant right now).
I guess we'll all be happy with just .RS, right? :-}
Cheers,
Alex
next prev parent reply other threads:[~2020-09-30 21:32 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-27 21:13 [PATCH " Alejandro Colomar
2020-09-27 21:13 ` [PATCH 2/3] system_data_types.7: Add 'FILE' Alejandro Colomar
2020-09-28 6:04 ` Michael Kerrisk (man-pages)
2020-09-28 9:06 ` [PATCH v2 " Alejandro Colomar
2020-09-29 13:15 ` Alejandro Colomar
2020-09-29 13:35 ` Michael Kerrisk (man-pages)
2020-09-27 21:13 ` [PATCH 3/3] FILE.3: New link to system_data_types(7) Alejandro Colomar
2020-09-28 5:59 ` [PATCH 1/3] system_data_types.7: ffix Michael Kerrisk (man-pages)
2020-09-28 9:03 ` [PATCH v2 " Alejandro Colomar
2020-09-28 10:34 ` Michael Kerrisk (man-pages)
2020-09-28 10:37 ` Alejandro Colomar
2020-09-28 11:13 ` G. Branden Robinson
2020-09-28 13:06 ` G. Branden Robinson
2020-09-28 13:44 ` Alejandro Colomar
2020-09-30 10:43 ` G. Branden Robinson
2020-09-30 21:32 ` Alejandro Colomar [this message]
2020-10-01 7:37 ` Michael Kerrisk (man-pages)
2020-10-01 7:52 ` Alejandro Colomar
2020-10-01 9:36 ` Michael Kerrisk (man-pages)
2020-09-28 10:40 ` [PATCH " G. Branden Robinson
2020-09-28 10:51 ` Alejandro Colomar
2020-09-28 12:49 ` G. Branden Robinson
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=f9871768-cc7a-fac0-3500-6a0ccaa78099@gmail.com \
--to=colomar.6.4.3@gmail.com \
--cc=g.branden.robinson@gmail.com \
--cc=libc-alpha@sourceware.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
/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).