Another microburst of snail-like progress.

1 files changed, 94 insertions, 106 deletions

diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
index 7558309..282fb3a 100644
--- a/Doc/lib/libdoctest.tex
+++ b/Doc/lib/libdoctest.tex
@@ -183,92 +183,6 @@ In any case, \function{testmod()} returns a 2-tuple of ints \code{(\var{f},
 failed and \var{t} is the total number of docstring examples
 attempted.
 
-\begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{,
-                          globs}\optional{, verbose}\optional{,
-                          isprivate}\optional{, report}\optional{,
-                          optionflags}\optional{, extraglobs}\optional{,
-                          raise_on_error}}
-
-  All arguments are optional, and all except for \var{m} should be
-  specified in keyword form.
-
-  Test examples in docstrings in functions and classes reachable
-  from module \var{m} (or the current module if \var{m} is not supplied
-  or is \code{None}), starting with \code{\var{m}.__doc__}.
-
-  Also test examples reachable from dict \code{\var{m}.__test__}, if it
-  exists and is not \code{None}.  \code{\var{m}.__test__} maps
-  names (strings) to functions, classes and strings; function and class
-  docstrings are searched for examples; strings are searched directly,
-  as if they were docstrings.
-
-  Only docstrings attached to objects belonging to module \var{m} are
-  searched.
-
-  Return \samp{(\var{failure_count}, \var{test_count})}.
-
-  Optional argument \var{name} gives the name of the module; by default,
-  or if \code{None}, \code{\var{m}.__name__} is used.
-
-  Optional argument \var{globs} gives a dict to be used as the globals
-  when executing examples; by default, or if \code{None},
-  \code{\var{m}.__dict__} is used.  A new shallow copy of this dict is
-  created for each docstring with examples, so that each docstring's
-  examples start with a clean slate.
-
-  Optional argument \var{extraglobs} gives a dict merged into the
-  globals used to execute examples.  This works like
-  \method{dict.update()}:  if \var{globs} and \var{extraglobs} have a
-  common key, the associated value in \var{extraglobs} appears in the
-  combined dict.  By default, or if \code{None}, no extra globals are
-  used.  This is an advanced feature that allows parameterization of
-  doctests.  For example, a doctest can be written for a base class, using
-  a generic name for the class, then reused to test any number of
-  subclasses by passing an \var{extraglobs} dict mapping the generic
-  name to the subclass to be tested.
-
-  Optional argument \var{verbose} prints lots of stuff if true, and prints
-  only failures if false; by default, or if \code{None}, it's true
-  if and only if \code{'-v'} is in \code{sys.argv}.
-
-  Optional argument \var{report} prints a summary at the end when true,
-  else prints nothing at the end.  In verbose mode, the summary is
-  detailed, else the summary is very brief (in fact, empty if all tests
-  passed).
-
-  Optional argument \var{optionflags} or's together option flags.  See
-  see section \ref{doctest-options}.
-
-  Optional argument \var{raise_on_error} defaults to false.  If true,
-  an exception is raised upon the first failure or unexpected exception
-  in an example.  This allows failures to be post-mortem debugged.
-  Default behavior is to continue running examples.
-
-  Optional argument \var{isprivate} specifies a function used to
-  determine whether a name is private.  The default function treats
-  all names as public.  \var{isprivate} can be set to
-  \code{doctest.is_private} to skip over names that are
-  private according to Python's underscore naming convention.
-  \deprecated{2.4}{\var{isprivate} was a stupid idea -- don't use it.
-  If you need to skip tests based on name, filter the list returned by
-  \code{DocTestFinder.find()} instead.}
-
-%  """ [XX] This is no longer true:
-%  Advanced tomfoolery:  testmod runs methods of a local instance of
-%  class doctest.Tester, then merges the results into (or creates)
-%  global Tester instance doctest.master.  Methods of doctest.master
-%  can be called directly too, if you want to do something unusual.
-%  Passing report=0 to testmod is especially useful then, to delay
-%  displaying a summary.  Invoke doctest.master.summarize(verbose)
-%  when you're done fiddling.
-
-  \versionchanged[The parameter \var{optionflags} was added]{2.3}
-
-  \versionchanged[The parameters \var{extraglobs} and \var{raise_on_error}
-                  were added]{2.4}
-\end{funcdesc}
-
-
 \subsection{Which Docstrings Are Examined?}
 
 The module docstring, and all function, class and method docstrings are
@@ -386,10 +300,10 @@ be left out, or could just as well be three (or three hundred) commas.
 
 \subsection{Option Flags and Directive Names\label{doctest-options}}
 
-A number of option flags control various aspects of doctest's behavior.
-Symbolic names for the flags are supplied as module constants, which
-can be or'ed together and passed to various functions.  The names can
-also be used in doctest directives.
+A number of option flags control various aspects of doctest's comparison
+behavior. Symbolic names for the flags are supplied as module constants,
+which can be or'ed together and passed to various functions.  The names
+can also be used in doctest directives.
 
 \begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
     By default, if an expected output block contains just \code{1},
@@ -445,8 +359,8 @@ also be used in doctest directives.
 \versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
     \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
     \constant{UNIFIED_DIFF}, and \constant{CONTEXT_DIFF}
-    were added, and \code{<BLANKLINE>} in expected output matches
-    an empty line in actual output by default]{2.4}
+    were added, and by default \code{<BLANKLINE>} in expected output
+    matches an empty line in actual output]{2.4}
 
 \subsection{Advanced Usage}
 
@@ -466,15 +380,80 @@ are run.
   \versionadded{2.3}
 \end{funcdesc}
 
-\begin{funcdesc}{testmod}{}
-  This function provides the most basic interface to the doctests.
-  It creates a local instance of class \class{Tester}, runs appropriate
-  methods of that class, and merges the results into the global \class{Tester}
-  instance, \code{master}.
+\begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{,
+                          globs}\optional{, verbose}\optional{,
+                          isprivate}\optional{, report}\optional{,
+                          optionflags}\optional{, extraglobs}\optional{,
+                          raise_on_error}}
+
+  All arguments are optional, and all except for \var{m} should be
+  specified in keyword form.
+
+  Test examples in docstrings in functions and classes reachable
+  from module \var{m} (or the current module if \var{m} is not supplied
+  or is \code{None}), starting with \code{\var{m}.__doc__}.
+
+  Also test examples reachable from dict \code{\var{m}.__test__}, if it
+  exists and is not \code{None}.  \code{\var{m}.__test__} maps
+  names (strings) to functions, classes and strings; function and class
+  docstrings are searched for examples; strings are searched directly,
+  as if they were docstrings.
+
+  Only docstrings attached to objects belonging to module \var{m} are
+  searched.
+
+  Return \samp{(\var{failure_count}, \var{test_count})}.
+
+  Optional argument \var{name} gives the name of the module; by default,
+  or if \code{None}, \code{\var{m}.__name__} is used.
+
+  Optional argument \var{globs} gives a dict to be used as the globals
+  when executing examples; by default, or if \code{None},
+  \code{\var{m}.__dict__} is used.  A new shallow copy of this dict is
+  created for each docstring with examples, so that each docstring's
+  examples start with a clean slate.
+
+  Optional argument \var{extraglobs} gives a dict merged into the
+  globals used to execute examples.  This works like
+  \method{dict.update()}:  if \var{globs} and \var{extraglobs} have a
+  common key, the associated value in \var{extraglobs} appears in the
+  combined dict.  By default, or if \code{None}, no extra globals are
+  used.  This is an advanced feature that allows parameterization of
+  doctests.  For example, a doctest can be written for a base class, using
+  a generic name for the class, then reused to test any number of
+  subclasses by passing an \var{extraglobs} dict mapping the generic
+  name to the subclass to be tested.
+
+  Optional argument \var{verbose} prints lots of stuff if true, and prints
+  only failures if false; by default, or if \code{None}, it's true
+  if and only if \code{'-v'} is in \code{sys.argv}.
+
+  Optional argument \var{report} prints a summary at the end when true,
+  else prints nothing at the end.  In verbose mode, the summary is
+  detailed, else the summary is very brief (in fact, empty if all tests
+  passed).
+
+  Optional argument \var{optionflags} or's together option flags.  See
+  see section \ref{doctest-options}.
+
+  Optional argument \var{raise_on_error} defaults to false.  If true,
+  an exception is raised upon the first failure or unexpected exception
+  in an example.  This allows failures to be post-mortem debugged.
+  Default behavior is to continue running examples.
 
-  To get finer control than \function{testmod()} offers, create an instance
-  of \class{Tester} with custom policies, or run methods of \code{master}
-  directly.  See \code{Tester.__doc__} for details.
+  Optional argument \var{isprivate} specifies a function used to
+  determine whether a name is private.  The default function treats
+  all names as public.  \var{isprivate} can be set to
+  \code{doctest.is_private} to skip over names that are
+  private according to Python's underscore naming convention.
+  \deprecated{2.4}{\var{isprivate} was a stupid idea -- don't use it.
+  If you need to skip tests based on name, filter the list returned by
+  \code{DocTestFinder.find()} instead.}
+
+  \versionchanged[The parameter \var{optionflags} was added]{2.3}
+
+  \versionchanged[The parameters \var{extraglobs} and \var{raise_on_error}
+                  were added]{2.4}
 \end{funcdesc}
 
 \begin{funcdesc}{testsource}{module, name}
@@ -527,10 +506,14 @@ are run.
 \subsection{How are Docstring Examples Recognized?}
 
 In most cases a copy-and-paste of an interactive console session works
-fine---just make sure the leading whitespace is rigidly consistent
-(you can mix tabs and spaces if you're too lazy to do it right, but
-\module{doctest} is not in the business of guessing what you think a tab
-means).
+fine, but doctest isn't trying to do an exact emulation of any specific
+Python shell.  All hard tab characters are expanded to spaces, using
+8-column tab stops.  If you don't believe tabs should mean that, too
+bad:  don't use hard tabs, or write your own \class{DocTestParser}
+class.
+
+\versionchanged[Expanding tabs to spaces is new; previous versions
+                tried to preserve hard tabs, with confusing results]{2.4}
 
 \begin{verbatim}
 >>> # comments are ignored
@@ -560,7 +543,12 @@ The fine print:
 \begin{itemize}
 
 \item Expected output cannot contain an all-whitespace line, since such a
-  line is taken to signal the end of expected output.
+  line is taken to signal the end of expected output.  If expected
+  output does contain a blank line, put \code{<BLANKLINE>} in your
+  doctest example each place a blank line is expected.
+  \versionchanged[\code{<BLANKLINE>} was added; there was no way to
+                  use expected output containing empty lines in
+                  previous versions]{2.4}
 
 \item Output to stdout is captured, but not output to stderr (exception
   tracebacks are captured via a different means).
@@ -600,7 +588,7 @@ Backslashes in a raw docstring: m\n
 
 and as many leading whitespace characters are stripped from the
 expected output as appeared in the initial \code{'>\code{>}>~'} line
-that triggered it.
+that started the example.
 \end{itemize}
 
 \subsection{Warnings}