1 files changed, 53 insertions, 0 deletions
diff --git a/Doc/lib/emailencoders.tex b/Doc/lib/emailencoders.tex
new file mode 100644
index 0000000..6ebb302
--- /dev/null
+++ b/Doc/lib/emailencoders.tex
@@ -0,0 +1,53 @@
+\section{\module{email.Encoders} ---
+         Email message payload encoders}
+
+\declaremodule{standard}{email.Encoders}
+\modulesynopsis{Encoders for email message payloads.}
+\sectionauthor{Barry A. Warsaw}{barry@zope.com}
+
+\versionadded{2.2}
+
+When creating \class{Message} objects from scratch, you often need to
+encode the payloads for transport through compliant mail servers.
+This is especially true for \code{image/*} and \code{text/*} type
+messages containing binary data.
+
+The \module{email} package provides some convenient encodings in its
+\module{Encoders} module.  These encoders are actually used by the
+\class{MIMEImage} and \class{MIMEText} class constructors to provide default
+encodings.  All encoder functions take exactly one argument, the
+message object to encode.  They usually extract the payload, encode
+it, and reset the payload to this newly encoded value.  They should also
+set the \code{Content-Transfer-Encoding:} header as appropriate.
+
+Here are the encoding functions provided:
+
+\begin{funcdesc}{encode_quopri}{msg}
+Encodes the payload into \emph{Quoted-Printable} form and sets the
+\code{Content-Transfer-Encoding:} header to
+\code{quoted-printable}\footnote{Note that encoding with
+\method{encode_quopri()} also encodes all tabs and space characters in
+the data.}.
+This is a good encoding to use when most of your payload is normal
+printable data, but contains a few unprintable characters.
+\end{funcdesc}
+
+\begin{funcdesc}{encode_base64}{msg}
+Encodes the payload into \emph{Base64} form and sets the
+\code{Content-Transfer-Encoding:} header to
+\code{base64}.  This is a good encoding to use when most of your payload
+is unprintable data since it is a more compact form than
+Quoted-Printable.  The drawback of Base64 encoding is that it
+renders the text non-human readable.
+\end{funcdesc}
+
+\begin{funcdesc}{encode_7or8bit}{msg}
+This doesn't actually modify the message's payload, but it does set
+the \code{Content-Transfer-Encoding:} header to either \code{7bit} or
+\code{8bit} as appropriate, based on the payload data.
+\end{funcdesc}
+
+\begin{funcdesc}{encode_noop}{msg}
+This does nothing; it doesn't even set the
+\code{Content-Transfer-Encoding:} header.
+\end{funcdesc}