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

Alejandro Colomar
2020-09-28T13:44:50Z

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