Corrections and additions to the documentation for POP3 and IMAP library
support, based on my fetchmail experience.
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 @@
\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 @@
\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 @@
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 @@
\var{octets})}.
\end{methoddesc}
+\begin{seealso}
+ \seemodule{imap}{The standard Python IMAP module.}
+\end{seealso}
\subsection{POP3 Example \label{pop3-example}}