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

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

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