Issue #18758: Fixed and improved cross-references.
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst
index dbff57b..57bec84 100644
--- a/Doc/library/2to3.rst
+++ b/Doc/library/2to3.rst
@@ -290,11 +290,11 @@
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/abc.rst b/Doc/library/abc.rst
index ef8b08e..3a00a9c 100644
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -110,19 +110,19 @@
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 1e2bcd8..70ca8e7 100644
--- a/Doc/library/asyncore.rst
+++ b/Doc/library/asyncore.rst
@@ -53,10 +53,10 @@
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 a9fa23c..e747ba1 100644
--- a/Doc/library/audioop.rst
+++ b/Doc/library/audioop.rst
@@ -247,7 +247,7 @@
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 f4f4693..a04505f 100644
--- a/Doc/library/calendar.rst
+++ b/Doc/library/calendar.rst
@@ -294,10 +294,11 @@
.. 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.
.. versionadded:: 2.0
diff --git a/Doc/library/chunk.rst b/Doc/library/chunk.rst
index 64ce4e2..04c7e27 100644
--- a/Doc/library/chunk.rst
+++ b/Doc/library/chunk.rst
@@ -55,8 +55,9 @@
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:`~file.read`. If the methods
+ :meth:`~file.seek` and :meth:`~file.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 38e26bc..698fb11 100644
--- a/Doc/library/code.rst
+++ b/Doc/library/code.rst
@@ -33,11 +33,11 @@
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.
+ :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[, symbol]])
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index d283ede..829be68 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -47,9 +47,9 @@
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:
@@ -315,8 +315,8 @@
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:
@@ -397,12 +397,14 @@
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.
+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:`encode`/:meth:`decode` method is the
-same as if all the single inputs were joined into one, and this input was
+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.rst b/Doc/library/collections.rst
index 838c507..5bb3569 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -818,9 +818,9 @@
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:`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/difflib.rst b/Doc/library/difflib.rst
index f3b23e0..878d8e6 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -632,10 +632,12 @@
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:`~file.readlines` method of file-like objects. The delta
+ generated also consists of newline-terminated strings, ready to be
+ printed as-is via the :meth:`~file.writelines` method of a
+ file-like object.
.. _differ-examples:
@@ -645,7 +647,7 @@
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:`~file.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 ad75ed5..a3e89ca 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -356,7 +356,7 @@
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:`StandardError`
or :exc:`Exception` so that it is not accidentally caught by code that catches
diff --git a/Doc/library/fileinput.rst b/Doc/library/fileinput.rst
index ce892ce..710bef3 100644
--- a/Doc/library/fileinput.rst
+++ b/Doc/library/fileinput.rst
@@ -126,11 +126,12 @@
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:`~file.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:`~file.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 559e8a2..b42cf64 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -265,8 +265,8 @@
Store a file in ASCII transfer mode. *command* should be an appropriate
``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the
- open file object *file* using its :meth:`readline` method to provide the data to
- be stored. *callback* is an optional single parameter callable
+ open file object *file* using its :meth:`~file.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.
.. versionchanged:: 2.6
diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index 9fcbaaa..ca18a9c 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -313,8 +313,9 @@
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/mailbox.rst b/Doc/library/mailbox.rst
index c016564..dfd4ba7 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -994,7 +994,7 @@
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`).
@@ -1365,7 +1365,7 @@
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 7c6f0b4..562388e 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -136,8 +136,9 @@
.. function:: trunc(x)
- Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
- a long integer). Uses the ``__trunc__`` method.
+ Return the :class:`~numbers.Real` value *x* truncated to an
+ :class:`~numbers.Integral` (usually a long integer). Uses the
+ ``__trunc__`` method.
.. versionadded:: 2.6
diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst
index 59e9cf9..17d71ab 100644
--- a/Doc/library/msilib.rst
+++ b/Doc/library/msilib.rst
@@ -432,8 +432,9 @@
-----------
: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 1a65d24..1a9f2f5 100644
--- a/Doc/library/ossaudiodev.rst
+++ b/Doc/library/ossaudiodev.rst
@@ -163,11 +163,11 @@
is only useful in non-blocking mode. Has no return value, since the amount of
data written is always equal to the amount of data supplied.
-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:`IOError`.
+:c:func:`ioctl` fails, they all raise :exc:`IOError`.
.. method:: oss_audio_device.nonblock()
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 453c944..80e3fb2 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -186,7 +186,7 @@
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.
.. versionadded:: 2.6
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index d225392..a9053d1 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -116,13 +116,13 @@
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 96f437c..a8f411a 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(), os.lstat() and os.fstat().
diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst
index f6340a9..ff73796 100644
--- a/Doc/library/telnetlib.rst
+++ b/Doc/library/telnetlib.rst
@@ -189,7 +189,7 @@
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 (strings). The optional second
+ (:class:`regex objects <re-objects>`) or uncompiled (strings). The optional second
argument is a timeout, in seconds; the default is to block indefinitely.
Return a tuple of three items: the index in the list of the first regular
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 1129ea4..24b52c1 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -553,8 +553,8 @@
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/xml.sax.reader.rst b/Doc/library/xml.sax.reader.rst
index e09ad7f..6956cd1 100644
--- a/Doc/library/xml.sax.reader.rst
+++ b/Doc/library/xml.sax.reader.rst
@@ -329,12 +329,12 @@
---------------------------------
:class:`Attributes` objects implement a portion of the mapping protocol,
-including the methods :meth:`~collections.abc.Mapping.copy`,
-:meth:`~collections.abc.Mapping.get`,
-:meth:`~collections.abc.Mapping.has_key`,
-:meth:`~collections.abc.Mapping.items`,
-:meth:`~collections.abc.Mapping.keys`,
-and :meth:`~collections.abc.Mapping.values`. The following methods
+including the methods :meth:`~collections.Mapping.copy`,
+:meth:`~collections.Mapping.get`,
+:meth:`~collections.Mapping.has_key`,
+:meth:`~collections.Mapping.items`,
+:meth:`~collections.Mapping.keys`,
+and :meth:`~collections.Mapping.values`. The following methods
are also provided:
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 3e64487..261747a 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -180,8 +180,9 @@
.. note::
The file-like object is read-only and provides the following methods:
- :meth:`!read`, :meth:`!readline`, :meth:`!readlines`, :meth:`!__iter__`,
- :meth:`!next`.
+ :meth:`~file.read`, :meth:`~file.readline`,
+ :meth:`~file.readlines`, :meth:`__iter__`,
+ :meth:`~object.next`.
.. note::