[Python-checkins] python/dist/src/Doc/lib libdoctest.tex,1.27,1.28

[tim_one at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv7200/Doc/lib

Modified Files:
	libdoctest.tex 
Log Message:
Now that they've settled down, document doctest directives.


Index: libdoctest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -d -r1.27 -r1.28
*** libdoctest.tex	13 Aug 2004 21:55:21 -0000	1.27
--- libdoctest.tex	19 Aug 2004 16:38:58 -0000	1.28
***************
*** 299,308 ****
  
  
! \subsection{Option Flags and Directive Names\label{doctest-options}}
  
  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}
--- 299,308 ----
  
  
! \subsection{Option Flags and Directives\label{doctest-options}}
  
  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 (see below).
  
  \begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
***************
*** 341,347 ****
      When specified, an ellipsis marker (\code{...}) in the expected output
      can match any substring in the actual output.  This includes
!     substrings that span line boundaries, so it's best to keep usage of
!     this simple.  Complicated uses can lead to the same kinds of
!     surprises that \regexp{.*} is prone to in regular expressions.
  \end{datadesc}
  
--- 341,348 ----
      When specified, an ellipsis marker (\code{...}) in the expected output
      can match any substring in the actual output.  This includes
!     substrings that span line boundaries, and empty substrings, so it's
!     best to keep usage of this simple.  Complicated uses can lead to the
!     same kinds of "oops, it matched too much!" surprises that \regexp{.*}
!     is prone to in regular expressions.
  \end{datadesc}
  
***************
*** 357,365 ****
  
  
  \versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
      \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
      \constant{UNIFIED_DIFF}, and \constant{CONTEXT_DIFF}
!     were added, and by default \code{<BLANKLINE>} in expected output
!     matches an empty line in actual output]{2.4}
  
  \subsection{Advanced Usage}
--- 358,423 ----
  
  
+ A "doctest directive" is a trailing Python comment on a line of a doctest
+ example:
+ 
+ \begin{productionlist}[doctest]
+     \production{directive}
+                {"#" "doctest:" \token{on_or_off} \token{directive_name}}
+     \production{on_or_off}
+                {"+" | "-"}
+     \production{directive_name}
+                {"DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...}
+ \end{productionlist}
+ 
+ Whitespace is not allowed between the \code{+} or \code{-} and the
+ directive name.  The directive name can be any of the option names
+ explained above.
+ 
+ The doctest directives appearing in a single example modify doctest's
+ behavior for that single example.  Use \code{+} to enable the named
+ behavior, or \code{-} to disable it.
+ 
+ For example, this test passes:
+ 
+ \begin{verbatim}
+ >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
+ [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
+ 10,  11, 12, 13, 14, 15, 16, 17, 18, 19]
+ \end{verbatim}
+ 
+ Without the directive it would fail, both because the actual output
+ doesn't have two blanks before the single-digit list elements, and
+ because the actual output is on a single line.  This test also passes,
+ and requires a directive to do so:
+ 
+ \begin{verbatim}
+ >>> print range(20) # doctest:+ELLIPSIS
+ [0, 1, ..., 18, 19]
+ \end{verbatim}
+ 
+ Only one directive per physical line is accepted.  If you want to
+ use multiple directives for a single example, you can add
+ \samp{...} lines to your example containing only directives:
+ 
+ \begin{verbatim}
+ >>> print range(20) #doctest: +ELLIPSIS
+ ...                 #doctest: +NORMALIZE_WHITESPACE
+ [0,    1, ...,   18,    19]
+ \end{verbatim}
+ 
+ Note that since all options are disabled by default, and directives apply
+ only to the example they appear in, enabling options (via \code{+} in a
+ directive) is usually the only meaningful choice.  However, option flags
+ can also be passed to functions that run doctests, establishing different
+ defaults.  In such cases, disabling an option via \code{-} in a directive
+ can be useful.
+ 
  \versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
      \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
      \constant{UNIFIED_DIFF}, and \constant{CONTEXT_DIFF}
!     were added; by default \code{<BLANKLINE>} in expected output
!     matches an empty line in actual output; and doctest directives
!     were added]{2.4}
! 
  
  \subsection{Advanced Usage}