Re: [IDEA] New pages for types: structs and typedfefs

Michael Kerrisk (man-pages)
2020-09-13T12:01:39Z

Hi Alex,

On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar <colomar.6.4.3@gmail.com> 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/