Proofread and spell checked, all except the Examples section (which
I'll do next).
diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex
index 271619d..d76e7fd 100644
--- a/Doc/lib/emailmessage.tex
+++ b/Doc/lib/emailmessage.tex
@@ -33,9 +33,9 @@
\end{classdesc}
\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}}
-Return the entire formatted message as a string. Optional
-\var{unixfrom}, when true, specifies to include the \emph{Unix-From}
-envelope header; it defaults to \code{False}.
+Return the entire message flatten as a string. When optional
+\var{unixfrom} is \code{True}, the envelope header is included in the
+returned string. \var{unixfrom} defaults to \code{False}.
\end{methoddesc}
\begin{methoddesc}[Message]{__str__}{}
@@ -59,7 +59,7 @@
\end{methoddesc}
\begin{methoddesc}[Message]{attach}{payload}
-Add the given payload to the current payload, which must be
+Add the given \var{payload} to the current payload, which must be
\code{None} or a list of \class{Message} objects before the call.
After the call, the payload will always be a list of \class{Message}
objects. If you want to set the payload to a scalar object (e.g. a
@@ -95,7 +95,7 @@
\begin{methoddesc}[Message]{set_payload}{payload\optional{, charset}}
Set the entire message object's payload to \var{payload}. It is the
client's responsibility to ensure the payload invariants. Optional
-\var{charset} sets the message's default character set (see
+\var{charset} sets the message's default character set; see
\method{set_charset()} for details.
\versionchanged[\var{charset} argument added]{2.2.2}
@@ -103,7 +103,7 @@
\begin{methoddesc}[Message]{set_charset}{charset}
Set the character set of the payload to \var{charset}, which can
-either be a \class{Charset} instance (see \refmodule{email.Charset}, a
+either be a \class{Charset} instance (see \refmodule{email.Charset}), a
string naming a character set,
or \code{None}. If it is a string, it will be converted to a
\class{Charset} instance. If \var{charset} is \code{None}, the
@@ -128,14 +128,18 @@
\end{methoddesc}
The following methods implement a mapping-like interface for accessing
-the message object's \rfc{2822} headers. Note that there are some
+the message's \rfc{2822} headers. Note that there are some
semantic differences between these methods and a normal mapping
(i.e. dictionary) interface. For example, in a dictionary there are
no duplicate keys, but here there may be duplicate message headers. Also,
in dictionaries there is no guaranteed order to the keys returned by
-\method{keys()}, but in a \class{Message} object, there is an explicit
-order. These semantic differences are intentional and are biased
-toward maximal convenience.
+\method{keys()}, but in a \class{Message} object, headers are always
+returned in the order they appeared in the original message, or were
+added to the message later. Any header deleted and then re-added are
+always appended to the end of the header list.
+
+These semantic differences are intentional and are biased toward
+maximal convenience.
Note that in all cases, any envelope header present in the message is
not included in the mapping interface.
@@ -175,8 +179,7 @@
Note that this does \emph{not} overwrite or delete any existing header
with the same name. If you want to ensure that the new header is the
only one present in the message with field name
-\var{name}, first use \method{__delitem__()} to delete all named
-fields, e.g.:
+\var{name}, delete the field first, e.g.:
\begin{verbatim}
del msg['subject']
@@ -196,27 +199,16 @@
\end{methoddesc}
\begin{methoddesc}[Message]{keys}{}
-Return a list of all the message's header field names. These keys
-will be sorted in the order in which they appeared in the original
-message, or were added to the message and may contain
-duplicates. Any fields deleted and then subsequently re-added are
-always appended to the end of the header list.
+Return a list of all the message's header field names.
\end{methoddesc}
\begin{methoddesc}[Message]{values}{}
-Return a list of all the message's field values. These will be sorted
-in the order in which they appeared in the original message, or were
-added to the message, and may contain
-duplicates. Any fields deleted and then subsequently re-added are
-always appended to the end of the header list.
+Return a list of all the message's field values.
\end{methoddesc}
\begin{methoddesc}[Message]{items}{}
Return a list of 2-tuples containing all the message's field headers
-and values. These will be sorted in the order in which they appeared
-in the original message, or were added to the message, and may contain
-duplicates. Any fields deleted and then subsequently re-added are
-always appended to the end of the header list.
+and values.
\end{methoddesc}
\begin{methoddesc}[Message]{get}{name\optional{, failobj}}
@@ -228,11 +220,7 @@
Here are some additional useful methods:
\begin{methoddesc}[Message]{get_all}{name\optional{, failobj}}
-Return a list of all the values for the field named \var{name}. These
-will be sorted in the order in which they appeared in the original
-message, or were added to the message. Any fields deleted and then
-subsequently re-added are always appended to the end of the list.
-
+Return a list of all the values for the field named \var{name}.
If there are no such named headers in the message, \var{failobj} is
returned (defaults to \code{None}).
\end{methoddesc}
@@ -351,10 +339,10 @@
Parameter keys are always compared case insensitively. The return
value can either be a string, or a 3-tuple if the parameter was
\rfc{2231} encoded. When it's a 3-tuple, the elements of the value are of
-the form \samp{(CHARSET, LANGUAGE, VALUE)}, where \var{LANGUAGE} may
+the form \code{(CHARSET, LANGUAGE, VALUE)}, where \code{LANGUAGE} may
be the empty string. Your application should be prepared to deal with
-3-tuple return values, which it can convert the parameter to a Unicode
-string like so:
+3-tuple return values, which it can convert to a Unicode string like
+so:
\begin{verbatim}
param = msg.get_param('foo')
@@ -363,7 +351,7 @@
\end{verbatim}
In any case, the parameter value (either the returned string, or the
-\var{VALUE} item in the 3-tuple) is always unquoted, unless
+\code{VALUE} item in the 3-tuple) is always unquoted, unless
\var{unquote} is set to \code{False}.
\versionchanged[\var{unquote} argument added, and 3-tuple return value
@@ -398,7 +386,7 @@
\mailheader{Content-Type} header. The header will be re-written in
place without the parameter or its value. All values will be quoted
as necessary unless \var{requote} is \code{False} (the default is
-\code{True}). Optional \var{header} specifies an alterative to
+\code{True}). Optional \var{header} specifies an alternative to
\mailheader{Content-Type}.
\versionadded{2.2.2}
@@ -417,8 +405,8 @@
will be quoted (the default).
An alternative header can be specified in the \var{header} argument.
-When the \mailheader{Content-Type} header is set, we'll always also
-add a \mailheader{MIME-Version} header.
+When the \mailheader{Content-Type} header is set a
+\mailheader{MIME-Version} header is also added.
\versionadded{2.2.2}
\end{methoddesc}
@@ -440,11 +428,10 @@
\end{methoddesc}
\begin{methoddesc}[Message]{set_boundary}{boundary}
-Set the \code{boundary} parameter of the \mailheader{Content-Type} header
-to \var{boundary}. \method{set_boundary()} will always quote
-\var{boundary} so you should not quote it yourself. A
-\exception{HeaderParseError} is raised if the message object has no
-\mailheader{Content-Type} header.
+Set the \code{boundary} parameter of the \mailheader{Content-Type}
+header to \var{boundary}. \method{set_boundary()} will always quote
+\var{boundary} if necessary. A \exception{HeaderParseError} is raised
+if the message object has no \mailheader{Content-Type} header.
Note that using this method is subtly different than deleting the old
\mailheader{Content-Type} header and adding a new one with the new boundary
@@ -459,9 +446,9 @@
header. If there is no \mailheader{Content-Type} header, or if that
header has no \code{charset} parameter, \var{failobj} is returned.
-Note that this method differs from \method{get_charset} which returns
-the \class{Charset} instance for the default encoding of the message
-body.
+Note that this method differs from \method{get_charset()} which
+returns the \class{Charset} instance for the default encoding of the
+message body.
\versionadded{2.2.2}
\end{methoddesc}
@@ -484,15 +471,15 @@
The \method{walk()} method is an all-purpose generator which can be
used to iterate over all the parts and subparts of a message object
tree, in depth-first traversal order. You will typically use
-\method{walk()} as the iterator in a \code{for ... in} loop; each
+\method{walk()} as the iterator in a \code{for} loop; each
iteration returns the next subpart.
-Here's an example that prints the MIME type of every part of a message
-object tree:
+Here's an example that prints the MIME type of every part of a
+multipart message structure:
\begin{verbatim}
>>> for part in msg.walk():
->>> print part.get_type('text/plain')
+>>> print part.get_content_type()
multipart/report
text/plain
message/delivery-status