Go to the first, previous, next, last section, table of contents.

The Summary Buffer

A line for each article is displayed in the summary buffer. You can move around, read articles, post articles and reply to articles.

Summary Buffer Format

Gnus will use the value of the gnus-extract-address-components variable as a function for getting the name and address parts of a From header. Two pre-defined function exist: gnus-extract-address-components, which is the default, quite fast, and too simplistic solution, and mail-extract-address-components, which works very nicely, but is slower.

gnus-summary-same-subject is a string indicating that the current article has the same subject as the previous. This string will be used with those specs that require it.

Summary Buffer Lines

You can change the format of the lines in the summary buffer by changing the gnus-summary-line-format variable. It works along the same lines a a normal format string, with some extensions.

The default string is `"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"'.

The following format specification characters are understood:

Article number.
Subject string.
Subject if the article is the root, gnus-summary-same-subject otherwise.
Full From line.
The name (from the From header).
The name (from the From header). This differs from the n spec in that it uses gnus-extract-address-components, which is slower, but may be more thorough.
The address (from the From header). This works the same way as the a spec.
Number of lines in the article.
Number of characters in the article.
Indentation based on thread level (see section Customizing Threading).
Nothing if the article is a root and lots of spaces if it isn't (it pushes everything after it off the screen).
Opening bracket, which is normally `\[', but can also be `<' for adopted articles.
Closing bracket, which is normally `\]', but can also be `>' for adopted articles.
One space for each thread level.
Twenty minus thread level spaces.
Score as a number.
Zcore, `+' if above the default level and `-' if below the default level. If the difference between gnus-summary-default-level and the score is less than gnus-summary-zcore-fuzz, this spec will not be used.
Number of articles in the current sub-thread. Using this spec will slow down summary buffer generation somewhat.
A single character will be displayed if the article has any children.
User defined specifier. The next character in the format string should be a letter. GNUS will call the function gnus-user-format-function-`X', where `X' is the letter following `%u'. The function will be passed the current header as argument. The function should return a string, which will be inserted into the summary just like information from any other summary specifier.

Text between `%(' and `%)' will be highlighted with gnus-mouse-face when the mouse point is placed inside the area. There can only be one such area.

The `%U' (status), `%R' (replied) and `%z' (zcore) specs have to be handled with care. For reasons of efficiency, Gnus will compute what column these characters will end up in, and "hard-code" that. This means that it is illegal to have these specs after a variable-length spec. Well, you might not be arrested, but your summary buffer will look strange, which is bad enough.

The smart choice is to have these specs as far to the left as possible. (Isn't that the case with everything, though? But I digress.)

This restriction may disappear in later versions of Gnus.

Summary Buffer Mode Line

You can also change the format of the summary mode bar. Set gnus-summary-mode-line-format to whatever you like. Here are the elements you can play with:

Group name.
Current article number.
Gnus version.
Number of unread articles in this group.
Number of unselected articles in this group.
A string with the number of unread and unselected articles represented either as `<%U(+%u) more>' if there are both unread and unselected articles, and just as `<%U more>' if there are just unread articles and no unselected ones.
Shortish group name. For instance, `rec.arts.anime' will be shortened to `r.a.anime'.
Subject of the current article.
Used-defined spec.
Name of the current score file.

Summary Maneuvering

All the straight movement commands understand the numeric prefix and behave pretty much as you'd expect.

None of these commands select articles.

G M-n
Go to the next summary line of an unread article (gnus-summary-next-unread-subject).
G M-p
Go to the previous summary line of an unread article (gnus-summary-prev-unread-subject).
G g
Ask for an article number and then go to this summary line (gnus-summary-goto-subject).

If you are at the end of the group and issue one of the movement commands, Gnus will offer to go to the next group. If gnus-auto-select-next is t and the next group is empty, Gnus will exit summary mode and return to the group buffer. If this variable is neither t nor nil, Gnus will select the next group, no matter whether it has any unread articles or not. As a special case, if this variable is quietly, Gnus will select the next group without asking for confirmation. Also See section Group Levels.

If Gnus asks you to press a key to confirm going to the next group, you can use the C-n and C-p keys to move around the group buffer, searching for the next group to read without actually returning to the group buffer.

If gnus-auto-select-same is non-nil, all the movement commands will try to go to the next article with the same subject as the current. This variable is not particularly useful if you use a threaded display.

If gnus-summary-check-current is non-nil, all the "unread" movement commands will not proceed to the next (or previous) article if the current article is unread. Instead, they will choose the current article.

If gnus-auto-center-summary is non-nil, Gnus will keep the point in the summary buffer centered at all times. This makes things quite tidy, but if you have a slow network connection, or simply do not like this un-Emacsism, you can set this variable to nil to get the normal Emacs scrolling action.

Choosing Articles

None of the following movement commands understand the numeric prefix, and they all select and display an article.

Select the current article, or, if that one's read already, the next unread article (gnus-summary-next-page).
G n
Go to next unread article (gnus-summary-next-unread-article).
G p
Go to previous unread article (gnus-summary-prev-unread-article).
Go to the next article (gnus-summary-next-article).
Go to the previous article (gnus-summary-prev-article).
G C-n
Go to the next article with the same subject (gnus-summary-next-same-subject).
G C-p
Go to the previous article with the same subject (gnus-summary-prev-same-subject).
G f
Go to the first unread article (gnus-summary-first-unread-article).
G b
Go to the article with the highest score (gnus-summary-best-unread-article).
G l
Go to the previous article read (gnus-summary-goto-last-article).
G p
Pop an article off the summary history and go to this article (gnus-summary-pop-article). This command differs from the command above in that you can pop as many previous articles off the history as you like.

Some variables that are relevant for moving and selecting articles:

All the movement commands will try to go to the previous (or next) article, even if that article isn't displayed in the Summary buffer if this variable is non-nil. Gnus will then fetch the article from the server and display it in the article buffer.
This hook is called whenever an article is selected. By default it exposes any threads hidden under the selected article.
This hook is called whenever an article is selected. It is intended to be used for marking articles as read.
This hook is run after selecting an article. It is meant to be used for highlighting the article in some way. It is not run if gnus-visual is nil.
This hook is called when a summary line is changed. It is not run if gnus-visual is nil.
This is the face (or font as some people call it) that is used to highlight the current article in the summary buffer.
Summary lines are highlighted according to this variable, which is a list where the elements are on the format (FORM . FACE). If you would, for instance, like ticked articles to be italic and high-scored articles to be bold, you could set this variable to something like
(((eq mark gnus-ticked-mark) . italic)
 ((> score default) . bold))
As you may have guessed, if FORM returns a non-nil value, FACE will be applied to the line.

Scrolling the Article

Pressing SPACE will scroll the current article forward one page, or, if you have come to the end of the current article, will choose the next article (gnus-summary-next-page).
Scroll the current article back one page (gnus-summary-prev-page).
Scroll the current article one line forward (gnus-summary-scroll-up).
A <
Scroll to the beginning of the article (gnus-summary-beginning-of-article).
A >
Scroll to the end of the article (gnus-summary-end-of-article).

Reply, Followup and Post

All the commands for posting and mailing will put you in a post or mail buffer where you can edit the article all you like, before you send the article by pressing C-c C-c. If you are in a foreign news group, and you wish to post the article using the foreign server, you can give a prefix to C-c C-c to make Gnus try to post using the foreign server.


Commands for composing a mail message:

S r
Mail a reply to the author of the current article (gnus-summary-reply).
Mail a reply to the author of the current article and include the original message (gnus-summary-reply-with-original). This command uses the process/prefix convention.
S o m
Forward the current article to some other person (gnus-summary-mail-forward).
S o p
Forward the current article to a newsgroup (gnus-summary-post-forward).
S m
Send a mail to some other person (gnus-summary-mail-other-window).
S O m
Digest the current series and forward the result using mail (gnus-uu-digest-mail-forward). This command uses the process/prefix convention (see section Process/Prefix).
S O p
Digest the current series and forward the result to a newsgroup (gnus-uu-digest-mail-forward).

Variables for customizing outgoing mail:

Gnus uses the normal methods to determine where replies are to go, but you can change the behavior to suit your needs by fiddling with this variable. If you want the replies to go to the `Sender' instead of the `From' in the group `mail.stupid-list', you could do something like this:
(setq gnus-reply-to-function
      (lambda (group)
       (cond ((string= group "mail.stupid-list")
               (mail-fetch-field "sender"))
This function will be called narrowed to the head of the article that is being replied to. As you can see, this function should return a string if it has an opinion as to what the To header should be. If it does not, it should just return nil, and the normal methods for determining the To header will be used. This function can also return a list. In that case, each list element should be a cons, where the car should be the name of an header (eg. `Cc') and the cdr should be the header value (eg. `larsi@ifi.uio.no'). All these headers will be inserted into the head of the outgoing mail.
This variable says how a mail should be mailed. It uses the function in the send-mail-function variable as the default.
List of regexps to match headers included in digested messages. The headers will be included in the sequence they are matched.
Hook called as the last thing after setting up a mail buffer.

There are three "methods" for handling all mail. The default is sendmail. Some people like what mh does better, and some people prefer vm.

Three variables for customizing what to use when:

This function is used to compose replies. The three functions avaibale are:
This function is used to forward messages. The three functions avaibale are:
This function is used to send mails. The three functions avaibale are:


Commands for posting an article:

S p
Post an article to the current group (gnus-summary-post-news).
S f
Post a followup to the current article (gnus-summary-followup).
Post a followup to the current article and include the original message (gnus-summary-followup-with-original). This command uses the process/prefix convention.
S u
Uuencode a file, split it into parts, and post it as a series (gnus-uu-post-news).

gnus-required-headers a list of header symbols. These headers will either be automatically generated, or, if that's impossible, they will be prompted for. The following symbols are legal:

This required header will be filled out with the result of the gnus-inews-user-name function, which depends on the gnus-user-from-line, gnus-user-login-name, gnus-local-domain and user-mail-address variables.
This required header will be prompted for if not present already.
This required header says which newsgroups the article is to be posted to. If it isn't present already, it will be prompted for.
This optional header will be filled out depending on the gnus-local-organization variable. gnus-organization-file will be used if that variable is nil.
This optional header will be computed by Gnus.
This required header will be generated by Gnus. A unique ID will be created based on date, time, user name and system name.
This optional header will be filled out with the Gnus version numbers.

In addition, you can enter conses into this list. The car of this cons should be a symbol who's name is the name of the header, and the cdr can either a string to be entered verbatim as the value of this header, or it can be a function to be called. This function should return a string to be inserted. For instance, if you want to insert `Mime-Version: 1.0', you should enter (Mime-Version . "1.0") into the list. If you want to insert a funny quote, you could enter something like (X-Yow . yow) into the list. The function yow will then be called without any arguments.

Other variables for customizing outgoing articles:

If non-nil, Gnus will use this method instead of the default select method when posting.
If non-nil, this variable will override mail-default-headers when posting. This variable should then be a string. This string will be inserted, as is, in the head of all outgoing articles.
If nil, always ignore the Followup-To header. If it is t, use its value, but ignore the special value `poster', which will send the followup as a reply mail to the person you are responding to. If it is the symbol ask, query the user before posting. If it is the symbol use, always use the value.
This variable is most useful in mail groups, where "following up" really means sending a mail to a list address. Gnus uses the normal methods to determine where follow-ups are to go, but you can change the behavior to suit your needs by fiddling with this variable. If you want the followups to go to the `Sender' instead of the `From' in the group `mail.stupid-list', you could do something like this:
(setq gnus-followup-to-function
      (lambda (group)
       (cond ((string= group "mail.stupid-list")
               (mail-fetch-field "sender"))
This function will be called narrowed to header of the article that is being followed up.
Some headers that are generated are toxic to the NNTP server. These include the NNTP-Posting-Host, Bcc and Xref, so these headers are deleted if they are present in this list of symbols.
Headers in this list that were previously generated by Gnus will be deleted before posting. Let's say you post an article. Then you decide to post it again to some other group, you naughty boy, so you jump back to the *post-buf* buffer, edit the Newsgroups line, and ship it off again. By default, this variable makes sure that the old generated Message-ID is deleted, and a new one generated. If this isn't done, the entire empire would probably crumble, anarchy would prevail, and cats would start walking on two legs and rule the world. Allegedly.
If non-nil, this variable should be a function that returns a signature file name. The function will be called with the name of the group being posted to. If the function returns a string that doesn't correspond to a file, the string itself is inserted. If the function returns nil, the gnus-signature-file variable will be used instead.
This function is called with the name of the current group after the post buffer has been initialized, and can be used for inserting a signature. Nice if you use different signatures in different groups.
This hook is called after a post buffer has been prepared. If you want to insert a signature at this point, you could put gnus-inews-insert-signature into this hook.
A related variable when following up and replying is this variable, which inserts the quote line. The default value is:
(defvar news-reply-header-hook
  (lambda ()
    (insert "In article " news-reply-yank-message-id
            " " news-reply-yank-from " writes:\n\n")))
This will create lines like:
In article <zngay8jrql@eyesore.no> Lars Mars <lars@eyesore.no> writes:
Having the Message-Id in this line is probably overkill, so I would suggest this hook instead:
(setq news-reply-header-hook
  (lambda () (insert news-reply-yank-from " writes:\n\n")))
This hook is called before the headers have been prepared. By default it inserts the signature specified by gnus-signature-file.
This function is used to do the actual article processing and header checking/generation.
This hook is called right before the article is posted. By default it handles FCC processing (i.e., saving the article to a file.)
This hook is called after inserting the required headers in an article to be posted. The hook is called from the *post-news* buffer, narrowed to the head, and is intended for people who would like to insert additional headers, or just change headers in some way or other.
If non-nil, Gnus will attempt to check the legality of the headers, as well as some other stuff, before posting. You can control the granularity of the check by adding or removing elements from this list. Legal elemetents are:
Check the subject for commands.
Check for the existence of multiple equal headers.
Check for the existence of version and sendsys commands.
Check whether the Message-ID looks ok.
Check whether the From header seems nice.
Check for too long lines.
Check for illegal characters.
Check for excessive size.
Check whether there is any new text in the messages.
Check the length of the signature

Mail & Post

Commands for sending mail and post at the same time:

S b
Post a followup and send a reply to the current article (gnus-summary-followup-and-reply).
Post a followup and send a reply to the current article and include the original message (gnus-summary-followup-and-reply-with-original). This command uses the process/prefix convention.

Here's a list of variables that are relevant to both mailing and posting:

If gnus-signature-file is non-nil, it should be the name of a file containing a signature (`~/.signature' by default). This signature will be appended to all outgoing post. Most people find it more convenient to use mail-signature, which (sort of) does the same, but inserts the signature into the buffer before you start editing the post (or mail). So - if you have both of these variables set, you will get two signatures. Note that mail-signature does not work the same way as gnus-signature-file, which is a bit confusing. If mail-signature is t, it will insert `~/.signature'. If it is a string, this string will be inserted. Note that RFC1036 says that a signature should be preceded by the three characters `-- ' on a line by themselves. This is to make it easier for the recipient to automatically recognize and process the signature. So don't remove those characters, even though you might feel that they ruin you beautiful design, like, totally. Also note that no signature should be more than four lines long. Including ASCII graphics is an efficient way to get everybody to believe that you are silly and have nothing important to say.
When you are replying to or following up an article, you normally want to quote the person you are answering. Inserting quoted text is done by yanking, and each quoted line you yank will have mail-yank-prefix prepended to it. This is ` ' by default, which isn't very pretty. Most everybody prefers that lines are prepended with `> ', so (setq mail-yank-prefix "> ") in your `.emacs' file.
When you yank a message, you do not want to quote any headers, so (setq mail-yank-ignored-headers ":").
If all of gnus-user-login-name, gnus-use-generic-from and gnus-local-domain are nil, Gnus will use user-mail-address as the address part of the From header.
Your full, complete e-mail address. This variable overrides the other Gnus variables if it is non-nil. Here are two example values of this variable: `"larsi@ifi.uio.no (Lars Magne Ingebrigtsen)"' and `"Lars Magne Ingebrigtsen <larsi@ifi.uio.no>"'. The latter version is recommended, but the name has to be quoted if it contains non-alpha-numerical characters - `"\"Lars M. Ingebrigtsen\" <larsi@ifi.uio.no>"'.
This is a string that will be inserted into the header of all outgoing mail messages and news articles. Convenient to use to insert standard headers. If nntp-news-default-headers is non-nil, that variable will override this one when posting articles.
If ask, you will be prompted for whether you want to send a mail copy to the author of the article you are following up. If non-nil and not ask, Gnus will send a mail with a copy of all follow-ups to the authors of the articles you follow up. It's nice in one way - you make sure that the person you are responding to gets your response. Other people loathe this method and will hate you dearly for it, because it means that they will first get a mail, and then have to read the same article later when they read the news. It is nil by default.
This is a string that will be prepended to all mails that are the result of using the variable described above.

You may want to do spell-checking on messages that you send out. Or, if you don't want to spell-check by hand, you could add automatic spell-checking via the ispell package:

(add-hook 'news-inews-hook 'ispell-message)	;For news posts
(add-hook 'mail-send-hook 'ispell-message)	;for mail posts via sendmail

If you want to insert some MIME headers into the articles you post, without doing any actual encoding, you could add gnus-inews-insert-mime-headers to gnus-inews-article-hook.

Canceling Articles

Have you ever written something, and then decided that you really, really, really wish you hadn't posted that?

Well, you can't cancel mail, but you can cancel posts.

Find the article you wish to cancel (you can only cancel your own articles, so don't try any funny stuff). Then press C or S c (gnus-summary-cancel-article). Your article will be canceled - machines all over the world will be deleting your article.

Be aware, however, that not all sites honor cancels, so your article may live on here and there, while most sites will delete the article in question.

If you discover that you have made some mistakes and want to do some corrections, you can post a superseding article that will replace your original article.

Go to the original article and press S s (gnus-summary-supersede-article). You will be put in a buffer where you can edit the article all you want before sending it off the usual way.

You probably want to delete some of the old headers before sending the superseding article - Path and Date are probably incorrect. Set gnus-delete-supersedes-headers to a regexp to match the lines you want removed. The default is `"^Path:\\|^Date"'.

The same goes for superseding as for canceling, only more so: Some sites do not honor superseding. On those sites, it will appear that you have posted almost the same article twice.

If you have just posted the article, and change your mind right away, there is a trick you can use to cancel/supersede the article without waiting for the article to appear on your site first. You simply return to the post buffer (which is called *post-buf*). There you will find the article you just posted, with all the headers intact. Change the `Message-ID' header to a `Cancel' or `Supersedes' header by substituting one of those words for `Message-ID'. Then just press C-c C-c to send the article as you would do normally. The previous article will be canceled/superseded.

Just remember, kids: There is no 'c' in 'supersede'.

Marking Articles

There are several marks you can set on an article.

You have marks that decide the readed-ness (whoo, neato-keano neologism ohoy!) of the article. Alphabetic marks generally mean read, while non-alphabetic characters generally mean unread.

In addition, you also have marks that do not affect readedness.

Unread Articles

The following marks mark articles as unread, in one form or other.

Ticked articles are articles that will remain visible always. If you see an article that you find interesting, or you want to put off reading it, or replying to it, until sometime later, you'd typically tick it. However, articles can be expired, so if you want to keep an article forever, you'll have to save it. Ticked articles have a `!' (gnus-ticked-mark) in the first column.
A dormant article is marked with a `?' (gnus-dormant-mark), and will only appear in the summary buffer if there are followups to it.
An unread article is marked with a `SPC' (gnus-unread-mark). These are articles that haven't been read at all yet.

Read Articles

All the following marks mark articles as read.

Articles that are marked as read. They have a `r' (gnus-del-mark) in the first column. These are articles that the user has marked as read more or less manually.
Articles that are actually read are marked with `R' (gnus-read-mark).
Articles that were marked as read in previous sessions are now old and marked with `O' (gnus-ancient-mark).
Marked as killed (gnus-killed-mark).
Marked as killed by kill files (gnus-kill-file-mark).
Marked as read by having a too low score (gnus-low-score-mark).
Marked as read by a catchup (gnus-catchup-mark).
Canceled article (gnus-cancelled-mark)

All these marks just mean that the article is marked as read, really. They are interpreted differently by the adaptive scoring scheme, however.

One more special mark, though:

You can also mark articles as expirable (or have them marked as such automatically). That doesn't make much sense in normal groups, because a user does not control the expiring of news articles, but in mail groups, for instance, articles that are marked as expirable can be deleted by Gnus at any time. Expirable articles are marked with `E' (gnus-expirable-mark).

Other Marks

There are some marks that have nothing to do with whether the article is read or not.

You can set a bookmark in the current article. Say you are reading a long thesis on cat's urinary tracts, and have to go home for dinner before you've finished reading the thesis. You can then set a bookmark in the article, and Gnus will jump to this bookmark the next time it encounters the article.

All articles that you have replied to or made a followup to (i.e., have answered) will be marked with an `A' in the second column (gnus-replied-mark).

It the `%e' spec is used, the presence of threads or not will be marked with gnus-not-empty-thread-mark and gnus-empty-thread-mark, respectively.

Finally we have the process mark (gnus-process-mark. A variety of commands react to the presence of the process mark. For instance, X u (gnus-uu-decode-uu) will uudecode and view all articles that have been marked with the process mark. Articles marked with the process mark have a `#' in the second column.

Setting Marks

All the marking commands understand the numeric prefix.

M t
Tick the current article (gnus-summary-tick-article-forward).
M ?
Mark the current article as dormant (gnus-summary-mark-as-dormant).
M d
Mark the current article as read (gnus-summary-mark-as-read-forward).
M k
Mark all articles that have the same subject as the current one as read, and then select the next unread article (gnus-summary-kill-same-subject-and-select).
Mark all articles that have the same subject as the current one as read (gnus-summary-kill-same-subject).
Catchup the current group (gnus-summary-catchup).
M C-c
Catchup all articles in the current group (gnus-summary-catchup-all).
Catchup the current group to point (gnus-summary-catchup-to-here).
Mark all articles between point and mark as read (gnus-summary-mark-region-as-read).
M c
Clear all readedness-marks from the current article (gnus-summary-clear-mark-forward).
M e
Mark the current article as expirable (gnus-summary-mark-as-expirable).
M b
Set a bookmark in the current article (gnus-summary-set-bookmark).
Remove the bookmark from the current article (gnus-summary-remove-bookmark).
M M-r
Expunge all deleted articles from the summary buffer (gnus-summary-remove-lines-marked-as-read).
M M-C-r
Ask for a mark and then expunge all articles that have been marked with that mark (gnus-summary-remove-lines-marked-with).
Display all expunged articles (gnus-summary-show-all-expunged).
Display all dormant articles (gnus-summary-show-all-dormant).
Hide all dormant articles (gnus-summary-hide-all-dormant).
M V k
Kill all articles with scores below the default score (or below the numeric prefix) (gnus-summary-kill-below).
M V c
Clear all marks from articles with scores over the default score (or over the numeric prefix) (gnus-summary-clear-above).
M V u
Tick all articles with scores over the default score (or over the numeric prefix) (gnus-summary-tick-above).
M V m
Prompt for a mark, and mark all articles with scores over the default score (or over the numeric prefix) with this mark (gnus-summary-clear-above).

gnus-summary-goto-unread The gnus-summary-goto-unread variable controls what action should be taken after setting a mark. If non-nil, point will move to the next/previous unread article. If nil, point will just move one line up or down.

Setting Process Marks

M P p
Mark the current article with the process mark (gnus-summary-mark-as-processable).
M P u
Remove the process mark, if any, from the current article (gnus-summary-unmark-as-processable).
Remove the process mark from all articles (gnus-summary-unmark-all-processable).
Mark articles by a regular expression (gnus-uu-mark-by-regexp).
M P r
Mark articles in region (gnus-uu-mark-region).
M P t
Mark all articles in the current (sub)thread (gnus-uu-mark-thread).
M P s
Mark all articles in the current series (gnus-uu-mark-series).
Mark all series that have already had some articles marked (gnus-uu-mark-sparse).
M P a
Mark all articles in series order (gnus-uu-mark-series).


Gnus threads articles by default. To thread is to put replies to articles directly after the articles they reply to - in a hierarchical fashion.

Customizing Threading

If this variable is nil, no threading will be done, and all of the rest of the variables here will have no effect. Turning threading off will speed group selection up a bit, but it is sure to make reading slower and more awkward.
If non-nil, Gnus will attempt to build old threads by fetching more old headers - headers to articles that are marked as read. If you would like to display as few summary lines as possible, but still connect as many loose threads as possible, you should set this variable to some. In either case, fetching old headers only works if the backend you are using carries overview files -- this would normally be nntp, nnspool and nnml. Also remember that if the root of the thread has been expired by the server, there's not much Gnus can do about that.
Loose threads are gathered by comparing subjects of articles. If this variable is nil, Gnus requires an exact match between the subjects of the loose threads before gathering them into one big super-thread. This might be too strict a requirement, what with the presence of stupid newsreaders that chop off long subjects lines. If you think so, set this variable to, say, 20 to require that only the first 20 characters of the subjects have to match. If you set this variable to a real low number, you'll find that Gnus will gather everything in sight into one thread, which isn't very helpful. If you set this variable to the special value fuzzy, Gnus will use a fuzzy string comparison algorithm on the subjects.
If non-nil, Gnus will gather all loose subtrees into one big tree and create a dummy root at the top. (Wait a minute. Root at the top? Yup.) Loose subtrees occur when the real root has expired, or you've read or killed the root in a previous session. When there is no real root of a thread, Gnus will have to fudge something. This variable says what fudging method Gnus should use. There are four possible values:
Gnus will make the first of the orphaned articles the parent. This parent will adopt all the other articles. The adopted articles will be marked as such by pointy brackets (`<>') instead of the standard square brackets (`[]'). This is the default method.
Gnus will create a dummy summary line that will pretend to be the parent. This dummy line does not correspond to any real article, so selecting it will just select the first real article after the dummy article.
Gnus won't actually make any article the parent, but simply leave the subject field of all orphans except the first empty. (Actually, it will use gnus-summary-same-subject as the subject (see section Summary Buffer Format).)
Don't make any article parent at all. Just gather the threads and display them after one another.
Don't gather loose threads.
If non-nil, all threads will be hidden when the summary buffer is generated.
if you kill a thread and this variable is non-nil, the subtree will be hidden.
Sometimes somebody changes the subject in the middle of a thread. If this variable is non-nil, the subject change is ignored. If it is nil, which is the default, a change in the subject will result in a new thread.
This is a number that says how much each sub-thread should be indented. The default is `4'.

Thread Commands

T k
Mark all articles in the current sub-thread as read (gnus-summary-kill-thread). If the prefix argument is positive, remove all marks instead. If the prefix argument is negative, tick articles instead.
T l
Lower the score of the current thread (gnus-summary-lower-thread).
T i
Increase the score of the current thread (gnus-summary-raise-thread).
T #
Mark the current thread with the process mark (gnus-uu-mark-thread).
Toggle threading (gnus-summary-toggle-threads).
T s
Expose the thread hidden under the current article, if any (gnus-summary-show-thread).
T h
Hide the current (sub)thread (gnus-summary-hide-thread).
Expose all hidden threads (gnus-summary-show-all-threads).
Hide all threads (gnus-summary-hide-all-threads).

The following commands are thread movement commands. They all understand the numeric prefix.

T n
Go to the next thread (gnus-summary-next-thread).
T p
Go to the previous thread (gnus-summary-prev-thread).
T d
Descend the thread (gnus-summary-down-thread).
T u
Ascend the thread (gnus-summary-up-thread).

Asynchronous Article Fetching

If you read your news from an NNTP server that's far away, the network latencies may make reading articles a chore. You have to wait for a while after pressing n to go to the next article before the article appears. Why can't Gnus just go ahead and fetch the article while you are reading the previous one? Why not, indeed.

First, some caveats. There are some pitfalls to using asynchronous article fetching, especially the way Gnus does it.

Let's say you are reading article 1, which is short, and article 2 is quite long, and you are not interested in reading that. Gnus does not know this, so it goes ahead and fetches article 2. You decide to read article 3, but since Gnus is in the process of fetching article 2, the connection is blocked.

To avoid these situations, Gnus will open two (count 'em two) connections to the server. Some people may think this isn't a very nice thing to do, but I don't see any real alternatives. Setting up that extra connection takes some time, so Gnus startup will be slower.

Gnus will fetch more articles than you will read. This will mean that the link between your machine and the NNTP server will become more loaded than if you didn't use article pre-fetch. The server itself will also become more loaded - both with the extra article requests, and the extra connection.

Ok, so now you know that you shouldn't really use this thing... unless you really want to.

Here's how: Set gnus-asynchronous to t. The rest should happen automatically.

You can control how many articles that are to be pre-fetched by setting nntp-async-number. This is five by default, which means that when you read an article in the group, nntp will pre-fetch the next five articles. If this variable is t, nntp will pre-fetch all the articles that it can without bound. If it is nil, no pre-fetching will be made.

You may wish to create some sort of scheme for choosing which articles that nntp should consider as candidates for pre-fetching. For instance, you may wish to pre-fetch all articles with high scores, and not pre-fetch low-scored articles. You can do that by setting the gnus-asynchronous-article-function, which will be called with an alist where the keys are the article numbers. Your function should return an alist where the articles you are not interested in have been removed. You could also do sorting on article score and the like.

Article Caching

If you have an extremely slow NNTP connection, you may consider turning article caching on. Each article will then be stored locally under your home directory. As you may surmise, this could potentially use huge amounts of disk space, as well as eat up all your inodes so fast it will make your head swim. In vodka.

Used carefully, though, it could be just an easier way to save articles.

To turn caching on, set gnus-use-cache to t. By default, all articles that are ticked or marked as dormant will then be copied over to your local cache (gnus-cache-directory). Whether this cache is flat or hierarchal is controlled by the gnus-use-long-file-name variable, as usual.

When re-select a ticked or dormant article, it will be fetched from the cache instead of from the server. As articles in your cache will never expire, this might serve as a method of saving articles while still keeping them where they belong. Just mark all articles you want to save as dormant, and don't worry.

When an article is marked as read, is it removed from the cache.

The entering/removal of articles from the cache is controlled by the gnus-cache-enter-articles and gnus-cache-remove-articles variables. Both are lists of symbols. The first is (ticked dormant) by default, meaning that ticked and dormant articles will be put in the cache. The latter is (read) by default, meaning that articles that are marked as read are removed from the cache. Possibly symbols in these two lists are ticked, dormant, unread and read.

So where does the massive article-fetching and storing come into the picture? The gnus-jog-cache command will go through all subscribed newsgroups, request all unread articles, and store them in the cache. You should only ever, ever ever ever, use this command if 1) your connection to the NNTP server is really, really, really slow and 2) you have a really, really, really huge disk. Seriously.

Exiting the Summary Buffer

Exiting from the summary buffer will normally update all info on the group and return you to the group buffer.

Exit the current group and update all information on the group (gnus-summary-exit). gnus-summary-prepare-exit-hook is called before doing much of the exiting, and calls gnus-summary-expire-articles by default. gnus-summary-exit-hook is called after finishing the exiting process.
Exit the current group without updating any information on the group (gnus-summary-exit-no-update).
Z c
Mark all unticked articles in the group as read and then exit (gnus-summary-catchup-and-exit).
Mark all articles, even the ticked ones, as read and then exit (gnus-summary-catchup-all-and-exit).
Z n
Mark all articles as read and go to the next group (gnus-summary-catchup-and-goto-next-group).
Exit this group, and then enter it again (gnus-summary-reselect-current-group). If given a prefix, select all articles, both read and unread.
Exit the group, check for new articles in the group, and select the group (gnus-summary-rescan-group). If given a prefix, select all articles, both read and unread.
Exit the group and go to the next group (gnus-summary-next-group).
Exit the group and go to the previous group (gnus-summary-prev-group).

gnus-exit-group-hook is called when you exit the current group.

The data on the current group will be updated (which articles you have read, which articles you have replied to, etc.) when you exit the summary buffer. If the gnus-use-cross-reference variable is t, articles that are cross-referenced to this group and are marked as read, will also be marked as read in the other subscribed groups they were cross-posted to. If this variable is neither nil nor t, the article will be marked as read in both subscribed and unsubscribed groups.

Marking cross-posted articles as read ensures that you'll never have to read the same article more than once. Unless, of course, somebody has posted it to several groups separately. Posting the same article to several groups (not cross-posting) is called spamming, and you are by law required to send nasty-grams to anyone who perpetrates such a heinous crime.

Remember: Cross-posting is kinda ok, but posting the same article separately to several groups is not.

One thing that may cause Gnus to not do the cross-posting thing correctly is if you use an NNTP server that supports XOVER (which is very nice, because it speeds things up considerably) which does not include the Xref header in its NOV lines. This is Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing even with XOVER by registering the Xref lines of all articles you actually read, but if you kill the articles, or just mark them as read without reading them, Gnus will not get a chance to snoop the Xref lines out of these articles, and will be unable to use the cross reference mechanism.

If you want Gnus to get the Xrefs right all the time, you have to set gnus-nov-is-evil to t, which slows things down considerably.

C'est la vie.


Many functions, among them functions for moving, decoding and saving articles, use what is known as the Process/Prefix convention.

This is a method for figuring out what articles that the user wants the command to be performed on.

It goes like this:

If the numeric prefix is N, perform the operation on the next N articles, starting with the current one. If the numeric prefix is negative, perform the operation on the previous N articles, starting with the current one.

If there is no numeric prefix, but some articles are marked with the process mark, perform the operation on the articles that are marked with the process mark.

If there is neither a numeric prefix nor any articles marked with the process mark, just perform the operation on the current article.

Quite simple, really, but it needs to be made clear so that surprises are avoided.

Saving Articles

Gnus can save articles in a number of ways. Below is the documentation for saving articles in a fairly straight-forward fashion (i.e., little processing of the article is done before it is saved). For a different approach (uudecoding, unsharing) you should use gnus-uu (see section Decoding Articles).

If gnus-save-all-headers is non-nil, Gnus will not delete unwanted headers before saving the article.

O o
Save the current article using the default article saver (gnus-summary-save-article).
O m
Save the current article in mail format (gnus-summary-save-article-mail).
O r
Save the current article in rmail format (gnus-summary-save-article-rmail).
O f
Save the current article in plain file format (gnus-summary-save-article-file).
O h
Save the current article in mh folder format (gnus-summary-save-article-folder).
O p
Save the current article in a pipe. Uhm, like, what I mean is - Pipe the current article to a process (gnus-summary-pipe-output).

All these commands use the process/prefix convention (see section Process/Prefix).

You can customize the gnus-default-article-saver variable to make Gnus do what you want it to. You can use any of the four ready-made functions below, or you can create your own.

This is the default format, babyl. Uses the function in the gnus-rmail-save-name variable to get a file name to save the article in. The default is gnus-plain-save-name.
Save in a Unix mail (mbox) file. Uses the function in the gnus-mail-save-name variable to get a file name to save the article in. The default is gnus-plain-save-name.
Append the article straight to an ordinary file. Uses the function in the gnus-file-save-name variable to get a file name to save the article in. The default is gnus-numeric-save-name.
Save the article to an MH folder using rcvstore from the MH library.
Save the article in a VM folder. You have to have the VM mail reader to use this setting.

All of these functions, except for the last one, will save the article in the gnus-article-save-directory, which is initialized from the `SAVEDIR' environment variable.

As you can see above, the functions use different functions to find a suitable name of a file to save the article in. Below is a list of available functions that generate names:

Generates file names that look like `~/News/Alt.andrea-dworkin/45'.
Generates file names that look like `~/News/alt.andrea-dworkin/45'.
Generates file names that look like `~/News/Alt.andrea-dworkin'.
Generates file names that look like `~/News/alt.andrea-dworkin'.

Finally, you have the gnus-use-long-file-name variable. If it is nil, all the preceding functions will replace all periods (`.') in the group names with slashes (`/') - which means that the functions will generate hierarchies of directories instead of having all the files in the toplevel directory (`~/News/alt/andrea-dworkin' instead of `~/News/alt.andrea-dworkin'.)

This function also affects kill and score file names. If this variable is a list, and the list contains the element not-score, long file names will not be used for score files, if it contains the element not-save, long file names will not be used for saving, and if it contains the element not-kill, long file names will not be used for kill files.

If you'd like to save articles in a hierarchy that looks something like a spool, you could

(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
(setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding

Then just save with o. You'd then read this hierarchy with ephemeral nneething groups - G D in the group buffer, and the toplevel directory as the argument (`~/News/'). Then just walk around to the groups/directories with nneething.

Decoding Articles

Sometime users post articles (or series of articles) that have been encoded in some way or other. Gnus can decode them for you.

All these functions use the process/prefix convention (see section Process/Prefix) for finding out what articles to work on, with the extension that a "single article" means "a single series". Gnus can find out by itself what articles belong to a series, decode all the articles and unpack/view/save the resulting file(s).

Gnus guesses what articles are in the series according to the following simplish rule: The subjects must be (nearly) identical, except for the last two numbers of the line. (Spaces are largely ignored, however.)

For example: If you choose a subject called `cat.gif (2/3)', Gnus will find all the articles that match the regexp `^cat.gif ([0-9]+/[0-9]+).*$'.

Subjects that are nonstandard, like `cat.gif (2/3) Part 6 of a series', will not be properly recognized by any of the automatic viewing commands, and you have to mark the articles manually with #.

Uuencoded Articles

X u
Uudecodes the current series (gnus-uu-decode-uu).
Uudecodes and saves the current series (gnus-uu-decode-uu-and-save).
X v u
Uudecodes and views the current series (gnus-uu-decode-uu-view).
X v U
Uudecodes, views and saves the current series (gnus-uu-decode-uu-and-save-view).

Remember that these all react to the presence of articles marked with the process mark. If, for instance, you'd like to uncode and save an entire newsgroup, you'd typically do M P a (gnus-uu-mark-all) and then X U (gnus-uu-decode-uu-and-save).

All this is very much different from how gnus-uu worked with GNUS 4.1, where you had explicit keystrokes for everything under the sun. This version of gnus-uu generally assumes that you mark articles in some way (see section Setting Process Marks) and then press X u.

Note: When trying to decode articles that have names matching gnus-uu-notify-files, which is hard-coded to `[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)', gnus-uu will automatically post an article on `comp.unix.wizards' saying that you have just viewed the file in question. This feature can't be turned off.

Shared Articles

X s
Unshars the current series (gnus-uu-decode-unshar).
Unshars and saves the current series (gnus-uu-decode-unshar-and-save).
X v s
Unshars and views the current series (gnus-uu-decode-unshar-view).
X v S
Unshars, views and saves the current series (gnus-uu-decode-unshar-and-save-view).

PostScript Files

X p
Unpack the current PostScript series (gnus-uu-decode-postscript).
Unpack and save the current PostScript series (gnus-uu-decode-postscript-and-save).
X v p
View the current PostScript series (gnus-uu-decode-postscript-view).
X v P
View and save the current PostScript series (gnus-uu-decode-postscript-and-save-view).

Decoding Variables

Adjective, not verb.

Rule Variables

Gnus uses rule variables to decide how to view a file. All these variables are on the form

      (list '(regexp1 command2)
            '(regexp2 command2)
This variable is consulted first when viewing files. If you wish to use, for instance, sox to convert an `.au' sound file, you could say something like:
       (setq gnus-uu-user-view-rules
         (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
This variable is consulted if Gnus couldn't make any matches from the user and default view rules.
This variable can be used to say what commands should be used to unpack archives.

Other Decode Variables

Files with name matching this regular expression won't be viewed.
Files with a MIME type matching this variable won't be viewed. Note that Gnus tries to guess what type the file is based on the name. gnus-uu is not a MIME package (yet), so this is slightly kludgey.
Where gnus-uu does its work.
Non-nil means that gnus-uu won't peek inside archives looking for files to display.
Non-nil means that the user will always be asked to save a file after viewing it.
Non-nil means that gnus-uu will ignore the default viewing rules.
Non-nil means that gnus-uu will ignore the default archive unpacking commands.
Non-nil means that gnus-uu will strip all carriage returns from articles.
Non-nil means that gnus-uu will mark articles that were unsuccessfully decoded as unread.
Non-nil means that gnus-uu will try to fix uuencoded files that have had trailing spaces deleted.
Non-nil means that gnus-uu will ignore the viewing commands defined by the rule variables and just fudge a MIME content type based on the file name. The result will be fed to metamail for viewing.
Non-nil means that gnus-uu, when asked to save without decoding, will save in digests. If this variable is nil, gnus-uu will just save everything in a file without any embellishments. The digesting almost conforms to RFC1153 - no easy way to specify any meaningful volume and issue numbers were found, so I simply dropped them.

Uuencoding & Posting

Non-nil means that gnus-uu will ask for a file to encode before you compose the article. If this variable is t, you can either include an encoded file with C-c C-i or have one included for you when you post the article.
Maximum length of an article. The encoded file will be split into how many articles it takes to post the entire file.
Non-nil means that gnus-uu will post the encoded file in a thread. This may not be smart, as no other decoder I have seen are able to follow threads when collecting uuencoded articles. (Well, I have seen one package that does that - gnus-uu, but somehow, I don't think that counts...) Default is nil.
Non-nil means that the description will be posted in a separate article. The first article will typically be numbered (0/x). If this variable is nil, the description the user enters will be included at the beginning of the first article, which will be numbered (1/x). Default is t.

Viewing Files

After decoding, if the file is some sort of archive, Gnus will attempt to unpack the archive and see if any of the files in the archive can be viewed. For instance, if you have a gzipped tar file `pics.tar.gz' containing the files `pic1.jpg' and `pic2.gif', Gnus will uncompress and detar the main file, and then view the two pictures. This unpacking process is recursive, so if the archive contains archives of archives, it'll all be unpacked.

Finally, Gnus will normally insert a pseudo-article for each extracted file into the summary buffer. If you go to these "articles", you will be prompted for a command to run (usually Gnus will make a suggestion), and then the command will be run.

If gnus-view-pseudo-asynchronously is nil, Emacs will wait until the viewing is done before proceeding.

If gnus-view-pseudos is automatic, Gnus will not insert the pseudo-articles into the summary buffer, but view them immediately. If this variable is not-confirm, the user won't even be asked for a confirmation before viewing is done.

If gnus-view-pseudos-separately is non-nil, one pseudo-article will be created for each file to be viewed. If nil, all files that use the same viewing command will be given as a list of parameters to that command.

So; there you are, reading your pseudo-articles in your virtual newsgroup from the virtual server; and you think: Why isn't anything real anymore? How did we get here?

Various Article Stuff

W l
Remove page breaks from the current article (gnus-summary-stop-page-breaking).
A s
Perform an isearch in the article buffer (gnus-summary-isearch-article).
W r
Do a Caesar rotate (rot13) on the article buffer (gnus-summary-caesar-message).
A g
(Re)fetch the current article (gnus-summary-show-article). If given a prefix, don't actually refetch any articles, just jump to the current article and configure the windows to display the current article.
W t
Toggle whether to display all headers in the article buffer (gnus-summary-toggle-header).
W m
Toggle whether to run the article through MIME before displaying (gnus-summary-toggle-mime).

There's a battery of commands for washing the article buffer:

W W h
Hide headers (gnus-article-hide-headers).
W W s
Hide signature (gnus-article-hide-signature).
W W c
Hide citation (gnus-article-hide-citation).
W o
Treat overstrike (gnus-article-treat-overstrike).
W w
Do word wrap (gnus-article-word-wrap).
W c
Remove CR (gnus-article-remove-cr).
W q
Treat quoted-printable (gnus-article-de-quoted-unreadable).
W f
Look for and display any X-Face headers (gnus-article-display-x-face). The command executed by this function is given by the gnus-article-x-face-command variable. If this variable is a string, this string will be executed in a sub-shell. If it is a function, this function will be called with the face as the argument. If the gnus-article-x-face-too-ugly (which is a regexp) matches the From header, the face will not be shown.
W H a
Highlight the current article (gnus-article-highlight).
W H h
Highlight the headers (gnus-article-highlight-headers).
W H c
Highlight cited text (gnus-article-highlight-citation).
W H s
Highlight the signature (gnus-article-highlight-signature).
W T u
Display the date in UT (aka. GMT, aka ZULU) (gnus-article-date-ut).
W T l
Display the date in the local timezone (gnus-article-date-local).
W T e
Say how much time has (e)lapsed between the article was posted and now (gnus-article-date-lapsed).

Summary Sorting

You can have the summary buffer sorted in various ways, even though I can't really see why you'd want that.

C-c C-s C-n
Sort by article number (gnus-summary-sort-by-number).
C-c C-s C-a
Sort by author (gnus-summary-sort-by-author).
C-c C-s C-s
Sort by subject (gnus-summary-sort-by-subject).
C-c C-s C-d
Sort by date (gnus-summary-sort-by-date).
C-c C-s C-i
Sort by score (gnus-summary-sort-by-score).

These functions will work both when you use threading and when you don't use threading. In the latter case, all summary lines will be sorted, line by line. In the former case, sorting will be done on a root-by-root basis, which might not be what you were looking for. To toggle whether to use threading, type T T (see section Thread Commands).

Finding the Parent

If you'd like to read the parent of the current article, and it is not displayed in the article buffer, you might still be able to. That is, if the current group is fetched by NNTP, the parent hasn't expired and the References in the current article are not mangled, you can just press ^ or A r (gnus-summary-refer-parent-article). If everything goes well, you'll get the parent. If the parent is already displayed in the summary buffer, point will just move to this article.

You can also ask the NNTP server for an arbitrary article, no matter what group it belongs to. M-^ (gnus-summary-refer-article) will ask you for a Message-Id, which is one of those long thingies that look something like `<38o6up$6f2@hymir.ifi.uio.no>'. You have to get it all exactly right. No fuzzy searches, I'm afraid.

If the group you are reading is located on a backend that does not support fetching by Message-Id very well (like nnspool), you can set gnus-refer-article-method to an NNTP method. It would, perhaps, be best if the NNTP server you consult is the same as the one that keeps the spool you are reading from updated, but that's not really necessary.

Score Files

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). 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.

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 (eg. `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).
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 a
Add a new score entry, and allow specifying all elements (gnus-summary-score-entry).
V c
Make a different score file the current (gnus-score-change-score-file).
V e
Edit the current score file (gnus-score-edit-alist). You will be popped into a gnus-score-mode buffer (see section Score File Editing).
V f
Edit a score file and make this score file the current one (gnus-score-edit-file).
I C-i
Increase the score of the current article (gnus-summary-raise-score).
L C-l
Lower the score of the current article (gnus-summary-lower-score).

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).
Expunge all articles with a score below the default score (or the numeric prefix) (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:
    Score on the author name.
    Score on the subject line.
    Score on the Xref line - i.e., the cross-posting line.
    Score on thread - the References line.
    Score on the date.
    Score on the number of lines.
    Score on the Message-ID.
    Score on followups.
    Score on the body.
    Score on the head.
  3. The third key is the match type. Which match types are legal depends on what headers you are scoring on.
    Exact matching.
    Substring matching.
    Fuzzy matching.
    Regexp matching
    Before date.
    At date.
    This date.
    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.
    Temporary score entry.
    Permanent score entry.
    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.

The gnus-score-mimic-keymap says whether these commands will pretend they are keymaps or not.

Score Variables

If nil, Gnus will not check for score files, and will not, in general, do any score-related work.
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.
All kill and score files will be stored in this directory, which is initialized from the `SAVEDIR' environment variable by default.
Suffix to add to the group name to arrive at the score file name (`SCORE' by default.)
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.
Default score of an article, which is 0 by default.
Mark (in the third column) used for articles with a score over the default. Default is `+'.
Mark (in the third column) used for articles with a score below the default. Default is `-'.
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:
Only apply the group's own score file.
Apply all score files that match, using bnews syntax. For instance, if the current group is `gnu.emacs.gnus', `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. If gnus-use-long-file-name is non-nil, this won't work very will. It will find stuff like `gnu/all/SCORE', but will not find files like `not/gnu/all/SCORE'.
Apply all score files from all the parent groups.
This variable can also be a list of functions. In that case, all these functions will be called, 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.
This variable says how many days should pass before an unused score file entry is expired. The default is 7.

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:

  ("Lars Ingebrigtsen" -10000)
  ("Per Abrahamsen")
  ("larsi\\|lmi" -50000 nil R))
  ("Ding is Badd" nil 728373))
  ("alt.politics" -1000 728372 s))
  (2 -100 nil <))
 (mark 0)
 (expunge -1000)
 (mark-and-expunge -10)
 (read-only nil)
 (orphan -10)
 (adapt t)
 (files "/hom/larsi/News/gnu.SCORE")
 (local (gnus-newsgroup-auto-expire t)
        (gnus-summary-make-false-root 'empty))
 (eval (ding)))

This example demonstrates absolutely everything about a score file.

Even though this looks much like lisp code, nothing here is actually evaled. The lisp reader is used to read this form, though, so it has to be legal syntactically, if not semantically.

Six keys are supported by this alist:

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. Following this key is a random 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.
  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 ce.
  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) types. If this element is not present, Gnus will assume that substring matching should be used. R and S differ from the other two 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 and exact types, which you can use instead, if you feel like.
    Lines, Chars
    These two headers use different match types: <, >, =, >= and <=.
    For the Date header we have three 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.
    Head, Body, All
    These three match keys use the same match types as the From (etc) header uses.
    This match key will add a score entry on all articles that followup to some author. Uses the same match types as the From header uses.
The value of this entry should be a number. Any articles with a score lower than this number will be marked as read.
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.
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.
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.
The clue of this entry should be any number of files. This files will not be loaded, even though they would normally be so, for some reason or other.
The value of this entry will be evalel. This element will be ignored when handling global score files.
Read-only score files will not be updated or saved. Global score files should feature this atom (see section Global Score Files).
The value of this entry should be a number. Articles that do not have parents will get this number added to their scores.
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.
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.

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.

Adaptive Scoring

If all this scoring is getting you down, Gnus has a way of making it all happen automatically - as if by magic. Or rather, as if by artificial stupidity, to be precise.

When you read an article, or mark an article as read, or kill an article, you leave marks behind. On exit from the group, Gnus can sniff these marks and add score elements depending on what marks it finds. You turn on this ability by setting gnus-use-adaptive-scoring to t.

To give you complete control over the scoring process, you can customize the gnus-default-adaptive-score-alist variable. By default, it looks something like this:

(defvar gnus-default-adaptive-score-alist
    (gnus-ticked-mark (from 4))
    (gnus-dormant-mark (from 5))
    (gnus-del-mark (from -4) (subject -1))
    (gnus-read-mark (from 4) (subject 2))
    (gnus-expirable-mark (from -1) (subject -1))
    (gnus-killed-mark (from -1) (subject -3))
    (gnus-catchup-mark (from -1) (subject -1))))

As you see, each element in this alist has a mark as a key (either a variable name or a "real" mark - a character). Following this key is a random number of header/score pairs.

To take gnus-del-mark as an example - this alist says that all articles that have that mark (i.e., are marked with `D') will have a score entry added to lower based on the From header by -4, and lowered by Subject by -1. Change this to fit your prejudices.

If you use this scheme, you should set mark-below to something small - like -300, perhaps, to avoid having small random changes result in articles getting marked as read.

After using adaptive scoring for a week or so, Gnus should start to become properly trained and enhance the authors you like best, and kill the authors you like least, without you having to say so explicitly.

You can control what groups the adaptive scoring is to be performed on by using the score files (see section Score File Format). This will also let you use different rules in different groups.

The adaptive score entries will be put into a file where the name is the group name with gnus-adaptive-file-suffix appended.

When doing adaptive scoring, substring or fuzzy matching would probably give you the best results in most cases. However, if the header one matches is short, the possibility for false positives is great, so if the length of the match is less than gnus-score-exact-adapt-limit, exact matching will be used. If this variable is nil, exact matching will always be used to avoid this problem.

Scoring Tips

If you want to lower the score of crossposts, the line to match on is the Xref header.
("xref" (" talk.politics.misc:" -1000))
Multiple crossposts
If you want to lower the score of articles that have been crossposted to more than, say, 3 groups:
("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
Matching on the body
This is generally not a very good idea - it takes a very long time. Gnus actually has to fetch each individual article from the server. But you might want to anyway, I guess. Even though there are three match keys (Head, Body and All), you should choose one and stick with it in each score file. If you use any two, each article will be fetched twice. If you want to match a bit on the Head and a bit on the Body, just use All for all the matches.
Marking as read
You will probably want to mark articles that has a score below a certain number as read. This is most easily achieved by putting the following in your `all.SCORE' file:
((mark -100))
You may also consider doing something similar with expunge.
Negated charater classes
If you say stuff like [^abcd]*, you may get unexpected results. That will match newlines, which might lead to, well, The Unknown. Say [^abcd\n]* instead.

Reverse Scoring

If you want to keep just articles that have `Sex with Emacs' in the subject header, and expunge all other articles, you could put something like this in your score file:

  ("Sex with Emacs" 2))
 (mark 1)
 (expunge 1))

So, you raise all articles that match `Sex with Emacs' and mark the rest as read, and expunge them to boot.

Global Score Files

Sure, other newsreaders have "global kill files". These are usually nothing more than a single kill file that applies to all groups, stored in the user's home directory. Bah! Puny, weak newsreaders!

What I'm talking about here are Global Score Files. Score files from all over the world, from users everywhere, uniting all nations in one big, happy score file union! Ange-score! New and untested!

All you have to do to use other people's score files is to set the gnus-global-score-files variable. One entry for each score file, or each score file directory. Gnus will decide by itself what score files are applicable to which group.

Say you want to use all score files in the `/ftp@ftp.some-where:/pub/score' directory and the single score file `/ftp@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE':

(setq gnus-global-score-files

Simple, eh? Directory names must end with a `/'. These directories are typically scanned only once during each Gnus session. If you feel the need to manually re-scan the remote directories, you can use the gnus-score-search-global-directories command.

Note that, at present, using this option will slow down group entry somewhat. (That is - a lot.)

If you want to start maintaining score files for other people to use, just put your score file up for anonymous ftp and announce it to the world. Become a retro-moderator! Participate in the retro-moderator wars sure to ensue, where retro-moderators battle it out for the sympathy of the people, luring them to use their score files on false premises! Yay! The net is saved!

Here are some tips for the would-be retro-moderator, off the top of my head:

... I wonder whether other newsreaders will support global score files in the future. Snicker. Yup, any day now, newsreaders like Blue Wave, xrn and 1stReader are bound to implement scoring. Should we start holding our breath yet?

Kill Files

Gnus still supports those pesky old kill files. In fact, the kill file entries can now be expiring, which is something I wrote before Per thought of doing score files, so I've left the code in there.

In short, kill processing is a lot slower (and I do mean a lot) than score processing, so it might be a good idea to rewrite your kill files into score files.

Anyway, a kill file is a normal emacs-lisp file. You can put any forms into this file, which means that you can use kill files as some sort of primitive hook function to be run on group entry, even though that isn't a very good idea.

XCNormal kill files look like this:

(gnus-kill "From" "Lars Ingebrigtsen")
(gnus-kill "Subject" "ding")
(gnus-expunge "X")

This will mark every article written by me as read, and remove them from the summary buffer. Very useful, you'll agree.

Other programs use a totally different kill file syntax. If Gnus encounters what looks like a rn kill file, it will take a stab at interpreting it.

Two functions for editing a GNUS kill file:

Edit this group's kill file (gnus-summary-edit-local-kill).
Edit the general kill file (gnus-summary-edit-global-kill).

A kill file for the group `soc.motss' is normally called `soc.motss.KILL'. The suffix appended to the group name to get this file name is detailed by the gnus-kill-file-name variable. The "global" kill file (not in the score file sense of "global", of course) is called just `KILL'.

If gnus-kill-save-kill-file is non-nil, Gnus will save the kill file after processing, which is necessary if you use expiring kills.

Mail Group Commands

Some commands only make sense in mail groups. If these commands are illegal in the current group, they will raise a hell and let you know.

All these commands (except the expiry and edit commands) use the process/prefix convention (see section Process/Prefix).

B e
Expire all expirable articles in the group (gnus-summary-expire-articles).
B M-C-e
Expunge all the expirable articles in the group (gnus-summary-expire-articles-now). This means that all articles that are eligeble for expiry in the current group will disappear forever into that big `/dev/null' in the sky.
Delete the mail article. This is "delete" as in "delete it from your disk forever and ever, never to return again." Use with caution. (gnus-summary-delete-article).
B m
Move the article from one mail group to another (gnus-summary-move-article).
B c
Copy the article from one group (mail group or not) to a mail group (gnus-summary-copy-article).
B i
Import a random file into the current mail newsgroup (gnus-summary-import-article). You will be prompted for a file name, a From header and a Subject header.
B r
Respool the mail article (gnus-summary-move-article).
B w
Edit the current article (gnus-summary-edit-article). To finish editing and make the changes permanent, type C-c C-c (gnus-summary-edit-article-done).
B q
If you are using fancy splitting, this command will tell you where an article would go (gnus-summary-fancy-query).

Various Summary Stuff

gnus-summary-prepare-hook is called after the summary buffer has been generated. You might use it to, for instance, highlight lines or modify the look of the buffer in some other ungodly manner. I don't care.

Group Information

H f
Try to fetch the FAQ (list of frequently asked questions) for the current group (gnus-summary-fetch-faq). Gnus will try to get the FAQ from gnus-group-faq-directory, which is usually a directory on a remote machine. ange-ftp will be used for fetching the file.
H d
Give a brief description of the current group (gnus-summary-describe-group). If given a prefix, force rereading the description from the server.
H h
Give a very brief description of the most important summary keystrokes (gnus-summary-describe-briefly).
H i
Go to the Gnus info node (gnus-info-find-node).

Searching for Articles

Search through all subsequent articles for a regexp (gnus-summary-search-article-forward).
Search through all previous articles for a regexp (gnus-summary-search-article-backward).
This command will prompt you for a header field, a regular expression to match on this field, and a command to be executed if the match is made (gnus-summary-execute-command).
Perform any operation on all articles that have been marked with the process mark (gnus-summary-universal-argument).

Really Various Summary Commands

If the current article is a digest, you might use this command to enter you into a group based on the current digest to ease reading (gnus-summary-enter-digest-group).
Toggle truncation of summary lines (gnus-summary-toggle-truncation).
Expand the summary buffer window (gnus-summary-expand-window). If given a prefix, force an article window configuration.

Go to the first, previous, next, last section, table of contents.