Hello Alex, On 9/16/20 9:51 PM, Alejandro Colomar wrote: > Hello Michael > > On 2020-09-16 21:24, Michael Kerrisk (man-pages) wrote: > > Hello Alex, > > > > On 9/16/20 1:01 PM, Alejandro Colomar wrote: > >> Signed-off-by: Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> > >> --- > >> > >> Hi Michael, > >> > >> Changelog since v4: > >> > >> - Comment "See also" about yet undocumented size_t > >> - Simplify header ordering > >> - Curate See also > >> - Remove incorrect headers > >> > >> > >> On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote: > >>> Okay. Time to nit pick:-). Do not be too dispirited, > >>> I think we started with some of the most difficult types... > >> > >> I was waiting for it :-). > >> > >>> I soppose what I meant is that POSIX defers to the C standard > >>> in the cases where they overlap, and I'd expect that the set > >>> of headers specified in the C standard and in POSIX might be the > >>> same, but where they're not, I suspect the list of POSIX headers > >>> would always be a superset of the C headers. So, just make a > >>> single list of those headers, followed by 3 and 4 (merged) > >> > >> See updated comment in the page. > > > > It looks good to me. > > It still doesn't convince me. > > Let's see how the standards define the types: > > C has a ¿main? header that defines a type > (for example, for 'time_t' it would be <time.h>; > for 'size_t' it would be <stddef.h>), > and then there may be other headers that shall also define the type > (for example, 'size_t' is also defined in <stdio.h> and others). > > POSIX does more or less the same: > It has a ¿main? header where the type is defined > (for 'time_t' it is <sys/types>, > which as you can it sometimes see differs from C), > and then there may be other headers that shall define the type. > > I think we should differentiate those 1 or 2 headers > by putting them the first ones, > and then the rest could be merged together > (and maybe use a comma or something to differentiate them?). Maybe a semicolon (;), just because more visually obvious? > Such as (for 'time_t'): > > Include: <sys/types.h> or <time.h>, or <sched.h> or <sys/msg.h> or > <sys/select.h> or <sys/sem.h> or <sys/shm.h> or <sys/stat.h> or > <sys/time.h> or <utime.h> > > However this still doesn't convince me... > I don't see a perfect way to express that. Maybe not perfect, but I don't think we have to come up with the perfect solution (yet). I think things are okay as you propose them currently. > Also, should we put a dot at the end of the includes? Yes, perhaps a little tidier. > > Include: <sys/types.h> or <time.h>¿.? [...] > >>> <sched.h> only defines time_t since POSIX.1-2008, as far as I can > >>> tell! I'm not sure how/if we want to represent that detail. > >> > >> I added a Notes section for that type. You like it? > > > > Yes. > > > >>> But size_t is not in this page (yet). Is it in your tree? > >> > >> Not yet. In my tree I didn't forget to comment it, though. As you can > >> guess, It'll be the next type to document, and then ptrdiff_t. > >> > >>> Today I learned: size_t is in C99, but ssize_t is not! > > > > [...] > > > > I have no comments on the page. It looks great! I'm happy to > > merge it now, unless you have something you want to change first. > > See above. That's the only thing that I don't fully like. > > Also there are a few cosmetic fixes that I have in my tree already. > > And, I trimmed a bit more the 'sigval' See also section. > > Here's what I already applied to my tree. I will show you the diff as > it is very short so you have an idea off what is coming: > > $ git diff types_draft_6 > diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 > index 8fc827332..ffdcc9793 100644 > --- a/man7/system_data_types.7 > +++ b/man7/system_data_types.7 > @@ -38,7 +38,7 @@ system_data_types \- overview of system data types > .\" 1) The header(s) that shall define the type > .\" according to the C standard, > .\" and > -.\" the header that shall define the type > +.\" the main header that shall define the type > .\" according to POSIX, > .\" in alphabetical order. > .\" 2) All other headers that shall define the type > > (inline comment): Actually this still doesn't convince me, as I already > said. > > @@ -81,11 +81,15 @@ Data passed with a signal. > Conforming to: POSIX.1-2001 and later. > .IP > See also: > -.BR rt_sigqueueinfo (2), > -.BR sigaction (2), > .BR pthread_sigqueue (3), > .BR sigqueue (3), > .BR sigevent (7) > +.\".IP > +.\"See also the > +.\".I sigevent > +.\"structure and the > +.\".I siginfo_t > +.\"type in this page. > .TP > .I ssize_t > .IP > > Those 2 man pages aren't very related to this type, > and instead are related to 'siginfo_t', which contains a member of > type 'union sigval'. > So I prefer to refer to 'siginfo_t', > and there we will refer to those pages. That sounds okay to me. I presume you plan to uncomment the lines above that mention sigevent and siginfo_t, right? Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
