Patchwork manual: Complete @standards in lang.texi.

login
register
mail settings
Submitter Rical Jasan
Date June 16, 2017, 11:09 a.m.
Message ID <20170616110951.24732-4-ricaljasan@pacific.net>
Download mbox | patch
Permalink /patch/21047/
State New
Headers show

Comments

Rical Jasan - June 16, 2017, 11:09 a.m.
* 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.
---
 manual/lang.texi | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)
Joseph Myers - June 16, 2017, 3:48 p.m.
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.
Rical Jasan - June 17, 2017, 5:50 a.m.
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
Joseph Myers - June 19, 2017, 2:53 p.m.
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".
Rical Jasan - June 20, 2017, 11:34 a.m.
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

Patch

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