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

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

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

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.

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.

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

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