# HG changeset patch
# User Jeroen Demeyer
# Date 1357226522 3600
# Node ID e3505549ffa6387983bdb4032ee21f6cfa4ff8cb
# Parent dae73a4694cbe91a3b3219ea0a4da05d63073707
Fix broken doctests, mention known bug #12815
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
@@ 687,17 +687,17 @@
The file ``f.py`` is not imported when running tests unless you have
arranged that it be imported into your Sage environment, i.e. unless
its functions are available when you start Sage using the ``sage``
command. For example, the function ``cdd_convert`` in the file
``SAGE_ROOT/devel/sage/sage/geometry/polyhedra.py`` includes
an EXAMPLES block containing the following:
+command. For example, the function ``AA()`` in the file
+``SAGE_ROOT/devel/sage/sage/algebras/steenrod/steenrod_algebra.py``
+includes an EXAMPLES block containing the following:
::
 sage: from sage.geometry.polyhedra import cdd_convert
 sage: cdd_convert(' 1 1 0 0')
 [1, 1, 0, 0]
+ sage: from sage.algebras.steenrod.steenrod_algebra import AA as A
+ sage: A()
+ mod 2 Steenrod algebra, milnor basis
Sage does not know about the function ``cdd_convert`` by default, so
+Sage does not know about the function ``AA()`` by default, so
it needs to be imported before it is tested. Hence the first line in
the example.
@@ 717,20 +717,13 @@
``2/3`` as a rational instead of the Python int ``0``. For more
information on preparsing, see :ref:`sectionpreparsing`.
 If a test outputs to a file, the file should be in a temporary
 directory. For example (taken from the file
 ``SAGE_ROOT/devel/sage/sage/plot/plot.py``)::
+ If a test outputs to a file, the file should be a temporary file.
+ Use :func:`tmp_filename` to get a temporary filename,
+ or :func:`tmp_dir` to get a temporary directory.
+ For example (taken from the file
+ ``SAGE_ROOT/devel/sage/sage/plot/graphics.py``)::
 sage: fig.savefig(os.path.join(SAGE_TMP, 'test.png'))

 Here ``fig.savefig`` is the function doing the saving, ``SAGE_TMP``
 is a temporary directorythis variable will always be defined
 properly during automated testingand ``os.path.join`` is the
 preferred way to construct a path from a directory and a file. It
 works more generally than a Unixflavored construction like
 ``SAGE_TMP + '/test.png'``. If you want to use ``SAGE_TMP`` in
 Sage code, not just in a doctest, then you need to import
 it. Search the Sage code for examples.
+ sage: plot(x^2  5, (x, 0, 5), ymin=0).save(tmp_filename(ext='.png'))
 If a test line contains the text ``random``, it is executed by
``sagedoctest`` but ``sagedoctest`` does not check that the
@@ 799,7 +792,7 @@
sage: A = matrix(RDF, 8, range(64))
sage: U, S, V = A.SVD()
 sage: (U.transpose()*Uidentity_matrix(8)).norm() # abs tol 1e10
+ sage: (U.transpose()*Uidentity_matrix(8)).norm(p=2) # abs tol 1e10
0.0
The 8th cyclotomic field is generated by the complex number
@@ 814,9 +807,7 @@
::
 sage: K = CyclotomicField(8)
 sage: g = K.gen(0); g
 zeta8
+ sage: K. = CyclotomicField(8)
sage: N(zeta8) # absolute tolerance 1e15
0.707106781186548 + 0.707106781186547*I
@@ 824,15 +815,15 @@
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.
+ of the predicted value may be used. **This is actually broken**, see
+ :trac:`12815`.
::
sage: y = polygen(RDF, 'y')
 sage: p = (y  10^16)*(y10^(13))*(y2); p
 y^3 + (1e+16)*y^2 + (2e+16)*y  2000.0
+ sage: p = (y  10^16) * (y  10^13) * (y  2)
sage: p.roots(multiplicities=False)[2] # relative tol 1e10
 10^16
+ 1e16
 If a line contains ``todo: not implemented``, it is never
tested. It is good to include lines like this to make clear what we