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

[Alejandro Colomar <colomar.6.4.3@gmail.com>]

Hi Branden,

On 2020-09-28 12:40, G. Branden Robinson wrote:
 > At 2020-09-28T07:59:14+0200, Michael Kerrisk (man-pages) wrote:
 >>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
 >>
 >> I do think this requires an explanation saying what you are
 >> trying to do with this change (and then perhaps a more expansive
 >> "Subject" also).
 >>
 >> I can visually see what you are doing with this patch,
 >> but I do wonder if there is a better way of doing it.
 >>
 >> I've dropped Branden into CC. Perhaps he has a comment.
 >
 > Hi Michael, yes--thank you!
 >
 > In my opinion, use of "raw" *roff requests in a man page is a "code
 > smell".
 >
 > Let me have a look...
 >
 >>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
 >>> index 361e8d411..ff0403df9 100644
 >>> --- a/man7/system_data_types.7
 >>> +++ b/man7/system_data_types.7
 >>> @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
 >>>   .TP
 >>>   .I aiocb
 >>>   .RS
 >>> -.PP
 >>> +.br
 >>>   Include:
 >>>   .IR <aio.h> .
 >>>   .PP
 >
 > This is changed already from my most recent "git pull", so things are
 > moving fast indeed in this area!  Here's what I show currently:
 >
 > .\"------------------------------------- aiocb ------------------------/
 > .TP
 > .I aiocb
 > .IP
 > Include:
 > .IR <aio.h> .
 > .IP
 > .EX
 > struct aiocb {
 >
 > So first the indented paragraph was replaced (or proposed to be
 > replaced) by a relative inset (.RS) and a paragraph break (.PP).  It's
 > not visible in this diff where the relative inset ends, but I reckon
 > it's right before the next tagged paragraph (.TP).
 >
 > Now, the .PP is being replaced by .br, I guess because you want to
 > eliminate some vertical space between the paragraph tag ("aiocb" in
 > italics above) and the following material?
 >
 > However, .TP already does this for you when the tag is wider than the
 > paragraph indentation.  You probably discovered this yourself with
 > "ptrdiff_t".
 >
 > I get the feeling you're going for something specific in terms of visual
 > presentation.
 >
 > What is it that you don't like about the following pattern?
 >
 > .TP
 > .I typename_t
 > Include
 > .IR <header.h> .
 > .IP
 > .EX
 > struct typename {
 >      // ...
 > }
 > .EE
 > .IP
 > Notes and commentary.

That's the first thing we tried; actually if I remember correctly,
that's what Michael suggested first.

But as you said, when we documented types with a long name such as
ptrdiff_t, the alginment broke: sometimes Include was in the same line,
and sometimes in the next one.

That's when we opted for

.\"------------------------------------- aiocb ------------------------/
.TP
.I aiocb
.IP
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {



 >
 > The above visually aligns everything by the type name with all the
 > material related to each type inset, which makes the page easy to scan.
 > Literal code is not filled, so code indentation is respected and (on
 > typesetters) the code be in a monospaced font so it will stand out and
 > align correctly.  You don't have to manage insets with .RS and .RE, and
 > you can still have as many paragraphs as you want with .IP.


Then, a few days ago, I pushed the change that you still didn't see:
Replace .IP with .RS/.RE + .PP

I'll refer to the patch for the rationale: it was a bit long. Basically,
it better represents a whole block, and it's easier to further indent:

https://lore.kernel.org/linux-man/16c0890e-33c0-d052-d7ee-39385cd79299@gmail.com/T/#m21da4dba4b3a44b0a59cad1e7eacb13a68a91636

This change actually didn't have visual effects; just source changes.

 >
 > I have some guesses as to what might be bothering you, but I don't want
 > to put words in your mouth, and my mails tend to run too long anwyay, so
 > I won't voice them right now.  :)
 >
 > Regards,
 > Branden
 >

Thanks,

Alex