Commit e7818cb7 authored by Basil L. Contovounesios's avatar Basil L. Contovounesios
Browse files

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).
parent 8b7c7762
Pipeline #2727 failed with stage
in 28 minutes and 14 seconds
...@@ -2917,9 +2917,9 @@ See also @code{gnus-total-expirable-newsgroups}. ...@@ -2917,9 +2917,9 @@ See also @code{gnus-total-expirable-newsgroups}.
If the group parameter has an element that looks like If the group parameter has an element that looks like
@code{(expiry-wait . 10)}, this value will override any @code{(expiry-wait . 10)}, this value will override any
@code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function} @code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function}
(@pxref{Expiring Mail}) when expiring expirable messages. The value settings (@pxref{Expiring Mail}) when expiring expirable messages.
can either be a number of days (not necessarily an integer) or the The value can be either a number of days (not necessarily an integer),
symbols @code{never} or @code{immediate}. or one of the symbols @code{never} or @code{immediate}.
   
@item expiry-target @item expiry-target
@cindex expiry-target @cindex expiry-target
...@@ -15826,40 +15826,46 @@ don't really mix very well. ...@@ -15826,40 +15826,46 @@ don't really mix very well.
   
@vindex nnmail-expiry-wait @vindex nnmail-expiry-wait
The @code{nnmail-expiry-wait} variable supplies the default time an The @code{nnmail-expiry-wait} variable supplies the default time an
expirable article has to live. Gnus starts counting days from when the expirable article has to live. The value of this variable can be
message @emph{arrived}, not from when it was sent. The default is seven either a number of days (not necessarily an integer), or one of the
days. 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 Gnus starts counting days from when the message @emph{arrived}, not
are to live, based on what group they are in. Let's say you want to from when it was sent. The default is seven days.
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:
   
@vindex nnmail-expiry-wait-function @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 @lisp
(setq nnmail-expiry-wait-function (setq nnmail-expiry-wait-function
(lambda (group) (lambda (group)
(cond ((string= group "mail.private") (cond ((string= group "mail.private")
31) 31)
((string= group "mail.junk") ((string= group "mail.junk")
1) 1)
((string= group "important") ((string= group "important")
'never) 'never)
(t (t
6)))) 6))))
@end lisp @end lisp
   
The group names this function is fed are ``unadorned'' group The group names this function is fed are ``unadorned'' group
names---no @samp{nnml:} prefixes and the like. names---no @samp{nnml:} prefixes and the like.
   
The @code{nnmail-expiry-wait} variable and As an alternative to the variables @code{nnmail-expiry-wait} or
@code{nnmail-expiry-wait-function} function can either be a number (not @code{nnmail-expiry-wait-function}, you can also use the
necessarily an integer) or one of the symbols @code{immediate} or @code{expiry-wait} group parameter to selectively change the expiry
@code{never}. period (@pxref{Group Parameters}).
You can also use the @code{expiry-wait} group parameter to selectively
change the expiry period (@pxref{Group Parameters}).
   
@vindex nnmail-expiry-target @vindex nnmail-expiry-target
The normal action taken when expiring articles is to delete them. The normal action taken when expiring articles is to delete them.
...@@ -140,10 +140,10 @@ rules as described later).") ...@@ -140,10 +140,10 @@ rules as described later).")
:format "%v")) "\ :format "%v")) "\
When to expire. When to expire.
Overrides any `nnmail-expiry-wait' and `nnmail-expiry-wait-function' Overrides any `nnmail-expiry-wait' or `nnmail-expiry-wait-function'
when expiring expirable messages. The value can either be a number of settings when expiring expirable messages. The value can be
days (not necessarily an integer) or the symbols `never' or either a number of days (not necessarily an integer), or one of
`immediate'.") the symbols `never' or `immediate'.")
(expiry-target (choice :tag "Expiry Target" (expiry-target (choice :tag "Expiry Target"
:value delete :value delete
......
...@@ -159,32 +159,33 @@ If nil, groups like \"mail.misc\" will end up in directories like ...@@ -159,32 +159,33 @@ If nil, groups like \"mail.misc\" will end up in directories like
(defcustom nnmail-expiry-wait 7 (defcustom nnmail-expiry-wait 7
"Expirable articles that are older than this will be expired. "Expirable articles that are older than this will be expired.
This variable can either be a number (which will be interpreted as a This variable can be either a number of days (not necessarily an
number of days) -- this doesn't have to be an integer. This variable integer), or one of the symbols `immediate' or `never', meaning
can also be `immediate' and `never'." an article is immediately or never expirable, respectively.
For more granular control, see `nnmail-expiry-wait-function'."
:group 'nnmail-expire :group 'nnmail-expire
:type '(choice (const immediate) :type '(choice (const :tag "Immediate" immediate)
(number :tag "days") (const :tag "Never" never)
(const never))) (number :tag "Days")))
(defcustom nnmail-expiry-wait-function nil (defcustom nnmail-expiry-wait-function nil
"Variable that holds function to specify how old articles should be before they are expired. "Function to determine how old articles should be before they are expired.
The function will be called with the name of the group that the expiry The function is called with the name of the group that the expiry
is to be performed in, and it should return an integer that says how is to be performed in, and should return a value supported by
many days an article can be stored before it is considered \"old\". `nnmail-expiry-wait', which it overrides. If this variable is
It can also return the values `never' and `immediate'. nil, the value of `nnmail-expiry-wait' is used instead.
E.g.: E.g.:
\(setq nnmail-expiry-wait-function \(setq nnmail-expiry-wait-function
(lambda (newsgroup) (lambda (group)
(cond ((string-match \"private\" newsgroup) 31) (cond ((string-match-p \"private\" group) 31)
((string-match \"junk\" newsgroup) 1) ((string-match-p \"junk\" group) 1)
((string-match \"important\" newsgroup) \\='never) ((string-match-p \"important\" group) \\='never)
(t 7))))" (t 7))))"
:group 'nnmail-expire :group 'nnmail-expire
:type '(choice (const :tag "nnmail-expiry-wait" nil) :type '(choice (const :tag "nnmail-expiry-wait" nil)
(function :format "%v" nnmail-))) (function :tag "Custom function")))
(defcustom nnmail-expiry-target 'delete (defcustom nnmail-expiry-target 'delete
"Variable that says where expired messages should end up. "Variable that says where expired messages should end up.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment