Corrections and additions to the documentation for POP3 and IMAP library

support, based on my fetchmail experience.

Doc/lib/libimaplib.tex

@@ -8,14 +8,15 @@
 
 % Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
 % converted by Fred L. Drake, Jr. <fdrake@acm.org>.
+% Revised by ESR, January 2000.
 
 \indexii{IMAP4}{protocol}
 
 This module defines a class, \class{IMAP4}, which encapsulates a
-connection to an IMAP4 server and implements the IMAP4rev1 client
-protocol as defined in \rfc{2060}. It is backward compatible with
-IMAP4 (\rfc{1730}) servers, but note that the \samp{STATUS} command is
-not supported in IMAP4.
+connection to an IMAP4 server and implements a large subset of the
+IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward
+compatible with IMAP4 (\rfc{1730}) servers, but note that the
+\samp{STATUS} command is not supported in IMAP4.
 
 A single class is provided by the \module{imaplib} module:
 
@@ -71,8 +72,10 @@ The following utility functions are defined:
 \end{funcdesc}
 
 
-Note that IMAP4 message numbers change as the mailbox changes, so it
-is highly advisable to use UIDs instead, with the UID command.
+Note that IMAP4 message numbers change as the mailbox changes; in
+particular, after an \samp{EXPUNGE} command performs deletions the
+remaining messages are renumbered. So it is highly advisable to use
+UIDs instead, with the UID command.
 
 At the end of the module, there is a test section that contains a more
 extensive example of usage.

Doc/lib/libpoplib.tex

@@ -8,6 +8,7 @@
 %Even though I put it into LaTeX, I cannot really claim that I wrote
 %it since I just stole most of it from the poplib.py source code and
 %the imaplib ``chapter''.
+%Revised by ESR, January 2000
 
 \indexii{POP3}{protocol}
 
@@ -16,6 +17,12 @@ connection to an POP3 server and implements protocol as defined in
 \rfc{1725}.  The \class{POP3} class supports both the minimal and
 optional command sets.
 
+Note that POP3, though widely supported, is obsolescent.  The
+implementation quality of POP3 servers varies widely, and too many are
+quite poor. If your mailserver supports IMAP, you would be better off
+using the \refmodule{IMAP} class, as IMAP servers tend to be better
+implemented.
+
 A single class is provided by the \module{poplib} module:
 
 \begin{classdesc}{POP3}{host\optional{, port}}
@@ -75,12 +82,15 @@ set, it is the message to list.
 \end{methoddesc}
 
 \begin{methoddesc}{retr}{which}
-Retrieve whole message number \var{which}.  Result is in form 
-\code{(\var{response}, ['line', ...], \var{octets})}.
+Retrieve whole message number \var{which}, and set its seen flag.
+Result is in form  \code{(\var{response}, ['line', ...], \var{octets})}.
 \end{methoddesc}
 
 \begin{methoddesc}{dele}{which}
-Delete message number \var{which}.
+Flag message number \var{which} for deletion.  On most servers
+deletions are not actually performed until QUIT (the major exception is
+Eudora QPOP, which deliberately violates the RFCs by doing pending 
+deletes on any disconnect).
 \end{methoddesc}
 
 \begin{methoddesc}{rset}{}
@@ -99,6 +109,12 @@ Signoff:  commit changes, unlock mailbox, drop connection.
 Retrieves the message header plus \var{howmuch} lines of the message
 after the header of message number \var{which}. Result is in form 
 \code{(\var{response}, ['line', ...], \var{octets})}.
+
+The POP3 TOP command this method uses, unlike the RETR command,
+doesn't set the message's seen flag; unfortunately, TOP is poorly
+specified in the RFCs and is frequently broken in off-brand servers.
+Test this method by hand against the POP3 servers you will use before
+trusting it.
 \end{methoddesc}
 
 \begin{methoddesc}{uidl}{\optional{which}}
@@ -109,6 +125,9 @@ otherwise result is list \code{(\var{response}, ['mesgnum uid', ...],
 \var{octets})}.
 \end{methoddesc}
 
+\begin{seealso}
+  \seemodule{imap}{The standard Python IMAP module.}
+\end{seealso}
 
 \subsection{POP3 Example \label{pop3-example}}