Vast update to email version 2. This could surely use proofreading.

1 files changed, 74 insertions, 19 deletions

diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex
index 63ceb73..03fee9f 100644
--- a/Doc/lib/emailgenerator.tex
+++ b/Doc/lib/emailgenerator.tex
@@ -1,11 +1,11 @@
 \declaremodule{standard}{email.Generator}
-\modulesynopsis{Generate flat text email messages from a message object tree.}
+\modulesynopsis{Generate flat text email messages from a message structure.}
 
 One of the most common tasks is to generate the flat text of the email
-message represented by a message object tree.  You will need to do
+message represented by a message object structure.  You will need to do
 this if you want to send your message via the \refmodule{smtplib}
 module or the \refmodule{nntplib} module, or print the message on the
-console.  Taking a message object tree and producing a flat text
+console.  Taking a message object structure and producing a flat text
 document is the job of the \class{Generator} class.
 
 Again, as with the \refmodule{email.Parser} module, you aren't limited
@@ -13,10 +13,9 @@ to the 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 an object tree via the
-\class{Parser} class,
-and back to flat text, is idempotent (the input is identical to the
-output).
+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).
 
 Here are the public methods of the \class{Generator} class:
 
@@ -27,14 +26,16 @@ object called \var{outfp} for an argument.  \var{outfp} must support
 the \method{write()} method and be usable as the output file in a
 Python 2.0 extended print statement.
 
-Optional \var{mangle_from_} is a flag that, when true, puts a \samp{>}
-character in front of any line in the body that starts exactly as
+Optional \var{mangle_from_} is a flag that, when \code{True}, puts a
+\samp{>} character in front of any line in the body that starts exactly as
 \samp{From } (i.e. \code{From} followed by a space at the front of the
 line).  This is the only guaranteed portable way to avoid having such
-lines be mistaken for \emph{Unix-From} headers (see
+lines be mistaken for a Unix mailbox format envelope header separator (see
 \ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
 {http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
-for details).
+for details).  \var{mangle_from_} defaults to \code{True}, but you
+might want to set this to \code{False} if you are not writing Unix
+mailbox format files.
 
 Optional \var{maxheaderlen} specifies the longest length for a
 non-continued header.  When a header line is longer than
@@ -47,20 +48,28 @@ recommended (but not required) by \rfc{2822}.
 
 The other public \class{Generator} methods are:
 
-\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
-Print the textual representation of the message object tree rooted at
+\begin{methoddesc}[Generator]{flatten()}{msg\optional{, unixfrom}}
+Print the textual representation of the message object structure rooted at
 \var{msg} to the output file specified when the \class{Generator}
 instance was created.  Sub-objects are visited depth-first and the
 resulting text will be properly MIME encoded.
 
 Optional \var{unixfrom} is a flag that forces the printing of the
-\emph{Unix-From} (a.k.a. envelope header or \code{From_} header)
-delimiter before the first \rfc{2822} header of the root message
-object.  If the root object has no \emph{Unix-From} header, a standard
-one is crafted.  By default, this is set to 0 to inhibit the printing
-of the \emph{Unix-From} delimiter.
+envelope header delimiter before the first \rfc{2822} header of the
+root message object.  If the root object has no envelope header, a
+standard one is crafted.  By default, this is set to \code{False} to
+inhibit the printing of the envelope delimiter.
+
+Note that for sub-objects, no envelope header is ever printed.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Generator]{clone}{fp}
+Return an independent clone of this \class{Generator} instance with
+the exact same options.
 
-Note that for sub-objects, no \emph{Unix-From} header is ever printed.
+\versionadded{2.2.2}
 \end{methoddesc}
 
 \begin{methoddesc}[Generator]{write}{s}
@@ -74,3 +83,49 @@ As a convenience, see the methods \method{Message.as_string()} and
 \code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which
 simplify the generation of a formatted string representation of a
 message object.  For more detail, see \refmodule{email.Message}.
+
+The \module{email.Generator} module also provides a derived class,
+called \class{DecodedGenerator} which is like the \class{Generator}
+base class, except that non-\mimetype{text} parts are substituted with
+a format string representing the part.
+
+\begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{,
+    maxheaderlen\optional{, fmt}}}}
+
+This class, derived from \class{Generator} walks through all the
+subparts of a message.  If the subpart is of main type
+\mimetype{text}, then it prints the decoded payload of the subpart.
+Optional \var{_mangle_from_} and \var{maxheaderlen} are as with the
+\class{Generator} base class.
+
+If the subpart is not of main type \mimetype{text}, optional \var{fmt}
+is a format string that is used instead of the message
+payload.  \var{fmt} is expanded with the following keywords (in
+\samp{\%(keyword)s} format):
+
+type       : Full MIME type of the non-\mimetype{text} part
+maintype   : Main MIME type of the non-\mimetype{text} part
+subtype    : Sub-MIME type of the non-\mimetype{text} part
+filename   : Filename of the non-\mimetype{text} part
+description: Description associated with the non-\mimetype{text} part
+encoding   : Content transfer encoding of the non-\mimetype{text} part
+
+The default value for \var{fmt} is \code{None}, meaning
+
+\begin{verbatim}
+[Non-text (%(type)s) part of message omitted, filename %(filename)s]
+\end{verbatim}
+
+\versionadded{2.2.2}
+\end{classdesc}
+
+\subsubsection{Deprecated methods}
+
+The following methods are deprecated in \module{email} version 2.
+They are documented here for completeness.
+
+\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
+This method is identical to the \method{flatten()} method.
+
+\deprecated{2.2.2}{Use the \method{flatten()} method instead.}
+\end{methoddesc}