From d0a0d10fff7e1310be63cc832ea6bcc7a0ff6784 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Fri, 2 Aug 2019 15:54:09 +0300 Subject: [PATCH] Fix nnmail-expiry-wait docs and custom :types * doc/misc/gnus.texi (Group Parameters, Expiring Mail): * lisp/gnus/gnus-cus.el (gnus-group-parameters): Clarify descriptions of nnmail-expiry, nnmail-expiry-wait, and nnmail-expiry-wait-function. * lisp/gnus/nnmail.el (nnmail-expiry-wait) (nnmail-expiry-wait-function): Clarify docstrings and fix custom :types (bug#36850). --- doc/misc/gnus.texi | 50 ++++++++++++++++++++++++------------------- lisp/gnus/gnus-cus.el | 8 +++---- lisp/gnus/nnmail.el | 35 +++++++++++++++--------------- 3 files changed, 50 insertions(+), 43 deletions(-) diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index dcba47aca0..32d98abd7e 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -2916,9 +2916,9 @@ Group Parameters If the group parameter has an element that looks like @code{(expiry-wait . 10)}, this value will override any @code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function} -(@pxref{Expiring Mail}) when expiring expirable messages. The value -can either be a number of days (not necessarily an integer) or the -symbols @code{never} or @code{immediate}. +settings (@pxref{Expiring Mail}) when expiring expirable messages. +The value can be either a number of days (not necessarily an integer), +or one of the symbols @code{never} or @code{immediate}. @item expiry-target @cindex expiry-target @@ -15878,40 +15878,46 @@ Expiring Mail @vindex nnmail-expiry-wait The @code{nnmail-expiry-wait} variable supplies the default time an -expirable article has to live. Gnus starts counting days from when the -message @emph{arrived}, not from when it was sent. The default is seven -days. +expirable article has to live. The value of this variable can be +either a number of days (not necessarily an integer), or one of the +symbols @code{immediate} or @code{never}, meaning an article is +immediately or never expirable, respectively. -Gnus also supplies a function that lets you fine-tune how long articles -are to live, based on what group they are in. Let's say you want to -have one month expiry period in the @samp{mail.private} group, a one day -expiry period in the @samp{mail.junk} group, and a six day expiry period -everywhere else: +Gnus starts counting days from when the message @emph{arrived}, not +from when it was sent. The default is seven days. @vindex nnmail-expiry-wait-function +The @code{nnmail-expiry-wait-function} variable lets you fine-tune how +long articles are to live, based on what group they are in. When set +to a function, its returned value, if non-@code{nil}, overrides that +of @code{nnmail-expiry-wait}. Otherwise, the value of +@code{nnmail-expiry-wait} is used instead. + +For example, let's say you want to have a one month expiry period in +the @samp{mail.private} group, a one day expiry period in the +@samp{mail.junk} group, and a six day expiry period everywhere else. +This can be achieved as follows: + @lisp (setq nnmail-expiry-wait-function (lambda (group) - (cond ((string= group "mail.private") + (cond ((string= group "mail.private") 31) - ((string= group "mail.junk") + ((string= group "mail.junk") 1) - ((string= group "important") + ((string= group "important") 'never) - (t + (t 6)))) @end lisp The group names this function is fed are ``unadorned'' group names---no @samp{nnml:} prefixes and the like. -The @code{nnmail-expiry-wait} variable and -@code{nnmail-expiry-wait-function} function can either be a number (not -necessarily an integer) or one of the symbols @code{immediate} or -@code{never}. - -You can also use the @code{expiry-wait} group parameter to selectively -change the expiry period (@pxref{Group Parameters}). +As an alternative to the variables @code{nnmail-expiry-wait} or +@code{nnmail-expiry-wait-function}, you can also use the +@code{expiry-wait} group parameter to selectively change the expiry +period (@pxref{Group Parameters}). @vindex nnmail-expiry-target The normal action taken when expiring articles is to delete them. diff --git a/lisp/gnus/gnus-cus.el b/lisp/gnus/gnus-cus.el index fb8b300e35..574b0c6913 100644 --- a/lisp/gnus/gnus-cus.el +++ b/lisp/gnus/gnus-cus.el @@ -140,10 +140,10 @@ gnus-group-parameters :format "%v")) "\ When to expire. -Overrides any `nnmail-expiry-wait' and `nnmail-expiry-wait-function' -when expiring expirable messages. The value can either be a number of -days (not necessarily an integer) or the symbols `never' or -`immediate'.") +Overrides any `nnmail-expiry-wait' or `nnmail-expiry-wait-function' +settings when expiring expirable messages. The value can be +either a number of days (not necessarily an integer), or one of +the symbols `never' or `immediate'.") (expiry-target (choice :tag "Expiry Target" :value delete diff --git a/lisp/gnus/nnmail.el b/lisp/gnus/nnmail.el index 0699e81812..f8248b0190 100644 --- a/lisp/gnus/nnmail.el +++ b/lisp/gnus/nnmail.el @@ -157,32 +157,33 @@ nnmail-default-file-modes (defcustom nnmail-expiry-wait 7 "Expirable articles that are older than this will be expired. -This variable can either be a number (which will be interpreted as a -number of days) -- this doesn't have to be an integer. This variable -can also be `immediate' and `never'." +This variable can be either a number of days (not necessarily an +integer), or one of the symbols `immediate' or `never', meaning +an article is immediately or never expirable, respectively. +For more granular control, see `nnmail-expiry-wait-function'." :group 'nnmail-expire - :type '(choice (const immediate) - (number :tag "days") - (const never))) + :type '(choice (const :tag "Immediate" immediate) + (const :tag "Never" never) + (number :tag "Days"))) (defcustom nnmail-expiry-wait-function nil - "Variable that holds function to specify how old articles should be before they are expired. -The function will be called with the name of the group that the expiry -is to be performed in, and it should return an integer that says how -many days an article can be stored before it is considered \"old\". -It can also return the values `never' and `immediate'. + "Function to determine how old articles should be before they are expired. +The function is called with the name of the group that the expiry +is to be performed in, and should return a value supported by +`nnmail-expiry-wait', which it overrides. If this variable is +nil, the value of `nnmail-expiry-wait' is used instead. E.g.: \(setq nnmail-expiry-wait-function - (lambda (newsgroup) - (cond ((string-match \"private\" newsgroup) 31) - ((string-match \"junk\" newsgroup) 1) - ((string-match \"important\" newsgroup) \\='never) - (t 7))))" + (lambda (group) + (cond ((string-match-p \"private\" group) 31) + ((string-match-p \"junk\" group) 1) + ((string-match-p \"important\" group) \\='never) + (t 7))))" :group 'nnmail-expire :type '(choice (const :tag "nnmail-expiry-wait" nil) - (function :format "%v" nnmail-))) + (function :tag "Custom function"))) (defcustom nnmail-expiry-target 'delete "Variable that says where expired messages should end up. -- 2.20.1