#16760: merge with 3.3.

Doc/howto/regex.rst

@@ -354,9 +354,9 @@ for a complete listing.
 +------------------+-----------------------------------------------+
 
 :meth:`match` and :meth:`search` return ``None`` if no match can be found.  If
-they're successful, a ``MatchObject`` instance is returned, containing
+they're successful, a :ref:`match object <match-objects>` instance is returned,
-information about the match: where it starts and ends, the substring it matched,
+containing information about the match: where it starts and ends, the substring
-and more.
+it matched, and more.
 
 You can learn about this by interactively experimenting with the :mod:`re`
 module.  If you have :mod:`tkinter` available, you may also want to look at
@@ -386,16 +386,16 @@ interpreter to print no output.  You can explicitly print the result of
    None
 
 Now, let's try it on a string that it should match, such as ``tempo``.  In this
-case, :meth:`match` will return a :class:`MatchObject`, so you should store the
+case, :meth:`match` will return a :ref:`match object <match-objects>`, so you
-result in a variable for later use. ::
+should store the result in a variable for later use. ::
 
    >>> m = p.match('tempo')
    >>> m  #doctest: +ELLIPSIS
    <_sre.SRE_Match object at 0x...>
 
-Now you can query the :class:`MatchObject` for information about the matching
+Now you can query the :ref:`match object <match-objects>` for information
-string.   :class:`MatchObject` instances also have several methods and
+about the matching string.  :ref:`match object <match-objects>` instances
-attributes; the most important ones are:
+also have several methods and attributes; the most important ones are:
 
 +------------------+--------------------------------------------+
 | Method/Attribute | Purpose                                    |
@@ -436,8 +436,9 @@ case. ::
    >>> m.span()
    (4, 11)
 
-In actual programs, the most common style is to store the :class:`MatchObject`
+In actual programs, the most common style is to store the
-in a variable, and then check if it was ``None``.  This usually looks like::
+:ref:`match object <match-objects>` in a variable, and then check if it was
+``None``.  This usually looks like::
 
    p = re.compile( ... )
    m = p.match( 'string goes here' )
@@ -454,8 +455,8 @@ Two pattern methods return all of the matches for a pattern.
    ['12', '11', '10']
 
 :meth:`findall` has to create the entire list before it can be returned as the
-result.  The :meth:`finditer` method returns a sequence of :class:`MatchObject`
+result.  The :meth:`finditer` method returns a sequence of
-instances as an :term:`iterator`::
+:ref:`match object <match-objects>` instances as an :term:`iterator`::
 
    >>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')
    >>> iterator  #doctest: +ELLIPSIS
@@ -476,7 +477,7 @@ You don't have to create a pattern object and call its methods; the
 :func:`search`, :func:`findall`, :func:`sub`, and so forth.  These functions
 take the same arguments as the corresponding pattern method, with
 the RE string added as the first argument, and still return either ``None`` or a
-:class:`MatchObject` instance. ::
+:ref:`match object <match-objects>` instance. ::
 
    >>> print(re.match(r'From\s+', 'Fromage amk'))
    None
@@ -786,9 +787,9 @@ Groups indicated with ``'('``, ``')'`` also capture the starting and ending
 index of the text that they match; this can be retrieved by passing an argument
 to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`.  Groups are
 numbered starting with 0.  Group 0 is always present; it's the whole RE, so
-:class:`MatchObject` methods all have group 0 as their default argument.  Later
+:ref:`match object <match-objects>` methods all have group 0 as their default
-we'll see how to express groups that don't capture the span of text that they
+argument.  Later we'll see how to express groups that don't capture the span
-match. ::
+of text that they match. ::
 
    >>> p = re.compile('(a)b')
    >>> m = p.match('ab')
@@ -908,10 +909,10 @@ numbers, groups can be referenced by a name.
 The syntax for a named group is one of the Python-specific extensions:
 ``(?P<name>...)``.  *name* is, obviously, the name of the group.  Named groups
 also behave exactly like capturing groups, and additionally associate a name
-with a group.  The :class:`MatchObject` methods that deal with capturing groups
+with a group.  The :ref:`match object <match-objects>` methods that deal with
-all accept either integers that refer to the group by number or strings that
+capturing groups all accept either integers that refer to the group by number
-contain the desired group's name.  Named groups are still given numbers, so you
+or strings that contain the desired group's name.  Named groups are still
-can retrieve information about a group in two ways::
+given numbers, so you can retrieve information about a group in two ways::
 
    >>> p = re.compile(r'(?P<word>\b\w+\b)')
    >>> m = p.search( '(((( Lots of punctuation )))' )
@@ -1175,11 +1176,11 @@ three variations of the replacement string. ::
 
 *replacement* can also be a function, which gives you even more control.  If
 *replacement* is a function, the function is called for every non-overlapping
-occurrence of *pattern*.  On each call, the function is  passed a
+occurrence of *pattern*.  On each call, the function is passed a
-:class:`MatchObject` argument for the match and can use this information to
+:ref:`match object <match-objects>` argument for the match and can use this
-compute the desired replacement string and return it.
+information to compute the desired replacement string and return it.
 
-In the following example, the replacement function translates  decimals into
+In the following example, the replacement function translates decimals into
 hexadecimal::
 
    >>> def hexrepl(match):