Added some more documentation to as_string() to make it clear that

it's a convenience only.  Give an example of what to do for more
flexibility.

1 files changed, 14 insertions, 0 deletions

diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex
index 61dc74b..f580edf 100644
--- a/Doc/lib/emailmessage.tex
+++ b/Doc/lib/emailmessage.tex
@@ -36,6 +36,20 @@ The constructor takes no arguments.
 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}.
+
+Note that this method is provided as a convenience and may not always
+format the message the way you want.  For more flexibility,
+instantiate a \class{Generator} instance and use its
+\method{flatten()} method directly.  For example:
+
+\begin{verbatim}
+from cStringIO import StringIO
+from email.Generator import Generator
+fp = StringIO()
+g = Generator(mangle_from_=False, maxheaderlen=60)
+g.flatten(msg)
+text = fp.getvalue()
+\end{verbatim}
 \end{methoddesc}
 
 \begin{methoddesc}[Message]{__str__}{}