This is ../info/gnus, produced by makeinfo version 4.0 from gnus.texi.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Gnus: (gnus). The newsreader Gnus.
END-INFO-DIR-ENTRY
This file documents Gnus, the GNU Emacs newsreader.
Copyright (C) 1995,96,97,98,99,2000,2001 Free Software Foundation,
Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being none, with the Front-Cover texts being "A GNU
Manual", and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled "GNU Free Documentation
License" in the Emacs manual.
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
File: gnus, Node: Agent Basics, Next: Agent Categories, Up: Gnus Unplugged
Agent Basics
------------
First, let's get some terminology out of the way.
The Gnus Agent is said to be "unplugged" when you have severed the
connection to the net (and notified the Agent that this is the case).
When the connection to the net is up again (and Gnus knows this), the
Agent is "plugged".
The "local" machine is the one you're running on, and which isn't
connected to the net continuously.
"Downloading" means fetching things from the net to your local
machine. "Uploading" is doing the opposite.
Let's take a typical Gnus session using the Agent.
* You start Gnus with `gnus-unplugged'. This brings up the Gnus
Agent in a disconnected state. You can read all the news that you
have already fetched while in this mode.
* You then decide to see whether any new news has arrived. You
connect your machine to the net (using PPP or whatever), and then
hit `J j' to make Gnus become "plugged" and use `g' to check for
new mail as usual. To check for new mail in unplugged mode, see
(*note Mail Source Specifiers::).
* You can then read the new news immediately, or you can download
the news onto your local machine. If you want to do the latter,
you press `g' to check if there are any new news and then `J s' to
fetch all the eligible articles in all the groups. (To let Gnus
know which articles you want to download, *note Agent
Categories::.)
* After fetching the articles, you press `J j' to make Gnus become
unplugged again, and you shut down the PPP thing (or whatever).
And then you read the news offline.
* And then you go to step 2.
Here are some things you should do the first time (or so) that you
use the Agent.
* Decide which servers should be covered by the Agent. If you have
a mail back end, it would probably be nonsensical to have it
covered by the Agent. Go to the server buffer (`^' in the group
buffer) and press `J a' the server (or servers) that you wish to
have covered by the Agent (*note Server Agent Commands::). This
will typically be only the primary select method, which is listed
on the bottom in the buffer.
* Decide on download policy. *Note Agent Categories::.
* Uhm... that's it.
File: gnus, Node: Agent Categories, Next: Agent Commands, Prev: Agent Basics, Up: Gnus Unplugged
Agent Categories
----------------
One of the main reasons to integrate the news transport layer into
the newsreader is to allow greater control over what articles to
download. There's not much point in downloading huge amounts of
articles, just to find out that you're not interested in reading any of
them. It's better to be somewhat more conservative in choosing what to
download, and then mark the articles for downloading manually if it
should turn out that you're interested in the articles anyway.
The main way to control what is to be downloaded is to create a
"category" and then assign some (or all) groups to this category.
Groups that do not belong in any other category belong to the `default'
category. Gnus has its own buffer for creating and managing categories.
* Menu:
* Category Syntax:: What a category looks like.
* The Category Buffer:: A buffer for maintaining categories.
* Category Variables:: Customize'r'Us.
File: gnus, Node: Category Syntax, Next: The Category Buffer, Up: Agent Categories
Category Syntax
...............
A category consists of two things.
1. A predicate which (generally) gives a rough outline of which
articles are eligible for downloading; and
2. 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.)
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.
`short'
True iff the article is shorter than `gnus-agent-short-article'
lines; default 100.
`long'
True iff the article is longer than `gnus-agent-long-article'
lines; default 200.
`low'
True iff the article has a download score less than
`gnus-agent-low-score'; default 0.
`high'
True iff the article has a download score greater than
`gnus-agent-high-score'; default 0.
`spam'
True iff 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.
(Note: this would have to be at a point *after* `gnus-agent' has been
loaded via `(gnus-agentize)')
(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 it's group
parameters like so:
(agent-predicate . short)
This is the group 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 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)
File: gnus, Node: The Category Buffer, Next: Category Variables, Prev: Category Syntax, Up: Agent Categories
The Category Buffer
...................
You'd normally do all category maintenance from the category buffer.
When you enter it for the first time (with the `J c' command from the
group buffer), you'll only see the `default' category.
The following commands are available in this buffer:
`q'
Return to the group buffer (`gnus-category-exit').
`k'
Kill the current category (`gnus-category-kill').
`c'
Copy the current category (`gnus-category-copy').
`a'
Add a new category (`gnus-category-add').
`p'
Edit the predicate of the current category
(`gnus-category-edit-predicate').
`g'
Edit the list of groups belonging to the current category
(`gnus-category-edit-groups').
`s'
Edit the download score rule of the current category
(`gnus-category-edit-score').
`l'
List all the categories (`gnus-category-list').
File: gnus, Node: Category Variables, Prev: The Category Buffer, Up: Agent Categories
Category Variables
..................
`gnus-category-mode-hook'
Hook run in category buffers.
`gnus-category-line-format'
Format of the lines in the category buffer (*note Formatting
Variables::). Valid elements are:
`c'
The name of the category.
`g'
The number of groups in the category.
`gnus-category-mode-line-format'
Format of the category mode line (*note Mode Line Formatting::).
`gnus-agent-short-article'
Articles that have fewer lines than this are short. Default 100.
`gnus-agent-long-article'
Articles that have more lines than this are long. Default 200.
`gnus-agent-low-score'
Articles that have a score lower than this have a low score.
Default 0.
`gnus-agent-high-score'
Articles that have a score higher than this have a high score.
Default 0.
File: gnus, Node: Agent Commands, Next: Agent Expiry, Prev: Agent Categories, Up: Gnus Unplugged
Agent Commands
--------------
All the Gnus Agent commands are on the `J' submap. The `J j'
(`gnus-agent-toggle-plugged' command works in all modes, and toggles
the plugged/unplugged state of the Gnus Agent.
* Menu:
* Group Agent Commands::
* Summary Agent Commands::
* Server Agent Commands::
You can run a complete batch fetch from the command line with the
following incantation:
$ emacs -batch -l ~/.gnus.el -f gnus-agent-batch-fetch
File: gnus, Node: Group Agent Commands, Next: Summary Agent Commands, Up: Agent Commands
Group Agent Commands
....................
`J u'
Fetch all eligible articles in the current group
(`gnus-agent-fetch-groups').
`J c'
Enter the Agent category buffer (`gnus-enter-category-buffer').
`J s'
Fetch all eligible articles in all groups
(`gnus-agent-fetch-session').
`J S'
Send all sendable messages in the draft group
(`gnus-group-send-drafts'). *Note Drafts::.
`J a'
Add the current group to an Agent category
(`gnus-agent-add-group'). This command understands the
process/prefix convention (*note Process/Prefix::).
`J r'
Remove the current group from its category, if any
(`gnus-agent-remove-group'). This command understands the
process/prefix convention (*note Process/Prefix::).
`J Y'
Synchronize flags changed while unplugged with remote server, if
any.
File: gnus, Node: Summary Agent Commands, Next: Server Agent Commands, Prev: Group Agent Commands, Up: Agent Commands
Summary Agent Commands
......................
`J #'
Mark the article for downloading (`gnus-agent-mark-article').
`J M-#'
Remove the downloading mark from the article
(`gnus-agent-unmark-article').
`@'
Toggle whether to download the article (`gnus-agent-toggle-mark').
`J c'
Mark all undownloaded articles as read (`gnus-agent-catchup').
File: gnus, Node: Server Agent Commands, Prev: Summary Agent Commands, Up: Agent Commands
Server Agent Commands
.....................
`J a'
Add the current server to the list of servers covered by the Gnus
Agent (`gnus-agent-add-server').
`J r'
Remove the current server from the list of servers covered by the
Gnus Agent (`gnus-agent-remove-server').
File: gnus, Node: Agent Expiry, Next: Agent and IMAP, Prev: Agent Commands, Up: Gnus Unplugged
Agent Expiry
------------
`nnagent' doesn't handle expiry. Instead, there's a special
`gnus-agent-expire' command that will expire all read articles that are
older than `gnus-agent-expire-days' days. It can be run whenever you
feel that you're running out of space. It's not particularly fast or
efficient, and it's not a particularly good idea to interrupt it (with
`C-g' or anything else) once you've started it.
if `gnus-agent-expire-all' is non-`nil', this command will expire
all articles--unread, read, ticked and dormant. If `nil' (which is the
default), only read articles are eligible for expiry, and unread,
ticked and dormant articles will be kept indefinitely.
File: gnus, Node: Agent and IMAP, Next: Outgoing Messages, Prev: Agent Expiry, Up: Gnus Unplugged
Agent and IMAP
--------------
The Agent work with any Gnus back end, including nnimap. However,
since there are some conceptual differences between NNTP and IMAP, this
section (should) provide you with some information to make Gnus Agent
work smoother as a IMAP Disconnected Mode client.
The first thing to keep in mind is that all flags (read, ticked, etc)
are kept on the IMAP server, rather than in `.newsrc' as is the case
for nntp. Thus Gnus need to remember flag changes when disconnected,
and synchronize these flags when you plug back in.
Gnus keep track of flag changes when reading nnimap groups under the
Agent by default. When you plug back in, by default Gnus will check if
you have any changed any flags and ask if you wish to synchronize these
with the server. This behavior is customizable with
`gnus-agent-synchronize-flags'.
If `gnus-agent-synchronize-flags' is `nil', the Agent will never
automatically synchronize flags. If it is `ask', the default, the
Agent will check if you made any changes and if so ask if you wish to
synchronize these when you re-connect. If it has any other value, all
flags will be synchronized automatically.
If you do not wish to automatically synchronize flags when you
re-connect, this can be done manually with the
`gnus-agent-synchronize-flags' command that is bound to `J Y' in the
group buffer by default.
Some things are currently not implemented in the Agent that you'd
might expect from a disconnected IMAP client, including:
* Copying/moving articles into nnimap groups when unplugged.
* Creating/deleting nnimap groups when unplugged.
Technical note: the synchronization algorithm does not work by
"pushing" all local flags to the server, but rather incrementally
update the server view of flags by changing only those flags that were
changed by the user. Thus, if you set one flag on a article, quit the
group and re-select the group and remove the flag; the flag will be set
and removed from the server when you "synchronize". The queued flag
operations can be found in the per-server `flags' file in the Agent
directory. It's emptied when you synchronize flags.
File: gnus, Node: Outgoing Messages, Next: Agent Variables, Prev: Agent and IMAP, Up: Gnus Unplugged
Outgoing Messages
-----------------
When Gnus is unplugged, all outgoing messages (both mail and news)
are stored in the draft groups (*note Drafts::). You can view them
there after posting, and edit them at will.
When Gnus is plugged again, you can send the messages either from the
draft group with the special commands available there, or you can use
the `J S' command in the group buffer to send all the sendable messages
in the draft group.
File: gnus, Node: Agent Variables, Next: Example Setup, Prev: Outgoing Messages, Up: Gnus Unplugged
Agent Variables
---------------
`gnus-agent-directory'
Where the Gnus Agent will store its files. The default is
`~/News/agent/'.
`gnus-agent-handle-level'
Groups on levels (*note Group Levels::) higher than this variable
will be ignored by the Agent. The default is
`gnus-level-subscribed', which means that only subscribed group
will be considered by the Agent by default.
`gnus-agent-plugged-hook'
Hook run when connecting to the network.
`gnus-agent-unplugged-hook'
Hook run when disconnecting from the network.
File: gnus, Node: Example Setup, Next: Batching Agents, Prev: Agent Variables, Up: Gnus Unplugged
Example Setup
-------------
If you don't want to read this manual, and you have a fairly standard
setup, you may be able to use something like the following as your
`.gnus.el' file to get started.
;;; Define how Gnus is to fetch news. We do this over NNTP
;;; from your ISP's server.
(setq gnus-select-method '(nntp "news.your-isp.com"))
;;; Define how Gnus is to read your mail. We read mail from
;;; your ISP's POP server.
(setq mail-sources '((pop :server "pop.your-isp.com")))
;;; Say how Gnus is to store the mail. We use nnml groups.
(setq gnus-secondary-select-methods '((nnml "")))
;;; Make Gnus into an offline newsreader.
(gnus-agentize)
That should be it, basically. Put that in your `~/.gnus.el' file,
edit to suit your needs, start up PPP (or whatever), and type `M-x
gnus'.
If this is the first time you've run Gnus, you will be subscribed
automatically to a few default newsgroups. You'll probably want to
subscribe to more groups, and to do that, you have to query the NNTP
server for a complete list of groups with the `A A' command. This
usually takes quite a while, but you only have to do it once.
After reading and parsing a while, you'll be presented with a list of
groups. Subscribe to the ones you want to read with the `u' command.
`l' to make all the killed groups disappear after you've subscribe to
all the groups you want to read. (`A k' will bring back all the killed
groups.)
You can now read the groups at once, or you can download the articles
with the `J s' command. And then read the rest of this manual to find
out which of the other gazillion things you want to customize.
File: gnus, Node: Batching Agents, Next: Agent Caveats, Prev: Example Setup, Up: Gnus Unplugged
Batching Agents
---------------
Having the Gnus Agent fetch articles (and post whatever messages
you've written) is quite easy once you've gotten things set up
properly. The following shell script will do everything that is
necessary:
#!/bin/sh
emacs -batch -l ~/.emacs -f gnus-agent-batch >/dev/null
File: gnus, Node: Agent Caveats, Prev: Batching Agents, Up: Gnus Unplugged
Agent Caveats
-------------
The Gnus Agent doesn't seem to work like most other offline
newsreaders. Here are some common questions that some imaginary people
may ask:
"If I read an article while plugged, do they get entered into the"
Agent?
*No.*
"If I read an article while plugged, and the article already exists"
in the Agent, will it get downloaded once more?
*Yes.*
In short, when Gnus is unplugged, it only looks into the locally
stored articles; when it's plugged, it only talks to your ISP.
File: gnus, Node: Scoring, Next: Various, Prev: Select Methods, Up: Top
Scoring
*******
Other people use "kill files", but we here at Gnus Towers like
scoring better than killing, so we'd rather switch than fight. They do
something completely different as well, so sit up straight and pay
attention!
All articles have a default score (`gnus-summary-default-score'),
which is 0 by default. This score may be raised or lowered either
interactively or by score files. Articles that have a score lower than
`gnus-summary-mark-below' are marked as read.
Gnus will read any "score files" that apply to the current group
before generating the summary buffer.
There are several commands in the summary buffer that insert score
entries based on the current article. You can, for instance, ask Gnus
to lower or increase the score of all articles with a certain subject.
There are two sorts of scoring entries: Permanent and temporary.
Temporary score entries are self-expiring entries. Any entries that are
temporary and have not been used for, say, a week, will be removed
silently to help keep the sizes of the score files down.
* Menu:
* Summary Score Commands:: Adding score entries for the current group.
* Group Score Commands:: General score commands.
* Score Variables:: Customize your scoring. (My, what terminology).
* Score File Format:: What a score file may contain.
* Score File Editing:: You can edit score files by hand as well.
* Adaptive Scoring:: Big Sister Gnus knows what you read.
* Home Score File:: How to say where new score entries are to go.
* Followups To Yourself:: Having Gnus notice when people answer you.
* Scoring Tips:: How to score effectively.
* Reverse Scoring:: That problem child of old is not problem.
* Global Score Files:: Earth-spanning, ear-splitting score files.
* Kill Files:: They are still here, but they can be ignored.
* Converting Kill Files:: Translating kill files to score files.
* GroupLens:: Getting predictions on what you like to read.
* Advanced Scoring:: Using logical expressions to build score rules.
* Score Decays:: It can be useful to let scores wither away.
File: gnus, Node: Summary Score Commands, Next: Group Score Commands, Up: Scoring
Summary Score Commands
======================
The score commands that alter score entries do not actually modify
real score files. That would be too inefficient. Gnus maintains a
cache of previously loaded score files, one of which is considered the
"current score file alist". The score commands simply insert entries
into this list, and upon group exit, this list is saved.
The current score file is by default the group's local score file,
even if no such score file actually exists. To insert score commands
into some other score file (e.g. `all.SCORE'), you must first make this
score file the current one.
General score commands that don't actually change the score file:
`V s'
Set the score of the current article (`gnus-summary-set-score').
`V S'
Display the score of the current article
(`gnus-summary-current-score').
`V t'
Display all score rules that have been used on the current article
(`gnus-score-find-trace').
`V R'
Run the current summary through the scoring process
(`gnus-summary-rescore'). This might be useful if you're playing
around with your score files behind Gnus' back and want to see the
effect you're having.
`V c'
Make a different score file the current
(`gnus-score-change-score-file').
`V e'
Edit the current score file (`gnus-score-edit-current-scores').
You will be popped into a `gnus-score-mode' buffer (*note Score
File Editing::).
`V f'
Edit a score file and make this score file the current one
(`gnus-score-edit-file').
`V F'
Flush the score cache (`gnus-score-flush-cache'). This is useful
after editing score files.
`V C'
Customize a score file in a visually pleasing manner
(`gnus-score-customize').
The rest of these commands modify the local score file.
`V m'
Prompt for a score, and mark all articles with a score below this
as read (`gnus-score-set-mark-below').
`V x'
Prompt for a score, and add a score rule to the current score file
to expunge all articles below this score
(`gnus-score-set-expunge-below').
The keystrokes for actually making score entries follow a very
regular pattern, so there's no need to list all the commands.
(Hundreds of them.)
1. The first key is either `I' (upper case i) for increasing the score
or `L' for lowering the score.
2. The second key says what header you want to score on. The
following keys are available:
`a'
Score on the author name.
`s'
Score on the subject line.
`x'
Score on the `Xref' line--i.e., the cross-posting line.
`r'
Score on the `References' line.
`d'
Score on the date.
`l'
Score on the number of lines.
`i'
Score on the `Message-ID' header.
`f'
Score on followups--this matches the author name, and adds
scores to the followups to this author.
`b'
Score on the body.
`h'
Score on the head.
`t'
Score on thread.
3. The third key is the match type. Which match types are valid
depends on what headers you are scoring on.
`strings'
`e'
Exact matching.
`s'
Substring matching.
`f'
Fuzzy matching (*note Fuzzy Matching::).
`r'
Regexp matching
`date'
`b'
Before date.
`a'
After date.
`n'
This date.
`number'
`<'
Less than number.
`='
Equal to number.
`>'
Greater than number.
4. The fourth and final key says whether this is a temporary (i.e.,
expiring) score entry, or a permanent (i.e., non-expiring) score
entry, or whether it is to be done immediately, without adding to
the score file.
`t'
Temporary score entry.
`p'
Permanent score entry.
`i'
Immediately scoring.
So, let's say you want to increase the score on the current author
with exact matching permanently: `I a e p'. If you want to lower the
score based on the subject line, using substring matching, and make a
temporary score entry: `L s s t'. Pretty easy.
To make things a bit more complicated, there are shortcuts. If you
use a capital letter on either the second or third keys, Gnus will use
defaults for the remaining one or two keystrokes. The defaults are
"substring" and "temporary". So `I A' is the same as `I a s t', and `I
a R' is the same as `I a r t'.
These functions take both the numerical prefix and the symbolic
prefix (*note Symbolic Prefixes::). A numerical prefix says how much
to lower (or increase) the score of the article. A symbolic prefix of
`a' says to use the `all.SCORE' file for the command instead of the
current score file.
The `gnus-score-mimic-keymap' says whether these commands will
pretend they are keymaps or not.
File: gnus, Node: Group Score Commands, Next: Score Variables, Prev: Summary Score Commands, Up: Scoring
Group Score Commands
====================
There aren't many of these as yet, I'm afraid.
`W f'
Gnus maintains a cache of score alists to avoid having to reload
them all the time. This command will flush the cache
(`gnus-score-flush-cache').
You can do scoring from the command line by saying something like:
$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score
File: gnus, Node: Score Variables, Next: Score File Format, Prev: Group Score Commands, Up: Scoring
Score Variables
===============
`gnus-use-scoring'
If `nil', Gnus will not check for score files, and will not, in
general, do any score-related work. This is `t' by default.
`gnus-kill-killed'
If this variable is `nil', Gnus will never apply score files to
articles that have already been through the kill process. While
this may save you lots of time, it also means that if you apply a
kill file to a group, and then change the kill file and want to
run it over you group again to kill more articles, it won't work.
You have to set this variable to `t' to do that. (It is `t' by
default.)
`gnus-kill-files-directory'
All kill and score files will be stored in this directory, which is
initialized from the `SAVEDIR' environment variable by default.
This is `~/News/' by default.
`gnus-score-file-suffix'
Suffix to add to the group name to arrive at the score file name
(`SCORE' by default.)
`gnus-score-uncacheable-files'
All score files are normally cached to avoid excessive re-loading
of score files. However, if this might make your Emacs grow big
and bloated, so this regexp can be used to weed out score files
unlikely to be needed again. It would be a bad idea to deny
caching of `all.SCORE', while it might be a good idea to not cache
`comp.infosystems.www.authoring.misc.ADAPT'. In fact, this
variable is `ADAPT$' by default, so no adaptive score files will
be cached.
`gnus-save-score'
If you have really complicated score files, and do lots of batch
scoring, then you might set this variable to `t'. This will make
Gnus save the scores into the `.newsrc.eld' file.
If you do not set this to `t', then manual scores (like those set
with `V s' (`gnus-summary-set-score')) will not be preserved
across group visits.
`gnus-score-interactive-default-score'
Score used by all the interactive raise/lower commands to
raise/lower score with. Default is 1000, which may seem
excessive, but this is to ensure that the adaptive scoring scheme
gets enough room to play with. We don't want the small changes
from the adaptive scoring to overwrite manually entered data.
`gnus-summary-default-score'
Default score of an article, which is 0 by default.
`gnus-summary-expunge-below'
Don't display the summary lines of articles that have scores lower
than this variable. This is `nil' by default, which means that no
articles will be hidden. This variable is local to the summary
buffers, and has to be set from `gnus-summary-mode-hook'.
`gnus-score-over-mark'
Mark (in the third column) used for articles with a score over the
default. Default is `+'.
`gnus-score-below-mark'
Mark (in the third column) used for articles with a score below the
default. Default is `-'.
`gnus-score-find-score-files-function'
Function used to find score files for the current group. This
function is called with the name of the group as the argument.
Predefined functions available are:
`gnus-score-find-single'
Only apply the group's own score file.
`gnus-score-find-bnews'
Apply all score files that match, using bnews syntax. This
is the default. If the current group is `gnu.emacs.gnus',
for instance, `all.emacs.all.SCORE', `not.alt.all.SCORE' and
`gnu.all.SCORE' would all apply. In short, the instances of
`all' in the score file names are translated into `.*', and
then a regexp match is done.
This means that if you have some score entries that you want
to apply to all groups, then you put those entries in the
`all.SCORE' file.
The score files are applied in a semi-random order, although
Gnus will try to apply the more general score files before
the more specific score files. It does this by looking at
the number of elements in the score file names--discarding
the `all' elements.
`gnus-score-find-hierarchical'
Apply all score files from all the parent groups. This means
that you can't have score files like `all.SCORE', but you can
have `SCORE', `comp.SCORE' and `comp.emacs.SCORE' for each
server.
This variable can also be a list of functions. In that case, all
these functions will be called with the group name as argument,
and all the returned lists of score files will be applied. These
functions can also return lists of score alists directly. In that
case, the functions that return these non-file score alists should
probably be placed before the "real" score file functions, to
ensure that the last score file returned is the local score file.
Phu.
For example, to do hierarchical scoring but use a
non-server-specific overall score file, you could use the value
(list (lambda (group) ("all.SCORE"))
'gnus-score-find-hierarchical)
`gnus-score-expiry-days'
This variable says how many days should pass before an unused
score file entry is expired. If this variable is `nil', no score
file entries are expired. It's 7 by default.
`gnus-update-score-entry-dates'
If this variable is non-`nil', matching score entries will have
their dates updated. (This is how Gnus controls expiry--all
non-matching entries will become too old while matching entries
will stay fresh and young.) However, if you set this variable to
`nil', even matching entries will grow old and will have to face
that oh-so grim reaper.
`gnus-score-after-write-file-function'
Function called with the name of the score file just written.
`gnus-score-thread-simplify'
If this variable is non-`nil', article subjects will be simplified
for subject scoring purposes in the same manner as with
threading--according to the current value of
gnus-simplify-subject-functions. If the scoring entry uses
`substring' or `exact' matching, the match will also be simplified
in this manner.
File: gnus, Node: Score File Format, Next: Score File Editing, Prev: Score Variables, Up: Scoring
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.
File: gnus, Node: Score File Editing, Next: Adaptive Scoring, Prev: Score File Format, Up: Scoring
Score File Editing
==================
You normally enter all scoring commands from the summary buffer, but
you might feel the urge to edit them by hand as well, so we've supplied
you with a mode for that.
It's simply a slightly customized `emacs-lisp' mode, with these
additional commands:
`C-c C-c'
Save the changes you have made and return to the summary buffer
(`gnus-score-edit-done').
`C-c C-d'
Insert the current date in numerical format
(`gnus-score-edit-insert-date'). This is really the day number, if
you were wondering.
`C-c C-p'
The adaptive score files are saved in an unformatted fashion. If
you intend to read one of these files, you want to "pretty print"
it first. This command (`gnus-score-pretty-print') does that for
you.
Type `M-x gnus-score-mode' to use this mode.
`gnus-score-menu-hook' is run in score mode buffers.
In the summary buffer you can use commands like `V f' and `V e' to
begin editing score files.