   This file documents Gnus, the GNU Emacs newsreader.

   Copyright (C) 1995,96 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

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

Category Variables
..................

`gnus-category-mode-hook'
     Hook run in category buffers.

`gnus-category-line-format'
     Format of the lines in the category buffer (see 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 (see 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.

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.

   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

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-agent-fetch-session').  See Drafts

`J a'
     Add the current group to an Agent category
     (`gnus-agent-add-group').

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

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

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.

Outgoing Messages
-----------------

   When Gnus is unplugged, all outgoing messages (both mail and news)
are stored in the draft groups (see 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.

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 (see 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.

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 "nntp.your-isp.com"))

     ;;; Define how Gnus is to read your mail.  We read mail from
     ;;; your ISP's POP server.
     (setenv "MAILHOST" "pop.your-isp.com")
     (setq nnmail-spool-file "po:username")

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

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

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.

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 (see 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.

    `f'
          Score on followups.

    `b'
          Score on the body.

    `h'
          Score on the head.

    `t'
          Score on thead.

  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 (see 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 (see 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.

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 -f gnus-batch-score

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

`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'.

     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.

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

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 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 <)' (see 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
               backends (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 (see 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.

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.

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'
or `(line)'.  If you want score adaptively on separate words appearing
in the subjects, you should set this variable to `(word)'.  If you want
to use both adaptive methods, set this variable to `(word line)'.

   To give you complete control over the scoring process, you can
customize the `gnus-default-adaptive-score-alist' variable.  For
instance, it might look something like this:

     (defvar gnus-default-adaptive-score-alist
       '((gnus-unread-mark)
         (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-kill-file-mark)
         (gnus-ancient-mark)
         (gnus-low-score-mark)
         (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
arbitrary number of header/score pairs.  If there are no header/score
pairs following the key, no adaptive scoring will be done on articles
that have that key as the article mark.  For instance, articles with
`gnus-unread-mark' in the example above will not get adaptive score
entries.

   Each article can have only one mark, so just a single of these rules
will be applied to each article.

   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 have marked 10 articles with the same subject with
`gnus-del-mark', the rule for that mark will be applied ten times.
That means that that subject will get a score of ten times -1, which
should be, unless I'm much mistaken, -10.

   If you have auto-expirable (mail) groups (see Expiring Mail.),
all the read articles will be marked with the `E' mark.  This'll
probably make adaptive scoring slightly impossible, so auto-expiring and
adaptive scoring doesn't really mix very well.

   The headers you can score on are `from', `subject', `message-id',
`references', `xref', `lines', `chars' and `date'.  In addition, you
can score on `followup', which will create an adaptive score entry that
matches on the `References' header using the `Message-ID' of the
current article, thereby matching the following thread.

   You can also score on `thread', which will try to score all articles
that appear in a thread.  `thread' matches uses a `Message-ID' to match
on the `References' header of the article.  If the match is made, the
`Message-ID' of the article is added to the `thread' rule.  (Think
about it.  I'd recommend two aspirins afterwards.)

   If you use this scheme, you should set the score file atom `mark' 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 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.  The default
is `ADAPT'.

   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.

   As mentioned above, you can adapt either on individual words or
entire headers.  If you adapt on words, the
`gnus-default-adaptive-word-score-alist' variable says what score each
instance of a word should add given a mark.

     (setq gnus-default-adaptive-word-score-alist
           `((,gnus-read-mark . 30)
             (,gnus-catchup-mark . -10)
             (,gnus-killed-mark . -20)
             (,gnus-del-mark . -15)))

   This is the default value.  If you have adaption on words enabled,
every word that appears in subjects of articles marked with
`gnus-read-mark' will result in a score rule that increase the score
with 30 points.

   Words that appear in the `gnus-default-ignored-adaptive-words' list
will be ignored.  If you wish to add more words to be ignored, use the
`gnus-ignored-adaptive-words' list instead.

   When the scoring is done, `gnus-adaptive-word-syntax-table' is the
syntax table in effect.  It is similar to the standard syntax table, but
it considers numbers to be non-word-constituent characters.

   If `gnus-adaptive-word-minimum' is set to a number, the adaptive
word scoring process will never bring down the score of an article to
below this number.  The default is `nil'.

   After using this scheme for a while, it might be nice to write a
`gnus-psychoanalyze-user' command to go through the rules and see what
words you like and what words you don't like.  Or perhaps not.

   Note that the adaptive word scoring thing is highly experimental and
is likely to change in the future.  Initial impressions seem to indicate
that it's totally useless as it stands.  Some more work (involving more
rigorous statistical methods) will have to be done to make this useful.

Home Score File
===============

   The score file where new score file entries will go is called the
"home score file".  This is normally (and by default) the score file
for the group itself.  For instance, the home score file for
`gnu.emacs.gnus' is `gnu.emacs.gnus.SCORE'.

   However, this may not be what you want.  It is often convenient to
share a common home score file among many groups--all `emacs' groups
could perhaps use the same home score file.

   The variable that controls this is `gnus-home-score-file'.  It can
be:

  1. A string.  Then this file will be used as the home score file for
     all groups.

  2. A function. The result of this function will be used as the home
     score file.  The function will be called with the name of the
     group as the parameter.

  3. A list.  The elements in this list can be:

       1. (REGEXP FILE-NAME).  If the REGEXP matches the group name,
          the FILE-NAME will will be used as the home score file.

       2. A function. If the function returns non-nil, the result will
          be used as the home score file.

       3. A string.  Use the string as the home score file.

     The list will be traversed from the beginning towards the end
     looking for matches.

   So, if you want to use just a single score file, you could say:

     (setq gnus-home-score-file
           "my-total-score-file.SCORE")

   If you want to use `gnu.SCORE' for all `gnu' groups and `rec.SCORE'
for all `rec' groups (and so on), you can say:

     (setq gnus-home-score-file
           'gnus-hierarchial-home-score-file)

   This is a ready-made function provided for your convenience.  Other
functions include

`gnus-current-home-score-file'
     Return the "current" regular score file.  This will make scoring
     commands add entry to the "innermost" matching score file.

   If you want to have one score file for the `emacs' groups and
another for the `comp' groups, while letting all other groups use their
own home score files:

     (setq gnus-home-score-file
           ;; All groups that match the regexp "\\.emacs"
           '(("\\.emacs" "emacs.SCORE")
             ;; All the comp groups in one score file
             ("^comp" "comp.SCORE")))

   `gnus-home-adapt-file' works exactly the same way as
`gnus-home-score-file', but says what the home adaptive score file is
instead.  All new adaptive file entries will go into the file specified
by this variable, and the same syntax is allowed.

   In addition to using `gnus-home-score-file' and
`gnus-home-adapt-file', you can also use group parameters (see Group Parameters.)
and topic parameters (see Topic Parameters.) to
achieve much the same.  Group and topic parameters take precedence over
this variable.

Followups To Yourself
=====================

   Gnus offers two commands for picking out the `Message-ID' header in
the current buffer.  Gnus will then add a score rule that scores using
this `Message-ID' on the `References' header of other articles.  This
will, in effect, increase the score of all articles that respond to the
article in the current buffer.  Quite useful if you want to easily note
when people answer what you've said.

`gnus-score-followup-article'
     This will add a score to articles that directly follow up your own
     article.

`gnus-score-followup-thread'
     This will add a score to all articles that appear in a thread
     "below" your own article.

   These two functions are both primarily meant to be used in hooks like
`message-sent-hook'.

   If you look closely at your own `Message-ID', you'll notice that the
first two or three characters are always the same.  Here's two of mine:

     <x6u3u47icf.fsf@eyesore.no>
     <x6sp9o7ibw.fsf@eyesore.no>

   So "my" ident on this machine is `x6'.  This can be exploited--the
following rule will raise the score on all followups to myself:

     ("references"
      ("<x6[0-9a-z]+\\.fsf\\(_-_\\)?@.*eyesore.no>"
       1000 nil r))

   Whether it's the first two or first three characters that are "yours"
is system-dependent.

Scoring Tips
============

"Crossposts"
     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 character 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:

     (("subject"
       ("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.