Markup and text fixes from Georg Brandl's review.

2 files changed, 36 insertions, 28 deletions

diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index c5e43a9..e70b429 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -211,16 +211,19 @@ in the top-level :mod:`email` package namespace.
    ``Parser().parsestr(s)``.  *_class* and *policy* are interpreted as
    with the :class:`Parser` class constructor.
 
-   .. versionchanged:: removed *strict*, added *policy*
+   .. versionchanged:: 3.3
+      Removed the *strict* argument.  Added the *policy* keyword.
 
-.. function:: message_from_bytes(s, _class=email.message.Message, strict=None)
+.. function:: message_from_bytes(s, _class=email.message.Message, *, \
+                                 policy=policy.default)
 
    Return a message object structure from a byte string.  This is exactly
    equivalent to ``BytesParser().parsebytes(s)``.  Optional *_class* and
    *strict* are interpreted as with the :class:`Parser` class constructor.
 
    .. versionadded:: 3.2
-   .. versionchanged:: 3.3 removed *strict*, added *policy*
+   .. versionchanged:: 3.3
+      Removed the *strict* argument.  Added the *policy* keyword.
 
 .. function:: message_from_file(fp, _class=email.message.Message, *, \
                                 policy=policy.default)
@@ -229,7 +232,8 @@ in the top-level :mod:`email` package namespace.
    This is exactly equivalent to ``Parser().parse(fp)``.  *_class*
    and *policy* are interpreted as with the :class:`Parser` class constructor.
 
-   .. versionchanged:: 3.3 removed *strict*, added *policy*
+   .. versionchanged::
+      Removed the *strict* argument.  Added the *policy* keyword.
 
 .. function:: message_from_binary_file(fp, _class=email.message.Message, *, \
                                        policy=policy.default)
@@ -240,7 +244,8 @@ in the top-level :mod:`email` package namespace.
    class constructor.
 
    .. versionadded:: 3.2
-   .. versionchanged:: 3.3 removed *strict*, added *policy*
+   .. versionchanged:: 3.3
+      Removed the *strict* argument.  Added the *policy* keyword.
 
 Here's an example of how you might use this at an interactive Python prompt::
 
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
index f7eb471..f95af39 100644
--- a/Doc/library/email.policy.rst
+++ b/Doc/library/email.policy.rst
@@ -4,6 +4,8 @@
 .. module:: email.policy
    :synopsis: Controlling the parsing and generating of messages
 
+.. versionadded: 3.3
+
 
 The :mod:`email` package's prime focus is the handling of email messages as
 described by the various email and MIME RFCs.  However, the general format of
@@ -14,8 +16,8 @@ email.  Some of these uses conform fairly closely to the main RFCs, some do
 not.  And even when working with email, there are times when it is desirable to
 break strict compliance with the RFCs.
 
-Policy objects are the mechanism used to provide the email package with the
-flexibility to handle all these disparate use cases,
+Policy objects give the email package the flexibility to handle all these
+disparate use cases.
 
 A :class:`Policy` object encapsulates a set of attributes and methods that
 control the behavior of various components of the email package during use.
@@ -39,24 +41,23 @@ program will use the same :class:`Policy` for both input and output, the two
 can be different.
 
 As an example, the following code could be used to read an email message from a
-file on disk and pass it to the system ``sendmail`` program on a ``unix``
-system::
+file on disk and pass it to the system ``sendmail`` program on a Unix system::
 
    >>> from email import msg_from_binary_file
    >>> from email.generator import BytesGenerator
    >>> import email.policy
    >>> from subprocess import Popen, PIPE
    >>> with open('mymsg.txt', 'b') as f:
-   >>>     msg = msg_from_binary_file(f, policy=email.policy.mbox)
+   ...     Msg = msg_from_binary_file(f, policy=email.policy.mbox)
    >>> p = Popen(['sendmail', msg['To'][0].address], stdin=PIPE)
-   >>> g = BytesGenerator(p.stdin, email.policy.policy=SMTP)
+   >>> g = BytesGenerator(p.stdin, policy=email.policy.SMTP)
    >>> g.flatten(msg)
    >>> p.stdin.close()
    >>> rc = p.wait()
 
 Some email package methods accept a *policy* keyword argument, allowing the
-policy to be overridden for that method.  For example, the following code use
-the :meth:`email.message.Message.as_string` method to the *msg* object from the
+policy to be overridden for that method.  For example, the following code uses
+the :meth:`email.message.Message.as_string` method of the *msg* object from the
 previous example and re-write it to a file using the native line separators for
 the platform on which it is running::
 
@@ -106,19 +107,19 @@ added matters.  To illustrate::
    .. attribute:: linesep
 
       The string to be used to terminate lines in serialized output.  The
-      default is '\\n' because that's the internal end-of-line discipline used
-      by Python, though '\\r\\n' is required by the RFCs.  See `Policy
+      default is ``\n`` because that's the internal end-of-line discipline used
+      by Python, though ``\r\n`` is required by the RFCs.  See `Policy
       Instances`_ for policies that use an RFC conformant linesep.  Setting it
       to :attr:`os.linesep` may also be useful.
 
    .. attribute:: must_be_7bit
 
-      If :const:`True`, data output by a bytes generator is limited to ASCII
+      If ``True``, data output by a bytes generator is limited to ASCII
       characters.  If :const:`False` (the default), then bytes with the high
       bit set are preserved and/or allowed in certain contexts (for example,
       where possible a content transfer encoding of ``8bit`` will be used).
-      String generators act as if ``must_be_7bit`` is `True` regardless of the
-      policy in effect, since a string cannot represent non-ASCII bytes.
+      String generators act as if ``must_be_7bit`` is ``True`` regardless of
+      the policy in effect, since a string cannot represent non-ASCII bytes.
 
    .. attribute:: raise_on_defect
 
@@ -126,6 +127,8 @@ added matters.  To illustrate::
       :const:`False` (the default), defects will be passed to the
       :meth:`register_defect` method.
 
+   :mod:`Policy` object also have the following methods:
+
    .. method:: handle_defect(obj, defect)
 
       *obj* is the object on which to register the defect.  *defect* should be
@@ -145,7 +148,7 @@ added matters.  To illustrate::
       handling of defects.  The default implementation calls the ``append``
       method of the ``defects`` attribute of *obj*.
 
-   .. method:: clone(obj, *kw):
+   .. method:: clone(obj, *kw)
 
       Return a new :class:`Policy` instance whose attributes have the same
       values as the current instance, except where those attributes are
@@ -153,27 +156,27 @@ added matters.  To illustrate::
 
 
 Policy Instances
-................
+^^^^^^^^^^^^^^^^
 
 The following instances of :class:`Policy` provide defaults suitable for
 specific common application domains.
 
 .. data:: default
 
-    An instance of :class:`Policy` with all defaults unchanged.
+   An instance of :class:`Policy` with all defaults unchanged.
 
 .. data:: SMTP
 
-    Output serialized from a message will conform to the email and SMTP
-    RFCs.  The only changed attribute is :attr:`linesep`, which is set to
-    ``\r\n``.
+   Output serialized from a message will conform to the email and SMTP
+   RFCs.  The only changed attribute is :attr:`linesep`, which is set to
+   ``\r\n``.
 
 .. data:: HTTP
 
-    Suitable for use when serializing headers for use in HTTP traffic.
-    :attr:`linesep` is set to ``\r\n``, and :attr:`max_line_length` is set to
-    :const:`None` (unlimited).
+   Suitable for use when serializing headers for use in HTTP traffic.
+   :attr:`linesep` is set to ``\r\n``, and :attr:`max_line_length` is set to
+   :const:`None` (unlimited).
 
 .. data:: strict
 
-    :attr:`raise_on_defect` is set to :const:`True`.
+   :attr:`raise_on_defect` is set to :const:`True`.