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

[Dave Martin <Dave.Martin@arm.com>]

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.

> 
> 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.

>  .\"
>  .\"		* 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.)

[...]

Cheers
---Dave