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

[Alejandro Colomar]

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