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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/