Re: [PATCH v2 1/3] system_data_types.7: ffix

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

At 2020-09-28T15:44:46+0200, Alejandro Colomar wrote:
> I did mean .SH:
> 
> For each type we're separating the paragraphs by description,
> conforming to, see also, ...  similar to the .SH sections.

Okay, I see; you were using an analogy.

> And therefore, I thought that we should use the same format for
> consistency: After the title, or in this case the tag,
> there should be no blank line.
> 
> 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.

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].

> 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.

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


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]