From bfdcd436f0410e2b3eb34ce4fd7411488d3f13fb Mon Sep 17 00:00:00 2001
From: Serhiy Storchaka <storchaka@gmail.com>
Date: Sun, 13 Oct 2013 23:09:14 +0300
Subject: Issue #18758: Fixed and improved cross-references.

---
 Doc/faq/design.rst              |  3 ++-
 Doc/howto/unicode.rst           | 10 ++++++----
 Doc/howto/urllib2.rst           |  2 +-
 Doc/library/2to3.rst            |  4 ++--
 Doc/library/_thread.rst         |  2 +-
 Doc/library/abc.rst             | 18 +++++++++---------
 Doc/library/asyncore.rst        |  8 ++++----
 Doc/library/audioop.rst         |  2 +-
 Doc/library/calendar.rst        |  9 +++++----
 Doc/library/chunk.rst           |  5 +++--
 Doc/library/code.rst            | 14 +++++++-------
 Doc/library/codecs.rst          | 24 +++++++++++++-----------
 Doc/library/collections.abc.rst |  5 +++--
 Doc/library/collections.rst     |  6 +++---
 Doc/library/configparser.rst    |  3 ++-
 Doc/library/dbm.rst             |  5 +++--
 Doc/library/difflib.rst         | 20 +++++++++++---------
 Doc/library/exceptions.rst      | 11 +++++------
 Doc/library/fileinput.rst       | 11 ++++++-----
 Doc/library/ftplib.rst          |  4 ++--
 Doc/library/http.server.rst     |  6 +++---
 Doc/library/imaplib.rst         |  5 +++--
 Doc/library/inspect.rst         |  5 +++--
 Doc/library/io.rst              |  4 ++--
 Doc/library/itertools.rst       |  6 +++---
 Doc/library/mailbox.rst         |  4 ++--
 Doc/library/math.rst            |  9 +++++----
 Doc/library/msilib.rst          |  5 +++--
 Doc/library/ossaudiodev.rst     |  4 ++--
 Doc/library/pyexpat.rst         | 10 +++++-----
 Doc/library/shelve.rst          |  4 ++--
 Doc/library/socket.rst          |  2 +-
 Doc/library/socketserver.rst    | 14 +++++++-------
 Doc/library/stat.rst            |  4 ++--
 Doc/library/telnetlib.rst       |  2 +-
 Doc/library/time.rst            |  4 ++--
 Doc/library/unittest.mock.rst   |  8 ++++----
 Doc/library/warnings.rst        |  2 +-
 Doc/library/zipfile.rst         |  5 +++--
 Misc/NEWS                       |  2 ++
 40 files changed, 145 insertions(+), 126 deletions(-)

diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index 0f1c558..49e0c6d 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -634,7 +634,8 @@ Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base Classes
 (ABCs).  You can then use :func:`isinstance` and :func:`issubclass` to check
 whether an instance or a class implements a particular ABC.  The
 :mod:`collections.abc` module defines a set of useful ABCs such as
-:class:`Iterable`, :class:`Container`, and :class:`MutableMapping`.
+:class:`~collections.abc.Iterable`, :class:`~collections.abc.Container`, and
+:class:`~collections.abc.MutableMapping`.
 
 For Python, many of the advantages of interface specifications can be obtained
 by an appropriate test discipline for components.  There is also a tool,
diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst
index 486195a..4fc8c5c 100644
--- a/Doc/howto/unicode.rst
+++ b/Doc/howto/unicode.rst
@@ -531,9 +531,10 @@ The solution would be to use the low-level decoding interface to catch the case
 of partial coding sequences.  The work of implementing this has already been
 done for you: the built-in :func:`open` function can return a file-like object
 that assumes the file's contents are in a specified encoding and accepts Unicode
-parameters for methods such as :meth:`read` and :meth:`write`.  This works through
-:func:`open`\'s *encoding* and *errors* parameters which are interpreted just
-like those in :meth:`str.encode` and :meth:`bytes.decode`.
+parameters for methods such as :meth:`~io.TextIOBase.read` and
+:meth:`~io.TextIOBase.write`.  This works through:func:`open`\'s *encoding* and
+*errors* parameters which are interpreted just like those in :meth:`str.encode`
+and :meth:`bytes.decode`.
 
 Reading Unicode from a file is therefore simple::
 
@@ -656,7 +657,8 @@ encodings, taking a stream that returns data in encoding #1
 and behaving like a stream returning data in encoding #2.
 
 For example, if you have an input file *f* that's in Latin-1, you
-can wrap it with a :class:`StreamRecoder` to return bytes encoded in UTF-8::
+can wrap it with a :class:`~codecs.StreamRecoder` to return bytes encoded in
+UTF-8::
 
     new_f = codecs.StreamRecoder(f,
         # en/decoder: used by read() to encode its results and
diff --git a/Doc/howto/urllib2.rst b/Doc/howto/urllib2.rst
index 7afe9a6..74eeee0 100644
--- a/Doc/howto/urllib2.rst
+++ b/Doc/howto/urllib2.rst
@@ -57,7 +57,7 @@ The simplest way to use urllib.request is as follows::
     html = response.read()
 
 If you wish to retrieve a resource via URL and store it in a temporary location,
-you can do so via the :func:`urlretrieve` function::
+you can do so via the :func:`~urllib.request.urlretrieve` function::
 
     import urllib.request
     local_filename, headers = urllib.request.urlretrieve('http://python.org/')
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst
index 97e692f..1e5f42d 100644
--- a/Doc/library/2to3.rst
+++ b/Doc/library/2to3.rst
@@ -290,11 +290,11 @@ and off individually.  They are described here in more detail.
 
    Converts the use of iterator's :meth:`~iterator.next` methods to the
    :func:`next` function.  It also renames :meth:`next` methods to
-   :meth:`~object.__next__`.
+   :meth:`~iterator.__next__`.
 
 .. 2to3fixer:: nonzero
 
-   Renames :meth:`~object.__nonzero__` to :meth:`~object.__bool__`.
+   Renames :meth:`__nonzero__` to :meth:`~object.__bool__`.
 
 .. 2to3fixer:: numliterals
 
diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst
index fae2781..2e130c1 100644
--- a/Doc/library/_thread.rst
+++ b/Doc/library/_thread.rst
@@ -177,7 +177,7 @@ In addition to these methods, lock objects can also be used via the
   equivalent to calling :func:`_thread.exit`.
 
 * Not all built-in functions that may block waiting for I/O allow other threads
-  to run.  (The most popular ones (:func:`time.sleep`, :meth:`file.read`,
+  to run.  (The most popular ones (:func:`time.sleep`, :meth:`io.FileIO.read`,
   :func:`select.select`) work as expected.)
 
 * It is not possible to interrupt the :meth:`acquire` method on a lock --- the
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
index 6f23596..9299124 100644
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -110,19 +110,19 @@ This module provides the following class:
       MyIterable.register(Foo)
 
    The ABC ``MyIterable`` defines the standard iterable method,
-   :meth:`__iter__`, as an abstract method.  The implementation given here can
-   still be called from subclasses.  The :meth:`get_iterator` method is also
-   part of the ``MyIterable`` abstract base class, but it does not have to be
-   overridden in non-abstract derived classes.
+   :meth:`~iterator.__iter__`, as an abstract method.  The implementation given
+   here can still be called from subclasses.  The :meth:`get_iterator` method
+   is also part of the ``MyIterable`` abstract base class, but it does not have
+   to be overridden in non-abstract derived classes.
 
    The :meth:`__subclasshook__` class method defined here says that any class
-   that has an :meth:`__iter__` method in its :attr:`__dict__` (or in that of
-   one of its base classes, accessed via the :attr:`__mro__` list) is
-   considered a ``MyIterable`` too.
+   that has an :meth:`~iterator.__iter__` method in its
+   :attr:`~object.__dict__` (or in that of one of its base classes, accessed
+   via the :attr:`~class.__mro__` list) is considered a ``MyIterable`` too.
 
    Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
-   even though it does not define an :meth:`__iter__` method (it uses the
-   old-style iterable protocol, defined in terms of :meth:`__len__` and
+   even though it does not define an :meth:`~iterator.__iter__` method (it uses
+   the old-style iterable protocol, defined in terms of :meth:`__len__` and
    :meth:`__getitem__`).  Note that this will not make ``get_iterator``
    available as a method of ``Foo``, so it is provided separately.
 
diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst
index 7cacca1..8f494d0 100644
--- a/Doc/library/asyncore.rst
+++ b/Doc/library/asyncore.rst
@@ -53,10 +53,10 @@ any that have been added to the map during asynchronous service) is closed.
    channels have been closed.  All arguments are optional.  The *count*
    parameter defaults to None, resulting in the loop terminating only when all
    channels have been closed.  The *timeout* argument sets the timeout
-   parameter for the appropriate :func:`select` or :func:`poll` call, measured
-   in seconds; the default is 30 seconds.  The *use_poll* parameter, if true,
-   indicates that :func:`poll` should be used in preference to :func:`select`
-   (the default is ``False``).
+   parameter for the appropriate :func:`~select.select` or :func:`~select.poll`
+   call, measured in seconds; the default is 30 seconds.  The *use_poll*
+   parameter, if true, indicates that :func:`~select.poll` should be used in
+   preference to :func:`~select.select` (the default is ``False``).
 
    The *map* parameter is a dictionary whose items are the channels to watch.
    As channels are closed they are deleted from their map.  If *map* is
diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst
index d4c0c95..edb3870 100644
--- a/Doc/library/audioop.rst
+++ b/Doc/library/audioop.rst
@@ -241,7 +241,7 @@ to be stateless (i.e. to be able to tolerate packet loss) you should not only
 transmit the data but also the state.  Note that you should send the *initial*
 state (the one you passed to :func:`lin2adpcm`) along to the decoder, not the
 final state (as returned by the coder).  If you want to use
-:func:`struct.struct` to store the state in binary you can code the first
+:class:`struct.Struct` to store the state in binary you can code the first
 element (the predicted value) in 16 bits and the second (the delta index) in 8.
 
 The ADPCM coders have never been tried against other ADPCM coders, only against
diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst
index f495271..3187c43 100644
--- a/Doc/library/calendar.rst
+++ b/Doc/library/calendar.rst
@@ -272,10 +272,11 @@ For simple text calendars this module provides the following functions.
 
 .. function:: timegm(tuple)
 
-   An unrelated but handy function that takes a time tuple such as returned by the
-   :func:`gmtime` function in the :mod:`time` module, and returns the corresponding
-   Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding.  In
-   fact, :func:`time.gmtime` and :func:`timegm` are each others' inverse.
+   An unrelated but handy function that takes a time tuple such as returned by
+   the :func:`~time.gmtime` function in the :mod:`time` module, and returns the
+   corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX
+   encoding.  In fact, :func:`time.gmtime` and :func:`timegm` are each others'
+   inverse.
 
 
 The :mod:`calendar` module exports the following data attributes:
diff --git a/Doc/library/chunk.rst b/Doc/library/chunk.rst
index c1ba497..ae0a221 100644
--- a/Doc/library/chunk.rst
+++ b/Doc/library/chunk.rst
@@ -54,8 +54,9 @@ instance will fail with a :exc:`EOFError` exception.
 
    Class which represents a chunk.  The *file* argument is expected to be a
    file-like object.  An instance of this class is specifically allowed.  The
-   only method that is needed is :meth:`read`.  If the methods :meth:`seek` and
-   :meth:`tell` are present and don't raise an exception, they are also used.
+   only method that is needed is :meth:`~io.IOBase.read`.  If the methods
+   :meth:`~io.IOBase.seek` and :meth:`~io.IOBase.tell` are present and don't
+   raise an exception, they are also used.
    If these methods are present and raise an exception, they are expected to not
    have altered the object.  If the optional argument *align* is true, chunks
    are assumed to be aligned on 2-byte boundaries.  If *align* is false, no
diff --git a/Doc/library/code.rst b/Doc/library/code.rst
index 56214b9..e869004 100644
--- a/Doc/library/code.rst
+++ b/Doc/library/code.rst
@@ -29,13 +29,13 @@ build applications which provide an interactive interpreter prompt.
 
 .. function:: interact(banner=None, readfunc=None, local=None)
 
-   Convenience function to run a read-eval-print loop.  This creates a new instance
-   of :class:`InteractiveConsole` and sets *readfunc* to be used as the
-   :meth:`raw_input` method, if provided.  If *local* is provided, it is passed to
-   the :class:`InteractiveConsole` constructor for use as the default namespace for
-   the interpreter loop.  The :meth:`interact` method of the instance is then run
-   with *banner* passed as the banner to use, if provided.  The console object is
-   discarded after use.
+   Convenience function to run a read-eval-print loop.  This creates a new
+   instance of :class:`InteractiveConsole` and sets *readfunc* to be used as
+   the :meth:`InteractiveConsole.raw_input` method, if provided.  If *local* is
+   provided, it is passed to the :class:`InteractiveConsole` constructor for
+   use as the default namespace for the interpreter loop.  The :meth:`interact`
+   method of the instance is then run with *banner* passed as the banner to
+   use, if provided.  The console object is discarded after use.
 
 
 .. function:: compile_command(source, filename="<input>", symbol="single")
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 004f5c7..009ae26 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -65,9 +65,9 @@ It defines the following functions:
    The various functions or classes take the following arguments:
 
    *encode* and *decode*: These must be functions or methods which have the same
-   interface as the :meth:`encode`/:meth:`decode` methods of Codec instances (see
-   Codec Interface). The functions/methods are expected to work in a stateless
-   mode.
+   interface as the :meth:`~Codec.encode`/:meth:`~Codec.decode` methods of Codec
+   instances (see :ref:`Codec Interface <codec-objects>`). The functions/methods
+   are expected to work in a stateless mode.
 
    *incrementalencoder* and *incrementaldecoder*: These have to be factory
    functions providing the following interface:
@@ -333,8 +333,8 @@ implement the file protocols.
 
 The :class:`Codec` class defines the interface for stateless encoders/decoders.
 
-To simplify and standardize error handling, the :meth:`encode` and
-:meth:`decode` methods may implement different error handling schemes by
+To simplify and standardize error handling, the :meth:`~Codec.encode` and
+:meth:`~Codec.decode` methods may implement different error handling schemes by
 providing the *errors* string argument.  The following string values are defined
 and implemented by all standard Python codecs:
 
@@ -428,12 +428,14 @@ interfaces of the stateless encoder and decoder:
 The :class:`IncrementalEncoder` and :class:`IncrementalDecoder` classes provide
 the basic interface for incremental encoding and decoding. Encoding/decoding the
 input isn't done with one call to the stateless encoder/decoder function, but
-with multiple calls to the :meth:`encode`/:meth:`decode` method of the
-incremental encoder/decoder. The incremental encoder/decoder keeps track of the
-encoding/decoding process during method calls.
-
-The joined output of calls to the :meth:`encode`/:meth:`decode` method is the
-same as if all the single inputs were joined into one, and this input was
+with multiple calls to the
+:meth:`~IncrementalEncoder.encode`/:meth:`~IncrementalDecoder.decode` method of
+the incremental encoder/decoder. The incremental encoder/decoder keeps track of
+the encoding/decoding process during method calls.
+
+The joined output of calls to the
+:meth:`~IncrementalEncoder.encode`/:meth:`~IncrementalDecoder.decode` method is
+the same as if all the single inputs were joined into one, and this input was
 encoded/decoded with the stateless encoder/decoder.
 
 
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 06dfe80..4b21932 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -98,8 +98,9 @@ ABC                        Inherits from          Abstract Methods        Mixin
 
 .. class:: Iterator
 
-   ABC for classes that provide the :meth:`__iter__` and :meth:`__next__` methods.
-   See also the definition of :term:`iterator`.
+   ABC for classes that provide the :meth:`~iterator.__iter__` and
+   :meth:`~iterator.__next__` methods.  See also the definition of
+   :term:`iterator`.
 
 .. class:: Sequence
            MutableSequence
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index a47d99b..7645f2a 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -974,9 +974,9 @@ reverse iteration using :func:`reversed`.
 Equality tests between :class:`OrderedDict` objects are order-sensitive
 and are implemented as ``list(od1.items())==list(od2.items())``.
 Equality tests between :class:`OrderedDict` objects and other
-:class:`Mapping` objects are order-insensitive like regular dictionaries.
-This allows :class:`OrderedDict` objects to be substituted anywhere a
-regular dictionary is used.
+:class:`~collections.abc.Mapping` objects are order-insensitive like regular
+dictionaries.  This allows :class:`OrderedDict` objects to be substituted
+anywhere a regular dictionary is used.
 
 The :class:`OrderedDict` constructor and :meth:`update` method both accept
 keyword arguments, but their order is lost because Python's function call
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index f9a87ef..024d27c 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -371,7 +371,8 @@ are changed on a section proxy, they are actually mutated in the original
 parser.
 
 :mod:`configparser` objects behave as close to actual dictionaries as possible.
-The mapping interface is complete and adheres to the ``MutableMapping`` ABC.
+The mapping interface is complete and adheres to the
+:class:`~collections.abc.MutableMapping` ABC.
 However, there are a few differences that should be taken into account:
 
 * By default, all keys in sections are accessible in a case-insensitive manner
diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index e3d50b9..81a05c7 100644
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -317,8 +317,9 @@ The module defines the following:
    database has to be created.  It defaults to octal ``0o666`` (and will be modified
    by the prevailing umask).
 
-   In addition to the methods provided by the :class:`collections.MutableMapping` class,
-   :class:`dumbdbm` objects provide the following method:
+   In addition to the methods provided by the
+   :class:`collections.abc.MutableMapping` class, :class:`dumbdbm` objects
+   provide the following method:
 
    .. method:: dumbdbm.sync()
 
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index ad1466e..5ab1a46 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -143,8 +143,8 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
 
    By default, the diff control lines (those with ``***`` or ``---``) are created
    with a trailing newline.  This is helpful so that inputs created from
-   :func:`file.readlines` result in diffs that are suitable for use with
-   :func:`file.writelines` since both the inputs and outputs have trailing
+   :func:`io.IOBase.readlines` result in diffs that are suitable for use with
+   :func:`io.IOBase.writelines` since both the inputs and outputs have trailing
    newlines.
 
    For inputs that do not have trailing newlines, set the *lineterm* argument to
@@ -275,8 +275,8 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
 
    By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) are
    created with a trailing newline.  This is helpful so that inputs created from
-   :func:`file.readlines` result in diffs that are suitable for use with
-   :func:`file.writelines` since both the inputs and outputs have trailing
+   :func:`io.IOBase.readlines` result in diffs that are suitable for use with
+   :func:`io.IOBase.writelines` since both the inputs and outputs have trailing
    newlines.
 
    For inputs that do not have trailing newlines, set the *lineterm* argument to
@@ -629,10 +629,12 @@ The :class:`Differ` class has this constructor:
 
       Compare two sequences of lines, and generate the delta (a sequence of lines).
 
-      Each sequence must contain individual single-line strings ending with newlines.
-      Such sequences can be obtained from the :meth:`readlines` method of file-like
-      objects.  The delta generated also consists of newline-terminated strings, ready
-      to be printed as-is via the :meth:`writelines` method of a file-like object.
+      Each sequence must contain individual single-line strings ending with
+      newlines.  Such sequences can be obtained from the
+      :meth:`~io.IOBase.readlines` method of file-like objects.  The delta
+      generated also consists of newline-terminated strings, ready to be
+      printed as-is via the :meth:`~io.IOBase.writelines` method of a
+      file-like object.
 
 
 .. _differ-examples:
@@ -642,7 +644,7 @@ Differ Example
 
 This example compares two texts. First we set up the texts, sequences of
 individual single-line strings ending with newlines (such sequences can also be
-obtained from the :meth:`readlines` method of file-like objects):
+obtained from the :meth:`~io.BaseIO.readlines` method of file-like objects):
 
    >>> text1 = '''  1. Beautiful is better than ugly.
    ...   2. Explicit is better than implicit.
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 2672cf2..1854318 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -146,10 +146,9 @@ The following exceptions are the exceptions that are usually raised.
 
 .. exception:: EOFError
 
-   Raised when one of the built-in functions (:func:`input` or :func:`raw_input`)
-   hits an end-of-file condition (EOF) without reading any data. (N.B.: the
-   :meth:`file.read` and :meth:`file.readline` methods return an empty string
-   when they hit EOF.)
+   Raised when the :func:`input` function hits an end-of-file condition (EOF)
+   without reading any data. (N.B.: the :meth:`io.IOBase.read` and
+   :meth:`io.IOBase.readline` methods return an empty string when they hit EOF.)
 
 
 .. exception:: FloatingPointError
@@ -360,7 +359,7 @@ The following exceptions are the exceptions that are usually raised.
    executed, and so that a debugger can execute a script without running the risk
    of losing control.  The :func:`os._exit` function can be used if it is
    absolutely positively necessary to exit immediately (for example, in the child
-   process after a call to :func:`fork`).
+   process after a call to :func:`os.fork`).
 
    The exception inherits from :exc:`BaseException` instead of :exc:`Exception` so
    that it is not accidentally caught by code that catches :exc:`Exception`.  This
@@ -623,7 +622,7 @@ module for more information.
 
 .. exception:: BytesWarning
 
-   Base class for warnings related to :class:`bytes` and :class:`buffer`.
+   Base class for warnings related to :class:`bytes` and :class:`bytearray`.
 
 
 .. exception:: ResourceWarning
diff --git a/Doc/library/fileinput.rst b/Doc/library/fileinput.rst
index f8ec436..d5a4875 100644
--- a/Doc/library/fileinput.rst
+++ b/Doc/library/fileinput.rst
@@ -136,11 +136,12 @@ available for subclassing as well:
 
    Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
    :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
-   :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions
-   of the same name in the module. In addition it has a :meth:`readline` method
-   which returns the next input line, and a :meth:`__getitem__` method which
-   implements the sequence behavior.  The sequence must be accessed in strictly
-   sequential order; random access and :meth:`readline` cannot be mixed.
+   :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the
+   functions of the same name in the module. In addition it has a
+   :meth:`~io.TextIOBase.readline` method which returns the next input line,
+   and a :meth:`__getitem__` method which implements the sequence behavior.
+   The sequence must be accessed in strictly sequential order; random access
+   and :meth:`~io.TextIOBase.readline` cannot be mixed.
 
    With *mode* you can specify which file mode will be passed to :func:`open`. It
    must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index d9f1895..dcb2ac4 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -272,7 +272,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
    Store a file in binary transfer mode.  *cmd* should be an appropriate
    ``STOR`` command: ``"STOR filename"``. *file* is a :term:`file object`
-   (opened in binary mode) which is read until EOF using its :meth:`read`
+   (opened in binary mode) which is read until EOF using its :meth:`~io.IOBase.read`
    method in blocks of size *blocksize* to provide the data to be stored.
    The *blocksize* argument defaults to 8192.  *callback* is an optional single
    parameter callable that is called on each block of data after it is sent.
@@ -286,7 +286,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
    Store a file in ASCII transfer mode.  *cmd* should be an appropriate
    ``STOR`` command (see :meth:`storbinary`).  Lines are read until EOF from the
-   :term:`file object` *file* (opened in binary mode) using its :meth:`readline`
+   :term:`file object` *file* (opened in binary mode) using its :meth:`~io.IOBase.readline`
    method to provide the data to be stored.  *callback* is an optional single
    parameter callable that is called on each line after it is sent.
 
diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst
index cbad3ed..5aeb719 100644
--- a/Doc/library/http.server.rst
+++ b/Doc/library/http.server.rst
@@ -29,8 +29,8 @@ handler.  Code to create and run the server looks like this::
 
 .. class:: HTTPServer(server_address, RequestHandlerClass)
 
-   This class builds on the :class:`TCPServer` class by storing the server
-   address as instance variables named :attr:`server_name` and
+   This class builds on the :class:`~socketserver.TCPServer` class by storing
+   the server address as instance variables named :attr:`server_name` and
    :attr:`server_port`. The server is accessible by the handler, typically
    through the handler's :attr:`server` instance variable.
 
@@ -319,7 +319,7 @@ of which this module provides three different variants:
       file's contents are returned; otherwise a directory listing is generated
       by calling the :meth:`list_directory` method. This method uses
       :func:`os.listdir` to scan the directory, and returns a ``404`` error
-      response if the :func:`listdir` fails.
+      response if the :func:`~os.listdir` fails.
 
       If the request was mapped to a file, it is opened and the contents are
       returned.  Any :exc:`OSError` exception in opening the requested file is
diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index 59a61da..01236fb 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -310,8 +310,9 @@ An :class:`IMAP4` instance has the following methods:
 
    Opens socket to *port* at *host*.  This method is implicitly called by
    the :class:`IMAP4` constructor.  The connection objects established by this
-   method will be used in the ``read``, ``readline``, ``send``, and ``shutdown``
-   methods.  You may override this method.
+   method will be used in the :meth:`IMAP4.read`, :meth:`IMAP4.readline`,
+   :meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods.  You may override
+   this method.
 
 
 .. method:: IMAP4.partial(message_num, message_part, start, length)
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 40f482b..625ea6e 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -906,8 +906,9 @@ but avoids executing code when it fetches attributes.
    that raise AttributeError). It can also return descriptors objects
    instead of instance members.
 
-   If the instance :attr:`__dict__` is shadowed by another member (for example a
-   property) then this function will be unable to find instance members.
+   If the instance :attr:`~object.__dict__` is shadowed by another member (for
+   example a property) then this function will be unable to find instance
+   members.
 
    .. versionadded:: 3.2
 
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 8f3964f..73288f8 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -157,7 +157,7 @@ standard stream implementations.
       The abstract base classes also provide default implementations of some
       methods in order to help implementation of concrete stream classes.  For
       example, :class:`BufferedIOBase` provides unoptimized implementations of
-      ``readinto()`` and ``readline()``.
+      :meth:`~IOBase.readinto` and :meth:`~IOBase.readline`.
 
 At the top of the I/O hierarchy is the abstract base class :class:`IOBase`.  It
 defines the basic interface to a stream.  Note, however, that there is no
@@ -228,7 +228,7 @@ I/O Base Classes
 
    The basic type used for binary data read from or written to a file is
    :class:`bytes`.  :class:`bytearray`\s are accepted too, and in some cases
-   (such as :class:`readinto`) required.  Text I/O classes work with
+   (such as :meth:`readinto`) required.  Text I/O classes work with
    :class:`str` data.
 
    Note that calling any method (even inquiries) on a closed stream is
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 0156c05..b37af61 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -88,9 +88,9 @@ loops that truncate the stream.
 .. function:: accumulate(iterable[, func])
 
     Make an iterator that returns accumulated sums. Elements may be any addable
-    type including :class:`Decimal` or :class:`Fraction`.  If the optional
-    *func* argument is supplied, it should be a function of two arguments
-    and it will be used instead of addition.
+    type including :class:`~decimal.Decimal` or :class:`~fractions.Fraction`.
+    If the optional *func* argument is supplied, it should be a function of two
+    arguments and it will be used instead of addition.
 
     Equivalent to::
 
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index 2d8ba71..d668a6ea 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -1009,7 +1009,7 @@ When a :class:`MaildirMessage` instance is created based upon a
       Set the "From " line to *from_*, which should be specified without a
       leading "From " or trailing newline. For convenience, *time_* may be
       specified and will be formatted appropriately and appended to *from_*. If
-      *time_* is specified, it should be a :class:`struct_time` instance, a
+      *time_* is specified, it should be a :class:`time.struct_time` instance, a
       tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
       :meth:`time.gmtime`).
 
@@ -1380,7 +1380,7 @@ When a :class:`BabylMessage` instance is created based upon an
       Set the "From " line to *from_*, which should be specified without a
       leading "From " or trailing newline. For convenience, *time_* may be
       specified and will be formatted appropriately and appended to *from_*. If
-      *time_* is specified, it should be a :class:`struct_time` instance, a
+      *time_* is specified, it should be a :class:`time.struct_time` instance, a
       tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
       :meth:`time.gmtime`).
 
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index b69d6c6..7c3ab59 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -31,7 +31,7 @@ Number-theoretic and representation functions
 
    Return the ceiling of *x*, the smallest integer greater than or equal to *x*.
    If *x* is not a float, delegates to ``x.__ceil__()``, which should return an
-   :class:`Integral` value.
+   :class:`~numbers.Integral` value.
 
 
 .. function:: copysign(x, y)
@@ -53,7 +53,7 @@ Number-theoretic and representation functions
 
    Return the floor of *x*, the largest integer less than or equal to *x*.
    If *x* is not a float, delegates to ``x.__floor__()``, which should return an
-   :class:`Integral` value.
+   :class:`~numbers.Integral` value.
 
 
 .. function:: fmod(x, y)
@@ -133,8 +133,9 @@ Number-theoretic and representation functions
 
 .. function:: trunc(x)
 
-   Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
-   an integer). Delegates to ``x.__trunc__()``.
+   Return the :class:`~numbers.Real` value *x* truncated to an
+   :class:`~numbers.Integral` (usually an integer). Delegates to
+   ``x.__trunc__()``.
 
 
 Note that :func:`frexp` and :func:`modf` have a different call/return pattern
diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst
index efb6667..d3451c8 100644
--- a/Doc/library/msilib.rst
+++ b/Doc/library/msilib.rst
@@ -429,8 +429,9 @@ GUI classes
 -----------
 
 :mod:`msilib` provides several classes that wrap the GUI tables in an MSI
-database. However, no standard user interface is provided; use :mod:`bdist_msi`
-to create MSI files with a user-interface for installing Python packages.
+database. However, no standard user interface is provided; use
+:mod:`~distutils.command.bdist_msi` to create MSI files with a user-interface
+for installing Python packages.
 
 
 .. class:: Control(dlg, name)
diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst
index 4a0c3a3..b53e80f 100644
--- a/Doc/library/ossaudiodev.rst
+++ b/Doc/library/ossaudiodev.rst
@@ -169,11 +169,11 @@ and (read-only) attributes:
    be used in a :keyword:`with` statement.
 
 
-The following methods each map to exactly one :func:`ioctl` system call.  The
+The following methods each map to exactly one :c:func:`ioctl` system call.  The
 correspondence is obvious: for example, :meth:`setfmt` corresponds to the
 ``SNDCTL_DSP_SETFMT`` ioctl, and :meth:`sync` to ``SNDCTL_DSP_SYNC`` (this can
 be useful when consulting the OSS documentation).  If the underlying
-:func:`ioctl` fails, they all raise :exc:`OSError`.
+:c:func:`ioctl` fails, they all raise :exc:`OSError`.
 
 
 .. method:: oss_audio_device.nonblock()
diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst
index e3b7917..b1543d8 100644
--- a/Doc/library/pyexpat.rst
+++ b/Doc/library/pyexpat.rst
@@ -484,8 +484,8 @@ ExpatError Exceptions
 .. attribute:: ExpatError.code
 
    Expat's internal error number for the specific error.  The
-   :data:`errors.messages` dictionary maps these error numbers to Expat's error
-   messages.  For example::
+   :data:`errors.messages <xml.parsers.expat.errors.messages>` dictionary maps
+   these error numbers to Expat's error messages.  For example::
 
       from xml.parsers.expat import ParserCreate, ExpatError, errors
 
@@ -495,9 +495,9 @@ ExpatError Exceptions
       except ExpatError as err:
           print("Error:", errors.messages[err.code])
 
-   The :mod:`errors` module also provides error message constants and a
-   dictionary :data:`~errors.codes` mapping these messages back to the error
-   codes, see below.
+   The :mod:`~xml.parsers.expat.errors` module also provides error message
+   constants and a dictionary :data:`~xml.parsers.expat.errors.codes` mapping
+   these messages back to the error codes, see below.
 
 
 .. attribute:: ExpatError.lineno
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 9d7d504..048f80a 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -103,8 +103,8 @@ Restrictions
 
 .. class:: Shelf(dict, protocol=None, writeback=False, keyencoding='utf-8')
 
-   A subclass of :class:`collections.MutableMapping` which stores pickled values
-   in the *dict* object.
+   A subclass of :class:`collections.abc.MutableMapping` which stores pickled
+   values in the *dict* object.
 
    By default, version 0 pickles are used to serialize values.  The version of the
    pickle protocol can be specified with the *protocol* parameter. See the
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index b442b7c..aa18ae4 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -275,7 +275,7 @@ The module :mod:`socket` exports the following constants and functions:
           RCVALL_*
 
    Constants for Windows' WSAIoctl(). The constants are used as arguments to the
-   :meth:`ioctl` method of socket objects.
+   :meth:`~socket.socket.ioctl` method of socket objects.
 
 
 .. data:: TIPC_*
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index 500b3cb..1ec4438 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -111,13 +111,13 @@ can be implemented by using a synchronous server and doing an explicit fork in
 the request handler class :meth:`handle` method.
 
 Another approach to handling multiple simultaneous requests in an environment
-that supports neither threads nor :func:`fork` (or where these are too expensive
-or inappropriate for the service) is to maintain an explicit table of partially
-finished requests and to use :func:`select` to decide which request to work on
-next (or whether to handle a new incoming request).  This is particularly
-important for stream services where each client can potentially be connected for
-a long time (if threads or subprocesses cannot be used).  See :mod:`asyncore`
-for another way to manage this.
+that supports neither threads nor :func:`~os.fork` (or where these are too
+expensive or inappropriate for the service) is to maintain an explicit table of
+partially finished requests and to use :func:`~select.select` to decide which
+request to work on next (or whether to handle a new incoming request).  This is
+particularly important for stream services where each client can potentially be
+connected for a long time (if threads or subprocesses cannot be used).  See
+:mod:`asyncore` for another way to manage this.
 
 .. XXX should data and methods be intermingled, or separate?
    how should the distinction between class and instance variables be drawn?
diff --git a/Doc/library/stat.rst b/Doc/library/stat.rst
index 02513df..6c20aa2 100644
--- a/Doc/library/stat.rst
+++ b/Doc/library/stat.rst
@@ -1,5 +1,5 @@
-:mod:`stat` --- Interpreting :func:`stat` results
-=================================================
+:mod:`stat` --- Interpreting :func:`~os.stat` results
+=====================================================
 
 .. module:: stat
    :synopsis: Utilities for interpreting the results of os.stat(),
diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst
index 9bc79c5..b0e4d1d 100644
--- a/Doc/library/telnetlib.rst
+++ b/Doc/library/telnetlib.rst
@@ -185,7 +185,7 @@ Telnet Objects
    Read until one from a list of a regular expressions matches.
 
    The first argument is a list of regular expressions, either compiled
-   (:class:`re.RegexObject` instances) or uncompiled (byte strings). The
+   (:ref:`regex objects <re-objects>`) or uncompiled (byte strings). The
    optional second argument is a timeout, in seconds; the default is to block
    indefinitely.
 
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index cc8f716..64b5e04 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -677,8 +677,8 @@ The module defines the following functions and data items:
       of many format specifiers in :func:`strftime` and :func:`strptime`.
 
    Module :mod:`calendar`
-      General calendar-related functions.   :func:`timegm` is the inverse of
-      :func:`gmtime` from this module.
+      General calendar-related functions.   :func:`~calendar.timegm` is the
+      inverse of :func:`gmtime` from this module.
 
 .. rubric:: Footnotes
 
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 6f3f693..9494861 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -210,8 +210,8 @@ the `new_callable` argument to `patch`.
       Accessing any attribute not in this list will raise an `AttributeError`.
 
       If `spec` is an object (rather than a list of strings) then
-      :attr:`__class__` returns the class of the spec object. This allows mocks
-      to pass `isinstance` tests.
+      :attr:`~instance.__class__` returns the class of the spec object. This
+      allows mocks to pass `isinstance` tests.
 
     * `spec_set`: A stricter variant of `spec`. If used, attempting to *set*
       or get an attribute on the mock that isn't on the object passed as
@@ -1969,8 +1969,8 @@ mock_open
     default) then a `MagicMock` will be created for you, with the API limited
     to methods or attributes available on standard file handles.
 
-    `read_data` is a string for the `read` method of the file handle to return.
-    This is an empty string by default.
+    `read_data` is a string for the `~io.IOBase.read` method of the file handle
+    to return.  This is an empty string by default.
 
 Using `open` as a context manager is a great way to ensure your file handles
 are closed properly and is becoming common::
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index ce69f7b..8a538ad 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -89,7 +89,7 @@ following warnings category classes are currently defined:
 |                                  | Unicode.                                      |
 +----------------------------------+-----------------------------------------------+
 | :exc:`BytesWarning`              | Base category for warnings related to         |
-|                                  | :class:`bytes` and :class:`buffer`.           |
+|                                  | :class:`bytes` and :class:`bytearray`.        |
 +----------------------------------+-----------------------------------------------+
 | :exc:`ResourceWarning`           | Base category for warnings related to         |
 |                                  | resource usage.                               |
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 75e8fd5..7a6482b 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -213,8 +213,9 @@ ZipFile Objects
    .. note::
 
       The file-like object is read-only and provides the following methods:
-      :meth:`!read`, :meth:`!readline`, :meth:`!readlines`, :meth:`!__iter__`,
-      :meth:`!__next__`.
+      :meth:`~io.BufferedIOBase.read`, :meth:`~io.IOBase.readline`,
+      :meth:`~io.IOBase.readlines`, :meth:`__iter__`,
+      :meth:`~iterator.__next__`.
 
    .. note::
 
diff --git a/Misc/NEWS b/Misc/NEWS
index 3b5b4c5..636f295 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -495,6 +495,8 @@ Tests
 Documentation
 -------------
 
+- Issue #18758: Fixed and improved cross-references.
+
 - Issue #18743: Fix references to non-existant "StringIO" module.
 
 - Issue #18783: Removed existing mentions of Python long type in docstrings,
-- 
cgit v0.12