gnus: Category Syntax
6.9.2.1 Category Syntax
.......................
A category consists of a name, the list of groups belonging to the
category, and a number of optional parameters that override the
customizable variables. The complete list of agent parameters are
listed below.
‘agent-groups’
The list of groups that are in this category.
‘agent-predicate’
A predicate which (generally) gives a rough outline of which
articles are eligible for downloading; and
‘agent-score’
a score rule which (generally) gives you a finer granularity when
deciding what articles to download. (Note that this “download
score” is not necessarily related to normal scores.)
‘agent-enable-expiration’
a boolean indicating whether the agent should expire old articles
in this group. Most groups should be expired to conserve disk
space. In fact, its probably safe to say that the gnus.* hierarchy
contains the only groups that should not be expired.
‘agent-days-until-old’
an integer indicating the number of days that the agent should wait
before deciding that a read article is safe to expire.
‘agent-low-score’
an integer that overrides the value of ‘gnus-agent-low-score’.
‘agent-high-score’
an integer that overrides the value of ‘gnus-agent-high-score’.
‘agent-short-article’
an integer that overrides the value of ‘gnus-agent-short-article’.
‘agent-long-article’
an integer that overrides the value of ‘gnus-agent-long-article’.
‘agent-enable-undownloaded-faces’
a symbol indicating whether the summary buffer should display
undownloaded articles using the ‘gnus-summary-*-undownloaded-face’
faces. Any symbol other than ‘nil’ will enable the use of
undownloaded faces.
The name of a category can not be changed once the category has been
created.
Each category maintains a list of groups that are exclusive members
of that category. The exclusivity rule is automatically enforced, add a
group to a new category and it is automatically removed from its old
category.
A predicate in its simplest form can be a single predicate such as
‘true’ or ‘false’. These two will download every available article or
nothing respectively. In the case of these two special predicates an
additional score rule is superfluous.
Predicates of ‘high’ or ‘low’ download articles in respect of their
scores in relationship to ‘gnus-agent-high-score’ and
‘gnus-agent-low-score’ as described below.
To gain even finer control of what is to be regarded eligible for
download a predicate can consist of a number of predicates with logical
operators sprinkled in between.
Perhaps some examples are in order.
Here’s a simple predicate. (It’s the default predicate, in fact,
used for all groups that don’t belong to any other category.)
short
Quite simple, eh? This predicate is true if and only if the article
is short (for some value of “short”).
Here’s a more complex predicate:
(or high
(and
(not low)
(not long)))
This means that an article should be downloaded if it has a high
score, or if the score is not low and the article is not long. You get
the drift.
The available logical operators are ‘or’, ‘and’ and ‘not’. (If you
prefer, you can use the more “C”-ish operators ‘|’, ‘&’ and ‘!’
instead.)
The following predicates are pre-defined, but if none of these fit
what you want to do, you can write your own.
When evaluating each of these predicates, the named constant will be
bound to the value determined by calling ‘gnus-agent-find-parameter’ on
the appropriate parameter. For example, gnus-agent-short-article will
be bound to ‘(gnus-agent-find-parameter group 'agent-short-article)’.
This means that you can specify a predicate in your category then tune
that predicate to individual groups.
‘short’
True if the article is shorter than ‘gnus-agent-short-article’
lines; default 100.
‘long’
True if the article is longer than ‘gnus-agent-long-article’ lines;
default 200.
‘low’
True if the article has a download score less than
‘gnus-agent-low-score’; default 0.
‘high’
True if the article has a download score greater than
‘gnus-agent-high-score’; default 0.
‘spam’
True if the Gnus Agent guesses that the article is spam. The
heuristics may change over time, but at present it just computes a
checksum and sees whether articles match.
‘true’
Always true.
‘false’
Always false.
If you want to create your own predicate function, here’s what you
have to know: The functions are called with no parameters, but the
‘gnus-headers’ and ‘gnus-score’ dynamic variables are bound to useful
values.
For example, you could decide that you don’t want to download
articles that were posted more than a certain number of days ago (e.g.,
posted more than ‘gnus-agent-expire-days’ ago) you might write a
function something along the lines of the following:
(defun my-article-old-p ()
"Say whether an article is old."
(< (time-to-days (date-to-time (mail-header-date gnus-headers)))
(- (time-to-days (current-time)) gnus-agent-expire-days)))
with the predicate then defined as:
(not my-article-old-p)
or you could append your predicate to the predefined
‘gnus-category-predicate-alist’ in your ‘~/.gnus.el’ or wherever.
(require 'gnus-agent)
(setq gnus-category-predicate-alist
(append gnus-category-predicate-alist
'((old . my-article-old-p))))
and simply specify your predicate as:
(not old)
If/when using something like the above, be aware that there are many
misconfigured systems/mailers out there and so an article’s date is not
always a reliable indication of when it was posted. Hell, some people
just don’t give a damn.
The above predicates apply to _all_ the groups which belong to the
category. However, if you wish to have a specific predicate for an
individual group within a category, or you’re just too lazy to set up a
new category, you can enter a group’s individual predicate in its group
parameters like so:
(agent-predicate . short)
This is the group/topic parameter equivalent of the agent category
default. Note that when specifying a single word predicate like this,
the ‘agent-predicate’ specification must be in dotted pair notation.
The equivalent of the longer example from above would be:
(agent-predicate or high (and (not low) (not long)))
The outer parenthesis required in the category specification are not
entered here as, not being in dotted pair notation, the value of the
predicate is assumed to be a list.
Now, the syntax of the download score is the same as the syntax of
normal score files, except that all elements that require actually
seeing the article itself are verboten. This means that only the
following headers can be scored on: ‘Subject’, ‘From’, ‘Date’,
‘Message-ID’, ‘References’, ‘Chars’, ‘Lines’, and ‘Xref’.
As with predicates, the specification of the ‘download score rule’ to
use in respect of a group can be in either the category definition if
it’s to be applicable to all groups in therein, or a group’s parameters
if it’s to be specific to that group.
In both of these places the ‘download score rule’ can take one of
three forms:
1. Score rule
This has the same syntax as a normal Gnus score file except only a
subset of scoring keywords are available as mentioned above.
example:
• Category specification
(("from"
("Lars Ingebrigtsen" 1000000 nil s))
("lines"
(500 -100 nil <)))
• Group/Topic Parameter specification
(agent-score ("from"
("Lars Ingebrigtsen" 1000000 nil s))
("lines"
(500 -100 nil <)))
Again, note the omission of the outermost parenthesis here.
2. Agent score file
These score files must _only_ contain the permitted scoring
keywords stated above.
example:
• Category specification
("~/News/agent.SCORE")
or perhaps
("~/News/agent.SCORE" "~/News/agent.group.SCORE")
• Group Parameter specification
(agent-score "~/News/agent.SCORE")
Additional score files can be specified as above. Need I say
anything about parenthesis?
3. Use ‘normal’ score files
If you don’t want to maintain two sets of scoring rules for a
group, and your desired ‘downloading’ criteria for a group are the
same as your ‘reading’ criteria then you can tell the agent to
refer to your ‘normal’ score files when deciding what to download.
These directives in either the category definition or a group’s
parameters will cause the agent to read in all the applicable score
files for a group, _filtering out_ those sections that do not
relate to one of the permitted subset of scoring keywords.
• Category Specification
file
• Group Parameter specification
(agent-score . file)
Info Catalog
gnus: Agent Categories
gnus: Category Buffer