Hi Dave,
On 2020-09-29 12:37, 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@xxxxxxxxx>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@xxxxxxxxx>
---
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 think I'll add a paragraph in the NOTES section at the bottom of the page.
Thanks,
Alex
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.
I hope a paragraph in the NOTES section will be explicit enough, as said
above.
.\"
.\" * 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"?
Well, it remarks a bit that those are something like 2nd class headers
for that definition. But that together with a paragraph in NOTES will
be better.
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.)
[...]
I wanted to avoid that because that would add a lot of noise lines.
Do you think the note in NOTES would be enough?
Thanks,
Alex
Cheers
---Dave
