Re: Navigational corrections

[Alejandro Colomar]

Hi Michael,

On 2020-10-03 10:00, Michael Kerrisk (man-pages) wrote:
> Hi Alex, et al.
> On 10/2/20 3:51 PM, Alejandro Colomar wrote:
>>
>> Hi Jonathan,
>>
>> On 2020-10-02 15:27, Jonathan Wakely wrote:
>>> 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.
>>
>> Agree in part.
>> I'll try to think about it again.
>>
>> In the meantime, I trust Michael to tell me when something is way off :)
>>
>> Thanks, really!
>>
>> Alex
>
> So, I think a navigational correction is needed.
>
> My vision was that system_data_types(7) would most usefully document
> the POSIX types, but by now there's too much of C creeping in. I have
> been a little slow to react to that, and I apologize for that.
> But I think we should not go in that direction
>
> I think it is worth having types like ssize_t and size_t in
> the page, simply because they turn up with so many of the POSIX
> APIs, and people often don't understand some details of these
> types (such as the necessary prinf() specifiers). So, as long as
> we're going to have a page about these types, it's fine by
> me to include size_t and ssize_t.
>
> Types like [u]intN_t are definitely on the borderline for me. But,
> they do appear in various APIs in the Linux interface (either
> explicitly, or as the similar __u32 ___64, etc.). And again
> many people don't understand some basic details, such as
> the PRI and SCN constants, so I think it is useful to have them
> briefly summarized in one place, and as long as they are already
> in the page, then let's keep them.
>
> I think __int128 etc definitely doesn't belong in this page.
>
> And I'd like to back pedal a bit. I think we really shouldn't have
> [u]int_fastN_t
> [u]int_leastN_t
> in the page. They are C details that have nothing to with POSIX,
> the kernel, or libc. Could you send me a patch to remove these
> from the page? And again, my apologies for not being focused
> enough on the big picture sooner.

I'm fine with removing them.
I only added them because while I was adding [u]intN_t,
they were in the same page, and I just took them too.
No problem with removing them.

To be clear, I should remove [u]int_*astN_t, right?

>
> I don't think 'void' belongs in this page. Nor basic types
> such as int, long, etc.
Fine.


>
> The question of 'void *' is an interesting one. It is something
> like a fundamental C type, and not something that comes from POSIX.
> But, it does appear in POSIX APIs and often details of using
> the type are not well understood. So, as a matter of practicality,
> and again since you've done the work, I am inclined to include
> this type in the page, just so it can be handily referred to
> along with all of the other types.
>
> Looking ahead (and I hope none of the above disheartens you,
> since you've done a lot of great work for this page),

Actually, not.
Its good to have you tell me what is good for the man and what's not.
Otherwise, I wouldn't know.
I keep a branch with all of the rejected patches,
just to have an idea of what I should not send you :-)

> it would
> be good if you could provide a bit of an advance roadmap about
> the types that you'd like to add to the page.

Well, I didn't have a clear roadmap.
I had some types which I clearly wanted to document,
and they were ptrdiff_t, and ssize_t,
which I documented in the first patches,
and then I was finding related types,
and also tended to document about types which I knew very well too,
to have something useful to add to the description.

I may now start writing about off_t and related types,
which were the ones that made me want this page.

>
> Thanks,
>
> Michael
>
>
>

Thanks,

Alex