Hi Alex, On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> wrote: > > Hi Michael, > > On 2020-09-12 08:33, Michael Kerrisk (man-pages) wrote: > > Your not the first to suggest this. Most recently, if I recall > > correctly, Florian also suggested it. > > > > The idea seems reasonable, but I wonder about the best way of doing it. > > libbsd already provides a few pages on types. Maybe we could have a > look at them. At least I've seen 'man timespec' (which redirects to > timeval.3bsd): > > https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/master/man/timeval.3bsd > > > > > I propose the desired information for each type would be > > > > * Type name > > * Short explanation of the type (often this mcould be just a > > few words, I think) > > * Whether the type is specified in POSIX; POSIX requirements on > > the type. > > * Header file that defines the type (in some cases, there > > may be more than one. This info can be discovered in the > > POSIX spec. (Alex, do you have a PDF of the POSIX spec?) > > * Cross references to manual pages of relevant APIs that use the type. > > I think that would be reasonable. > > No, I don't have a PDF. I usually search here: > > https://pubs.opengroup.org/onlinepubs/9699919799/ You can get a PDF by registering as a member of The Open Group. I think the necessary info is here: https://www.opengroup.org/austin/lists.html (I find having everything in a single PDF is useful for searching.) > > There are some weird corner cases. For example, clock_t: > > > > * times(2): clock_t == clock ticks (sysconf(_SC_CLK_TCK)) > > * clock(3): clock_t measures in CLOCKS_PER_SEC > > That would just be 1 or 2 more lines in the explanation, I guess. Yes, I guess. > That's also similar to the typical (mis?)use of size_t as a ptrdiff_t. > > > Then, do we do one page per type? At first glance, that seems > > unwieldy to me. (I could be wrong.) And it seems to me that > > there might be benefits in having all of the information in > > one place rather than spread across multiple pages. (For example > > cantralizing the info would make it easier for the reader to > > get an overview.) > > I agree in that everything should be centralized, at least in the > beginning. That would make it much easier to maintain and find the > information. If the future requires the information to be spread > across many pages, let the future solve that problem :) > > > > > Alternatively, we could have one big page that is a list of the > > types with the above information. Say "system_data_types(7)". > > That page might be an alphabetically ordered hanging list of > > entries that look like this: > > > > timer_t <time.h> or <sys/types.h> > > POSIX timer ID. > > > > Conforming to: POSIX.1-2008. > > > > See: timer_create(2), timer_delete(2), timer_getoverrun(2), > > timer_settime(2) > > I'd say here is missing the POSIX requirements on the type. As far as I can tell, in the case of timer_t, I think there are no requirements in POSIX. > Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned? POSIX doesn't specify, I think. One other thing the page should show of course is definition of the structure types. > > Then of course, we'd need to have links to that page, so that > > people could just type 'man timer_t'. What section should the links > > be in? The reasonable candidates would be section 3 or 7. I'm not > > yet sure which is better. But the point is that we'd have files > > such as timer_t.3 (or timer_t.7) that are link pages containing the > > line: > > > > .so man7/system_data_types.7 > > Sure. And for the structs, I'd allow: > > 'man struct timespec' (For simplicity) > 'man struct-timespec' (Similar to the git man pages) > 'man timespec' (For compatibility with libbsd) Mainly, I'm interested in the last case. That's the one I think that people would most likely use. In a follow-up mail, you expressed concern with conflicts with libbsd pages. I'm not too worried about that. There are already *many* conflicts between libbsd and man-pages. > > For the moment at least, I'd favor the "one big page plus > > links" approach. > > Yes. Would you like to take a shot at this? I'd suggest just a simple page covering just two or three types to start with. Maybe time_t and timer_t, or otherwise some types that seem good choices to you? Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
