Improvements in regular expression doc

Doc/library/re.rst

@@ -33,8 +33,9 @@ usage of the backslash in string literals now generate a :exc:`SyntaxWarning`
 and in the future this will become a :exc:`SyntaxError`. This behaviour
 will happen even if it is a valid escape sequence for a regular expression.
 
-The solution is to use Python's raw string notation for regular expression
-patterns; backslashes are not handled in any special way in a string literal
+The solution is to use :ref:`Python's raw string notation
+for regular expression patterns <raw-string-notation>`; backslashes are not
+handled in any special way in a string literal
 prefixed with ``'r'``.  So ``r"\n"`` is a two-character string containing
 ``'\'`` and ``'n'``, while ``"\n"`` is a one-character string containing a
 newline.  Usually patterns will be expressed in Python code using this raw
@@ -83,6 +84,12 @@ characters, so ``last`` matches the string ``'last'``.  (In the rest of this
 section, we'll write RE's in ``this special style``, usually without quotes, and
 strings to be matched ``'in single quotes'``.)
 
+
+.. _re-special-characters:
+
+Special characters
+^^^^^^^^^^^^^^^^^^
+
 Some characters, like ``'|'`` or ``'('``, are special. Special
 characters either stand for classes of ordinary characters, or affect
 how the regular expressions around them are interpreted.
@@ -93,7 +100,6 @@ directly nested. This avoids ambiguity with the non-greedy modifier suffix
 repetition to an inner repetition, parentheses may be used. For example,
 the expression ``(?:a{6})*`` matches any multiple of six ``'a'`` characters.
 
-
 The special characters are:
 
 .. index:: single: . (dot); in regular expressions
@@ -114,31 +120,33 @@ The special characters are:
 ``$``
    Matches the end of the string or just before the newline at the end of the
    string, and in :const:`MULTILINE` mode also matches before a newline.  ``foo``
-   matches both 'foo' and 'foobar', while the regular expression ``foo$`` matches
-   only 'foo'.  More interestingly, searching for ``foo.$`` in ``'foo1\nfoo2\n'``
-   matches 'foo2' normally, but 'foo1' in :const:`MULTILINE` mode; searching for
+   matches both ``'foo'`` and ``'foobar'``, while the regular expression ``foo$``
+   matches
+   only ``'foo'``.  More interestingly, searching for ``foo.$`` in ``'foo1\nfoo2\n'``
+   matches ``'foo2'`` normally, but also ``'foo1'`` in :const:`MULTILINE` mode; searching
+   for
    a single ``$`` in ``'foo\n'`` will find two (empty) matches: one just before
    the newline, and one at the end of the string.
 
 .. index:: single: * (asterisk); in regular expressions
 
 ``*``
    Causes the resulting RE to match 0 or more repetitions of the preceding RE, as
-   many repetitions as are possible.  ``ab*`` will match 'a', 'ab', or 'a' followed
-   by any number of 'b's.
+   many repetitions as are possible.  ``ab*`` will match ``'a'``, ``'ab'``, or
+   ``'a'``  followed by any number of ``'b'``\ s.
 
 .. index:: single: + (plus); in regular expressions
 
 ``+``
    Causes the resulting RE to match 1 or more repetitions of the preceding RE.
-   ``ab+`` will match 'a' followed by any non-zero number of 'b's; it will not
-   match just 'a'.
+   ``ab+`` will match ``'a'`` followed by any non-zero number of ``'b'``\ s; it
+   will not match just ``'a'``.
 
 .. index:: single: ? (question mark); in regular expressions
 
 ``?``
    Causes the resulting RE to match 0 or 1 repetitions of the preceding RE.
-   ``ab?`` will match either 'a' or 'ab'.
+   ``ab?`` will match either ``'a'`` or ``'ab'``.
 
 .. index::
    single: *?; in regular expressions
@@ -224,7 +232,8 @@ The special characters are:
    ``'*'``, ``'?'``, and so forth), or signals a special sequence; special
    sequences are discussed below.
 
-   If you're not using a raw string to express the pattern, remember that Python
+   If you're not using a :ref:`raw string to express the
+   pattern<raw-string-notation>`, remember that Python
    also uses the backslash as an escape sequence in string literals; if the escape
    sequence isn't recognized by Python's parser, the backslash and subsequent
    character are included in the resulting string.  However, if Python would
@@ -315,6 +324,12 @@ The special characters are:
    special sequence, described below.  To match the literals ``'('`` or ``')'``,
    use ``\(`` or ``\)``, or enclose them inside a character class: ``[(]``, ``[)]``.
 
+
+.. _re_extension_notation:
+
+Extension notation
+""""""""""""""""""
+
 .. index:: single: (?; in regular expressions
 
 ``(?...)``
@@ -514,6 +529,9 @@ The special characters are:
 
 .. _re-special-sequences:
 
+Escape sequences
+""""""""""""""""
+
 The special sequences consist of ``'\'`` and a character from the list below.
 If the ordinary character is not an ASCII digit or an ASCII letter, then the
 resulting RE will match the second character.  For example, ``\$`` matches the
@@ -660,6 +678,12 @@ character ``'$'``.
 ``\Z``
    Matches only at the end of the string.
 
+
+.. _re-escape-sequences:
+
+String literal escapes
+""""""""""""""""""""""
+
 .. index::
    single: \a; in regular expressions
    single: \b; in regular expressions
@@ -771,11 +795,11 @@ Flags
 
    Note that when the Unicode patterns ``[a-z]`` or ``[A-Z]`` are used in
    combination with the :const:`IGNORECASE` flag, they will match the 52 ASCII
-   letters and 4 additional non-ASCII letters: 'İ' (U+0130, Latin capital
-   letter I with dot above), 'ı' (U+0131, Latin small letter dotless i),
-   'ſ' (U+017F, Latin small letter long s) and 'K' (U+212A, Kelvin sign).
-   If the :py:const:`~re.ASCII` flag is used, only letters 'a' to 'z'
-   and 'A' to 'Z' are matched.
+   letters and 4 additional non-ASCII letters: ``'İ'`` (U+0130, Latin capital
+   letter I with dot above), ``'ı'`` (U+0131, Latin small letter dotless i),
+   ``'ſ'`` (U+017F, Latin small letter long s) and ``'K'`` (U+212A, Kelvin sign).
+   If the :py:const:`~re.ASCII` flag is used, only letters  ``'a'`` to ``'z'``
+   and ``'A'`` to ``'Z'`` are matched.
 
 .. data:: L
           LOCALE
@@ -1191,25 +1215,26 @@ Exceptions
    error if a string contains no match for a pattern.  The ``PatternError`` instance has
    the following additional attributes:
 
-   .. attribute:: msg
+   .. list-table::
+      :header-rows: 1
 
-      The unformatted error message.
+      * - Attribute
+        - Meaning
 
-   .. attribute:: pattern
+      * - .. attribute:: msg
+        - The unformatted error message.
 
-      The regular expression pattern.
+      * - .. attribute:: pattern
+        - The regular expression pattern.
 
-   .. attribute:: pos
+      * - .. attribute:: pos
+        - The index in *pattern* where compilation failed (may be ``None``).
 
-      The index in *pattern* where compilation failed (may be ``None``).
+      * - .. attribute:: lineno
+        - The line corresponding to *pos* (may be ``None``).
 
-   .. attribute:: lineno
-
-      The line corresponding to *pos* (may be ``None``).
-
-   .. attribute:: colno
-
-      The column corresponding to *pos* (may be ``None``).
+      * - .. attribute:: colno
+        - The column corresponding to *pos* (may be ``None``).
 
    .. versionchanged:: 3.5
       Added additional attributes.
@@ -1578,6 +1603,8 @@ Regular Expression Examples
 ---------------------------
 
 
+.. _checking-for-a-pair:
+
 Checking for a Pair
 ^^^^^^^^^^^^^^^^^^^
 
@@ -1632,6 +1659,8 @@ To find out what card the pair consists of, one could use the
    'a'
 
 
+.. _simulating-scanf:
+
 Simulating scanf()
 ^^^^^^^^^^^^^^^^^^
 
@@ -1719,6 +1748,8 @@ beginning with ``'^'`` will match at the beginning of each line. ::
    <re.Match object; span=(4, 5), match='X'>
 
 
+.. _making-a-phonebook:
+
 Making a Phonebook
 ^^^^^^^^^^^^^^^^^^
 
@@ -1780,6 +1811,8 @@ house number from the street name:
    ['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]
 
 
+.. _text-munging:
+
 Text Munging
 ^^^^^^^^^^^^
 
@@ -1800,6 +1833,8 @@ in each word of a sentence except for the first and last characters::
    'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'
 
 
+.. _finding-all-adverbs:
+
 Finding all Adverbs
 ^^^^^^^^^^^^^^^^^^^
 
@@ -1813,6 +1848,8 @@ the following manner::
    ['carefully', 'quickly']
 
 
+.. _finding-all-adverbs-and-their-positions:
+
 Finding all Adverbs and their Positions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1829,6 +1866,8 @@ to find all of the adverbs *and their positions* in some text, they would use
    40-47: quickly
 
 
+.. _raw-string-notation:
+
 Raw String Notation
 ^^^^^^^^^^^^^^^^^^^
 
@@ -1853,6 +1892,8 @@ functionally identical::
    <re.Match object; span=(0, 1), match='\\'>
 
 
+.. _writing-a-tokenizer:
+
 Writing a Tokenizer
 ^^^^^^^^^^^^^^^^^^^