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

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

[Alejandro Colomar]

Note:  I used this commit to fix the comment that separates with gid_t.

It wasn't aligned with the rest (col 72).

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.

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.
+A floating-point control mode is a system variable whose
+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
-- 
2.28.0

[PATCH 2/2] fexcept_t.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/fexcept_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/fexcept_t.3

diff --git a/man3/fexcept_t.3 b/man3/fexcept_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/fexcept_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

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

[Michael Kerrisk (man-pages)]

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/

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

[Alejandro Colomar]

Hi Michael,

On 2020-09-22 21:57, Michael Kerrisk (man-pages) wrote:
 >
 > 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

Yes.  A few patches ago I asked about that,
but you didn't answer to that specifically,
so I guessed that it was just fair use:

https://lore.kernel.org/linux-man/6dc80c25-85bf-925c-49c2-f79865027c0f@gmail.com/T/#mbfdcaf4fe625b4ff7ea90dc7396005fda1283612

But I guess explicitly quoting POSIX would be easy and better,
as you proposed.

I never used that type, so I wouldn't dare to describe it in my own words.

Thanks,

Alex

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

[Michael Kerrisk (man-pages)]

On 9/22/20 10:05 PM, Alejandro Colomar wrote:
> Hi Michael,
> 
> On 2020-09-22 21:57, Michael Kerrisk (man-pages) wrote:
>  >
>  > 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
> 
> Yes.  A few patches ago I asked about that,

Sorry -- there was so much mail from you that I missed it!

> but you didn't answer to that specifically,
> so I guessed that it was just fair use:
> 
> https://lore.kernel.org/linux-man/6dc80c25-85bf-925c-49c2-f79865027c0f@gmail.com/T/#mbfdcaf4fe625b4ff7ea90dc7396005fda1283612

Thanks for the pointer.

> But I guess explicitly quoting POSIX would be easy and better,
> as you proposed.

Yes, I think it''s simplest. (And a patch for 'fenv_t' may be
a good idea here as well.)

> I never used that type, so I wouldn't dare to describe it in my own words.

Okay.

Thanks,

Michael


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

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

[Alejandro Colomar]

Actually, POSIX already ripped (part of) the description from the C 
standard:

 > Represents the floating-point status flags collectively,
 > including any status the implementation associates with the flags.

This part is in the C standard (and POSIX also has it).

 > 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.
 > A floating-point control mode is a system variable whose
 > value may be set by the user to affect
 > the subsequent behavior of floating-point arithmetic.

And this is from POSIX only.

How would you go about it?


 > Represents the floating-point status flags collectively,
 > including any status the implementation associates with the flags.
POSIX describes a
 > [s/A//] floating-point status flag [s/is/as] 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.
According to POSIX,
 > [s/A/a/] floating-point control mode is a system variable whose
 > value may be set by the user to affect
 > the subsequent behavior of floating-point arithmetic.

Like this?

Thanks,

Alex

On 2020-09-22 22:14, Michael Kerrisk (man-pages) wrote:
> On 9/22/20 10:05 PM, Alejandro Colomar wrote:
>> Hi Michael,
>>
>> On 2020-09-22 21:57, Michael Kerrisk (man-pages) wrote:
>>   >
>>   > 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
>>
>> Yes.  A few patches ago I asked about that,
> 
> Sorry -- there was so much mail from you that I missed it!
> 
>> but you didn't answer to that specifically,
>> so I guessed that it was just fair use:
>>
>> https://lore.kernel.org/linux-man/6dc80c25-85bf-925c-49c2-f79865027c0f@gmail.com/T/#mbfdcaf4fe625b4ff7ea90dc7396005fda1283612
> 
> Thanks for the pointer.
> 
>> But I guess explicitly quoting POSIX would be easy and better,
>> as you proposed.
> 
> Yes, I think it''s simplest. (And a patch for 'fenv_t' may be
> a good idea here as well.)
> 
>> I never used that type, so I wouldn't dare to describe it in my own words.
> 
> Okay.
> 
> Thanks,
> 
> Michael
> 
> 

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

[Michael Kerrisk (man-pages)]

On 9/22/20 10:32 PM, Alejandro Colomar wrote:
> Actually, POSIX already ripped (part of) the description from the C 
> standard:
> 
>  > Represents the floating-point status flags collectively,
>  > including any status the implementation associates with the flags.
> 
> This part is in the C standard (and POSIX also has it).

I think they probably have an agreement for this :-).

>  > 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.
>  > A floating-point control mode is a system variable whose
>  > value may be set by the user to affect
>  > the subsequent behavior of floating-point arithmetic.
> 
> And this is from POSIX only.
> 
> How would you go about it?

Just quote POSIX (no need to mention the C standard
when quoting, I think).

>  > Represents the floating-point status flags collectively,
>  > including any status the implementation associates with the flags.
> POSIX describes a
>  > [s/A//] floating-point status flag [s/is/as] 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.
> According to POSIX,
>  > [s/A/a/] floating-point control mode is a system variable whose
>  > value may be set by the user to affect
>  > the subsequent behavior of floating-point arithmetic.

I think so. 

Thanks,

Michael

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

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

On 2020-09-23 10:36, Michael Kerrisk (man-pages) wrote:
> [Thorsten, I have removed you from the CC because I get persistent
> bounce messages whenever I send you mail. Hopefully you see this reply
> via the list.]

Me too :(

> While I'm pretty sure they would allow this without problem, I'm
> wondering if it's worth the effort. Ideally, we'd have text written by
> someone in their own words. Reproducing the text of the standard has
> limited value, since people can in any case consult the standard
> directly.
> 
> Alex, how about we just go much simpler, saying something like:
> 
> [[
> This type represents floating-point status flags; for further details
> see fenv(3).
> ]]

Nice and simple.

Thanks,

Alex

 man7/system_data_types.7 | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 4352d6a6e..ea3e25175 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -110,7 +110,22 @@ 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
+This type represents the floating-point status flags collectively;
+for further details see
+.BR fenv (3).
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR fenv (3)
+.\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t
 .IP
-- 
2.28.0

[PATCH v2 2/2] fexcept_t.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/fexcept_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/fexcept_t.3

diff --git a/man3/fexcept_t.3 b/man3/fexcept_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/fexcept_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

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

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/23/20 3:17 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> On 2020-09-23 10:36, Michael Kerrisk (man-pages) wrote:
>> [Thorsten, I have removed you from the CC because I get persistent
>> bounce messages whenever I send you mail. Hopefully you see this reply
>> via the list.]
> 
> Me too :(
> 
>> While I'm pretty sure they would allow this without problem, I'm
>> wondering if it's worth the effort. Ideally, we'd have text written by
>> someone in their own words. Reproducing the text of the standard has
>> limited value, since people can in any case consult the standard
>> directly.
>>
>> Alex, how about we just go much simpler, saying something like:
>>
>> [[
>> This type represents floating-point status flags; for further details
>> see fenv(3).
>> ]]
> 
> Nice and simple.
> 
> Thanks,
> 
> Alex

Thanks! Patch applied.

Cheers,

Michael


>  man7/system_data_types.7 | 17 ++++++++++++++++-
>  1 file changed, 16 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 4352d6a6e..ea3e25175 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -110,7 +110,22 @@ 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
> +This type represents the floating-point status flags collectively;
> +for further details see
> +.BR fenv (3).
> +.IP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR fenv (3)
> +.\"------------------------------------- gid_t ------------------------/
>  .TP
>  .I gid_t
>  .IP
> 


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

Re: [PATCH v2 2/2] fexcept_t.3: New link to system_data_types(7)

[Michael Kerrisk (man-pages)]

On 9/23/20 3:17 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Thanks, Alex. Patch applied.

Cheers,

Michael


> ---
>  man3/fexcept_t.3 | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 man3/fexcept_t.3
> 
> diff --git a/man3/fexcept_t.3 b/man3/fexcept_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/fexcept_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


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