SF patch #598163 (Ville Vainio, vvainio@users.sourceforge.net):

document dedent() function.

1 files changed, 29 insertions, 4 deletions

diff --git a/Doc/lib/libtextwrap.tex b/Doc/lib/libtextwrap.tex
index 8c58d5d..fa0b1fc 100644
--- a/Doc/lib/libtextwrap.tex
+++ b/Doc/lib/libtextwrap.tex
@@ -10,10 +10,10 @@
 
 The \module{textwrap} module provides two convenience functions,
 \function{wrap()} and \function{fill()}, as well as
-\class{TextWrapper}, the class that does all the work.  If you're just
-wrapping or filling one or two text strings, the convenience functions
-should be good enough; otherwise, you should use an instance of
-\class{TextWrapper} for efficiency.
+\class{TextWrapper}, the class that does all the work, and a utility function 
+\function{dedent()}.  If you're just wrapping or filling one or two 
+text strings, the convenience functions should be good enough; otherwise, 
+you should use an instance of \class{TextWrapper} for efficiency.
 
 \begin{funcdesc}{wrap}{text\optional{, width\optional{, \moreargs}}}
 Wraps the single paragraph in \var{text} (a string) so every line is at
@@ -42,6 +42,31 @@ instance is not reused, so for applications that wrap/fill many text
 strings, it will be more efficient for you to create your own
 \class{TextWrapper} object.
 
+An additional utility function, \function{dedent()}, is provided to
+remove indentation from strings that have unwanted whitespace to the
+left of the text.
+
+\begin{funcdesc}{dedent}{text} 
+Remove any whitespace than can be uniformly removed from the left
+of every line in \var{text}.
+
+This is typically used to make triple-quoted strings line up with
+the left edge of screen/whatever, while still presenting it in the
+source code in indented form. 
+
+For example:
+\begin{verbatim}
+def test():
+    # end first line with \ to avoid the empty line!
+    s = '''\
+    Hey
+    there
+    '''
+    print repr(s)          # prints '    Hey\n    there\n    '
+    print repr(dedent(s))  # prints 'Hey\nthere\n'
+\end{verbatim}
+\end{funcdesc}
+
 \begin{classdesc}{TextWrapper}{...}
 The \class{TextWrapper} constructor accepts a number of optional
 keyword arguments.  Each argument corresponds to one instance attribute,