document what exactly str.splitlines() splits on (closes #12855)

Patch by Martin Panter.

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index d3fc0939530683fb97d70efd8f6961a582418e73..0aa9c1205e4fa9a0a9261cb108351a7f3e9379b2 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1855,10 +1855,42 @@ expression support in the :mod:`re` module).
 
 .. method:: str.splitlines([keepends])
 
-   Return a list of the lines in the string, breaking at line boundaries.
-   This method uses the :term:`universal newlines` approach to splitting lines.
-   Line breaks are not included in the resulting list unless *keepends* is
-   given and true.
+   Return a list of the lines in the string, breaking at line boundaries.  Line
+   breaks are not included in the resulting list unless *keepends* is given and
+   true.
+
+   This method splits on the following line boundaries.  In particular, the
+   boundaries are a superset of :term:`universal newlines`.
+
+   +-----------------------+-----------------------------+
+   | Representation        | Description                 |
+   +=======================+=============================+
+   | ``\n``                | Line Feed                   |
+   +-----------------------+-----------------------------+
+   | ``\r``                | Carriage Return             |
+   +-----------------------+-----------------------------+
+   | ``\r\n``              | Carriage Return + Line Feed |
+   +-----------------------+-----------------------------+
+   | ``\v`` or ``\x0b``    | Line Tabulation             |
+   +-----------------------+-----------------------------+
+   | ``\f`` or ``\x0c``    | Form Feed                   |
+   +-----------------------+-----------------------------+
+   | ``\x1c``              | File Separator              |
+   +-----------------------+-----------------------------+
+   | ``\x1d``              | Group Separator             |
+   +-----------------------+-----------------------------+
+   | ``\x1e``              | Record Separator            |
+   +-----------------------+-----------------------------+
+   | ``\x85``              | Next Line (C1 Control Code) |
+   +-----------------------+-----------------------------+
+   | ``\u2028``            | Line Separator              |
+   +-----------------------+-----------------------------+
+   | ``\u2029``            | Paragraph Separator         |
+   +-----------------------+-----------------------------+
+
+   .. versionchanged:: 3.2
+
+      ``\v`` and ``\f`` added to list of line boundaries.
 
    For example::