[RFC v1] system_data_types.7: Draft (and links to it: <type>.3)

[Michael Kerrisk (man-pages)]

Hello Alex,

On 9/14/20 2:20 AM, Alejandro Colomar wrote:
>>From ffd8ea312527935cd86cc7ed1133a08d4e642b06 Mon Sep 17 00:00:00 2001
> From: Alejandro Colomar <colomar.6.4.3 at gmail.com>
> Date: Mon, 14 Sep 2020 02:07:50 +0200
> Subject: [RFC] First draft for system_data_types.7 (and links to it:
>  <type>.3)
> 
> Hi Michael,
> 
> This is my first draft.
> 
> There are still TODO things:
> - Add types (obviously)
> - Write specific "Conforming to" versions
>   For now I just wrote POSIX, but I'll write the specific versions.

Good. I think that we can get away with just mentioning one each of
POSIX.1-200x and Cxx, with the latter starting at C99. I think C89 is
far enough back in time that we don't need to clutter the page with
it. Something like:

Conforming to: C99 and later; POSIX.1-2001 and later.


>   Should I write the latest one, the oldest one, or how?

See above.

>   For C versions I did the following:
> 	If the type has been there since C89, I wrote C89, C99.
> 	If the type is >= C99, I wrote C99.
> 	If the type is >= C11, I wrote C11.
> - Correctly highlight function names and similar (see timer_t)
>   For this first draft, I just want to show you the idea.  I'll add
>   italics and all that stuff later on.
> - Review "See also" (right now: all results of 'grep -rl <type>')
>   I put everything that came up with grep in the See also section.
>   Is it too much?  Any other references I should add?

I am ambivalent on the question of "is it too much?". Some of those
lists seem rather long. But the question of whether it is valuable to
mention *all* of the APIs is open: maybe it is; maybe it is not. Then
again, trying to be exhaustive, makes the lists fragile (new API
appears, but we forgot to add it to the list). And then if we
do not include all of the APIs, what are the criteria for
inclusion/exclusion?

I'm going to hold my finger in the wind, and say: lets restrict the
list to what seem like the most relevant APIs, where obviously that is
a somewhat subjective choice. You could include all the other APIs in
.\" comments, so we can see what's excluded, and this may trigger some
tweaking. So, for 'struct timespec' the list might be as simple as:

clock_gettime(2), clock_nanosleep(2), nanosleep(2)
timerfd_gettime(2), timer_gettime(2)

Note by the way, that that list is not a subset of your list.
Instead, I looked inside the pages that you listed to see which APIs
seemed "relevant".

I cannot think of other references that you should add.

You better include suseconds_t in the next draft :-).

I think it would be better not to split the types into separate lists.
Instead (and note the formatting) order by type name:

.TP
.BI "union " sigval
...
.TP
.I time_t
...
.TP
.I timer_t
...
.TP
.BI "struct " timespec
...
.TP
.BI "struct " timeval
...

Having seen how it looks with the header files, I'm going to suggest a
differnt approach. Let's put them on a separate line, something like:

Obtained by including: <abc.h> or <xyz.h>

> ---
>  man3/sigval.3            |   1 +
>  man3/time_t.3            |   1 +
>  man3/timer_t.3           |   1 +
>  man3/timespec.3          |   1 +
>  man3/timeval.3           |   1 +

It's an open question whether the links should be in section 3 or 
section 7. Do you have any thoughts on what's better?

Don't get wrapped up in including too many more types in the
yet, while we try to iron out the format.

Also, I'd like to see the types added incrementally (one or a few
at a time), so that it's easy to comment on each type, when needed.

Thanks,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/