Re: [RFC] system_data_types.7: wfix + ffix

[Alejandro Colomar <colomar.6.4.3@gmail.com>]

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
>