[Python-checkins] CVS: python/dist/src/Doc/lib libimaplib.tex,1.16,1.17 libpoplib.tex,1.9,1.10

[Eric S. Raymond]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv15465

Modified Files:
	libimaplib.tex libpoplib.tex 
Log Message:
Corrections and additions to the documentation for POP3 and IMAP library
support, based on my fetchmail experience.


Index: libimaplib.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libimaplib.tex,v
retrieving revision 1.16
retrieving revision 1.17
diff -C2 -r1.16 -r1.17
*** libimaplib.tex	2000/07/16 19:01:09	1.16
--- libimaplib.tex	2001/01/11 04:19:52	1.17
***************
*** 9,20 ****
  % Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
  % converted by Fred L. Drake, Jr. <fdrake@acm.org>.
  
  \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.
  
  A single class is provided by the \module{imaplib} module:
--- 9,21 ----
  % 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 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:
***************
*** 72,77 ****
  
  
! Note that IMAP4 message numbers change as the mailbox changes, 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
--- 73,80 ----
  
  
! 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

Index: libpoplib.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libpoplib.tex,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -r1.9 -r1.10
*** libpoplib.tex	2000/07/16 19:01:10	1.9
--- libpoplib.tex	2001/01/11 04:19:52	1.10
***************
*** 9,12 ****
--- 9,13 ----
  %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}
***************
*** 17,20 ****
--- 18,27 ----
  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:
  
***************
*** 76,85 ****
  
  \begin{methoddesc}{retr}{which}
! Retrieve whole message number \var{which}.  Result is in form 
! \code{(\var{response}, ['line', ...], \var{octets})}.
  \end{methoddesc}
  
  \begin{methoddesc}{dele}{which}
! Delete message number \var{which}.
  \end{methoddesc}
  
--- 83,95 ----
  
  \begin{methoddesc}{retr}{which}
! 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}
! 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}
  
***************
*** 100,103 ****
--- 110,119 ----
  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}
  
***************
*** 110,113 ****
--- 126,132 ----
  \end{methoddesc}
  
+ \begin{seealso}
+   \seemodule{imap}{The standard Python IMAP module.}
+ \end{seealso}
  
  \subsection{POP3 Example \label{pop3-example}}