Better discussion of the old-message problem.

svn path=/trunk/; revision=195

1 files changed, 29 insertions, 11 deletions

diff --git a/fetchmail.man b/fetchmail.man
index 1f2dec19..ed252e28 100644
--- a/fetchmail.man
+++ b/fetchmail.man
@@ -457,7 +457,35 @@ For correct initialization,
 requires either that both the USER and HOME environment variables are
 correctly set, or that \fBgetpwuid\fR(3) be able to retrieve a password
 entry from your user ID.
-.SH KNOWN PROBLEMS
+.SH OLD-MESSAGE PROBLEMS
+The normal mode of \fIfetchmail\fR is to try to download only `new'
+messages, leaving untouched (and undeleted) messages you have already
+read directly on the server (or fetched with a previous \fIfetchmail
+--keep\fR).  But you may find that messages you've already read on the
+server are being fetched and deleted even when you don't specify
+--all.  There are several reasons this can happen.
+.PP
+One could be that you're using POP2.  The POP2 protocol includes no
+representation of `new' or `old' state in messages, so \fIfetchmail\fR
+must treat all messages as new all the time.
+.PP
+Under POP3, blame RFC1725.  That late version of the POP3 protocol
+specification ill-advisedly removed the LAST command, and some POP
+servers (including the one distributed with at least some versions of
+SunOS) follow it (you can verify this by invoking \fIfetchmail -v\fR
+and watching the response to LAST early in the query).  The fix is to
+install an older POP3 server with LAST or switch to an IMAP server.
+.PP
+The IMAP code uses the presence or absence of the server flag \eSeen
+to decide whether or not a message is new.  Under Unix, it counts on
+your IMAP server to notice the BSD-style Status flags set by mail user
+agents and set the \Seen flag from them when appropriate.  All Unix
+IMAP servers we know of do this, though it's not specified by the IMAP
+RFCs.  If you ever trip over a server that doesn't, the symptom will
+be that messages you have already read on your host will look new to
+the server.  In this (unlikely) case, only messages you fetched with
+\fIfetchmail --keep\fR will be both undeleted and marked old.
+.SH OTHER KNOWN PROBLEMS
 Use of any of the supported protocols other than APOP requires that
 the program send unencrypted passwords over the TCP/IP connection to
 the mail server.  This creates a risk that name/password pairs might
@@ -470,16 +498,6 @@ in POP2 or POP3 mode pointed at the same mailbox may cause messages to
 be lost or remain unfetched. (This is a design problem of the POP2 and
 POP3 protocols; IMAP is less vulnerable.)
 .PP
-If, using POP3, you find that messages you've already read on the
-server are being fetched even when you don't specify --all, blame
-RFC1725.  That late version of the POP3 protocol specification
-ill-advisedly removed the LAST command, and some servers (including
-the one distributed with at least some versions of SunOS) follow it
-(you can verify this by invoking
-.I fetchmail -v
-and watching the response to LAST early in the query).  The fix is to
-install an older POP3 server with LAST or switch to an IMAP server.
-.PP
 The RPOP support is not yet well tested.
 .PP
 Send comments, bug reports, gripes, and the like to Eric S. Raymond