Hi Michael & Dave,
On 2020-09-29 13:34, Michael Kerrisk (man-pages) wrote:
> Hi Alex, Dave,
>
> [Alex, just to note: this patch doesn't apply against current master.]
>
> On 9/29/20 12:37 PM, Dave Martin wrote:
>> On Mon, Sep 28, 2020 at 05:16:47PM +0200, Alejandro Colomar wrote:
>>> The previous format/wording for the includes wasn't very clear.
>>> Improve it a bit following Branden's proposal.
>>>
>>> Reported-by: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>
>>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@xxxxxxxxx>
>>> ---
>>>
>>> Hi,
>>>
>>> What do you think about this?
>>>
>>> Would you change something?
>>
>> Why should the user of a man page have to go look at the comments in the
>> page source in order to find an explanation of what the notation in the
>> page means? That seems very strange.
>
> I do agree that we need to add some help for the reader.
>
> Alex, how about we start as follows. At the end of the NOTES Section,
> let's add a "Conventions used in this page" subsection (.SS).
I just sent an email I wrote an hour ago,
where I proposed to add a paragraph in NOTES.
Your proposal is a bit more specific :)
>
> Some things to mention there:
>
> * In "Conforming to" we only concern ourselves
> with POSIX.2001 and later and C99 and later.
> The type may be specified in earlier versions
> of one of these standards, but in the interests
> of simplicity we omit details from earlier standards.
Agree.
>
> * In "Include", we first note the "primary" header(s)
> that define the type according to either the C or POSIX.1
> standards. Under "Alternatively", we note additional headers
> that the standards specify shall define the type.
Agree.
>
> And then I have a question. Alex, did you so far find a case of
> type where the C standard specified that a particular header
> shall define the type, but PPOSIX.1 either did not have that
> requirement or did not specify that header?
No.
I've found types where the "primary" header is different in C and POSIX.
But in all the cases I've checked, POSIX always adds headers to C,
and never removes them.
I hope it is always true, because I didn't check all of them one by one.
> I've been kind of
> expecting that the set of headers specified by POSIX be a proper
> superset of the the set of headers specified by C, but maybe
> you have found otherwise.
AFAICS, that holds true.
>
>>> man7/system_data_types.7 | 285
++++++++++++++++-----------------------
>>> 1 file changed, 113 insertions(+), 172 deletions(-)
>>>
>>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>>> index 16930985e..dc4a3bae4 100644
>>> --- a/man7/system_data_types.7
>>> +++ b/man7/system_data_types.7
>>> @@ -33,20 +33,21 @@ system_data_types \- overview of system data types
>>> .\" Each entry will have the following parts:
>>> .\" * Include
>>> .\" The headers will be in the following order:
>>> +.\" "Include:"
>>> .\" 1) The main header that shall define the type
>>> -.\" according to the C Standard,
>>> -.\" and
>>> -.\" the main header that shall define the type
>>> -.\" according to POSIX,
>>> -.\" in alphabetical order.
>>> -.\" ;
>>> -.\" 2) All other headers that shall define the type
>>> +.\" according to the C Standard.
>>> +.\" ["or"]
>>> +.\" 2) The main header that shall define the type
>>> +.\" according to POSIX.
>>> +.\" [". Alternatively,"]
>>> +.\" 3) All other headers that shall define the type
>>> .\" as described in the previous header(s)
>>> .\" according to the C Standard or POSIX,
>>> .\" in alphabetical order.
>>> .\" *) All headers that define the type
>>> .\" *if* the type is not defined by C nor POSIX,
>>> .\" in alphabetical order.
>>> +.\" "."
>>
>> It is fine to have notes about page maintenance here -- i.e., which
>> headers should be placed where in the list, and what order to sort them
>> in.
>>
>> However, I think that statements about which header(s) provide the type
>> under which standard need to be in the actual page text. Programmers
>> need this information.
>
> My question (to Alex) above is related. (And to repeat, the thing
> I most care about in the man pages is POSIX.1, rather than C.)
If/when the NOTES section documents that clearly,
I may remove that comment.
>
>>> .\"
>>> .\" * Definition (no "Definition" header)
>>> .\" Only struct/union types will have definition;
>>> @@ -203,8 +204,8 @@ See also:
>>> .RS
>>> .br
>>> Include:
>>> -.IR <stdio.h> ;
>>> -or
>>> +.IR <stdio.h> .
>>> +Alternatively,
>>> .IR <wchar.h> .
>>> .PP
>>> An object type used for streams.
>>> @@ -268,19 +269,14 @@ type in this page.
>>> .RS
>>> .br
>>> Include:
>>> -.IR <sys/types.h> ;
>>> -or
>>> -.I <grp.h>
>>> -or
>>> -.I <pwd.h>
>>> -or
>>> -.I <signal.h>
>>> -or
>>> -.i <stropts.h>
>>> -or
>>> -.I <sys/ipc.h>
>>> -or
>>> -.I <sys/stat.h>
>>> +.IR <sys/types.h> .
>>> +Alternatively,
>>
>> How does the reader of the page know that "alternatively" here has a
>> specific and different meaning from "or"?
>>
>> Can we describe this somehow along the lines of:
>>
>> The C standards specify this type in the following header:
>>
>> <stddef.h>
>>
>> In POSIX environments, it is sufficient instead to include any of the
>> following headers, but the resulting program may not be portable to
>> other C implementations unless <stddef.h> is also included:
>>
>> [etc.]
>>
>>
>> (I'm not sure this is 100% true, but it seems a safe recommendation.
>> I'm also being lazy by writing "the C standards" and "POSIX
>> environments" here -- it would be better to be specific.)
>
> This feels too verbose to me. Again, I care more about POSIX
> than C here. This is Linux; it quacks like a UNIX; so POSIX
> is the most relevant thing. And I want to keep the discussion
> of these types reasonably brief. In particular, I think that
> people who care a lot about portability across C implementations
> need to be looking somewhere else than the Linux manual pages.
Agree,
>
> Thanks,
>
> Michael
>
Thanks,
Alex
