Add documentation for new textwrap module.

Doc/lib/libtextwrap.tex

@@ -0,0 +1,141 @@
+\section{\module{textwrap} ---
+         Text wrapping and filling}
+
+\declaremodule{standard}{textwrap}
+\modulesynopsis{Text wrapping and filling}
+\moduleauthor{Greg Ward}{gward@python.net}
+\sectionauthor{Greg Ward}{gward@python.net}
+
+\versionadded{2.3}
+
+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.
+
+\begin{funcdesc}{wrap}{text, width=70, **kwargs}
+Wraps the single paragraph in \var{text} (a string) so every line is at
+most \var{width} characters long.  Returns a list of output lines,
+without final newlines.
+
+Optional keyword arguments correspond to the instance attributes of
+\class{TextWrapper}, documented below.
+\end{funcdesc}
+
+\begin{funcdesc}{fill}{text, width=70, **kwargs}
+Wraps the single paragraph in \var{text}, and returns a single string
+containing the wrapped paragraph.  \function{fill()} is shorthand for
+\begin{verbatim}
+"\n".join(wrap(text, ...))
+\end{verbatim}
+
+In particular, \function{fill()} accepts exactly the same keyword
+arguments as \function{wrap()}.
+\end{funcdesc}
+
+Both \function{wrap()} and \function{fill()} work by creating a
+\class{TextWrapper} instance and calling a single method on it.  That
+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.
+
+% XXX how to typeset long argument lists? this just spills off
+% the edge of the page, with or without \\ delimiters
+\begin{classdesc}{TextWrapper}{width=70, \\
+                               initial_indent="", \\
+                               subsequent_indent="", \\
+                               expand_tabs=True, \\
+                               replace_whitespace=True, \\
+                               fix_sentence_endings=False, \\
+                               break_long_words=True}
+
+Each keyword argument to the constructor corresponds to an instance
+attribute, so for example
+\begin{verbatim}
+wrapper = TextWrapper(initial_indent="* ")
+\end{verbatim}
+is the same as
+\begin{verbatim}
+wrapper = TextWrapper()
+wrapper.initial_indent = "* "
+\end{verbatim}
+
+You can re-use the same \class{TextWrapper} object many times, and you
+can change any of its options through direct assignment to instance
+attributes between uses.  The effects of the instance attributes are as
+follows:
+
+\begin{memberdesc}[bool]{expand_tabs}
+If true (the default), then all tab characters in \var{text} will be
+expanded to spaces using the \method{expand_tabs()} method of
+\var{text}.
+\end{memberdesc}
+
+\begin{memberdesc}[bool]{replace_whitespace}
+If true (the default), each whitespace character (as defined by
+\var{string.whitespace}) remaining after tab expansion will be replaced
+by a single space.  \note{If \var{expand_tabs} is false and
+\var{replace_whitespace} is true, each tab character will be replaced by
+a single space, which is \emph{not} the same as tab expansion.}
+\end{memberdesc}
+
+% XXX how to typeset the empty string? this looks awful, and "" is worse.
+\begin{memberdesc}[string]{initial_indent}
+(default: '') String that will be prepended to the first line of wrapped
+output.  Counts towards the length of the first line.
+\end{memberdesc}
+
+\begin{memberdesc}[string]{subsequent_indent}
+(default: '') String that will be prepended to all lines of wrapped
+output except the first.  Counts towards the length of each line except
+the first.
+\end{memberdesc}
+
+\begin{memberdesc}[bool]{fix_sentence_endings}
+(default: false) If true, \class{TextWrapper} attempts to detect
+sentence endings and ensure that sentences are always separated by
+exactly two spaces.  This is generally desired for text in a monospaced
+font.  However, the sentence detection algorithm is imperfect: it
+assumes that a sentence ending consists of a lowercase letter followed
+by one of \character{.},
+\character{!}, or \character{?}, possibly followed by one of
+\character{"} or \character{'}.  One problem with this is algoritm is
+that it is unable to detect the difference between ``Dr.'' in
+\begin{verbatim}
+[...] Dr. Frankenstein's monster [...]
+\end{verbatim}
+and ``Spot.'' in
+\begin{verbatim}
+[...] See Spot.  See Spot run [...]
+\end{verbatim}
+Furthermore, since it relies on \var{string.lowercase} for the
+definition of ``lowercase letter'', it is specific to English-language
+texts.  Thus, \var{fix_sentence_endings} is false by default.
+\end{memberdesc}
+
+\begin{memberdesc}[bool]{break_long_words}
+If true (the default), then words longer than \var{width} will be broken
+in order to ensure that no lines are longer than \var{width}.  If it is
+false, long words will not be broken, and some lines may be longer than
+\var{width}.  (Long words will be put on a line by themselves, in order
+to minimize the amount by which \var{width} is exceeded.)
+\end{memberdesc}
+
+\class{TextWrapper} also provides two public methods, analogous to the
+module-level convenience functions:
+
+\begin{methoddesc}{wrap}{text}
+Wraps the single paragraph in \var{text} (a string) so every line is at
+most \var{width} characters long.  All wrapping options are taken from
+instance attributes of the \class{TextWrapper} instance.  Returns a list
+of output lines, without final newlines.
+\end{methoddesc}
+
+\begin{methoddesc}{fill}{text}
+Wraps the single paragraph in \var{text}, and returns a single string
+containing the wrapped paragraph.
+\end{methoddesc}
+
+\end{classdesc}