Score File Format
=================
A score file is an `emacs-lisp' file that normally contains just a
single form. Casual users are not expected to edit these files;
everything can be changed from the summary buffer.
Anyway, if you'd like to dig into it yourself, here's an example:
(("from"
("Lars Ingebrigtsen" -10000)
("Per Abrahamsen")
("larsi\\|lmi" -50000 nil R))
("subject"
("Ding is Badd" nil 728373))
("xref"
("alt.politics" -1000 728372 s))
("lines"
(2 -100 nil <))
(mark 0)
(expunge -1000)
(mark-and-expunge -10)
(read-only nil)
(orphan -10)
(adapt t)
(files "/hom/larsi/News/gnu.SCORE")
(exclude-files "all.SCORE")
(local (gnus-newsgroup-auto-expire t)
(gnus-summary-make-false-root empty))
(eval (ding)))
This example demonstrates most score file elements. For a different
approach, see Note:Advanced Scoring.
Even though this looks much like lisp code, nothing here is actually
`eval'ed. The lisp reader is used to read this form, though, so it has
to be valid syntactically, if not semantically.
Six keys are supported by this alist:
`STRING'
If the key is a string, it is the name of the header to perform the
match on. Scoring can only be performed on these eight headers:
`From', `Subject', `References', `Message-ID', `Xref', `Lines',
`Chars' and `Date'. In addition to these headers, there are three
strings to tell Gnus to fetch the entire article and do the match
on larger parts of the article: `Body' will perform the match on
the body of the article, `Head' will perform the match on the head
of the article, and `All' will perform the match on the entire
article. Note that using any of these last three keys will slow
down group entry _considerably_. The final "header" you can score
on is `Followup'. These score entries will result in new score
entries being added for all follow-ups to articles that matches
these score entries.
Following this key is a arbitrary number of score entries, where
each score entry has one to four elements.
1. The first element is the "match element". On most headers
this will be a string, but on the Lines and Chars headers,
this must be an integer.
2. If the second element is present, it should be a number--the
"score element". This number should be an integer in the
neginf to posinf interval. This number is added to the score
of the article if the match is successful. If this element
is not present, the `gnus-score-interactive-default-score'
number will be used instead. This is 1000 by default.
3. If the third element is present, it should be a number--the
"date element". This date says when the last time this score
entry matched, which provides a mechanism for expiring the
score entries. It this element is not present, the score
entry is permanent. The date is represented by the number of
days since December 31, 1 BCE.
4. If the fourth element is present, it should be a symbol--the
"type element". This element specifies what function should
be used to see whether this score entry matches the article.
What match types that can be used depends on what header you
wish to perform the match on.
"From, Subject, References, Xref, Message-ID"
For most header types, there are the `r' and `R'
(regexp), as well as `s' and `S' (substring) types, and
`e' and `E' (exact match), and `w' (word match) types.
If this element is not present, Gnus will assume that
substring matching should be used. `R', `S', and `E'
differ from the others in that the matches will be done
in a case-sensitive manner. All these one-letter types
are really just abbreviations for the `regexp',
`string', `exact', and `word' types, which you can use
instead, if you feel like.
"Lines, Chars"
These two headers use different match types: `<', `>',
`=', `>=' and `<='.
These predicates are true if
(PREDICATE HEADER MATCH)
evaluates to non-`nil'. For instance, the advanced match
`("lines" 4 <)' (Note:Advanced Scoring) will result
in the following form:
(< header-value 4)
Or to put it another way: When using `<' on `Lines' with
4 as the match, we get the score added if the article
has less than 4 lines. (It's easy to get confused and
think it's the other way around. But it's not. I
think.)
When matching on `Lines', be careful because some back
ends (like `nndir') do not generate `Lines' header, so
every article ends up being marked as having 0 lines.
This can lead to strange results if you happen to lower
score of the articles with few lines.
"Date"
For the Date header we have three kinda silly match
types: `before', `at' and `after'. I can't really
imagine this ever being useful, but, like, it would feel
kinda silly not to provide this function. Just in case.
You never know. Better safe than sorry. Once burnt,
twice shy. Don't judge a book by its cover. Never not
have sex on a first date. (I have been told that at
least one person, and I quote, "found this function
indispensable", however.)
A more useful match type is `regexp'. With it, you can
match the date string using a regular expression. The
date is normalized to ISO8601 compact format
first--YYYYMMDD`T'HHMMSS. If you want to match all
articles that have been posted on April 1st in every
year, you could use `....0401.........' as a match
string, for instance. (Note that the date is kept in
its original time zone, so this will match articles that
were posted when it was April 1st where the article was
posted from. Time zones are such wholesome fun for the
whole family, eh?)
"Head, Body, All"
These three match keys use the same match types as the
`From' (etc) header uses.
"Followup"
This match key is somewhat special, in that it will
match the `From' header, and affect the score of not
only the matching articles, but also all followups to
the matching articles. This allows you e.g. increase
the score of followups to your own articles, or decrease
the score of followups to the articles of some known
trouble-maker. Uses the same match types as the `From'
header uses. (Using this match key will lead to
creation of `ADAPT' files.)
"Thread"
This match key works along the same lines as the
`Followup' match key. If you say that you want to score
on a (sub-)thread started by an article with a
`Message-ID' X, then you add a `thread' match. This
will add a new `thread' match for each article that has
X in its `References' header. (These new `thread'
matches will use the `Message-ID's of these matching
articles.) This will ensure that you can raise/lower
the score of an entire thread, even though some articles
in the thread may not have complete `References'
headers. Note that using this may lead to
undeterministic scores of the articles in the thread.
(Using this match key will lead to creation of `ADAPT'
files.)
`mark'
The value of this entry should be a number. Any articles with a
score lower than this number will be marked as read.
`expunge'
The value of this entry should be a number. Any articles with a
score lower than this number will be removed from the summary
buffer.
`mark-and-expunge'
The value of this entry should be a number. Any articles with a
score lower than this number will be marked as read and removed
from the summary buffer.
`thread-mark-and-expunge'
The value of this entry should be a number. All articles that
belong to a thread that has a total score below this number will
be marked as read and removed from the summary buffer.
`gnus-thread-score-function' says how to compute the total score
for a thread.
`files'
The value of this entry should be any number of file names. These
files are assumed to be score files as well, and will be loaded
the same way this one was.
`exclude-files'
The clue of this entry should be any number of files. These files
will not be loaded, even though they would normally be so, for
some reason or other.
`eval'
The value of this entry will be `eval'el. This element will be
ignored when handling global score files.
`read-only'
Read-only score files will not be updated or saved. Global score
files should feature this atom (Note:Global Score Files).
(Note: "Global" here really means "global"; not your personal
apply-to-all-groups score files.)
`orphan'
The value of this entry should be a number. Articles that do not
have parents will get this number added to their scores. Imagine
you follow some high-volume newsgroup, like `comp.lang.c'. Most
likely you will only follow a few of the threads, also want to see
any new threads.
You can do this with the following two score file entries:
(orphan -500)
(mark-and-expunge -100)
When you enter the group the first time, you will only see the new
threads. You then raise the score of the threads that you find
interesting (with `I T' or `I S'), and ignore (`C y') the rest.
Next time you enter the group, you will see new articles in the
interesting threads, plus any new threads.
I.e.--the orphan score atom is for high-volume groups where there
exist a few interesting threads which can't be found automatically
by ordinary scoring rules.
`adapt'
This entry controls the adaptive scoring. If it is `t', the
default adaptive scoring rules will be used. If it is `ignore', no
adaptive scoring will be performed on this group. If it is a
list, this list will be used as the adaptive scoring rules. If it
isn't present, or is something other than `t' or `ignore', the
default adaptive scoring rules will be used. If you want to use
adaptive scoring on most groups, you'd set
`gnus-use-adaptive-scoring' to `t', and insert an `(adapt ignore)'
in the groups where you do not want adaptive scoring. If you only
want adaptive scoring in a few groups, you'd set
`gnus-use-adaptive-scoring' to `nil', and insert `(adapt t)' in
the score files of the groups where you want it.
`adapt-file'
All adaptive score entries will go to the file named by this
entry. It will also be applied when entering the group. This
atom might be handy if you want to adapt on several groups at
once, using the same adaptive file for a number of groups.
`local'
The value of this entry should be a list of `(VAR VALUE)' pairs.
Each VAR will be made buffer-local to the current summary buffer,
and set to the value specified. This is a convenient, if somewhat
strange, way of setting variables in some groups if you don't like
hooks much. Note that the VALUE won't be evaluated.