[IDEA] New pages for types: structs and typedfefs

[Michael Kerrisk (man-pages)]

Hi Alex,

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