Merged revisions 71572 via svnmerge from

birkenfeld · birkenfeld · commit 3638e487b94d · 2009-04-27T16:46:17.000Z
svn+ssh://pythondev@svn.python.org/python/trunk ........ r71572 | georg.brandl | 2009-04-13 15:13:25 +0200 (Mo, 13 Apr 2009) | 1 line python#5745: more linking for identifiers in email docs. ........
diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst
@@ -161,8 +161,8 @@ Import this class from the :mod:`email.charset` module.
       charset to the output charset automatically.  This is not useful for
       multibyte character sets, which have line length issues (multibyte
       characters must be split on a character, not a byte boundary); use the
-      higher-level :class:`Header` class to deal with these issues (see
-      :mod:`email.header`).  *convert* defaults to ``False``.
+      higher-level :class:`~email.header.Header` class to deal with these issues
+      (see :mod:`email.header`).  *convert* defaults to ``False``.
 
       The type of encoding (base64 or quoted-printable) will be based on the
       *header_encoding* attribute.
diff --git a/Doc/library/email.encoders.rst b/Doc/library/email.encoders.rst
@@ -5,18 +5,18 @@
    :synopsis: Encoders for email message payloads.
 
 
-When creating :class:`Message` objects from scratch, you often need to encode
-the payloads for transport through compliant mail servers. This is especially
-true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages containing
-binary data.
+When creating :class:`~email.message.Message` objects from scratch, you often
+need to encode the payloads for transport through compliant mail servers. This
+is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages
+containing binary data.
 
 The :mod:`email` package provides some convenient encodings in its
 :mod:`encoders` module.  These encoders are actually used by the
-:class:`MIMEAudio` and :class:`MIMEImage` class constructors to provide default
-encodings.  All encoder functions take exactly one argument, the message object
-to encode.  They usually extract the payload, encode it, and reset the payload
-to this newly encoded value.  They should also set the
-:mailheader:`Content-Transfer-Encoding` header as appropriate.
+:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
+class constructors to provide default encodings.  All encoder functions take
+exactly one argument, the message object to encode.  They usually extract the
+payload, encode it, and reset the payload to this newly encoded value.  They
+should also set the :mailheader:`Content-Transfer-Encoding` header as appropriate.
 
 Here are the encoding functions provided:
 
diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst
@@ -17,8 +17,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
 
 .. exception:: MessageParseError()
 
-   This is the base class for exceptions thrown by the :class:`Parser` class.  It
-   is derived from :exc:`MessageError`.
+   This is the base class for exceptions thrown by the :class:`~email.parser.Parser`
+   class.  It is derived from :exc:`MessageError`.
 
 
 .. exception:: HeaderParseError()
@@ -55,11 +55,12 @@ The following exception classes are defined in the :mod:`email.errors` module:
    Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised
    in practice.  However the exception may also be raised if the :meth:`attach`
    method is called on an instance of a class derived from
-   :class:`MIMENonMultipart` (e.g. :class:`MIMEImage`).
+   :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
+   :class:`~email.mime.image.MIMEImage`).
 
-Here's the list of the defects that the :class:`FeedParser` can find while
-parsing messages.  Note that the defects are added to the message where the
-problem was found, so for example, if a message nested inside a
+Here's the list of the defects that the :class:`~email.mime.parser.FeedParser`
+can find while parsing messages.  Note that the defects are added to the message
+where the problem was found, so for example, if a message nested inside a
 :mimetype:`multipart/alternative` had a malformed header, that nested message
 object would have a defect, but the containing messages would not.
 
diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst
@@ -16,8 +16,8 @@ functionality of the bundled generator; you could write one from scratch
 yourself.  However the bundled generator knows how to generate most email in a
 standards-compliant way, should handle MIME and non-MIME email messages just
 fine, and is designed so that the transformation from flat text, to a message
-structure via the :class:`Parser` class, and back to flat text, is idempotent
-(the input is identical to the output).
+structure via the :class:`~email.parser.Parser` class, and back to flat text,
+is idempotent (the input is identical to the output).
 
 Here are the public methods of the :class:`Generator` class, imported from the
 :mod:`email.generator` module:
@@ -41,8 +41,8 @@ Here are the public methods of the :class:`Generator` class, imported from the
    Optional *maxheaderlen* specifies the longest length for a non-continued header.
    When a header line is longer than *maxheaderlen* (in characters, with tabs
    expanded to 8 spaces), the header will be split as defined in the
-   :mod:`email.header.Header` class.  Set to zero to disable header wrapping.  The
-   default is 78, as recommended (but not required) by :rfc:`2822`.
+   :class:`~email.header.Header` class.  Set to zero to disable header wrapping.
+   The default is 78, as recommended (but not required) by :rfc:`2822`.
 
    The other public :class:`Generator` methods are:
 
diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst
@@ -21,10 +21,10 @@ in its :mod:`email.header` and :mod:`email.charset` modules.
 
 If you want to include non-ASCII characters in your email headers, say in the
 :mailheader:`Subject` or :mailheader:`To` fields, you should use the
-:class:`Header` class and assign the field in the :class:`Message` object to an
-instance of :class:`Header` instead of using a string for the header value.
-Import the :class:`Header` class from the :mod:`email.header` module.  For
-example::
+:class:`Header` class and assign the field in the :class:`~email.message.Message`
+object to an instance of :class:`Header` instead of using a string for the header
+value.  Import the :class:`Header` class from the :mod:`email.header` module.
+For example::
 
    >>> from email.message import Message
    >>> from email.header import Header
@@ -39,9 +39,9 @@ example::
 Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
 character?  We did this by creating a :class:`Header` instance and passing in
 the character set that the byte string was encoded in.  When the subsequent
-:class:`Message` instance was flattened, the :mailheader:`Subject` field was
-properly :rfc:`2047` encoded.  MIME-aware mail readers would show this header
-using the embedded ISO-8859-1 character.
+:class:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
+field was properly :rfc:`2047` encoded.  MIME-aware mail readers would show this
+header using the embedded ISO-8859-1 character.
 
 Here is the :class:`Header` class description:
 
@@ -81,10 +81,11 @@ Here is the :class:`Header` class description:
 
       Append the string *s* to the MIME header.
 
-      Optional *charset*, if given, should be a :class:`Charset` instance (see
-      :mod:`email.charset`) or the name of a character set, which will be
-      converted to a :class:`Charset` instance.  A value of ``None`` (the
-      default) means that the *charset* given in the constructor is used.
+      Optional *charset*, if given, should be a :class:`~email.charset.Charset`
+      instance (see :mod:`email.charset`) or the name of a character set, which
+      will be converted to a :class:`~email.charset.Charset` instance.  A value
+      of ``None`` (the default) means that the *charset* given in the constructor
+      is used.
 
       *s* may be an instance of :class:`bytes` or :class:`str`.  If it is an
       instance of :class:`bytes`, then *charset* is the encoding of that byte
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
@@ -45,8 +45,8 @@ Here are the methods of the :class:`Message` class:
       Note that this method is provided as a convenience and may not always
       format the message the way you want.  For example, by default it mangles
       lines that begin with ``From``.  For more flexibility, instantiate a
-      :class:`Generator` instance and use its :meth:`flatten` method directly.
-      For example::
+      :class:`~email.generator.Generator` instance and use its :meth:`flatten`
+      method directly.  For example::
 
          from io import StringIO
          from email.generator import Generator
@@ -122,11 +122,12 @@ Here are the methods of the :class:`Message` class:
    .. method:: set_charset(charset)
 
       Set the character set of the payload to *charset*, which can either be a
-      :class:`Charset` instance (see :mod:`email.charset`), a string naming a
-      character set, or ``None``.  If it is a string, it will be converted to a
-      :class:`Charset` instance.  If *charset* is ``None``, the ``charset``
-      parameter will be removed from the :mailheader:`Content-Type`
-      header. Anything else will generate a :exc:`TypeError`.
+      :class:`~email.charset.Charset` instance (see :mod:`email.charset`), a
+      string naming a character set, or ``None``.  If it is a string, it will
+      be converted to a :class:`~email.charset.Charset` instance.  If *charset*
+      is ``None``, the ``charset`` parameter will be removed from the
+      :mailheader:`Content-Type` header. Anything else will generate a
+      :exc:`TypeError`.
 
       The message will be assumed to be of type :mimetype:`text/\*` encoded with
       *charset.input_charset*.  It will be converted to *charset.output_charset*
@@ -137,8 +138,8 @@ Here are the methods of the :class:`Message` class:
 
    .. method:: get_charset()
 
-      Return the :class:`Charset` instance associated with the message's
-      payload.
+      Return the :class:`~email.charset.Charset` instance associated with the
+      message's payload.
 
    The following methods implement a mapping-like interface for accessing the
    message's :rfc:`2822` headers.  Note that there are some semantic differences
@@ -445,7 +446,7 @@ Here are the methods of the :class:`Message` class:
       that header has no ``charset`` parameter, *failobj* is returned.
 
       Note that this method differs from :meth:`get_charset` which returns the
-      :class:`Charset` instance for the default encoding of the message body.
+      :class:`~email.charset.Charset` instance for the default encoding of the message body.
 
 
    .. method:: get_charsets([failobj])
@@ -495,10 +496,11 @@ Here are the methods of the :class:`Message` class:
       text can become visible.
 
       The *preamble* attribute contains this leading extra-armor text for MIME
-      documents.  When the :class:`Parser` discovers some text after the headers
-      but before the first boundary string, it assigns this text to the
-      message's *preamble* attribute.  When the :class:`Generator` is writing
-      out the plain text representation of a MIME message, and it finds the
+      documents.  When the :class:`~email.parser.Parser` discovers some text
+      after the headers but before the first boundary string, it assigns this
+      text to the message's *preamble* attribute.  When the
+      :class:`~email.generator.Generator` is writing out the plain text
+      representation of a MIME message, and it finds the
       message has a *preamble* attribute, it will write this text in the area
       between the headers and the first boundary.  See :mod:`email.parser` and
       :mod:`email.generator` for details.
diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
