Corrections and additions to the documentation for POP3 and IMAP library

support, based on my fetchmail experience.

1 files changed, 22 insertions, 3 deletions

diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex
index d75e6da..7e3780b 100644
--- a/Doc/lib/libpoplib.tex
+++ b/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}}