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

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

Hi Branden & Michael,

On 2020-09-28 15:06, G. Branden Robinson wrote:
 > Hi Alex!
 >
 > At 2020-09-28T11:03:23+0200, Alejandro Colomar wrote:
 >> Normally, text under a section header starts in the next line after
 >> the header, without a blank line.  Follow that pattern.
 >
 > I think your terminology could confuse some people.  A section heading
 > in a man page is what is typeset by the .SH macro.  For instance, ".SH
 > Name", ".SH See also", and so forth[1].
 >
 > In the below, "aiocb" (in italics) is properly termed a "paragraph tag",
 > hence the mnemonic for the macro right before it: "TP" for "tagged
 > paragraph".
 >
 > Just FYI.

I did mean .SH:

For each type we're separating the paragraphs by description,
conforming to, see also, ...  similar to the .SH sections.

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.

But Michael did already apply the patch (was it by mistake? or did you
agree with the patch, Michael?)

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.
If you however prefer consistency in the visual page,
I'd use .br, or something that doesn't look like a workaround.

Regards,

Alex

 >
 > [...]
 >> 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
 >> @@ -101,7 +101,7 @@ See also:
 >
 > Regards,
 > Branden
 >
 > [1] Often section headings are written in full capitals in man page
 > source documents, which loses information.  The next release of groff
 > will feature support for mixed-case section headings with optional
 > full-caps rendering under user control.
 >