gmp 4.1 documentation improvement suggestions

[Serge Winitzki]

>    It's surprising that mpfr doesn't track precision. Its documentation
>    seems to say that the main difference between mpfr_* and mpf_* is that
>    mpfr knows the "actual exact number of precise bits" in any number. They
>    use this wording in the manual. This seems to suggest that e.g.
>    "10.010-10.000=0.0100" and the result will know that it has 2 precise
>    bits. At least I thought so after reading the mpfr manual and after 
>    glancing at the code for adding two numbers in mpfr_add. Maybe I was 
>    mistaken.
> 
> mpfr is only an extension to multiple-precision of the IEEE 754 fixed
> precision arithmetic. The mpfr documentation doesn't say that mpfr knows
> the "actual exact number of precise bits" (otherwise please tell us where,
> it is a mistake) but that whenever you ask for p bits of precision for a
> mpfr variable, you get *exactly* p bits.

I looked at the mpfr manual again; it doesn't quite say explicitly what
I thought it implied (it doesn't say that mpfr tracks precision), but I
still think it could be made clearer. On page 7 ("5. Floating-point 
functions", paragraph 4):

"...if two low-precision numbers of nearly equal magnitude are added, 
the precision of the result will be limited to what is required to 
represent the result accurately."

This seems to reinforce the impression that any mpfr object knows how
many precise digits it has after any arithmetic operation. I think the
problem is the wording "precision of x", which here refers to the actual
obtained precision of the real number x, and but later in the manual it
refers to the value stored in the mpfr object x. It seems that the
manual uses these two meanings of the phrase "precision of x"
interchangeably, and that's why it made this impression on me. Now that
I looked more closely, it seems that the above is the only place in the
manual where "precision of x" is ambiguously used.

Later in descriptions of individual functions, for example, I find:

Page 8: "int mpfr_round_prec() Rounds x according to rnd with precision
prec, which may be different from that of x. ... In both cases, the
precision of x is changed to prec. The returned value is zero when the
result is exact, positive when it is greater than the original value of
x ..."

Here I read "result is exact" to mean "the object x knew how many digits
it had, and we have guessed it correctly". But of course this refers
only to the value of precision stored in x, that may have little to do
with the actual achieved precision of the approximation of some real
number.



-- 
	Serge