Added section for MimeWriter, contributed by Christopher Petrilli

<petrilli@amber.org>.

This spells the end of another whole section in the undoc chapter!

1 files changed, 75 insertions, 0 deletions

diff --git a/Doc/lib/libmimewriter.tex b/Doc/lib/libmimewriter.tex
new file mode 100644
index 0000000..ec57584
--- /dev/null
+++ b/Doc/lib/libmimewriter.tex
@@ -0,0 +1,75 @@
+\section{\module{MimeWriter} ---
+         Generic MIME file writer}
+
+\declaremodule{standard}{MimeWriter}
+
+\modulesynopsis{Generic MIME file writer.}
+\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
+
+This module defines the class \class{MimeWriter}.  The
+\class{MimeWriter} class implements a basic formatter for creating
+MIME multi-part files.  It doesn't seek around the output file nor
+does it use large amounts of buffer space. You must write the parts
+out in the order that they should occur in the final
+file. \class{MimeWriter} does buffer the headers you add, allowing you 
+to rearrange their order.
+
+\begin{classdesc}{MimeWriter}{fp}
+Return a new instance of the \class{MimeWriter} class.  The only
+argument passed, \var{fp}, is a file object to be used for
+writing. Note that a \class{StringIO} object could also be used.
+\end{classdesc}
+
+
+\subsection{MimeWriter Objects \label{MimeWriter-objects}}
+
+
+\class{MimeWriter} instances have the following methods:
+
+\begin{methoddesc}{addheader}{key, value\optional{, prefix}}
+Add a header line to the MIME message. The \var{key} is the name of
+the header, where the \var{value} obviously provides the value of the
+header. The optional argument \var{prefix} determines where the header 
+is inserted; \samp{0} means append at the end, \samp{1} is insert at
+the start. The default is to append.
+\end{methoddesc}
+
+\begin{methoddesc}{flushheaders}{}
+Causes all headers accumulated so far to be written out (and
+forgotten). This is useful if you don't need a body part at all,
+e.g.\ for a subpart of type \mimetype{message/rfc822} that's (mis)used
+to store some header-like information.
+\end{methoddesc}
+
+\begin{methoddesc}{startbody}{ctype\optional{, plist\optional{, prefix}}}
+Returns a file-like object which can be used to write to the
+body of the message.  The content-type is set to the provided
+\var{ctype}, and the optional parameter \var{plist} provides
+additional parameters for the content-type declaration. \var{prefix}
+functions as in \method{addheader()} except that the default is to
+insert at the start.
+\end{methoddesc}
+
+\begin{methoddesc}{startmultipartbody}{subtype\optional{,
+                   boundary\optional{, plist\optional{, prefix}}}}
+Returns a file-like object which can be used to write to the
+body of the message.  Additionally, this method initializes the
+multi-part code, where \var{subtype} provides the mutlipart subtype,
+\var{boundary} may provide a user-defined boundary specification, and
+\var{plist} provides optional parameters for the subtype.
+\var{prefix} functions as in \method{startbody()}.  Subparts should be
+created using \method{nextpart()}.
+\end{methoddesc}
+
+\begin{methoddesc}{nextpart}{}
+Returns a new instance of \class{MimeWriter} which represents an
+individual part in a multipart message.  This may be used to write the 
+part as well as used for creating recursively complex multipart
+messages. The message must first be initialized with
+\method{startmultipartbody()} before using \method{nextpart()}.
+\end{methoddesc}
+
+\begin{methoddesc}{lastpart}{}
+This is used to designate the last part of a multipart message, and
+should \emph{always} be used when writing multipart messages.
+\end{methoddesc}