Hi Dave,
On 2020-09-29 16:43, Dave Martin wrote:
> On Tue, Sep 29, 2020 at 04:22:19PM +0200, Alejandro Colomar wrote:
>> The previous format/wording for the includes wasn't very clear.
>> Improve it a bit following Branden's proposal.
>> It also helps reduce lines of code.
>>
>> Add a subsection in NOTES explaining the conventions used.
>>
>> Remove the comment for helping maintain the page,
>> as the NOTES section is now clear enough.
>>
>> Reported-by: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>
>> Reported-by: Dave Martin <Dave.Martin@xxxxxxx>
>> Reported-by: Michael Kerrisk <mtk.manpages@xxxxxxxxx>
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@xxxxxxxxx>
>> ---
>>
>> Hi Michael,
>>
>> After this patch, we're at a sync-point: no more pending patches
from me.
>>
>> Tomorrow I'll go to the mountain, so you can have a small break from
me :p
>>
>> Cheers,
>>
>> Alex
>>
>>
>> man7/system_data_types.7 | 302 +++++++++++++++------------------------
>> 1 file changed, 119 insertions(+), 183 deletions(-)
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index af0c55c65..9cf67ee6f 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -31,22 +31,7 @@ system_data_types \- overview of system data types
>> .\" Layout:
>> .\" A list of type names (the struct/union keyword will be omitted).
>> .\" Each entry will have the following parts:
>> -.\" * Include
>> -.\" The headers will be in the following order:
>> -.\" 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
>> -.\" 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.
>> +.\" * Include (see NOTES)
>> .\"
>> .\" * Definition (no "Definition" header)
>> .\" Only struct/union types will have definition;
>> @@ -55,9 +40,10 @@ system_data_types \- overview of system data types
>> .\" * Description (no "Description" header)
>> .\" A few lines describing the type.
>> .\"
>> -.\" * Conforming to
>> +.\" * Bugs (if any)
>> +.\"
>> +.\" * Conforming to (see NOTES)
>> .\" Format: CXY and later; POSIX.1-XXXX and later.
>> -.\" Forget about pre-C99 C standards (i.e., C89/C90)
>> .\"
>> .\" * Notes (optional)
>> .\"
>> @@ -203,8 +189,8 @@ See also:
>> .RS
>> .br
>> Include:
>> -.IR <stdio.h> ;
>> -or
>> +.IR <stdio.h> .
>> +Alternatively,
>> .IR <wchar.h> .
>> .PP
>> An object type used for streams.
>> @@ -269,19 +255,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,
>> +.IR <grp.h> ,
>> +.IR <pwd.h> ,
>> +.IR <signal.h> ,
>> +.IR <stropts.h> ,
>> +.IR <sys/ipc.h> ,
>> +.IR <sys/stat.h> ,
>> or
>> .IR <unistd.h> .
>> .PP
>> @@ -306,8 +287,8 @@ See also:
>> .RS
>> .br
>> Include:
>> -.IR <sys/types.h> ;
>> -or
>> +.IR <sys/types.h> .
>> +Alternatively,
>> .IR <sys/resource.h> .
>> .PP
>> A type used to hold a general identifier.
>> @@ -586,29 +567,19 @@ See also:
>> .RS
>> .br
>> Include
>> -.IR <sys/types.h> ;
>> -or
>> -.I <fcntl.h>
>> -or
>> -.I <sched.h>
>> -or
>> -.I <signal.h>
>> -or
>> -.I <spawn.h>
>> -or
>> -.I <sys/msg.h>
>> -or
>> -.I <sys/sem.h>
>> -or
>> -.I <sys/shm.h>
>> -or
>> -.I <sys/wait.h>
>> -or
>> -.I <termios.h>
>> -or
>> -.I <time.h>
>> -or
>> -.I <unistd.h>
>> +.IR <sys/types.h> .
>> +Alternatively,
>> +.IR <fcntl.h> ,
>> +.IR <sched.h> ,
>> +.IR <signal.h> ,
>> +.IR <spawn.h> ,
>> +.IR <sys/msg.h> ,
>> +.IR <sys/sem.h> ,
>> +.IR <sys/shm.h> ,
>> +.IR <sys/wait.h> ,
>> +.IR <termios.h> ,
>> +.IR <time.h> ,
>> +.IR <unistd.h> ,
>> or
>> .IR <utmpx.h> .
>> .PP
>> @@ -738,11 +709,10 @@ types in this page.
>> .RS
>> .br
>> Include:
>> -.IR <signal.h> ;
>> -or
>> -.I <aio.h>
>> -or
>> -.I <mqueue.h>
>> +.IR <signal.h> .
>> +Alternatively,
>> +.IR <aio.h> ,
>> +.IR <mqueue.h> ,
>> or
>> .IR <time.h> .
>> .PP
>> @@ -787,8 +757,8 @@ structure in this page.
>> .RS
>> .br
>> Include:
>> -.IR <signal.h> ;
>> -or
>> +.IR <signal.h> .
>> +Alternatively,
>> .IR <sys/wait.h> .
>> .PP
>> .EX
>> @@ -823,9 +793,9 @@ See also:
>> .RS
>> .br
>> Include:
>> -.IR <signal.h> ;
>> -or
>> -.I <spawn.h>
>> +.IR <signal.h> .
>> +Alternatively,
>> +.IR <spawn.h> ,
>> or
>> .IR <sys/select.h> .
>> .PP
>> @@ -886,55 +856,32 @@ in this page.
>> Include:
>> .I <stddef.h>
>> or
>> -.IR <sys/types.h> ;
>> -or
>> -.I <aio.h>
>> -or
>> -.I <glob.h>
>> -or
>> -.I <grp.h>
>> -or
>> -.I <iconv.h>
>> -or
>> -.I <monetary.h>
>> -or
>> -.I <mqueue.h>
>> -or
>> -.I <ndbm.h>
>> -or
>> -.I <pwd.h>
>> -or
>> -.I <regex.h>
>> -or
>> -.I <search.h>
>> -or
>> -.I <signal.h>
>> -or
>> -.I <stdio.h>
>> -or
>> -.I <stdlib.h>
>> -or
>> -.I <string.h>
>> -or
>> -.I <strings.h>
>> -or
>> -.I <sys/mman.h>
>> -or
>> -.I <sys/msg.h>
>> -or
>> -.I <sys/sem.h>
>> -or
>> -.I <sys/shm.h>
>> -or
>> -.I <sys/socket.h>
>> -or
>> -.I <sys/uio.h>
>> -or
>> -.I <time.h>
>> -or
>> -.I <unistd.h>
>> -or
>> -.I <wchar.h>
>> +.IR <sys/types.h> .
>> +Alternatively,
>> +.IR <aio.h> ,
>> +.IR <glob.h> ,
>> +.IR <grp.h> ,
>> +.IR <iconv.h> ,
>> +.IR <monetary.h> ,
>> +.IR <mqueue.h> ,
>> +.IR <ndbm.h> ,
>> +.IR <pwd.h> ,
>> +.IR <regex.h> ,
>> +.IR <search.h> ,
>> +.IR <signal.h> ,
>> +.IR <stdio.h> ,
>> +.IR <stdlib.h> ,
>> +.IR <string.h> ,
>> +.IR <strings.h> ,
>> +.IR <sys/mman.h> ,
>> +.IR <sys/msg.h> ,
>> +.IR <sys/sem.h> ,
>> +.IR <sys/shm.h> ,
>> +.IR <sys/socket.h> ,
>> +.IR <sys/uio.h> ,
>> +.IR <time.h> ,
>> +.IR <unistd.h> ,
>> +.IR <wchar.h> ,
>> or
>> .IR <wordexp.h> .
>> .PP
>> @@ -1007,21 +954,15 @@ types in this page.
>> .RS
>> .br
>> Include:
>> -.IR <sys/types.h> ;
>> -or
>> -.I <aio.h>
>> -or
>> -.I <monetary.h>
>> -or
>> -.I <mqueue.h>
>> -or
>> -.I <stdio.h>
>> -or
>> -.I <sys/msg.h>
>> -or
>> -.I <sys/socket.h>
>> -or
>> -.I <sys/uio.h>
>> +.IR <sys/types.h> .
>> +Alternatively,
>> +.IR <aio.h> ,
>> +.IR <monetary.h> ,
>> +.IR <mqueue.h> ,
>> +.IR <stdio.h> ,
>> +.IR <sys/msg.h> ,
>> +.IR <sys/socket.h> ,
>> +.IR <sys/uio.h> ,
>> or
>> .IR <unistd.h> .
>> .PP
>> @@ -1083,9 +1024,9 @@ types in this page.
>> .RS
>> .br
>> Include:
>> -.IR <sys/types.h> ;
>> -or
>> -.I <sys/select.h>
>> +.IR <sys/types.h> .
>> +Alternatively,
>> +.IR <sys/select.h> ,
>> or
>> .IR <sys/time.h> .
>> .PP
>> @@ -1110,23 +1051,17 @@ structure in this page.
>> .RS
>> .br
>> Include:
>> -.I <sys/types.h>
>> -or
>> -.IR <time.h> ;
>> -or
>> -.I <sched.h>
>> -or
>> -.I <sys/msg.h>
>> -or
>> -.I <sys/select.h>
>> -or
>> -.I <sys/sem.h>
>> -or
>> -.I <sys/shm.h>
>> -or
>> -.I <sys/stat.h>
>> +.I <time.h>
>> or
>> -.I <sys/time.h>
>> +.IR <sys/types.h> .
>> +Alternatively,
>> +.IR <sched.h> ,
>> +.IR <sys/msg.h> ,
>> +.IR <sys/select.h> ,
>> +.IR <sys/sem.h> ,
>> +.IR <sys/shm.h> ,
>> +.IR <sys/stat.h> ,
>> +.IR <sys/time.h> ,
>> or
>> .IR <utime.h> .
>> .PP
>> @@ -1153,8 +1088,8 @@ See also:
>> .RS
>> .br
>> Include:
>> -.IR <sys/types.h> ;
>> -or
>> +.IR <sys/types.h> .
>> +Alternatively,
>> .IR <time.h> .
>> .PP
>> Used for timer ID returned by
>> @@ -1176,17 +1111,13 @@ See also:
>> .RS
>> .br
>> Include:
>> -.IR <time.h> ;
>> -or
>> -.I <aio.h>
>> -or
>> -.I <mqueue.h>
>> -or
>> -.I <sched.h>
>> -or
>> -.I <signal.h>
>> -or
>> -.I <sys/select.h>
>> +.IR <time.h> .
>> +Alternatively,
>> +.IR <aio.h> ,
>> +.IR <mqueue.h> ,
>> +.IR <sched.h> ,
>> +.IR <signal.h> ,
>> +.IR <sys/select.h> ,
>> or
>> .IR <sys/stat.h> .
>> .PP
>> @@ -1214,11 +1145,10 @@ See also:
>> .RS
>> .br
>> Include:
>> -.IR <sys/time.h> ;
>> -or
>> -.I <sys/resource.h>
>> -or
>> -.I <sys/select.h>
>> +.IR <sys/time.h> .
>> +Alternatively,
>> +.IR <sys/resource.h> ,
>> +.IR <sys/select.h> ,
>> or
>> .IR <utmpx.h> .
>> .PP
>> @@ -1247,17 +1177,13 @@ See also:
>> .RS
>> .br
>> Include:
>> -.IR <sys/types.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,
>> +.IR <pwd.h> ,
>> +.IR <signal.h> ,
>> +.IR <stropts.h> ,
>> +.IR <sys/ipc.h> ,
>> +.IR <sys/stat.h> ,
>> or
>> .IR <unistd.h> .
>> .PP
>> @@ -1418,9 +1344,9 @@ types in this page.
>> .RS
>> .br
>> Include:
>> -.IR <stdarg> ;
>> -or
>> -.I <stdio.h>
>> +.IR <stdarg> .
>> +Alternatively,
>> +.IR <stdio.h> ,
>> or
>> .IR <wchar.h> .
>> .PP
>> @@ -1473,6 +1399,16 @@ If the type has upper and lower limits,
>> the user should check that the value is within those limits,
>> before actually copying the value.
>> The example below shows how these conversions should be done.
>> +.SS Conventions used in this page
>> +In "Conforming to" we only concern ourselves with
>> +C99 and later and POSIX.1-2001 and later.
>> +Some types may be specified in earlier versions of one of these
standards,
>> +but in the interests of simplicity we omit details from earlier
standards.
>> +.PP
>> +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.
>
> While this is more informative, it still doesn't help the programmer
> know which header(s) to use in a given situation. I'd worry that people
> may not read as far as the NOTES, or may not remember what's in there
> when referring to the header lists.
I hope they do :)
And if not, I hope that people will take the first one they see
(and not go through some obscure alternative headers).
>
> Can we not just annotate each header listed with the originating
> standard, say:
>
> <stddef.h> (C)
>
> <sys/types.h> (POSIX)
> ... (POSIX)
> ...
That may be a good idea; I've thought about doing that in the past;
but also thought that it's still too much noise.
Let's see what others think about it.
The downside is that it adds a lot of lines,
being harder to read for types with too many headers (e.g., size_t).
It could also be done in the same line, but maybe it adds too much noise
for the eyes to actually parse the headers.
>
> while this is a bit more effort in the man page, it should make things
> clear for the reader.
>
> (the annotations can be terse, with a more complete citation of the
> applicable standard in the NOTES or elsewhere).
>
> I'm not trying to be awkard here -- actually having man pages defining
> key types and the relevant headers to include is a really good idea.
No problem. I've already thought about this many times:
how to be as informative as possible,
without distracting from the main information.
>
>
> Can we please alias all the actual type names to point to this page,
> so that e.g., "man size_t" works?
We already have that :)
>
> (This might be considered overkill, so if others shoot the suggestion
> down, fair enough -- in any case the alises could be added by a later
> patch.)
>
> Cheers
> ---Dave
>
Cheers,
Alex
