Re: [PATCH 1/2] system_data_types.7: Document size_t

Alejandro Colomar
2020-09-28T14:47:15Z

Hi Branden,

On 2020-09-28 15:55, G. Branden Robinson wrote:
> Hi, Alex!
>
> At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
>>> Where does this arbitrary-looking list of headers come from?
>>
>> There are two parts: left to the ';', and right to the ';'.
>>
>> Left: The canonical C standard header, and the canonical POSIX header,
>> in alphabetical order.
>>
>> Right: All other headers that shall define the header, according to
>> either the C or the POSIX standards, in alphabetical order.
>
> That's not a bad scheme but it is not inferable from the current man
> page text; I almost commented on the inconsistency in one of my earlier
> messages but deemed it out of scope. Please document it, perhaps in an
> introductory paragraph at the top of the Description section.
>
> Or, you could spend a word to do the same work:
>
> gid_t Include: <sys/types.h>. Alternatively, <grp.h>, <pwd.h>,
> <signal.h>, <stropts.h>, <sys/ipc.h>, <sys/stat.h>, or <unistd.h>.
>
> Regards,
> Branden
>
Thanks!

We talked about it. I wasn't convinced by my scheme,
but we couldn't come up with a better solution, so we kept that.

For the readers, it wasn't clear, but for the developers of the page,
I wrote a comment at the beginning of the page,
which I hope was clear enough:

.\" Layout:
.\" A list of type names (the struct/union keyword will be omitted).
.\" Each entry will have the following parts:
.\" * Include
.\" The headers will be in the following order:
.\" 1) The main header that shall define the type
.\" according to the C Standard,
.\" and
.\" the main header that shall define the type
.\" according to POSIX,
.\" in alphabetical order.
.\" ;
.\" 2) All other headers that shall define the type
.\" as described in the previous header(s)
.\" according to the C Standard or POSIX,
.\" in alphabetical order.
.\" *) All headers that define the type
.\" *if* the type is not defined by C nor POSIX,
.\" in alphabetical order.
.\"
.\" * Definition (no "Definition" header)
.\" Only struct/union types will have definition;
.\" typedefs will remain opaque.
.\"
.\" * Description (no "Description" header)
.\" A few lines describing the type.
.\"
.\" * Conforming to
.\" Format: CXY and later; POSIX.1-XXXX and later.
.\" Forget about pre-C99 C standards (i.e., C89/C90)
.\"
.\" * Notes (optional)
.\"
.\" * See also

But I like very much your "Alternatively, " wording. I'll use it!

Thanks,

Alex