From 92816de18e3456f8304a1aaa6f28b151858a6e5d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20v=2E=20L=C3=B6wis?= <martin@v.loewis.de>
Date: Mon, 31 May 2004 19:01:00 +0000
Subject: Patch #932930: suggest the use of rawstrings for backslashes.

---
 Doc/lib/libdoctest.tex | 29 ++++++++++++++++++++---------
 Lib/doctest.py         | 33 +++++++++++++++++++++------------
 2 files changed, 41 insertions(+), 21 deletions(-)

diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
index e8983c9..6c72dbc 100644
--- a/Doc/lib/libdoctest.tex
+++ b/Doc/lib/libdoctest.tex
@@ -361,17 +361,28 @@ The fine print:
 \item Output to stdout is captured, but not output to stderr (exception
   tracebacks are captured via a different means).
 
-\item If you continue a line via backslashing in an interactive session, or
-  for any other reason use a backslash, you need to double the backslash in
-  the docstring version.  This is simply because you're in a string, and so
-  the backslash must be escaped for it to survive intact.  Like:
+\item If you continue a line via backslashing in an interactive session,
+  or for any other reason use a backslash, you should use a raw
+  docstring, which will preserve your backslahses exactly as you type
+  them:
 
 \begin{verbatim}
->>> if "yes" == \\
-...     "y" +   \\
-...     "es":
-...     print 'yes'
-yes
+>>> def f(x): 
+...     r'''Backslashes in a raw docstring: m\n'''
+>>> print f.__doc__
+Backslashes in a raw docstring: m\n
+\end{verbatim}
+  
+  Otherwise, the backslash will be interpreted as part of the string.
+  E.g., the "\textbackslash" above would be interpreted as a newline
+  character.  Alternatively, you can double each backslash in the
+  doctest version (and not use a raw string):
+
+\begin{verbatim}
+>>> def f(x): 
+...     '''Backslashes in a raw docstring: m\\n'''
+>>> print f.__doc__
+Backslashes in a raw docstring: m\n
 \end{verbatim}
 
 \item The starting column doesn't matter:
diff --git a/Lib/doctest.py b/Lib/doctest.py
index 5020684..acde9c1 100644
--- a/Lib/doctest.py
+++ b/Lib/doctest.py
@@ -4,7 +4,7 @@
 
 # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
 
-"""Module doctest -- a framework for running examples in docstrings.
+r"""Module doctest -- a framework for running examples in docstrings.
 
 NORMAL USAGE
 
@@ -200,17 +200,26 @@ Bummers:
 + Output to stdout is captured, but not output to stderr (exception
   tracebacks are captured via a different means).
 
-+ If you continue a line via backslashing in an interactive session, or for
-  any other reason use a backslash, you need to double the backslash in the
-  docstring version.  This is simply because you're in a string, and so the
-  backslash must be escaped for it to survive intact.  Like:
-
->>> if "yes" == \\
-...     "y" +   \\
-...     "es":   # in the source code you'll see the doubled backslashes
-...     print 'yes'
-yes
-
++ If you continue a line via backslashing in an interactive session,
+  or for any other reason use a backslash, you should use a raw
+  docstring, which will preserve your backslahses exactly as you type
+  them:
+
+      >>> def f(x): 
+      ...     r'''Backslashes in a raw docstring: m\n'''
+      >>> print f.__doc__
+      Backslashes in a raw docstring: m\n
+
+  Otherwise, the backslash will be interpreted as part of the string.
+  E.g., the "\n" above would be interpreted as a newline character.
+  Alternatively, you can double each backslash in the doctest version
+  (and not use a raw string):
+
+      >>> def f(x): 
+      ...     '''Backslashes in a raw docstring: m\\n'''
+      >>> print f.__doc__
+      Backslashes in a raw docstring: m\n
+      
 The starting column doesn't matter:
 
 >>> assert "Easy!"
-- 
cgit v0.12