On Tue, Sep 29, 2020 at 04:52:18PM +0200, Alejandro Colomar wrote: > 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. OK > > 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 :) Great :) [...] Cheers ---Dave
