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

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}.
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
......@@ -15826,40 +15826,46 @@ don't really mix very well.
@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.
......@@ -140,10 +140,10 @@ rules as described later).")
: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
......
......@@ -159,32 +159,33 @@ If nil, groups like \"mail.misc\" will end up in directories like
(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.
......
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