From: Dave Martin <Dave.Martin@arm.com>
To: Alejandro Colomar <colomar.6.4.3@gmail.com>
Cc: mtk.manpages@gmail.com, linux-man@vger.kernel.org,
libc-alpha@sourceware.org, g.branden.robinson@gmail.com
Subject: Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES
Date: Tue, 29 Sep 2020 16:10:48 +0100 [thread overview]
Message-ID: <20200929151047.GN6642@arm.com> (raw)
In-Reply-To: <3dae4d7f-3c08-4f1c-47ce-8815255ca24c@gmail.com>
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@gmail.com>
> >> Reported-by: Dave Martin <Dave.Martin@arm.com>
> >> Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
> >> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> >> ---
> >>
> >> 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
next prev parent reply other threads:[~2020-09-29 15:10 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-18 11:27 [PATCH 0/2] Document size_t Alejandro Colomar
2020-09-18 11:27 ` [PATCH 1/2] system_data_types.7: " Alejandro Colomar
2020-09-18 14:34 ` Florian Weimer
2020-09-18 15:53 ` Alejandro Colomar
2020-09-18 17:27 ` Florian Weimer
2020-09-18 17:42 ` Paul Eggert
2020-09-18 17:53 ` Florian Weimer
2020-09-30 15:50 ` Joseph Myers
2020-09-18 20:13 ` Michael Kerrisk (man-pages)
2020-09-28 13:41 ` Dave Martin
2020-09-28 13:48 ` Alejandro Colomar
2020-09-28 13:55 ` G. Branden Robinson
2020-09-28 14:15 ` Dave Martin
2020-09-28 14:51 ` Alejandro Colomar
2020-09-28 15:16 ` [RFC] system_data_types.7: wfix + ffix Alejandro Colomar
2020-09-29 10:37 ` Dave Martin
2020-09-29 11:34 ` Michael Kerrisk (man-pages)
2020-09-29 12:10 ` Alejandro Colomar
2020-09-29 14:22 ` [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES Alejandro Colomar
2020-09-29 14:43 ` Dave Martin
2020-09-29 14:52 ` Alejandro Colomar
2020-09-29 15:06 ` Michael Kerrisk (man-pages)
2020-09-29 15:13 ` Dave Martin
2020-09-29 15:21 ` Alejandro Colomar
2020-09-29 15:10 ` Dave Martin [this message]
2020-09-29 11:57 ` [RFC] system_data_types.7: wfix + ffix Alejandro Colomar
2020-09-30 17:16 ` [PATCH 1/2] system_data_types.7: Document size_t Joseph Myers
2020-09-29 11:11 ` Michael Kerrisk (man-pages)
2020-09-28 14:47 ` Alejandro Colomar
2020-09-18 11:27 ` [PATCH 2/2] size_t.3: New link to new documented type in system_data_types(7) Alejandro Colomar
2020-09-18 20:14 ` Michael Kerrisk (man-pages)
2020-09-18 20:13 ` [PATCH 0/2] Document size_t Michael Kerrisk (man-pages)
2020-09-18 21:28 ` Alejandro Colomar
2020-09-18 21:32 ` Florian Weimer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200929151047.GN6642@arm.com \
--to=dave.martin@arm.com \
--cc=colomar.6.4.3@gmail.com \
--cc=g.branden.robinson@gmail.com \
--cc=libc-alpha@sourceware.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).