SF bug #901654: split method documentation can be improved

* Discuss the algorithmic distinctions between s.split() and s.split(sep).
* Document the split behavior for empty strings.
* Note the behavior when maxsplit is zero.
* Include short examples.

diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index e97009e52691493672830a0c837f5c790128ad72..2f54cae1a5713802dc2c966227a3f52dfe62ac7e 100644 (file)
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -750,8 +750,22 @@ string this method is called on.
 \begin{methoddesc}[string]{split}{\optional{sep \optional{,maxsplit}}}
 Return a list of the words in the string, using \var{sep} as the
 delimiter string.  If \var{maxsplit} is given, at most \var{maxsplit}
-splits are done.  If \var{sep} is not specified or \code{None}, any
-whitespace string is a separator.
+splits are done. (thus, the list will have at most \code{\var{maxsplit}+1}
+elements).  If \var{maxsplit} is not specified or is zero, then there
+is no limit on the number of splits (all possible splits are made).
+Consecutive delimiters are not grouped together and are
+deemed to delimit empty strings (for example, \samp{'1,,2'.split(',')}
+returns \samp{['1', '', '2']}.  The \var{sep} argument may consist of
+multiple characters (for example, \samp{'1, 2, 3'.split(', ')} returns
+\samp{['1', '2', '3']}.  Splitting an empty string with a specified
+separator returns an empty list.
+
+If \var{sep} is not specified or is \code{None}, a different splitting
+algorithm is applied.  Words are separated by arbitrary length strings of
+whitespace characters (spaces, tabs, newlines, returns, and formfeeds).
+Consecutive whitespace delimiters are treated as a single delimiter
+(\samp{'1   2  3'.split()} returns \samp{['1', '2', '3']}.  Splitting an
+empty string returns \samp{['']}.
 \end{methoddesc}
 
 \begin{methoddesc}[string]{splitlines}{\optional{keepends}}