[PATCH v2 1/3] system_data_types.7: ffix
Alejandro Colomar
colomar.6.4.3@gmail.com
Mon Sep 28 13:44:46 GMT 2020
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.
>
More information about the Libc-alpha
mailing list