# HG changeset patch
# User Jeroen Demeyer
# Date 1357636755 3600
# Node ID 0d68a886ccf3a651fd5bfd92f11c55a59bed3d75
# Parent 7b89b8deffb55ebc7951552bbbf3d2009b8e97ec
Fix documentation for "tolerance" doctests
diff git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
 a/doc/en/developer/conventions.rst
+++ b/doc/en/developer/conventions.rst
@@ 795,34 +795,22 @@
0.0
The 8th cyclotomic field is generated by the complex number
 `e^\frac{i\pi}{4}`. Here we compute a numerical approximation.
 The value provided in the source of the doctest
 (``0.707106781186548 + 0.707106781186547*I``), and the value
 computed by the tested instance of Sage (``N(zeta8)``) are
 subtracted from each other and fed into the ``abs()`` function
 for comparison to the tolerance. So the only prerequisite for
 using this feature is that the ``abs()`` function may be applied.
 Of course, for a relative tolerance, division must also be possible.

 ::
+ `e^\frac{i\pi}{4}`. Here we compute a numerical approximation::
sage: K. = CyclotomicField(8)
 sage: N(zeta8) # absolute tolerance 1e15
 0.707106781186548 + 0.707106781186547*I
+ sage: N(zeta8) # absolute tolerance 1e10
+ 0.7071067812 + 0.7071067812*I
 A relative tolerance on a root of a polynomial. Notice that
 the root should normally print as ``1e+16``, or something similar.
 However, the tolerance testing causes the doctest framework to
 use the output in a *computation*, so any valid text representation
 of the predicted value may be used. **This is actually broken**, see
 :trac:`12815`.

 ::
+ The "tolerance" feature checks for floatingpoint literals, which
+ may occur anywhere in the doctest output, for example as polynomial
+ coefficients::
sage: y = polygen(RDF, 'y')
 sage: p = (y  10^16) * (y  10^13) * (y  2)
 sage: p.roots(multiplicities=False)[2] # relative tol 1e10
 1e16
+ sage: p = (y  10^10) * (y  1); p
+ y^2  10000000001.0*y + 10000000000.0
+ sage: p # rel tol 1e9
+ y^2  1e10*y + 1e10
+
 If a line contains ``todo: not implemented``, it is never
tested. It is good to include lines like this to make clear what we