Issue #19197: Improved cross-references in the shlex module documentation.

1 files changed, 59 insertions, 51 deletions

diff --git a/Doc/library/shlex.rst b/Doc/library/shlex.rst
index 941e090c4f..e40a10daa5 100644
--- a/Doc/library/shlex.rst
+++ b/Doc/library/shlex.rst
@@ -12,9 +12,9 @@
 
 --------------
 
-The :class:`shlex` class makes it easy to write lexical analyzers for simple
-syntaxes resembling that of the Unix shell.  This will often be useful for
-writing minilanguages, (for example, in run control files for Python
+The :class:`~shlex.shlex` class makes it easy to write lexical analyzers for
+simple syntaxes resembling that of the Unix shell.  This will often be useful
+for writing minilanguages, (for example, in run control files for Python
 applications) or for parsing quoted strings.
 
 The :mod:`shlex` module defines the following functions:
@@ -24,15 +24,16 @@ The :mod:`shlex` module defines the following functions:
 
    Split the string *s* using shell-like syntax. If *comments* is :const:`False`
    (the default), the parsing of comments in the given string will be disabled
-   (setting the :attr:`commenters` attribute of the :class:`shlex` instance to
-   the empty string).  This function operates in POSIX mode by default, but uses
-   non-POSIX mode if the *posix* argument is false.
+   (setting the :attr:`~shlex.commenters` attribute of the
+   :class:`~shlex.shlex` instance to the empty string).  This function operates
+   in POSIX mode by default, but uses non-POSIX mode if the *posix* argument is
+   false.
 
    .. note::
 
-      Since the :func:`split` function instantiates a :class:`shlex` instance,
-      passing ``None`` for *s* will read the string to split from standard
-      input.
+      Since the :func:`split` function instantiates a :class:`~shlex.shlex`
+      instance, passing ``None`` for *s* will read the string to split from
+      standard input.
 
 
 .. function:: quote(s)
@@ -73,17 +74,19 @@ The :mod:`shlex` module defines the following class:
 
 .. class:: shlex(instream=None, infile=None, posix=False)
 
-   A :class:`shlex` instance or subclass instance is a lexical analyzer object.
-   The initialization argument, if present, specifies where to read characters
-   from. It must be a file-/stream-like object with :meth:`read` and
-   :meth:`readline` methods, or a string.  If no argument is given, input will
-   be taken from ``sys.stdin``.  The second optional argument is a filename
-   string, which sets the initial value of the :attr:`infile` attribute.  If the
-   *instream* argument is omitted or equal to ``sys.stdin``, this second
-   argument defaults to "stdin".  The *posix* argument defines the operational
-   mode: when *posix* is not true (default), the :class:`shlex` instance will
-   operate in compatibility mode.  When operating in POSIX mode, :class:`shlex`
-   will try to be as close as possible to the POSIX shell parsing rules.
+   A :class:`~shlex.shlex` instance or subclass instance is a lexical analyzer
+   object.  The initialization argument, if present, specifies where to read
+   characters from. It must be a file-/stream-like object with
+   :meth:`~io.TextIOBase.read` and :meth:`~io.TextIOBase.readline` methods, or
+   a string.  If no argument is given, input will be taken from ``sys.stdin``.
+   The second optional argument is a filename string, which sets the initial
+   value of the :attr:`~shlex.infile` attribute.  If the *instream*
+   argument is omitted or equal to ``sys.stdin``, this second argument
+   defaults to "stdin".  The *posix* argument defines the operational mode:
+   when *posix* is not true (default), the :class:`~shlex.shlex` instance will
+   operate in compatibility mode.  When operating in POSIX mode,
+   :class:`~shlex.shlex` will try to be as close as possible to the POSIX shell
+   parsing rules.
 
 
 .. seealso::
@@ -97,14 +100,14 @@ The :mod:`shlex` module defines the following class:
 shlex Objects
 -------------
 
-A :class:`shlex` instance has the following methods:
+A :class:`~shlex.shlex` instance has the following methods:
 
 
 .. method:: shlex.get_token()
 
    Return a token.  If tokens have been stacked using :meth:`push_token`, pop a
    token off the stack.  Otherwise, read one from the input stream.  If reading
-   encounters an immediate end-of-file, :attr:`self.eof` is returned (the empty
+   encounters an immediate end-of-file, :attr:`eof` is returned (the empty
    string (``''``) in non-POSIX mode, and ``None`` in POSIX mode).
 
 
@@ -122,9 +125,9 @@ A :class:`shlex` instance has the following methods:
 
 .. method:: shlex.sourcehook(filename)
 
-   When :class:`shlex` detects a source request (see :attr:`source` below) this
-   method is given the following token as argument, and expected to return a tuple
-   consisting of a filename and an open file-like object.
+   When :class:`~shlex.shlex` detects a source request (see :attr:`source`
+   below) this method is given the following token as argument, and expected
+   to return a tuple consisting of a filename and an open file-like object.
 
    Normally, this method first strips any quotes off the argument.  If the result
    is an absolute pathname, or there was no previous source request in effect, or
@@ -141,8 +144,9 @@ A :class:`shlex` instance has the following methods:
 
    This hook is exposed so that you can use it to implement directory search paths,
    addition of file extensions, and other namespace hacks. There is no
-   corresponding 'close' hook, but a shlex instance will call the :meth:`close`
-   method of the sourced input stream when it returns EOF.
+   corresponding 'close' hook, but a shlex instance will call the
+   :meth:`~io.IOBase.close` method of the sourced input stream when it returns
+   EOF.
 
    For more explicit control of source stacking, use the :meth:`push_source` and
    :meth:`pop_source` methods.
@@ -172,8 +176,8 @@ A :class:`shlex` instance has the following methods:
    messages in the standard, parseable format understood by Emacs and other Unix
    tools.
 
-Instances of :class:`shlex` subclasses have some public instance variables which
-either control lexical analysis or can be used for debugging:
+Instances of :class:`~shlex.shlex` subclasses have some public instance
+variables which either control lexical analysis or can be used for debugging:
 
 
 .. attribute:: shlex.commenters
@@ -218,8 +222,8 @@ either control lexical analysis or can be used for debugging:
 .. attribute:: shlex.whitespace_split
 
    If ``True``, tokens will only be split in whitespaces. This is useful, for
-   example, for parsing command lines with :class:`shlex`, getting tokens in a
-   similar way to shell arguments.
+   example, for parsing command lines with :class:`~shlex.shlex`, getting
+   tokens in a similar way to shell arguments.
 
 
 .. attribute:: shlex.infile
@@ -231,7 +235,8 @@ either control lexical analysis or can be used for debugging:
 
 .. attribute:: shlex.instream
 
-   The input stream from which this :class:`shlex` instance is reading characters.
+   The input stream from which this :class:`~shlex.shlex` instance is reading
+   characters.
 
 
 .. attribute:: shlex.source
@@ -240,16 +245,16 @@ either control lexical analysis or can be used for debugging:
    string will be recognized as a lexical-level inclusion request similar to the
    ``source`` keyword in various shells.  That is, the immediately following token
    will opened as a filename and input taken from that stream until EOF, at which
-   point the :meth:`close` method of that stream will be called and the input
-   source will again become the original input stream. Source requests may be
-   stacked any number of levels deep.
+   point the :meth:`~io.IOBase.close` method of that stream will be called and
+   the input source will again become the original input stream.  Source
+   requests may be stacked any number of levels deep.
 
 
 .. attribute:: shlex.debug
 
-   If this attribute is numeric and ``1`` or more, a :class:`shlex` instance will
-   print verbose progress output on its behavior.  If you need to use this, you can
-   read the module source code to learn the details.
+   If this attribute is numeric and ``1`` or more, a :class:`~shlex.shlex`
+   instance will print verbose progress output on its behavior.  If you need
+   to use this, you can read the module source code to learn the details.
 
 
 .. attribute:: shlex.lineno
@@ -273,7 +278,7 @@ either control lexical analysis or can be used for debugging:
 Parsing Rules
 -------------
 
-When operating in non-POSIX mode, :class:`shlex` will try to obey to the
+When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey to the
 following rules.
 
 * Quote characters are not recognized within words (``Do"Not"Separate`` is
@@ -287,16 +292,17 @@ following rules.
 * Closing quotes separate words (``"Do"Separate`` is parsed as ``"Do"`` and
   ``Separate``);
 
-* If :attr:`whitespace_split` is ``False``, any character not declared to be a
-  word character, whitespace, or a quote will be returned as a single-character
-  token. If it is ``True``, :class:`shlex` will only split words in whitespaces;
+* If :attr:`~shlex.whitespace_split` is ``False``, any character not
+  declared to be a word character, whitespace, or a quote will be returned as
+  a single-character token. If it is ``True``, :class:`~shlex.shlex` will only
+  split words in whitespaces;
 
 * EOF is signaled with an empty string (``''``);
 
 * It's not possible to parse empty strings, even if quoted.
 
-When operating in POSIX mode, :class:`shlex` will try to obey to the following
-parsing rules.
+When operating in POSIX mode, :class:`~shlex.shlex` will try to obey to the
+following parsing rules.
 
 * Quotes are stripped out, and do not separate words (``"Do"Not"Separate"`` is
   parsed as the single word ``DoNotSeparate``);
@@ -304,14 +310,16 @@ parsing rules.
 * Non-quoted escape characters (e.g. ``'\'``) preserve the literal value of the
   next character that follows;
 
-* Enclosing characters in quotes which are not part of :attr:`escapedquotes`
-  (e.g. ``"'"``) preserve the literal value of all characters within the quotes;
+* Enclosing characters in quotes which are not part of
+  :attr:`~shlex.escapedquotes` (e.g. ``"'"``) preserve the literal value
+  of all characters within the quotes;
 
-* Enclosing characters in quotes which are part of :attr:`escapedquotes` (e.g.
-  ``'"'``) preserves the literal value of all characters within the quotes, with
-  the exception of the characters mentioned in :attr:`escape`. The escape
-  characters retain its special meaning only when followed by the quote in use, or
-  the escape character itself. Otherwise the escape character will be considered a
+* Enclosing characters in quotes which are part of
+  :attr:`~shlex.escapedquotes` (e.g. ``'"'``) preserves the literal value
+  of all characters within the quotes, with the exception of the characters
+  mentioned in :attr:`~shlex.escape`.  The escape characters retain its
+  special meaning only when followed by the quote in use, or the escape
+  character itself. Otherwise the escape character will be considered a
   normal character.
 
 * EOF is signaled with a :const:`None` value;