[04/10] system_data_types.7: Add float_t

Message ID 20200925073140.173394-5-colomar.6.4.3@gmail.com
State Superseded
Headers show
Series
  • Add types, and some fixes
Related show

Commit Message

Stafford Horne via Libc-alpha Sept. 25, 2020, 7:31 a.m.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

---
 man7/system_data_types.7 | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

-- 
2.28.0

Comments

Stafford Horne via Libc-alpha Sept. 25, 2020, 8:13 a.m. | #1
Hi Alex,

A few comments here that also apply for the double_t patch. 
Could you revise please?

On 9/25/20 9:31 AM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

> ---

>  man7/system_data_types.7 | 36 ++++++++++++++++++++++++++++++++++++

>  1 file changed, 36 insertions(+)

> 

> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7

> index b04457bbf..238b9593b 100644

> --- a/man7/system_data_types.7

> +++ b/man7/system_data_types.7

> @@ -147,6 +147,42 @@ Conforming to: C99 and later; POSIX.1-2001 and later.

>  .IP

>  See also:

>  .BR fenv (3)

> +.\"------------------------------------- float_t ----------------------/

> +.TP

> +.I float_t

> +.IP

> +Include:

> +.IR <math.h> .

> +.IP

> +The implementation's most efficient floating type at least as wide as

> +.IR float .


The C standard is rather terse here. Perhaps we could make the 
reader's life a little easier. How about something like:

[[
This a type that is intended to be the implementation's
most efficient floating type that is at least as wide as
.IR float .
]]

> +Its type depends on the value of the macro

> +.BR FLT_EVAL_METHOD :

> +.RS

> +.IP *

> +0;

> +.I float_t

> +is

> +.IR float .

> +.IP *

> +1;

> +.I float_t

> +is

> +.IR double .

> +.IP *

> +2;

> +.I float_t

> +is

> +.IR "long double" .

> +.IP *

> +Other implementation-defined values.

> +.RE


I think we can format this better as a hanging list.
Something like this:

[[
.TP
0
.I float_t
is
.IR float .
.TP
1
.I float_t
is
.IR double .
.TP
2
.I float_t
is
.IR "long double" .
.IP
For other values of
.BR FLT_EVAL_METHOD ,
the type of
.I float_t
is implementation-defined.
]]

> +.IP

> +Conforming to: C99 and later; POSIX.1-2001 and later.

> +.IP

> +See also the

> +.I double_t

> +type in this page.

>  .\"------------------------------------- gid_t ------------------------/

>  .TP

>  .I gid_t


Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Stafford Horne via Libc-alpha Sept. 25, 2020, 8:22 a.m. | #2
Hi Michael,

On 2020-09-25 10:13, Michael Kerrisk (man-pages) wrote:
> Hi Alex,

> 

> A few comments here that also apply for the double_t patch.

> Could you revise please?

> 

> On 9/25/20 9:31 AM, Alejandro Colomar wrote:

>> +The implementation's most efficient floating type at least as wide as

>> +.IR float .

> 

> The C standard is rather terse here. Perhaps we could make the

> reader's life a little easier. How about something like:

> 

> [[

> This a type that is intended to be the implementation's

> most efficient floating type that is at least as wide as

> .IR float .

> ]]


I removed the "intended" part to simplify it a bit. Do you prefer to 
keep it?

> 

>> +Its type depends on the value of the macro

>> +.BR FLT_EVAL_METHOD :

>> +.RS

>> +.IP *

>> +0;

>> +.I float_t

>> +is

>> +.IR float .

>> +.IP *

>> +1;

>> +.I float_t

>> +is

>> +.IR double .

>> +.IP *

>> +2;

>> +.I float_t

>> +is

>> +.IR "long double" .

>> +.IP *

>> +Other implementation-defined values.

>> +.RE

> 

> I think we can format this better as a hanging list.

> Something like this:

> 

> [[

> .TP

> 0

> .I float_t

> is

> .IR float .

> .TP

> 1

> .I float_t

> is

> .IR double .

> .TP

> 2

> .I float_t

> is

> .IR "long double" .

> .IP

> For other values of

> .BR FLT_EVAL_METHOD ,

> the type of

> .I float_t

> is implementation-defined.

> ]

Yes, I wasn't convinced by my formatting.  Thanks!

I'll fix this patch, and the srcfix that depends on this too.

BTW, I'll also add a note that FLT_EVAL_METHOD is defined in <float.h>
Would you add that to "Notes", or as part of the description?

> 

>> +.IP

>> +Conforming to: C99 and later; POSIX.1-2001 and later.

>> +.IP

>> +See also the

>> +.I double_t

>> +type in this page.

>>   .\"------------------------------------- gid_t ------------------------/

>>   .TP

>>   .I gid_t

> 

> Thanks,

> 

> Michael

> 

> 

Thanks,

Alex
Stafford Horne via Libc-alpha Sept. 25, 2020, 9:30 a.m. | #3
Hi Alex,

On 9/25/20 10:22 AM, Alejandro Colomar wrote:
> Hi Michael,

> 

> On 2020-09-25 10:13, Michael Kerrisk (man-pages) wrote:

>> Hi Alex,

>>

>> A few comments here that also apply for the double_t patch.

>> Could you revise please?

>>

>> On 9/25/20 9:31 AM, Alejandro Colomar wrote:

>>> +The implementation's most efficient floating type at least as wide as

>>> +.IR float .

>>

>> The C standard is rather terse here. Perhaps we could make the

>> reader's life a little easier. How about something like:

>>

>> [[

>> This a type that is intended to be the implementation's

>> most efficient floating type that is at least as wide as

>> .IR float .

>> ]]

> 

> I removed the "intended" part to simplify it a bit. Do you prefer to 

> keep it?


Well, as long as you are going to lift the detail about "most
efficient" from the C standard, I'd be inclined to keep 
the word "intended" from the standard as well. But I do not feel
strongly about it.

>>> +Its type depends on the value of the macro

>>> +.BR FLT_EVAL_METHOD :

>>> +.RS

>>> +.IP *

>>> +0;

>>> +.I float_t

>>> +is

>>> +.IR float .

>>> +.IP *

>>> +1;

>>> +.I float_t

>>> +is

>>> +.IR double .

>>> +.IP *

>>> +2;

>>> +.I float_t

>>> +is

>>> +.IR "long double" .

>>> +.IP *

>>> +Other implementation-defined values.

>>> +.RE

>>

>> I think we can format this better as a hanging list.

>> Something like this:

>>

>> [[

>> .TP

>> 0

>> .I float_t

>> is

>> .IR float .

>> .TP

>> 1

>> .I float_t

>> is

>> .IR double .

>> .TP

>> 2

>> .I float_t

>> is

>> .IR "long double" .

>> .IP

>> For other values of

>> .BR FLT_EVAL_METHOD ,

>> the type of

>> .I float_t

>> is implementation-defined.

>> ]

> Yes, I wasn't convinced by my formatting.  Thanks!

> 

> I'll fix this patch, and the srcfix that depends on this too.


Okay.

> BTW, I'll also add a note that FLT_EVAL_METHOD is defined in <float.h>

> Would you add that to "Notes", or as part of the description?


As part of the description I think. (And I don't mind if it's 
repeated in the double_t description.)

Cheers,

Michael

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

Patch

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index b04457bbf..238b9593b 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -147,6 +147,42 @@  Conforming to: C99 and later; POSIX.1-2001 and later.
 .IP
 See also:
 .BR fenv (3)
+.\"------------------------------------- float_t ----------------------/
+.TP
+.I float_t
+.IP
+Include:
+.IR <math.h> .
+.IP
+The implementation's most efficient floating type at least as wide as
+.IR float .
+Its type depends on the value of the macro
+.BR FLT_EVAL_METHOD :
+.RS
+.IP *
+0;
+.I float_t
+is
+.IR float .
+.IP *
+1;
+.I float_t
+is
+.IR double .
+.IP *
+2;
+.I float_t
+is
+.IR "long double" .
+.IP *
+Other implementation-defined values.
+.RE
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also the
+.I double_t
+type in this page.
 .\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t