nnimap doc patch

nnimap doc patch

[Jouni K Seppanen]

[-- Attachment #1: Type: text/plain, Size: 172 bytes --]

It seems that my doc patch from November
<29hdb27qbn.fsf@itl-pc9.hut.fi> hasn't been applied. Was there some
problem with it, or was it just forgotten?

Here it is again:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: nnimap-doc.patch --]
[-- Type: text/x-patch, Size: 6798 bytes --]

Index: texi/gnus.texi
===================================================================
RCS file: /usr/local/cvsroot/gnus/texi/gnus.texi,v
retrieving revision 7.168
diff -u -r7.168 gnus.texi
--- texi/gnus.texi	5 Apr 2006 16:40:48 -0000	7.168
+++ texi/gnus.texi	6 Apr 2006 05:53:22 -0000
@@ -2825,6 +2825,7 @@
 
 @item auto-expire
 @cindex auto-expire
+@cindex expiring mail
 If the group parameter has an element that looks like @code{(auto-expire
 . t)}, all articles read will be marked as expirable.  For an
 alternative approach, @pxref{Expiring Mail}.
@@ -2833,6 +2834,7 @@
 
 @item total-expire
 @cindex total-expire
+@cindex expiring mail
 If the group parameter has an element that looks like
 @code{(total-expire . t)}, all read articles will be put through the
 expiry process, even if they are not marked as expirable.  Use with
@@ -2842,7 +2844,7 @@
 See also @code{gnus-total-expirable-newsgroups}.
 
 @item expiry-wait
-@cindex expiry-wait
+@vindex expiry-wait
 @vindex nnmail-expiry-wait-function
 If the group parameter has an element that looks like
 @code{(expiry-wait . 10)}, this value will override any
@@ -2852,7 +2854,7 @@
 symbols @code{never} or @code{immediate}.
 
 @item expiry-target
-@cindex expiry-target
+@vindex expiry-target
 Where expired messages end up.  This parameter overrides
 @code{nnmail-expiry-target}.
 
@@ -3462,6 +3464,7 @@
 @item C-c C-x
 @kindex C-c C-x (Group)
 @findex gnus-group-expire-articles
+@cindex expiring mail
 Run all expirable articles in the current group through the expiry
 process (if any) (@code{gnus-group-expire-articles}).  That is, delete
 all expirable articles in the group that have been around for a while.
@@ -3470,6 +3473,7 @@
 @item C-c C-M-x
 @kindex C-c C-M-x (Group)
 @findex gnus-group-expire-all-groups
+@cindex expiring mail
 Run all expirable articles in all groups through the expiry process
 (@code{gnus-group-expire-all-groups}).
 
@@ -3830,6 +3834,7 @@
 @item C-c C-x
 @kindex C-c C-x (Topic)
 @findex gnus-topic-expire-articles
+@cindex expiring mail
 Run all expirable articles in the current group or topic through the
 expiry process (if any)
 (@code{gnus-topic-expire-articles}).  (@pxref{Expiring Mail}).
@@ -10113,6 +10118,7 @@
 @item B e
 @kindex B e (Summary)
 @findex gnus-summary-expire-articles
+@cindex expiring mail
 Run all expirable articles in the current group through the expiry
 process (@code{gnus-summary-expire-articles}).  That is, delete all
 expirable articles in the group that have been around for a while.
@@ -10121,6 +10127,7 @@
 @item B C-M-e
 @kindex B C-M-e (Summary)
 @findex gnus-summary-expire-articles-now
+@cindex expiring mail
 Delete all the expirable articles in the group
 (@code{gnus-summary-expire-articles-now}).  This means that @strong{all}
 articles eligible for expiry in the current group will
@@ -14674,6 +14681,7 @@
 @node Expiring Mail
 @subsection Expiring Mail
 @cindex article expiry
+@cindex expiring mail
 
 Traditional mail readers have a tendency to remove mail articles when
 you mark them as read, in some way.  Gnus takes a fundamentally
@@ -16628,6 +16636,7 @@
 @item nnimap-expunge-search-string
 @cindex expunging
 @vindex nnimap-expunge-search-string
+@cindex expiring @acronym{IMAP} mail
 
 This variable contain the @acronym{IMAP} search command sent to server when
 searching for articles eligible for expiring.  The default is
@@ -16639,6 +16648,10 @@
 messages instead of the internal article date.  See section 6.4.4 of
 RFC 2060 for more information on valid strings.
 
+However, if @code{nnimap-search-uids-not-since-is-evil} 
+is true, the command is @code{"UID NOT SINCE @var{date}"},
+regardless of this variable.
+
 @item nnimap-authinfo-file
 @vindex nnimap-authinfo-file
 
@@ -16664,6 +16677,47 @@
 seem to need this under some circumstances; it was reported that
 Courier 1.7.1 did.
 
+@item nnimap-nov-is-evil
+@vindex nnimap-nov-is-evil
+@cindex Courier @acronym{IMAP} server
+@cindex @acronym{NOV}
+
+Never generate or use a local @acronym{NOV} database. Defaults to the
+value of @code{gnus-agent}.
+
+Using a @acronym{NOV} database usually makes header fetching much
+faster, but it uses the @code{UID SEARCH UID} command, which is very
+slow on some servers (notably some versions of Courier). Since the Gnus
+Agent caches the information in the @acronym{NOV} database without using
+the slow command, this variable defaults to true if the Agent is in use,
+and false otherwise.
+
+@item nnimap-search-uids-not-since-is-evil
+@vindex nnimap-search-uids-not-since-is-evil
+@cindex Courier @acronym{IMAP} server
+@cindex expiring @acronym{IMAP} mail
+
+Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE
+@var{date}} command, which is slow on some @acronym{IMAP} servers
+(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE
+@var{date}} and prune the list of expirable articles within Gnus.
+
+When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a
+list of expirable articles and asks the IMAP server questions like ``Of
+these articles, which ones are older than a week?'' While this seems
+like a perfectly reasonable question, some IMAP servers take a long time
+to answer it, since they seemingly go looking into every old article to
+see if it is one of the expirable ones. Curiously, the question ``Of
+@emph{all} articles, which ones are newer than a week?'' seems to be
+much faster to answer, so setting this variable causes Gnus to ask this
+question and figure out the answer to the real question itself.
+
+This problem can really sneak up on you: when you first configure Gnus,
+everything works fine, but once you accumulate a couple thousand
+messages, you start cursing Gnus for being so slow. On the other hand,
+if you get a lot of email within a week, setting this variable will
+cause a lot of network traffic between Gnus and the IMAP server.
+
 @end table
 
 @menu
@@ -16851,7 +16905,7 @@
 
 @node Expiring in IMAP
 @subsection Expiring in IMAP
-@cindex expiring imap mail
+@cindex expiring @acronym{IMAP} mail
 
 Even though @code{nnimap} is not a proper @code{nnmail} derived back
 end, it supports most features in regular expiring (@pxref{Expiring
@@ -16870,6 +16924,9 @@
 your server must support permanent storage of client specific flags on
 messages.  Most do, fortunately.
 
+If expiring @acronym{IMAP} mail seems very slow, try setting the server
+variable @code{nnimap-search-uids-not-since-is-evil}.
+
 @table @code
 
 @item nnmail-expiry-wait
@@ -19154,7 +19211,7 @@
 @findex gnus-agent-expire-group
 @cindex agent expiry
 @cindex Gnus agent expiry
-@cindex expiry
+@cindex expiry, in Gnus agent
 
 The Agent back end, @code{nnagent}, doesn't handle expiry.  Well, at
 least it doesn't handle it like other back ends.  Instead, there are

[-- Attachment #3: Type: text/plain, Size: 11 bytes --]


-- 
Jouni

Re: nnimap doc patch

[Reiner Steib]

[ Resent.  I already sent this yesterday, but it didn't appear on Gmane. ]

On Thu, Apr 06 2006, Jouni K Seppanen wrote:

> It seems that my doc patch from November
> <29hdb27qbn.fsf@itl-pc9.hut.fi> hasn't been applied. Was there some
> problem with it, or was it just forgotten?

If the content is correct (I'm not sure about the IMAP details: Could
someone review it, please?), we could install it now (Jouni has a
copyright assignment for Gnus on file).

AFAIKS, it should go to v5-10 as well as the trunk.

> -@cindex expiry-wait
> +@vindex expiry-wait
>  @vindex nnmail-expiry-wait-function
>  If the group parameter has an element that looks like
>  @code{(expiry-wait . 10)}, this value will override any
> @@ -2852,7 +2854,7 @@
>  symbols @code{never} or @code{immediate}.
>  
>  @item expiry-target
> -@cindex expiry-target
> +@vindex expiry-target

Shouldn't the variable index contain only variables?  `expiry-target'
is a group parameter.  I'm not sure about this.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: nnimap doc patch

[Lars Magne Ingebrigtsen]

Reiner Steib <reinersteib+gmane@imap.cc> writes:

> [ Resent.  I already sent this yesterday, but it didn't appear on Gmane. ]

(I'm wondering whether the ding mailing list is a bit flaky...)

>> -@cindex expiry-target
>> +@vindex expiry-target
>
> Shouldn't the variable index contain only variables?  `expiry-target'
> is a group parameter.  I'm not sure about this.

Yes, the variable index should only have variables.

-- 
(domestic pets only, the antidote for overdose, milk.)
  larsi@gnus.org * Lars Magne Ingebrigtsen

Re: nnimap doc patch

[Simon Josefsson]

Jouni K Seppanen <jks@iki.fi> writes:

> It seems that my doc patch from November
> <29hdb27qbn.fsf@itl-pc9.hut.fi> hasn't been applied. Was there some
> problem with it, or was it just forgotten?

The latter, sorry!  Could you send an updated patch with the (minor)
fixes below?  We should add it.

> -@cindex expiry-wait
> +@vindex expiry-wait

This is probably wrong, see the other e-mails.

> +However, if @code{nnimap-search-uids-not-since-is-evil} 
> +is true, the command is @code{"UID NOT SINCE @var{date}"},
> +regardless of this variable.

This seems backwards, if that variable is non-nil, the command is UID
SINCE @var{date}.  See the doc string:

nnimap-search-uids-not-since-is-evil is a variable defined in `nnimap.el'.
Its value is nil

Documentation:
If non-nil, avoid "UID SEARCH UID ... NOT SINCE" queries when expiring.
Instead, use "UID SEARCH SINCE" to prune the list of expirable
articles within Gnus.  This seems to be faster on Courier in some cases.

This is a Gnus server variable.  See Info node `(gnus)Select Methods'.

> +@item nnimap-nov-is-evil
> +@vindex nnimap-nov-is-evil
> +@cindex Courier @acronym{IMAP} server
> +@cindex @acronym{NOV}
> +
> +Never generate or use a local @acronym{NOV} database. Defaults to the
> +value of @code{gnus-agent}.
>
> +Using a @acronym{NOV} database usually makes header fetching much
> +faster, but it uses the @code{UID SEARCH UID} command, which is very
> +slow on some servers (notably some versions of Courier). Since the Gnus
> +Agent caches the information in the @acronym{NOV} database without using
> +the slow command, this variable defaults to true if the Agent is in use,
> +and false otherwise.

Seems good!

> +@item nnimap-search-uids-not-since-is-evil
> +@vindex nnimap-search-uids-not-since-is-evil
> +@cindex Courier @acronym{IMAP} server
> +@cindex expiring @acronym{IMAP} mail
> +
> +Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE
> +@var{date}} command, which is slow on some @acronym{IMAP} servers
> +(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE
> +@var{date}} and prune the list of expirable articles within Gnus.
> +
> +When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a
> +list of expirable articles and asks the IMAP server questions like ``Of
> +these articles, which ones are older than a week?'' While this seems
> +like a perfectly reasonable question, some IMAP servers take a long time
> +to answer it, since they seemingly go looking into every old article to
> +see if it is one of the expirable ones. Curiously, the question ``Of
> +@emph{all} articles, which ones are newer than a week?'' seems to be
> +much faster to answer, so setting this variable causes Gnus to ask this
> +question and figure out the answer to the real question itself.
> +
> +This problem can really sneak up on you: when you first configure Gnus,
> +everything works fine, but once you accumulate a couple thousand
> +messages, you start cursing Gnus for being so slow. On the other hand,
> +if you get a lot of email within a week, setting this variable will
> +cause a lot of network traffic between Gnus and the IMAP server.

Nice!