Updates do email package documentation for markup, style, and
organization.
diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex
index 2cb58ec..6ded8d1 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.}
-\versionadded{2.2}
+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.
-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.
+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).
+
+Here are the public methods of the \class{Generator} class:
\begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
maxheaderlen}}}
@@ -25,8 +32,9 @@
\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