From 537caa2a0dba5f101b95319b0a273a9773ab613e Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Tue, 28 Apr 2009 18:16:02 +0000
Subject: [PATCH] Merged revisions 71540,71544,71546,71563,71572,71607,71653
 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk

........
  r71540 | georg.brandl | 2009-04-12 22:30:53 +0200 (So, 12 Apr 2009) | 1 line

  #5719: add short usage example to optparse docstring.
........
  r71544 | benjamin.peterson | 2009-04-13 01:19:56 +0200 (Mo, 13 Apr 2009) | 1 line

  fix extra parenthesis #5774
........
  r71546 | benjamin.peterson | 2009-04-13 01:44:15 +0200 (Mo, 13 Apr 2009) | 1 line

  fix missing quote
........
  r71563 | georg.brandl | 2009-04-13 14:36:18 +0200 (Mo, 13 Apr 2009) | 1 line

  Simplify markup.
........
  r71572 | georg.brandl | 2009-04-13 15:13:25 +0200 (Mo, 13 Apr 2009) | 1 line

  #5745: more linking for identifiers in email docs.
........
  r71607 | benjamin.peterson | 2009-04-14 23:23:09 +0200 (Di, 14 Apr 2009) | 1 line

  tupel -> tuple
........
  r71653 | raymond.hettinger | 2009-04-16 20:16:10 +0200 (Do, 16 Apr 2009) | 1 line

  Clarify the behavior of any() and all() with an empty iterable.
........
---
 Doc/library/email.charset.rst    |   4 +-
 Doc/library/email.encoders.rst   |  18 ++---
 Doc/library/email.errors.rst     |  13 ++--
 Doc/library/email.generator.rst  |   8 +--
 Doc/library/email.header.rst     |  23 +++----
 Doc/library/email.message.rst    |  30 +++++----
 Doc/library/email.mime.rst       | 110 +++++++++++++++++--------------
 Doc/library/email.parser.rst     |  29 ++++----
 Doc/library/functions.rst        |   6 +-
 Doc/library/turtle.rst           |   6 +-
 Doc/reference/compound_stmts.rst |   9 +--
 Lib/optparse.py                  |  13 ++++
 12 files changed, 147 insertions(+), 122 deletions(-)

diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst
index 8ead0ce520a..b0083868408 100644
--- a/Doc/library/email.charset.rst
+++ b/Doc/library/email.charset.rst
@@ -163,8 +163,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
index 28669c42cdc..5421b9f66f3 100644
--- 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
index 916d2a564ee..7a0c52a67e6 100644
--- 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
index 1bffa731346..8ba426a296b 100644
--- 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
index 000d48ec597..718200516e6 100644
--- 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.
 
 .. versionadded:: 2.2.2
 
@@ -83,10 +83,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 a byte string or a Unicode string.  If it is a byte string
       (i.e.  ``isinstance(s, str)`` is true), then *charset* is the encoding of
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index 35a9f6a719c..0e79b6c8a44 100644
--- 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 cStringIO import StringIO
          from email.generator import Generator
@@ -126,11 +126,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*
@@ -144,8 +145,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.
 
       .. versionadded:: 2.2.2
 
@@ -478,7 +479,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.
 
       .. versionadded:: 2.2.2
 
@@ -534,10 +535,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
index 8a0b01f3590..94df8f04820 100644
--- a/Doc/library/email.mime.rst
+++ b/Doc/library/email.mime.rst
@@ -8,14 +8,15 @@
 Ordinarily, you get a message object structure by passing a file or some text to
 a parser, which parses the text and returns the root message object.  However
 you can also build a complete message structure from scratch, or even individual
-:class:`Message` objects by hand.  In fact, you can also take an existing
-structure and add new :class:`Message` objects, move them around, etc.  This
-makes a very convenient interface for slicing-and-dicing MIME messages.
+:class:`~email.message.Message` objects by hand.  In fact, you can also take an
+existing structure and add new :class:`~email.message.Message` objects, move them
+around, etc.  This makes a very convenient interface for slicing-and-dicing MIME
+messages.
 
-You can create a new object structure by creating :class:`Message` instances,
-adding attachments and all the appropriate headers manually.  For MIME messages
-though, the :mod:`email` package provides some convenient subclasses to make
-things easier.
+You can create a new object structure by creating :class:`~email.message.Message`
+instances, adding attachments and all the appropriate headers manually.  For MIME
+messages though, the :mod:`email` package provides some convenient subclasses to
+make things easier.
 
 Here are the classes:
 
@@ -25,10 +26,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.base`
 
-   This is the base class for all the MIME-specific subclasses of :class:`Message`.
-   Ordinarily you won't create instances specifically of :class:`MIMEBase`,
-   although you could.  :class:`MIMEBase` is provided primarily as a convenient
-   base class for more specific MIME-aware subclasses.
+   This is the base class for all the MIME-specific subclasses of
+   :class:`~email.message.Message`.  Ordinarily you won't create instances
+   specifically of :class:`MIMEBase`, although you could.  :class:`MIMEBase`
+   is provided primarily as a convenient base class for more specific
+   MIME-aware subclasses.
 
    *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
    or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
@@ -46,11 +48,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.nonmultipart`
 
-   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
-   messages that are not :mimetype:`multipart`.  The primary purpose of this class
-   is to prevent the use of the :meth:`attach` method, which only makes sense for
-   :mimetype:`multipart` messages.  If :meth:`attach` is called, a
-   :exc:`MultipartConversionError` exception is raised.
+   A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
+   class for MIME messages that are not :mimetype:`multipart`.  The primary
+   purpose of this class is to prevent the use of the :meth:`attach` method,
+   which only makes sense for :mimetype:`multipart` messages.  If :meth:`attach`
+   is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
 
    .. versionadded:: 2.2.2
 
@@ -61,12 +63,12 @@ Here are the classes:
 
    Module: :mod:`email.mime.multipart`
 
-   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
-   messages that are :mimetype:`multipart`.  Optional *_subtype* defaults to
-   :mimetype:`mixed`, but can be used to specify the subtype of the message.  A
-   :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype` will be
-   added to the message object.  A :mailheader:`MIME-Version` header will also be
-   added.
+   A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
+   class for MIME messages that are :mimetype:`multipart`.  Optional *_subtype*
+   defaults to :mimetype:`mixed`, but can be used to specify the subtype of the
+   message.  A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype`
+   will be added to the message object.  A :mailheader:`MIME-Version` header will
+   also be added.
 
    Optional *boundary* is the multipart boundary string.  When ``None`` (the
    default), the boundary is calculated when needed.
@@ -88,10 +90,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.application`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is
-   used to represent MIME message objects of major type :mimetype:`application`.
-   *_data* is a string containing the raw byte data.  Optional *_subtype* specifies
-   the MIME subtype and defaults to :mimetype:`octet-stream`.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEApplication` class is used to represent MIME message objects of
+   major type :mimetype:`application`.  *_data* is a string containing the raw
+   byte data.  Optional *_subtype* specifies the MIME subtype and defaults to
+   :mimetype:`octet-stream`.
 
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the data for transport.  This callable takes one argument, which is
@@ -112,13 +115,14 @@ Here are the classes:
 
    Module: :mod:`email.mime.audio`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to
-   create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a
-   string containing the raw audio data.  If this data can be decoded by the
-   standard Python module :mod:`sndhdr`, then the subtype will be automatically
-   included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly
-   specify the audio subtype via the *_subtype* parameter.  If the minor type could
-   not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEAudio` class is used to create MIME message objects of major type
+   :mimetype:`audio`. *_audiodata* is a string containing the raw audio data.  If
+   this data can be decoded by the standard Python module :mod:`sndhdr`, then the
+   subtype will be automatically included in the :mailheader:`Content-Type` header.
+   Otherwise you can explicitly specify the audio subtype via the *_subtype*
+   parameter.  If the minor type could not be guessed and *_subtype* was not given,
+   then :exc:`TypeError` is raised.
 
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the audio data for transport.  This callable takes one argument,
@@ -137,13 +141,14 @@ Here are the classes:
 
    Module: :mod:`email.mime.image`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to
-   create MIME message objects of major type :mimetype:`image`. *_imagedata* is a
-   string containing the raw image data.  If this data can be decoded by the
-   standard Python module :mod:`imghdr`, then the subtype will be automatically
-   included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly
-   specify the image subtype via the *_subtype* parameter.  If the minor type could
-   not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEImage` class is used to create MIME message objects of major type
+   :mimetype:`image`. *_imagedata* is a string containing the raw image data.  If
+   this data can be decoded by the standard Python module :mod:`imghdr`, then the
+   subtype will be automatically included in the :mailheader:`Content-Type` header.
+   Otherwise you can explicitly specify the image subtype via the *_subtype*
+   parameter.  If the minor type could not be guessed and *_subtype* was not given,
+   then :exc:`TypeError` is raised.
 
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the image data for transport.  This callable takes one argument,
@@ -153,7 +158,8 @@ Here are the classes:
    object as necessary.  The default encoding is base64.  See the
    :mod:`email.encoders` module for a list of the built-in encoders.
 
-   *_params* are passed straight through to the :class:`MIMEBase` constructor.
+   *_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
+   constructor.
 
 
 .. currentmodule:: email.mime.message
@@ -162,10 +168,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.message`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used
-   to create MIME objects of main type :mimetype:`message`. *_msg* is used as the
-   payload, and must be an instance of class :class:`Message` (or a subclass
-   thereof), otherwise a :exc:`TypeError` is raised.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEMessage` class is used to create MIME objects of main type
+   :mimetype:`message`. *_msg* is used as the payload, and must be an instance
+   of class :class:`~email.message.Message` (or a subclass thereof), otherwise
+   a :exc:`TypeError` is raised.
 
    Optional *_subtype* sets the subtype of the message; it defaults to
    :mimetype:`rfc822`.
@@ -177,12 +184,13 @@ Here are the classes:
 
    Module: :mod:`email.mime.text`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to
-   create MIME objects of major type :mimetype:`text`. *_text* is the string for
-   the payload.  *_subtype* is the minor type and defaults to :mimetype:`plain`.
-   *_charset* is the character set of the text and is passed as a parameter to the
-   :class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``.  No guessing
-   or encoding is performed on the text data.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEText` class is used to create MIME objects of major type
+   :mimetype:`text`. *_text* is the string for the payload.  *_subtype* is the
+   minor type and defaults to :mimetype:`plain`.  *_charset* is the character
+   set of the text and is passed as a parameter to the
+   :class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
+   to ``us-ascii``.  No guessing or encoding is performed on the text data.
 
    .. versionchanged:: 2.4
       The previously deprecated *_encoding* argument has been removed.  Encoding
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index bbfc51032e3..234c0c0231e 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -6,18 +6,18 @@
 
 
 Message object structures can be created in one of two ways: they can be created
-from whole cloth by instantiating :class:`Message` objects and stringing them
-together via :meth:`attach` and :meth:`set_payload` calls, or they can be
-created by parsing a flat text representation of the email message.
+from whole cloth by instantiating :class:`~email.message.Message` objects and
+stringing them together via :meth:`attach` and :meth:`set_payload` calls, or they
+can be created by parsing a flat text representation of the email message.
 
 The :mod:`email` package provides a standard parser that understands most email
 document structures, including MIME documents.  You can pass the parser a string
-or a file object, and the parser will return to you the root :class:`Message`
-instance of the object structure.  For simple, non-MIME messages the payload of
-this root object will likely be a string containing the text of the message.
-For MIME messages, the root object will return ``True`` from its
-:meth:`is_multipart` method, and the subparts can be accessed via the
-:meth:`get_payload` and :meth:`walk` methods.
+or a file object, and the parser will return to you the root
+:class:`~email.message.Message` instance of the object structure.  For simple,
+non-MIME messages the payload of this root object will likely be a string
+containing the text of the message.  For MIME messages, the root object will
+return ``True`` from its :meth:`is_multipart` method, and the subparts can be
+accessed via the :meth:`get_payload` and :meth:`walk` methods.
 
 There are actually two parser interfaces available for use, the classic
 :class:`Parser` API and the incremental :class:`FeedParser` API.  The classic
@@ -31,8 +31,8 @@ incrementally, and only returns the root object when you close the parser [#]_.
 Note that the parser can be extended in limited ways, and of course you can
 implement your own parser completely from scratch.  There is no magical
 connection between the :mod:`email` package's bundled parser and the
-:class:`Message` class, so your custom parser can create message object trees
-any way it finds necessary.
+:class:`~email.message.Message` class, so your custom parser can create message
+object trees any way it finds necessary.
 
 
 FeedParser API
@@ -103,8 +103,8 @@ class.
    The constructor for the :class:`Parser` class takes an optional argument
    *_class*.  This must be a callable factory (such as a function or a class), and
    it is used whenever a sub-message object needs to be created.  It defaults to
-   :class:`Message` (see :mod:`email.message`).  The factory will be called without
-   arguments.
+   :class:`~email.message.Message` (see :mod:`email.message`).  The factory will
+   be called without arguments.
 
    The optional *strict* flag is ignored.
 
@@ -199,7 +199,8 @@ Here are some notes on the parsing semantics:
 * All :mimetype:`multipart` type messages will be parsed as a container message
   object with a list of sub-message objects for their payload.  The outer
   container message will return ``True`` for :meth:`is_multipart` and their
-  :meth:`get_payload` method will return the list of :class:`Message` subparts.
+  :meth:`get_payload` method will return the list of :class:`~email.message.Message`
+  subparts.
 
 * Most messages with a content type of :mimetype:`message/\*` (e.g.
   :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 499be9d116c..70db1d863de 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -17,7 +17,8 @@ available.  They are listed here in alphabetical order.
 
 .. function:: all(iterable)
 
-   Return True if all elements of the *iterable* are true. Equivalent to::
+   Return True if all elements of the *iterable* are true (or if the iterable
+   is empty).  Equivalent to::
 
       def all(iterable):
           for element in iterable:
@@ -30,7 +31,8 @@ available.  They are listed here in alphabetical order.
 
 .. function:: any(iterable)
 
-   Return True if any element of the *iterable* is true. Equivalent to::
+   Return True if any element of the *iterable* is true.  If the iterable
+   is empty, return False.  Equivalent to::
 
       def any(iterable):
           for element in iterable:
diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index 97074204a4b..bf567a2cb10 100644
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -1244,9 +1244,9 @@ Window control
 
 .. function:: screensize(canvwidth=None, canvheight=None, bg=None)
 
-   :param canvwidth: positive integer, new width of canvas in pixels
-   :param canvheight: positive integer, new height of canvas in pixels
-   :param bg: colorstring or color-tupel, new background color
+   :param canvwidth: positive integer, new width of canvas in pixels :param
+   canvheight: positive integer, new height of canvas in pixels :param bg:
+   colorstring or color-tuple, new background color
 
    If no arguments are given, return current (canvaswidth, canvasheight).  Else
    resize the canvas the turtles are drawing on.  Do not alter the drawing
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 408298d031c..4d7addbbd2b 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -1,4 +1,3 @@
-
 .. _compound:
 
 *******************
@@ -195,12 +194,10 @@ effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list
    inserts an item in the sequence before the current item, the current item will
    be treated again the next time through the loop. This can lead to nasty bugs
    that can be avoided by making a temporary copy using a slice of the whole
-   sequence, e.g.,
+   sequence, e.g., ::
 
-::
-
-   for x in a[:]:
-       if x < 0: a.remove(x)
+      for x in a[:]:
+          if x < 0: a.remove(x)
 
 
 .. _try:
diff --git a/Lib/optparse.py b/Lib/optparse.py
index 4a74a684c9c..53bdef0ddc9 100644
--- a/Lib/optparse.py
+++ b/Lib/optparse.py
@@ -6,6 +6,19 @@ Originally distributed as Optik.
 
 For support, use the optik-users@lists.sourceforge.net mailing list
 (http://lists.sourceforge.net/lists/listinfo/optik-users).
+
+Simple usage example:
+
+   from optparse import OptionParser
+
+   parser = OptionParser()
+   parser.add_option("-f", "--file", dest="filename",
+                     help="write report to FILE", metavar="FILE")
+   parser.add_option("-q", "--quiet",
+                     action="store_false", dest="verbose", default=True,
+                     help="don't print status messages to stdout")
+
+   (options, args) = parser.parse_args()
 """
 
 __version__ = "1.5.3"