Updated the documentation in several respects:
- This module, despite its name, now should conform to RFC 2822, the
update to RFC 822.
- This module doesn't just represent "email headers", but entire email
messages.
- Added documentation for other useful public functions such as
quote(), unquote(), praseaddr(), and dump_address_pair().
diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex
index f0110eb..8a30500 100644
--- a/Doc/lib/librfc822.tex
+++ b/Doc/lib/librfc822.tex
@@ -1,15 +1,20 @@
\section{\module{rfc822} ---
- Parse RFC 822 mail headers}
+ Parse RFC 2822 mail headers}
\declaremodule{standard}{rfc822}
-\modulesynopsis{Parse \rfc{822} style mail headers.}
+\modulesynopsis{Parse \rfc{2822} style mail messages.}
-This module defines a class, \class{Message}, which represents a
-collection of ``email headers'' as defined by the Internet standard
-\rfc{822}. It is used in various contexts, usually to read such
-headers from a file. This module also defines a helper class
-\class{AddressList} for parsing \rfc{822} addresses. Please refer to
-the RFC for information on the specific syntax of \rfc{822} headers.
+This module defines a class, \class{Message}, which represents an
+``email message'' as defined by the Internet standard
+\rfc{2822}\footnote{This module originally conformed to \rfc{822},
+hence the name. Since then, \rfc{2822} has been released as an
+update to \rfc{822}. This module should be considered
+\rfc{2822}-conformant, especially in cases where the
+syntax or semantics have changed since \rfc{822}.}. Such messages
+consist of a collection of message headers, and a message body. This
+module also defines a helper class
+\class{AddressList} for parsing \rfc{2822} addresses. Please refer to
+the RFC for information on the specific syntax of \rfc{2822} messages.
The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes
to read mailboxes produced by various end-user mail programs.
@@ -50,15 +55,42 @@
\begin{classdesc}{AddressList}{field}
You may instantiate the \class{AddressList} helper class using a single
-string parameter, a comma-separated list of \rfc{822} addresses to be
+string parameter, a comma-separated list of \rfc{2822} addresses to be
parsed. (The parameter \code{None} yields an empty list.)
\end{classdesc}
+\begin{funcdesc}{quote}{str}
+Return a new string with backslashes in \var{str} replaced by two
+backslashes and double quotes replaced by backslash-double quote.
+\end{funcdesc}
+
+\begin{funcdesc}{unquote}{str}
+Return a new string which is an \emph{unquoted} version of \var{str}.
+If \var{str} ends and begins with double quotes, they are stripped
+off. Likewise if \var{str} ends and begins with angle brackets, they
+are stripped off.
+\end{funcdesc}
+
+\begin{funcdesc}{parseaddr}{address}
+Parse address -- which should be the value of some address-containing
+field such as \code{To:} or \code{Cc:} -- into its constituent
+``realname'' and ``email address'' parts. Returns a tuple of that
+information, unless the parse fails, in which case a 2-tuple of
+\code{(None, None)} is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{dump_address_pair}{pair}
+The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
+\code{(realname, email_address)} and returns the string value suitable
+for a \code{To:} or \code{Cc:} header. If the first element of
+\var{pair} is false, then the second element is returned unmodified.
+\end{funcdesc}
+
\begin{funcdesc}{parsedate}{date}
-Attempts to parse a date according to the rules in \rfc{822}.
+Attempts to parse a date according to the rules in \rfc{2822}.
however, some mailers don't follow that format as specified, so
\function{parsedate()} tries to guess correctly in such cases.
-\var{date} is a string containing an \rfc{822} date, such as
+\var{date} is a string containing an \rfc{2822} date, such as
\code{'Mon, 20 Nov 1995 19:12:08 -0500'}. If it succeeds in parsing
the date, \function{parsedate()} returns a 9-tuple that can be passed
directly to \function{time.mktime()}; otherwise \code{None} will be
@@ -74,7 +106,7 @@
term for Greenwich Mean Time). (Note that the sign of the timezone
offset is the opposite of the sign of the \code{time.timezone}
variable for the same timezone; the latter variable follows the
-\POSIX{} standard while this module follows \rfc{822}.) If the input
+\POSIX{} standard while this module follows \rfc{2822}.) If the input
string has no timezone, the last element of the tuple returned is
\code{None}. Note that fields 6, 7, and 8 of the result tuple are not
usable.
@@ -109,7 +141,7 @@
\begin{methoddesc}{isheader}{line}
Returns a line's canonicalized fieldname (the dictionary key that will
-be used to index it) if the line is a legal \rfc{822} header; otherwise
+be used to index it) if the line is a legal \rfc{2822} header; otherwise
returns None (implying that parsing should stop here and the line be
pushed back on the input stream). It is sometimes useful to override
this method in a subclass.