[RFC] system_data_types.7: wfix + ffix

  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@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi,

What do you think about this?

Would you change something?

Thanks,

Alex


 man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
 1 file changed, 113 insertions(+), 172 deletions(-)
  

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@gmail.com>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> 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.

> 
> Thanks,
> 
> Alex
> 
> 
>  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.

>  .\"
>  .\"		* 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.)

[...]

Cheers
---Dave
  

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@gmail.com>
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>
>> 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).

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.

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

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

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

>>  .\"
>>  .\"		* 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.

Thanks,

Michael
  

Hi Dave,

On 2020-09-29 12:37, 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@gmail.com>
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>
>> 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 think I'll add a paragraph in the NOTES section at the bottom of the page.

> 
>>
>> Thanks,
>>
>> Alex
>>
>>
>>   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.

I hope a paragraph in the NOTES section will be explicit enough, as said 
above.

> 
>>   .\"
>>   .\"		* 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"?

Well, it remarks a bit that those are something like 2nd class headers 
for that definition.  But that together with a paragraph in NOTES will 
be better.

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

I wanted to avoid that because that would add a lot of noise lines.

Do you think the note in NOTES would be enough?

Thanks,

Alex

> 
> Cheers
> ---Dave
>
  

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@gmail.com>
 >>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
 >>> ---
 >>>
 >>> 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