| Message ID | 20170616110951.24732-4-ricaljasan@pacific.net |
|---|---|
| State | New |
| Headers | show |
On Fri, 16 Jun 2017, Rical Jasan wrote: > * manual/lang.texi (LDBL_MANT_DIG): Add annotation. > (LDBL_DIG): Likewise. > (LDBL_MIN_EXP): Likewise. > (LDBL_MIN_10_EXP): Likewise. > (LDBL_MAX_EXP): Likewise. > (LDBL_MAX_10_EXP): Likewise. > (LDBL_MAX): Likewise. > (LDBL_MIN): Likewise. > (LDBL_EPSILON): Likewise. > (FLT_ROUNDS): Change standard from ISO to C90. > (FLT_RADIX): Likewise. > (FLT_MANT_DIG, DBL_MANT_DIG): Likewise. > (FLT_DIG, DBL_DIG): Likewise. > (FLT_MIN_EXP, DBL_MIN_EXP): Likewise. > (FLT_MIN_10_EXP, DBL_MIN_10_EXP): Likewise. > (FLT_MAX_EXP, DBL_MAX_EXP): Likewise. > (FLT_MAX_10_EXP, DBL_MAX_10_EXP): Likewise. > (FLT_MAX, DBL_MAX): Likewise. > (FLT_MIN, DBL_MIN): Likewise. > (FLT_EPSILON, DBL_EPSILON): Likewise. OK, but if we're making such changes from ISO to C90 we should have a comment (or visible text in the manual) somewhere (maybe on the definition of @standards) stating the preferred forms of standard names, and what they mean, and how combinations of standards should be represented.
On 06/16/2017 08:48 AM, Joseph Myers wrote: > On Fri, 16 Jun 2017, Rical Jasan wrote: > >> * manual/lang.texi (LDBL_MANT_DIG): Add annotation. >> (LDBL_DIG): Likewise. >> (LDBL_MIN_EXP): Likewise. >> (LDBL_MIN_10_EXP): Likewise. >> (LDBL_MAX_EXP): Likewise. >> (LDBL_MAX_10_EXP): Likewise. >> (LDBL_MAX): Likewise. >> (LDBL_MIN): Likewise. >> (LDBL_EPSILON): Likewise. >> (FLT_ROUNDS): Change standard from ISO to C90. >> (FLT_RADIX): Likewise. >> (FLT_MANT_DIG, DBL_MANT_DIG): Likewise. >> (FLT_DIG, DBL_DIG): Likewise. >> (FLT_MIN_EXP, DBL_MIN_EXP): Likewise. >> (FLT_MIN_10_EXP, DBL_MIN_10_EXP): Likewise. >> (FLT_MAX_EXP, DBL_MAX_EXP): Likewise. >> (FLT_MAX_10_EXP, DBL_MAX_10_EXP): Likewise. >> (FLT_MAX, DBL_MAX): Likewise. >> (FLT_MIN, DBL_MIN): Likewise. >> (FLT_EPSILON, DBL_EPSILON): Likewise. > > OK, but if we're making such changes from ISO to C90 we should have a > comment (or visible text in the manual) somewhere (maybe on the definition > of @standards) stating the preferred forms of standard names, and what > they mean, and how combinations of standards should be represented. I agree. One of my eventual goals is to add canonical standards names as part of summary.pl's syntax checking. At (or before) that point -- whenever we reach consensus on what the canonical standards should be -- I envision an update, maybe to creature.texi, where we've talked about having the rendered Standards: refer to (starting around [1]), that will meet your above request (visibly). The reason I extended this patch to touch all the FLT_*, DBL_*, and LDBL_* constants was because of your comment in [2]: "The FLT_* and LDBL_* constants are C90." It seemed more efficient to do it now, rather than having to (remember to) dig back through old threads, yet again, later. Another consideration I held was your suggested list of standards in [3], which used C90 and not ISO. I understand that list was merely a suggestion (and some amendments were also offered, IIRC), but I've got to start somewhere, and I like the more-specific standards. (In fact, I wouldn't argue against "ISO C90" since I think having the standards body be explicit where possible is better, but we will theoretically be referencing some documentation of the standards anyway, so an abbreviated form in @standards could be fine if it makes the boilerplate more palatable.) The combinations issue will have some examples coming up soon. I've been deferring them until later in the completion patches, so the simple stuff hopefully gets reviewed sooner and out of the way. There are still 2 other patches to complete lang.texi, by the way. The additional ISO->C90 conversions weren't actually what I was referring to when I said, "this file is better served by a different set of changes". That was opportunistic when I encountered your comment above while reviewing yours and Zack's reviews of the completion patch in v2. So my question is, does, "OK, but.." mean, "commit and don't forget to ... later", or, "looks good but also needs ... first"? I can cut the conversion out easily enough and still complete the annotations. Rical [1] https://sourceware.org/ml/libc-alpha/2016-11/msg01100.html [2] https://sourceware.org/ml/libc-alpha/2016-12/msg00183.html [3] https://sourceware.org/ml/libc-alpha/2016-11/msg00898.html
On Fri, 16 Jun 2017, Rical Jasan wrote: > So my question is, does, "OK, but.." mean, "commit and don't forget to > ... later", or, "looks good but also needs ... first"? I can cut the > conversion out easily enough and still complete the annotations. In this case, "commit and don't forget to ... later" together with "while there isn't such a list, you need to be extra careful about being consistent about naming of standards in annotations you add or refine, and about what if anything should be listed in @standards in the way of information about a function's history beyond which standards supported by the glibc headers it's in".
On 06/19/2017 07:53 AM, Joseph Myers wrote: > On Fri, 16 Jun 2017, Rical Jasan wrote: > >> So my question is, does, "OK, but.." mean, "commit and don't forget to >> ... later", or, "looks good but also needs ... first"? I can cut the >> conversion out easily enough and still complete the annotations. > > In this case, "commit and don't forget to ... later" together with "while > there isn't such a list, you need to be extra careful about being > consistent about naming of standards in annotations you add or refine, and > about what if anything should be listed in @standards in the way of > information about a function's history beyond which standards supported by > the glibc headers it's in". Duly noted, and committed (b8216e82). Thank you, Rical
diff --git a/manual/lang.texi b/manual/lang.texi index cacbdfb7c5..c4b641d4e1 100644 --- a/manual/lang.texi +++ b/manual/lang.texi @@ -969,7 +969,7 @@ supported are suitable. @vtable @code @item FLT_ROUNDS -@standards{ISO, float.h} +@standards{C90, float.h} This value characterizes the rounding mode for floating point addition. The following values indicate standard rounding modes: @@ -1008,14 +1008,14 @@ the IEEE single-precision standard. @end smallexample @item FLT_RADIX -@standards{ISO, float.h} +@standards{C90, float.h} This is the value of the base, or radix, of the exponent representation. This is guaranteed to be a constant expression, unlike the other macros described in this section. The value is 2 on all machines we know of except the IBM 360 and derivatives. @item FLT_MANT_DIG -@standards{ISO, float.h} +@standards{C90, float.h} This is the number of base-@code{FLT_RADIX} digits in the floating point mantissa for the @code{float} data type. The following expression yields @code{1.0} (even though mathematically it should not) due to the @@ -1032,14 +1032,14 @@ where @code{radix} appears @code{FLT_MANT_DIG} times. @item DBL_MANT_DIG @itemx LDBL_MANT_DIG -@standardsx{DBL_MANT_DIG, ISO, float.h} +@standards{C90, float.h} This is the number of base-@code{FLT_RADIX} digits in the floating point mantissa for the data types @code{double} and @code{long double}, respectively. @comment Extra blank lines make it look better. @item FLT_DIG -@standards{ISO, float.h} +@standards{C90, float.h} This is the number of decimal digits of precision for the @code{float} data type. Technically, if @var{p} and @var{b} are the precision and @@ -1054,14 +1054,14 @@ The value of this macro is supposed to be at least @code{6}, to satisfy @item DBL_DIG @itemx LDBL_DIG -@standardsx{DBL_DIG, ISO, float.h} +@standards{C90, float.h} These are similar to @code{FLT_DIG}, but for the data types @code{double} and @code{long double}, respectively. The values of these macros are supposed to be at least @code{10}. @item FLT_MIN_EXP -@standards{ISO, float.h} +@standards{C90, float.h} This is the smallest possible exponent value for type @code{float}. More precisely, it is the minimum negative integer such that the value @code{FLT_RADIX} raised to this power minus 1 can be represented as a @@ -1069,25 +1069,25 @@ normalized floating point number of type @code{float}. @item DBL_MIN_EXP @itemx LDBL_MIN_EXP -@standardsx{DBL_MIN_EXP, ISO, float.h} +@standards{C90, float.h} These are similar to @code{FLT_MIN_EXP}, but for the data types @code{double} and @code{long double}, respectively. @item FLT_MIN_10_EXP -@standards{ISO, float.h} +@standards{C90, float.h} This is the minimum negative integer such that @code{10} raised to this power minus 1 can be represented as a normalized floating point number of type @code{float}. This is supposed to be @code{-37} or even less. @item DBL_MIN_10_EXP @itemx LDBL_MIN_10_EXP -@standardsx{DBL_MIN_10_EXP, ISO, float.h} +@standards{C90, float.h} These are similar to @code{FLT_MIN_10_EXP}, but for the data types @code{double} and @code{long double}, respectively. @item FLT_MAX_EXP -@standards{ISO, float.h} +@standards{C90, float.h} This is the largest possible exponent value for type @code{float}. More precisely, this is the maximum positive integer such that value @code{FLT_RADIX} raised to this power minus 1 can be represented as a @@ -1095,24 +1095,24 @@ floating point number of type @code{float}. @item DBL_MAX_EXP @itemx LDBL_MAX_EXP -@standardsx{DBL_MAX_EXP, ISO, float.h} +@standards{C90, float.h} These are similar to @code{FLT_MAX_EXP}, but for the data types @code{double} and @code{long double}, respectively. @item FLT_MAX_10_EXP -@standards{ISO, float.h} +@standards{C90, float.h} This is the maximum positive integer such that @code{10} raised to this power minus 1 can be represented as a normalized floating point number of type @code{float}. This is supposed to be at least @code{37}. @item DBL_MAX_10_EXP @itemx LDBL_MAX_10_EXP -@standardsx{DBL_MAX_10_EXP, ISO, float.h} +@standards{C90, float.h} These are similar to @code{FLT_MAX_10_EXP}, but for the data types @code{double} and @code{long double}, respectively. @item FLT_MAX -@standards{ISO, float.h} +@standards{C90, float.h} The value of this macro is the maximum number representable in type @code{float}. It is supposed to be at least @code{1E+37}. The value @@ -1122,14 +1122,14 @@ The smallest representable number is @code{- FLT_MAX}. @item DBL_MAX @itemx LDBL_MAX -@standardsx{DBL_MAX, ISO, float.h} +@standards{C90, float.h} These are similar to @code{FLT_MAX}, but for the data types @code{double} and @code{long double}, respectively. The type of the macro's value is the same as the type it describes. @item FLT_MIN -@standards{ISO, float.h} +@standards{C90, float.h} The value of this macro is the minimum normalized positive floating point number that is representable in type @code{float}. It is supposed @@ -1137,14 +1137,14 @@ to be no more than @code{1E-37}. @item DBL_MIN @itemx LDBL_MIN -@standardsx{DBL_MIN, ISO, float.h} +@standards{C90, float.h} These are similar to @code{FLT_MIN}, but for the data types @code{double} and @code{long double}, respectively. The type of the macro's value is the same as the type it describes. @item FLT_EPSILON -@standards{ISO, float.h} +@standards{C90, float.h} This is the difference between 1 and the smallest floating point number of type @code{float} that is greater than 1. It's supposed to @@ -1152,7 +1152,7 @@ be no greater than @code{1E-5}. @item DBL_EPSILON @itemx LDBL_EPSILON -@standardsx{DBL_EPSILON, ISO, float.h} +@standards{C90, float.h} These are similar to @code{FLT_EPSILON}, but for the data types @code{double} and @code{long double}, respectively. The type of the