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
