Make sys.xxx variable references into links, note that print_last only

works when an exception gets to the interactive prompt, and update the
examples after testing.  The last one is now a valid Sphinx doctest,
but of the preceding two one can't be made a doctest and the other one
I'm postponing to 3.x because sphinx handles doctests as Unicode strings
and that makes the 2.x output confusing.

1 files changed, 22 insertions, 28 deletions

diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 31a4583..adf0648 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -14,7 +14,7 @@ interpreter.
 .. index:: object: traceback
 
 The module uses traceback objects --- this is the object type that is stored in
-the variables ``sys.exc_traceback`` (deprecated) and ``sys.last_traceback`` and
+the variables :data:`sys.exc_traceback` (deprecated) and :data:`sys.last_traceback` and
 returned as the third item from :func:`sys.exc_info`.
 
 The module defines the following functions:
@@ -58,7 +58,8 @@ The module defines the following functions:
 .. function:: print_last([limit[, file]])
 
    This is a shorthand for ``print_exception(sys.last_type, sys.last_value,
-   sys.last_traceback, limit, file)``.
+   sys.last_traceback, limit, file)``.  In general it will work only after
+   an exception has reached an interactive prompt (see :data:`sys.last_type`).
 
 
 .. function:: print_stack([f[, limit[, file]]])
@@ -195,27 +196,25 @@ exception and traceback::
        print "*** format_tb:"
        print repr(traceback.format_tb(exceptionTraceback))
        print "*** tb_lineno:", traceback.tb_lineno(exceptionTraceback)
-   print "*** print_last:"
-   traceback.print_last()
 
 
 The output for the example would look similar to this::
 
    *** print_tb:
-     File "<doctest>", line 9, in <module>
+     File "<doctest...>", line 10, in <module>
        lumberjack()
    *** print_exception:
    Traceback (most recent call last):
-     File "<doctest>", line 9, in <module>
+     File "<doctest...>", line 10, in <module>
        lumberjack()
-     File "<doctest>", line 3, in lumberjack
+     File "<doctest...>", line 4, in lumberjack
        bright_side_of_death()
    IndexError: tuple index out of range
    *** print_exc:
    Traceback (most recent call last):
-     File "<doctest>", line 9, in <module>
+     File "<doctest...>", line 10, in <module>
        lumberjack()
-     File "<doctest>", line 3, in lumberjack
+     File "<doctest...>", line 4, in lumberjack
        bright_side_of_death()
    IndexError: tuple index out of range
    *** format_exc, first and last line:
@@ -223,27 +222,19 @@ The output for the example would look similar to this::
    IndexError: tuple index out of range
    *** format_exception:
    ['Traceback (most recent call last):\n',
-    '  File "<doctest>", line 9, in <module>\n    lumberjack()\n',
-    '  File "<doctest>", line 3, in lumberjack\n    bright_side_of_death()\n',
-    '  File "<doctest>", line 6, in bright_side_of_death\n    return tuple()[0]\n',
+    '  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
+    '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
+    '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n',
     'IndexError: tuple index out of range\n']
    *** extract_tb:
-   [('<doctest>', 9, '<module>', 'lumberjack()'),
-    ('<doctest>', 3, 'lumberjack', 'bright_side_of_death()'),
-    ('<doctest>', 6, 'bright_side_of_death', 'return tuple()[0]')]
+   [('<doctest...>', 10, '<module>', 'lumberjack()'),
+    ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
+    (u'<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
    *** format_tb:
-   ['  File "<doctest>", line 9, in <module>\n    lumberjack()\n',
-    '  File "<doctest>", line 3, in lumberjack\n    bright_side_of_death()\n',
-    '  File "<doctest>", line 6, in bright_side_of_death\n    return tuple()[0]\n']
-   *** tb_lineno: 2
-   *** print_last:
-   Traceback (most recent call last):
-     File "<doctest>", line 9, in <module>
-       lumberjack()
-     File "<doctest>", line 3, in lumberjack
-       bright_side_of_death()
-   IndexError: tuple index out of range
-
+   ['  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
+    '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
+    '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n']
+   *** tb_lineno: 10
 
 The following example shows the different ways to print and format the stack::
 
@@ -271,7 +262,10 @@ The following example shows the different ways to print and format the stack::
     '  File "<doctest>", line 8, in lumberstack\n    print repr(traceback.format_stack())\n']
 
 
-This last example demonstrates the final few formatting functions::
+This last example demonstrates the final few formatting functions:
+
+.. doctest::
+   :options: +NORMALIZE_WHITESPACE
 
    >>> import traceback
    >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),