Issue #18760: Improved cross-references in the xml package.

7 files changed, 67 insertions, 44 deletions

diff --git a/Doc/library/xml.dom.pulldom.rst b/Doc/library/xml.dom.pulldom.rst
index 8aa9cfb..a9c9f67 100644
--- a/Doc/library/xml.dom.pulldom.rst
+++ b/Doc/library/xml.dom.pulldom.rst
@@ -74,7 +74,8 @@ and switch to DOM-related processing.
 
    Return a :class:`DOMEventStream` from the given input. *stream_or_string* may be
    either a file name, or a file-like object. *parser*, if given, must be a
-   :class:`XmlReader` object. This function will change the document handler of the
+   :class:`~xml.sax.xmlreader.XMLReader` object. This function will change the
+   document handler of the
    parser and activate namespace support; other parser configuration (like
    setting an entity resolver) must have been done in advance.
 
diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst
index 1a3a6a4..19512ed 100644
--- a/Doc/library/xml.dom.rst
+++ b/Doc/library/xml.dom.rst
@@ -422,14 +422,15 @@ objects:
 
 In addition, the Python DOM interface requires that some additional support is
 provided to allow :class:`NodeList` objects to be used as Python sequences.  All
-:class:`NodeList` implementations must include support for :meth:`__len__` and
-:meth:`__getitem__`; this allows iteration over the :class:`NodeList` in
+:class:`NodeList` implementations must include support for
+:meth:`~object.__len__` and
+:meth:`~object.__getitem__`; this allows iteration over the :class:`NodeList` in
 :keyword:`for` statements and proper support for the :func:`len` built-in
 function.
 
 If a DOM implementation supports modification of the document, the
-:class:`NodeList` implementation must also support the :meth:`__setitem__` and
-:meth:`__delitem__` methods.
+:class:`NodeList` implementation must also support the
+:meth:`~object.__setitem__` and :meth:`~object.__delitem__` methods.
 
 
 .. _dom-documenttype-objects:
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index d0b59ef..7270067 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -664,8 +664,9 @@ Element Objects
       or contents.
 
    :class:`Element` objects also support the following sequence type methods
-   for working with subelements: :meth:`__delitem__`, :meth:`__getitem__`,
-   :meth:`__setitem__`, :meth:`__len__`.
+   for working with subelements: :meth:`~object.__delitem__`,
+   :meth:`~object.__getitem__`, :meth:`~object.__setitem__`,
+   :meth:`~object.__len__`.
 
    Caution: Elements with no subelements will test as ``False``.  This behavior
    will change in future versions.  Use specific ``len(elem)`` or ``elem is
diff --git a/Doc/library/xml.sax.handler.rst b/Doc/library/xml.sax.handler.rst
index 1a6b391..0fb3341 100644
--- a/Doc/library/xml.sax.handler.rst
+++ b/Doc/library/xml.sax.handler.rst
@@ -237,7 +237,8 @@ events in the input document:
    Signals the start of an element in non-namespace mode.
 
    The *name* parameter contains the raw XML 1.0 name of the element type as a
-   string and the *attrs* parameter holds an object of the :class:`Attributes`
+   string and the *attrs* parameter holds an object of the
+   :class:`~xml.sax.xmlreader.Attributes`
    interface (see :ref:`attributes-objects`) containing the attributes of
    the element.  The object passed as *attrs* may be re-used by the parser; holding
    on to a reference to it is not a reliable way to keep a copy of the attributes.
@@ -260,7 +261,8 @@ events in the input document:
    The *name* parameter contains the name of the element type as a ``(uri,
    localname)`` tuple, the *qname* parameter contains the raw XML 1.0 name used in
    the source document, and the *attrs* parameter holds an instance of the
-   :class:`AttributesNS` interface (see :ref:`attributes-ns-objects`)
+   :class:`~xml.sax.xmlreader.AttributesNS` interface (see
+   :ref:`attributes-ns-objects`)
    containing the attributes of the element.  If no namespace is associated with
    the element, the *uri* component of *name* will be ``None``.  The object passed
    as *attrs* may be re-used by the parser; holding on to a reference to it is not
@@ -376,8 +378,9 @@ ErrorHandler Objects
 --------------------
 
 Objects with this interface are used to receive error and warning information
-from the :class:`XMLReader`.  If you create an object that implements this
-interface, then register the object with your :class:`XMLReader`, the parser
+from the :class:`~xml.sax.xmlreader.XMLReader`.  If you create an object that
+implements this interface, then register the object with your
+:class:`~xml.sax.xmlreader.XMLReader`, the parser
 will call the methods in your object to report all warnings and errors. There
 are three levels of errors available: warnings, (possibly) recoverable errors,
 and unrecoverable errors.  All methods take a :exc:`SAXParseException` as the
diff --git a/Doc/library/xml.sax.reader.rst b/Doc/library/xml.sax.reader.rst
index 6683da1..3ab6063 100644
--- a/Doc/library/xml.sax.reader.rst
+++ b/Doc/library/xml.sax.reader.rst
@@ -106,47 +106,50 @@ The :class:`XMLReader` interface supports the following methods:
 
 .. method:: XMLReader.getContentHandler()
 
-   Return the current :class:`ContentHandler`.
+   Return the current :class:`~xml.sax.handler.ContentHandler`.
 
 
 .. method:: XMLReader.setContentHandler(handler)
 
-   Set the current :class:`ContentHandler`.  If no :class:`ContentHandler` is set,
-   content events will be discarded.
+   Set the current :class:`~xml.sax.handler.ContentHandler`.  If no
+   :class:`~xml.sax.handler.ContentHandler` is set, content events will be
+   discarded.
 
 
 .. method:: XMLReader.getDTDHandler()
 
-   Return the current :class:`DTDHandler`.
+   Return the current :class:`~xml.sax.handler.DTDHandler`.
 
 
 .. method:: XMLReader.setDTDHandler(handler)
 
-   Set the current :class:`DTDHandler`.  If no :class:`DTDHandler` is set, DTD
+   Set the current :class:`~xml.sax.handler.DTDHandler`.  If no
+   :class:`~xml.sax.handler.DTDHandler` is set, DTD
    events will be discarded.
 
 
 .. method:: XMLReader.getEntityResolver()
 
-   Return the current :class:`EntityResolver`.
+   Return the current :class:`~xml.sax.handler.EntityResolver`.
 
 
 .. method:: XMLReader.setEntityResolver(handler)
 
-   Set the current :class:`EntityResolver`.  If no :class:`EntityResolver` is set,
+   Set the current :class:`~xml.sax.handler.EntityResolver`.  If no
+   :class:`~xml.sax.handler.EntityResolver` is set,
    attempts to resolve an external entity will result in opening the system
    identifier for the entity, and fail if it is not available.
 
 
 .. method:: XMLReader.getErrorHandler()
 
-   Return the current :class:`ErrorHandler`.
+   Return the current :class:`~xml.sax.handler.ErrorHandler`.
 
 
 .. method:: XMLReader.setErrorHandler(handler)
 
-   Set the current error handler.  If no :class:`ErrorHandler` is set, errors will
-   be raised as exceptions, and warnings will be printed.
+   Set the current error handler.  If no :class:`~xml.sax.handler.ErrorHandler`
+   is set, errors will be raised as exceptions, and warnings will be printed.
 
 
 .. method:: XMLReader.setLocale(locale)
@@ -322,9 +325,11 @@ InputSource Objects
 The :class:`Attributes` Interface
 ---------------------------------
 
-:class:`Attributes` objects implement a portion of the mapping protocol,
-including the methods :meth:`copy`, :meth:`get`, :meth:`__contains__`,
-:meth:`items`, :meth:`keys`, and :meth:`values`.  The following methods
+:class:`Attributes` objects implement a portion of the :term:`mapping protocol
+<mapping>`, including the methods :meth:`~collections.abc.Mapping.copy`,
+:meth:`~collections.abc.Mapping.get`, :meth:`~object.__contains__`,
+:meth:`~collections.abc.Mapping.items`, :meth:`~collections.abc.Mapping.keys`,
+and :meth:`~collections.abc.Mapping.values`.  The following methods
 are also provided:
 
 
diff --git a/Doc/library/xml.sax.rst b/Doc/library/xml.sax.rst
index d5c56b6..e95d6b0 100644
--- a/Doc/library/xml.sax.rst
+++ b/Doc/library/xml.sax.rst
@@ -26,7 +26,8 @@ The convenience functions are:
 
 .. function:: make_parser(parser_list=[])
 
-   Create and return a SAX :class:`XMLReader` object.  The first parser found will
+   Create and return a SAX :class:`~xml.sax.xmlreader.XMLReader` object.  The
+   first parser found will
    be used.  If *parser_list* is provided, it must be a sequence of strings which
    name modules that have a function named :func:`create_parser`.  Modules listed
    in *parser_list* will be used before modules in the default list of parsers.
@@ -36,8 +37,9 @@ The convenience functions are:
 
    Create a SAX parser and use it to parse a document.  The document, passed in as
    *filename_or_stream*, can be a filename or a file object.  The *handler*
-   parameter needs to be a SAX :class:`ContentHandler` instance.  If
-   *error_handler* is given, it must be a SAX :class:`ErrorHandler` instance; if
+   parameter needs to be a SAX :class:`~handler.ContentHandler` instance.  If
+   *error_handler* is given, it must be a SAX :class:`~handler.ErrorHandler`
+   instance; if
    omitted,  :exc:`SAXParseException` will be raised on all errors.  There is no
    return value; all work must be done by the *handler* passed in.
 
@@ -62,10 +64,12 @@ For these objects, only the interfaces are relevant; they are normally not
 instantiated by the application itself.  Since Python does not have an explicit
 notion of interface, they are formally introduced as classes, but applications
 may use implementations which do not inherit from the provided classes.  The
-:class:`InputSource`, :class:`Locator`, :class:`Attributes`,
-:class:`AttributesNS`, and :class:`XMLReader` interfaces are defined in the
+:class:`~xml.sax.xmlreader.InputSource`, :class:`~xml.sax.xmlreader.Locator`,
+:class:`~xml.sax.xmlreader.Attributes`, :class:`~xml.sax.xmlreader.AttributesNS`,
+and :class:`~xml.sax.xmlreader.XMLReader` interfaces are defined in the
 module :mod:`xml.sax.xmlreader`.  The handler interfaces are defined in
-:mod:`xml.sax.handler`.  For convenience, :class:`InputSource` (which is often
+:mod:`xml.sax.handler`.  For convenience,
+:class:`~xml.sax.xmlreader.InputSource` (which is often
 instantiated directly) and the handler classes are also available from
 :mod:`xml.sax`.  These interfaces are described below.
 
@@ -78,7 +82,8 @@ classes.
    Encapsulate an XML error or warning.  This class can contain basic error or
    warning information from either the XML parser or the application: it can be
    subclassed to provide additional functionality or to add localization.  Note
-   that although the handlers defined in the :class:`ErrorHandler` interface
+   that although the handlers defined in the
+   :class:`~xml.sax.handler.ErrorHandler` interface
    receive instances of this exception, it is not required to actually raise the
    exception --- it is also useful as a container for information.
 
@@ -91,22 +96,26 @@ classes.
 
 .. exception:: SAXParseException(msg, exception, locator)
 
-   Subclass of :exc:`SAXException` raised on parse errors. Instances of this class
-   are passed to the methods of the SAX :class:`ErrorHandler` interface to provide
-   information about the parse error.  This class supports the SAX :class:`Locator`
-   interface as well as the :class:`SAXException` interface.
+   Subclass of :exc:`SAXException` raised on parse errors. Instances of this
+   class are passed to the methods of the SAX
+   :class:`~xml.sax.handler.ErrorHandler` interface to provide information
+   about the parse error.  This class supports the SAX
+   :class:`~xml.sax.xmlreader.Locator` interface as well as the
+   :class:`SAXException` interface.
 
 
 .. exception:: SAXNotRecognizedException(msg, exception=None)
 
-   Subclass of :exc:`SAXException` raised when a SAX :class:`XMLReader` is
+   Subclass of :exc:`SAXException` raised when a SAX
+   :class:`~xml.sax.xmlreader.XMLReader` is
    confronted with an unrecognized feature or property.  SAX applications and
    extensions may use this class for similar purposes.
 
 
 .. exception:: SAXNotSupportedException(msg, exception=None)
 
-   Subclass of :exc:`SAXException` raised when a SAX :class:`XMLReader` is asked to
+   Subclass of :exc:`SAXException` raised when a SAX
+   :class:`~xml.sax.xmlreader.XMLReader` is asked to
    enable a feature that is not supported, or to set a property to a value that the
    implementation does not support.  SAX applications and extensions may use this
    class for similar purposes.
diff --git a/Doc/library/xml.sax.utils.rst b/Doc/library/xml.sax.utils.rst
index 0a4038c..14cf078 100644
--- a/Doc/library/xml.sax.utils.rst
+++ b/Doc/library/xml.sax.utils.rst
@@ -52,7 +52,8 @@ or as base classes.
 
 .. class:: XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False)
 
-   This class implements the :class:`ContentHandler` interface by writing SAX
+   This class implements the :class:`~xml.sax.handler.ContentHandler` interface
+   by writing SAX
    events back into an XML document. In other words, using an :class:`XMLGenerator`
    as the content handler will reproduce the original document being parsed. *out*
    should be a file-like object which will default to *sys.stdout*. *encoding* is
@@ -67,7 +68,8 @@ or as base classes.
 
 .. class:: XMLFilterBase(base)
 
-   This class is designed to sit between an :class:`XMLReader` and the client
+   This class is designed to sit between an
+   :class:`~xml.sax.xmlreader.XMLReader` and the client
    application's event handlers.  By default, it does nothing but pass requests up
    to the reader and events on to the handlers unmodified, but subclasses can
    override specific methods to modify the event stream or the configuration
@@ -76,9 +78,10 @@ or as base classes.
 
 .. function:: prepare_input_source(source, base='')
 
-   This function takes an input source and an optional base URL and returns a fully
-   resolved :class:`InputSource` object ready for reading.  The input source can be
-   given as a string, a file-like object, or an :class:`InputSource` object;
-   parsers will use this function to implement the polymorphic *source* argument to
-   their :meth:`parse` method.
+   This function takes an input source and an optional base URL and returns a
+   fully resolved :class:`~xml.sax.xmlreader.InputSource` object ready for
+   reading.  The input source can be given as a string, a file-like object, or
+   an :class:`~xml.sax.xmlreader.InputSource` object; parsers will use this
+   function to implement the polymorphic *source* argument to their
+   :meth:`parse` method.