[IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar]

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/

 >
 > 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.

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.

Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned?

 >
 > 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)

Your thoughts?

 >
 > For the moment at least, I'd favor the "one big page plus
 > links" approach.

Yes.

Thanks,

Alex