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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Alex,

On 9/11/20 2:47 PM, Alejandro Colomar wrote:
> Hello Michael,
> 
> In the past, when I was beginning to learn C, I had a lot of trouble 
> with the types.
> 
> When you want to know about a function, you just type 'man function' and 
> that tells you everything you need to know.
> 
> However, when you need to use a type, such as a struct or one of those 
> weird POSIX types (e.g., loff_t), the only solution is to grep through 
> the system headers (e.g., 'cd /usr/include/; grep -rn "struct 
> timespec"'), unless you already know in which man page the type appears.
> 
> I remember well when I wanted to use 'ssize_t' for the first time: it 
> was a nightmare to find which header I had to include to get it.
> 
> Do you agree that it would be a good idea to write man pages for the 
> types, or at least write link pages that link to the page where the type 
> is mentioned?

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.

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.

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

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

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)

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

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

Your thoughts?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/