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

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

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