Re: [PATCH 1/2] system_data_types.7: Add 'fexcept_t'

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Alex,

On 9/22/20 5:38 PM, Alejandro Colomar wrote:
> Note:  I used this commit to fix the comment that separates with gid_t.
> 
> It wasn't aligned with the rest (col 72).

That's fine.

> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> Would you prefer a separate patch for the cosmetic change?
> I put it in the same one, as it was in an adjacent line,
> and the diff looks good; to avoid noise in the log.
> But maybe a separate commit is better.

(It's fine as is.)

> 
> Thanks,
> 
> Alex
> 
>  man7/system_data_types.7 | 24 +++++++++++++++++++++++-
>  1 file changed, 23 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 59c64fb89..97411a193 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -111,7 +111,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
>  .IP
>  See also:
>  .BR fenv (3)
> -.\"------------------------------------- gid_t ----------------------/
> +.\"------------------------------------- fexcept_t --------------------/
> +.TP
> +.I fexcept_t
> +.IP
> +Include:
> +.IR <fenv.h> .
> +.IP
> +Represents the floating-point status flags collectively,
> +including any status the implementation associates with the flags.
> +A floating-point status flag is a system variable
> +whose value is set (but never cleared)
> +when a floating-point exception is raised,
> +which occurs as a side-effect of
> +exceptional floating-point arithmetic to provide auxiliary information.

The previous sentence is rather hard to parse. What (other) part of
the sentence does "to provide auxiliary information" relate to.
I suggest splitting the sentence in two and rewording.


> +A floating-point control mode is a system variable whose

You suddenly introduce "floating-point control mode" here. 
How does it relate to the preceding sentences? It's not clear.

Going off to look at the standard... I see that actually your
sentences come pretty much straight from the standard. So, first, I
think the standard could have been clearer here. Second, and more
important, (for copyright reasons) we are on shaky ground if we just
lift whole passages from the standard.  The text does really need to
be in your own words. Can you come up with something?

Alternatively, I guess we could explicitly quote the standard.
Something like

    POSIX describes this type as follows:
    .RS
    .PP
    [The text]
    .RE

> +value may be set by the user to affect
> +the subsequent behavior of floating-point arithmetic.
> +.IP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR fenv (3)
> +.\"------------------------------------- gid_t ------------------------/
>  .TP
>  .I gid_t
>  .IP
> 

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/