Give a saner example for script_from_examples(); also mention an intended

but not entirely obvious use case.

1 files changed, 25 insertions, 11 deletions

diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
index 66de841..2381880 100644
--- a/Doc/lib/libdoctest.tex
+++ b/Doc/lib/libdoctest.tex
@@ -1655,22 +1655,36 @@ the synthesized code under the debugger:
   is converted to a Python script, where doctest examples in \var{s}
   are converted to regular code, and everything else is converted to
   Python comments.  The generated script is returned as a string.
-  For example, given file \file{a.py} as above,
+  For example,
 
     \begin{verbatim}
-    >>> print doctest.script_from_examples(open("a.py").read())
-    # """
-    def f(x):
-        g(x*2)
-    def g(x):
-        print x+3
-        import pdb; pdb.set_trace()
-    f(3)
+    import doctest
+    print doctest.script_from_examples(r"""
+        Set x and y to 1 and 2.
+        >>> x, y = 1, 2
+
+        Print their sum:
+        >>> print x+y
+        3
+    """)
+    \end{verbatim}
+
+  displays:
+
+    \begin{verbatim}
+    # Set x and y to 1 and 2.
+    x, y = 1, 2
+    #
+    # Print their sum:
+    print x+y
     # Expected:
-    ## 9
-    ## """
+    ## 3
     \end{verbatim}
 
+  This function is used internally by other functions (see below), but
+  can also be useful when you want to transform an interactive Python
+  session into a Python script.
+
   \versionadded{2.4}
 \end{funcdesc}