gmp 4.1 documentation improvement suggestions

[Vincent Lefevre]

On Mon, Dec 09, 2002 at 12:53:20 -0500, Serge Winitzki wrote:
> 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."

I think the manual is clear (well, almost...); it says:

    The precision of a calculation is defined as follows: Compute
    the requested operation exactly (with ``infinite precision''),
    and round the result to the destination variable precision with
    the given rounding mode.

However, this is not a definition of "the precision of a calculation",
but the definition of the result of an operation (function call). Also,
I don't understand the following two sentences:

    Even if the user has asked for a very high precision, MP will
    not calculate with superfluous digits. For example, 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.

They should probably be removed.

> 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.

One should probably say "... when the result is equal to the original
value of x...".

-- 
Vincent Lefèvre <vincent@vinc17.org> - Web: <http://www.vinc17.org/> - 100%
validated (X)HTML - Acorn Risc PC, Yellow Pig 17, Championnat International
des Jeux Mathématiques et Logiques, TETRHEX, etc.
Work: CR INRIA - computer arithmetic / SPACES project at LORIA