Merge changes made in Gnus master

2012-10-05  Katsumi Yamaoka  <yamaoka@jpl.org>
 * gnus.texi (Mail Source Specifiers):
 Document :leave keyword used for pop mail source.
2012-10-25  Tassilo Horn  <tsdh@gnu.org>
 * gnus-dired.el (gnus-dired-attach): Attach to last used message buffer
 by default.  Patch provided by Stephen Eglen.
2012-10-05  Katsumi Yamaoka  <yamaoka@jpl.org>
 New UIDL implementation.
 * mail-source.el (mail-sources, mail-source-keyword-map):
 Add :leave as a pop3 keyword.
 (mail-source-fetch-pop): Bind pop3-leave-mail-on-server.
 * pop3.el (pop3-leave-mail-on-server): Allow number.
 (pop3-uidl-file, pop3-uidl-file-backup): New user options.
 (pop3-movemail): Add UIDL support.
 (pop3-send-streaming-command): Take a list of mail numbers instead of
 the number of mails.
 (pop3-write-to-file): Add X-UIDL header.
 (pop3-uidl-stat, pop3-uidl-dele, pop3-uidl-load, pop3-uidl-save)
 (pop3-uidl-add-xheader): New functions.
 * message.el (message-ignored-resent-headers):
 Add X-Content-Length and X-UIDL headers.

2 files changed, 38 insertions, 8 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index d719a02e32e..768a846bd1a 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2012-11-02  Katsumi Yamaoka  <yamaoka@jpl.org>
+
+        * gnus.texi (Mail Source Specifiers):
+        Document :leave keyword used for pop mail source.
+
 2012-11-01  Glenn Morris  <rgm@gnu.org>
 
         * cl.texi: General copyedits for style, line-breaks, etc.
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index a9cd0d3567c..47ff355d946 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -14759,20 +14759,37 @@ This can be either the symbol @code{password} or the symbol @code{apop}
 and says what authentication scheme to use.  The default is
 @code{password}.
 
+@item :leave
+Non-@code{nil} if the mail is to be left on the @acronym{POP} server
+after fetching.  Mails once fetched will never be fetched again by the
+@acronym{UIDL} control.  Only the built-in @code{pop3-movemail} program
+(the default) supports this keyword.
+
+If this is neither @code{nil} nor a number, all mails will be left on
+the server.  If this is a number, leave mails on the server for this
+many days since you first checked new mails.  If this is @code{nil}
+(the default), mails will be deleted on the server right after fetching.
+
+@vindex pop3-uidl-file
+The @code{pop3-uidl-file} variable specifies the file to which the
+@acronym{UIDL} data are locally stored.  The default value is
+@file{~/.pop3-uidl}.
+
+Note that @acronym{POP} servers maintain no state information between
+sessions, so what the client believes is there and what is actually
+there may not match up.  If they do not, then you may get duplicate
+mails or the whole thing can fall apart and leave you with a corrupt
+mailbox.
+
 @end table
 
-@vindex pop3-movemail
+@findex pop3-movemail
 @vindex pop3-leave-mail-on-server
 If the @code{:program} and @code{:function} keywords aren't specified,
-@code{pop3-movemail} will be used.  If @code{pop3-leave-mail-on-server}
-is non-@code{nil} the mail is to be left on the @acronym{POP} server
-after fetching when using @code{pop3-movemail}.  Note that POP servers
-maintain no state information between sessions, so what the client
-believes is there and what is actually there may not match up.  If they
-do not, then you may get duplicate mails or the whole thing can fall
-apart and leave you with a corrupt mailbox.
+@code{pop3-movemail} will be used.
 
 Here are some examples for getting mail from a @acronym{POP} server.
+
 Fetch from the default @acronym{POP} server, using the default user
 name, and default fetcher:
 
@@ -14787,6 +14804,14 @@ Fetch from a named server with a named user and password:
      :user "user-name" :password "secret")
 @end lisp
 
+Leave mails on the server for 14 days:
+
+@lisp
+(pop :server "my.pop.server"
+     :user "user-name" :password "secret"
+     :leave 14)
+@end lisp
+
 Use @samp{movemail} to move the mail:
 
 @lisp