On Fri, 2 Oct 2020 at 14:20, Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> wrote: > > > > On 2020-10-02 15:06, Jonathan Wakely wrote: > > On Fri, 2 Oct 2020 at 12:31, Michael Kerrisk (man-pages) > > <mtk.manpages@xxxxxxxxx> wrote: > >> > >> On Fri, 2 Oct 2020 at 12:49, Jonathan Wakely <jwakely.gcc@xxxxxxxxx> > wrote: > >>> > >>> On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc > <gcc@xxxxxxxxxxx> wrote: > >>>> However, it might be good that someone starts a page called > >>>> 'type_qualifiers(7)' or something like that. > >>> > >>> Who is this for? Who is trying to learn C from man pages? Should > >>> somebody stop them? > >> > >> Yes, I think so. To add context, Alex has been doing a lot of work to > >> build up the new system_data_types(7) page [1], which I think is > >> especially useful for the POSIX system data types that are used with > >> various APIs. > > > > It's definitely useful for types like struct siginfo_t and struct > > timeval, which aren't in C. > > Hi Jonathan, > > But then the line is a bit diffuse. > Would you document 'ssize_t' and not 'size_t'? Yes. My documentation for ssize_t would mention size_t, refer to the C standard, and not define it. > Would you not document intN_t types? > Would you document stdint types, including 'intptr_t', and not 'void *'? I would document neither. I can see some small value in documenting size_t and the stdint types, as they are technically defined by the libc headers. But documenting void* seems very silly. It's one of the most fundamental built-in parts of the C language, not an interface provided by the system. > I guess the basic types (int, long, ...) can be left out for now, I should hope so! > and apart from 'int' those rarely are the most appropriate types > for most uses. > But other than that, I would document all of the types. > And even... when all of the other types are documented, > it will be only a little extra effort to document those, > so in the future I might consider that. [insert Jurassic Park meme "Your scientists were so preoccupied with whether or not they could, they didn't stop to think if they should." ] I don't see value in bloating the man-pages with information nobody will ever use, and which doesn't (IMHO) belong there anyway. We seem to fundamentally disagree about what the man pages are for. I don't think they are supposed to teach C programming from scratch. > But yes, priority should probably go to Linux/POSIX-only types.
