diff mbox series

[04/10] system_data_types.7: Add float_t

Message ID 20200925073140.173394-5-colomar.6.4.3@gmail.com
State Not Applicable
Headers show
Series Add types, and some fixes | expand

Commit Message

Alejandro Colomar Sept. 25, 2020, 7:31 a.m. UTC
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

Comments

Michael Kerrisk \(man-pages\) Sept. 25, 2020, 8:13 a.m. UTC | #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
Alejandro Colomar Sept. 25, 2020, 8:22 a.m. UTC | #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
Michael Kerrisk \(man-pages\) Sept. 25, 2020, 9:30 a.m. UTC | #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
diff mbox series

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