Updates do email package documentation for markup, style, and

organization.

1 files changed, 21 insertions, 13 deletions

diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex
index 2cb58ecd2c..6ded8d12d4 100644
--- a/Doc/lib/emailgenerator.tex
+++ b/Doc/lib/emailgenerator.tex
@@ -1,17 +1,24 @@
-\section{\module{email.Generator} ---
-         Generating flat text from an email message object tree}
-
 \declaremodule{standard}{email.Generator}
-\modulesynopsis{Generate flat text email messages to from a message
-	        object tree.}
-\sectionauthor{Barry A. Warsaw}{barry@zope.com}
+\modulesynopsis{Generate flat text email messages from a message object tree.}
+
+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
+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
+document is the job of the \class{Generator} class.
 
-\versionadded{2.2}
+Again, as with the \refmodule{email.Parser} module, you aren't limited
+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, be idempotent (the input is identical to the
+output).
 
-The \class{Generator} class is used to render a message object model
-into its flat text representation, including MIME encoding any
-sub-messages, generating the correct \rfc{2822} headers, etc.  Here
-are the public methods of the \class{Generator} class.
+Here are the public methods of the \class{Generator} class:
 
 \begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
     maxheaderlen}}}
@@ -25,8 +32,9 @@ 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
-\url{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
- for details).
+\ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
+{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
+for details).
 
 Optional \var{maxheaderlen} specifies the longest length for a
 non-continued header.  When a header line is longer than