# HG changeset patch
# User Rob Beezer <beezer@ups.edu>
# Date 1314202161 25200
# Node ID 19869e55d88e0b45c9ad19f73c949f7e925d29bf
# Parent  f32a34f366fbbd1b1942c4585bdd0c61e2fa0a4c
10952: reviewer documentation additions

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
@@ -727,21 +727,67 @@
        sage: E.regulator()              # long time (1 second)
        0.0511114082399688
 
--  If a line contains ``tol`` or ``tolerance, numerical results are only
-   verified to the given tolerance. This may be prefixed by ``abs[olute``
+-  If a line contains ``tol`` or ``tolerance``, numerical results are only
+   verified to the given tolerance. This may be prefixed by ``abs[olute]``
    or ``rel[ative]`` to specify whether to measure absolute or relative
-   error; defaults to relative error except when the expected value is
-   exactly zero:
+   error; this defaults to relative error except when the expected value 
+   is exactly zero:
 
    ::
 
-           sage: RDF(pi)                               # abs tol 1e-5
-           3.14159
-           sage: [10^n for n in [0.0 .. 4]]            # rel tol 2e-4
-           [0.9999, 10.001, 100.01, 999.9, 10001]
+       sage: RDF(pi)                               # abs tol 1e-5
+       3.14159
+       sage: [10^n for n in [0.0 .. 4]]            # rel tol 2e-4
+       [0.9999, 10.001, 100.01, 999.9, 10001]
 
    This can be useful when the exact output is subject to rounding error
-   and/or processor floating point arithmetic variation.
+   and/or processor floating point arithmetic variation.  Here are some 
+   more examples.
+   
+   A singular value decomposition of a matrix will produce two unitary
+   matrices.  Over the reals, this means the inverse of the matrix is
+   equal to its transpose.  We test this result by applying the norm to
+   a matrix difference.  The result will usually be a "small" number,
+   distinct from zero.
+   
+   ::
+
+       sage: A = matrix(RDF, 8, range(64))
+       sage: U, S, V = A.SVD()
+       sage: (U.transpose()*U-identity_matrix(8)).norm()    # abs tol 1e-10
+       0.0
+       
+   The 8-th 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.
+   
+   ::
+       
+       sage: K = CyclotomicField(8)                     
+       sage: g = K.gen(0); g
+       zeta8
+       sage: N(zeta8)                             # absolute tolerance 1e-15
+       0.707106781186548 + 0.707106781186547*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. 
+    
+   ::
+
+       sage: y = polygen(RDF, 'y')
+       sage: p = (y - 10^16)*(y-10^(-13))*(y-2); p
+       y^3 + (-1e+16)*y^2 + (2e+16)*y - 2000.0
+       sage: p.roots(multiplicities=False)[2]     # relative tol 1e-10
+       10^16
 
 -  If a line contains ``todo: not implemented``, it is never
    tested. It is good to include lines like this to make clear what we