emacs/info/gnus-2

This is ../../info/gnus, produced by makeinfo version 4.13 from
gnus.texi.

Copyright (C) 1995-2012 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being "A GNU Manual", and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     "GNU Free Documentation License".

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION Emacs network features
START-INFO-DIR-ENTRY
* Gnus: (gnus).                 The newsreader Gnus.
END-INFO-DIR-ENTRY


File: gnus,  Node: Charsets,  Next: Article Commands,  Prev: MIME Commands,  Up: Summary Buffer

3.20 Charsets
=============

People use different charsets, and we have MIME to let us know what
charsets they use.  Or rather, we wish we had.  Many people use
newsreaders and mailers that do not understand or use MIME, and just
send out messages without saying what character sets they use.  To help
a bit with this, some local news hierarchies have policies that say
what character set is the default.  For instance, the `fj' hierarchy
uses `iso-2022-jp'.

   This knowledge is encoded in the `gnus-group-charset-alist'
variable, which is an alist of regexps (use the first item to match full
group names) and default charsets to be used when reading these groups.

   In addition, some people do use soi-disant MIME-aware agents that
aren't.  These blithely mark messages as being in `iso-8859-1' even if
they really are in `koi-8'.  To help here, the
`gnus-newsgroup-ignored-charsets' variable can be used.  The charsets
that are listed here will be ignored.  The variable can be set on a
group-by-group basis using the group parameters (*note Group
Parameters::).  The default value is `(unknown-8bit x-unknown)', which
includes values some agents insist on having in there.

   When posting, `gnus-group-posting-charset-alist' is used to
determine which charsets should not be encoded using the MIME
encodings.  For instance, some hierarchies discourage using
quoted-printable header encoding.

   This variable is an alist of regexps and permitted unencoded charsets
for posting.  Each element of the alist has the form `('TEST HEADER
BODY-LIST`)', where:

TEST
     is either a regular expression matching the newsgroup header or a
     variable to query,

HEADER
     is the charset which may be left unencoded in the header (`nil'
     means encode all charsets),

BODY-LIST
     is a list of charsets which may be encoded using 8bit
     content-transfer encoding in the body, or one of the special
     values `nil' (always encode using quoted-printable) or `t' (always
     use 8bit).

   *Note Encoding Customization: (emacs-mime)Encoding Customization,
for additional variables that control which MIME charsets are used when
sending messages.

   Other charset tricks that may be useful, although not Gnus-specific:

   If there are several MIME charsets that encode the same Emacs
charset, you can choose what charset to use by saying the following:

     (put-charset-property 'cyrillic-iso8859-5
                           'preferred-coding-system 'koi8-r)

   This means that Russian will be encoded using `koi8-r' instead of
the default `iso-8859-5' MIME charset.

   If you want to read messages in `koi8-u', you can cheat and say

     (define-coding-system-alias 'koi8-u 'koi8-r)

   This will almost do the right thing.

   And finally, to read charsets like `windows-1251', you can say
something like

     (codepage-setup 1251)
     (define-coding-system-alias 'windows-1251 'cp1251)


File: gnus,  Node: Article Commands,  Next: Summary Sorting,  Prev: Charsets,  Up: Summary Buffer

3.21 Article Commands
=====================

`A P'
     Generate and print a PostScript image of the article buffer
     (`gnus-summary-print-article').  `gnus-ps-print-hook' will be run
     just before printing the buffer.  An alternative way to print
     article is to use Muttprint (*note Saving Articles::).

`A C'
     If `<backend>-fetch-partial-articles' is non-`nil', Gnus will
     fetch partial articles, if the backend it fetches them from
     supports it.  Currently only `nnimap' does.  If you're looking at a
     partial article, and want to see the complete article instead, then
     the `A C' command (`gnus-summary-show-complete-article') will do
     so.



File: gnus,  Node: Summary Sorting,  Next: Finding the Parent,  Prev: Article Commands,  Up: Summary Buffer

3.22 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-m C-n'
     Sort by most recent article number
     (`gnus-summary-sort-by-most-recent-number').

`C-c C-s C-a'
     Sort by author (`gnus-summary-sort-by-author').

`C-c C-s C-t'
     Sort by recipient (`gnus-summary-sort-by-recipient').

`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-m C-d'
     Sort by most recent date (`gnus-summary-sort-by-most-recent-date').

`C-c C-s C-l'
     Sort by lines (`gnus-summary-sort-by-lines').

`C-c C-s C-c'
     Sort by article length (`gnus-summary-sort-by-chars').

`C-c C-s C-i'
     Sort by score (`gnus-summary-sort-by-score').

`C-c C-s C-r'
     Randomize (`gnus-summary-sort-by-random').

`C-c C-s C-o'
     Sort using the default sorting method
     (`gnus-summary-sort-by-original').

   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' (*note Thread Commands::).

   If a prefix argument if given, the sort order is reversed.


File: gnus,  Node: Finding the Parent,  Next: Alternative Approaches,  Prev: Summary Sorting,  Up: Summary Buffer

3.23 Finding the Parent
=======================

`^'
     If you'd like to read the parent of the current article, and it is
     not displayed in the summary 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.

     If given a positive numerical prefix, fetch that many articles
     back into the ancestry.  If given a negative numerical prefix,
     fetch just that ancestor.  So if you say `3 ^', Gnus will fetch
     the parent, the grandparent and the grandgrandparent of the
     current article.  If you say `-3 ^', Gnus will only fetch the
     grandgrandparent of the current article.

`A R (Summary)'
     Fetch all articles mentioned in the `References' header of the
     article (`gnus-summary-refer-references').

`A T (Summary)'
     Display the full thread where the current article appears
     (`gnus-summary-refer-thread').  This command has to fetch all the
     headers in the current group to work, so it usually takes a while.
     If you do it often, you may consider setting
     `gnus-fetch-old-headers' to `invisible' (*note Filling In
     Threads::).  This won't have any visible effects normally, but
     it'll make this command work a whole lot faster.  Of course, it'll
     make group entry somewhat slow.

     The `gnus-refer-thread-limit' variable says how many old (i. e.,
     articles before the first displayed in the current group) headers
     to fetch when doing this command.  The default is 200.  If `t', all
     the available headers will be fetched.  This variable can be
     overridden by giving the `A T' command a numerical prefix.

`M-^ (Summary)'
     You can also ask Gnus 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,
     hard-to-read 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.

     Gnus looks for the `Message-ID' in the headers that have already
     been fetched, but also tries all the select methods specified by
     `gnus-refer-article-method' if it is not found.

   If the group you are reading is located on a back end 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 one updating the spool
you are reading from, but that's not really necessary.

   It can also be a list of select methods, as well as the special
symbol `current', which means to use the current select method.  If it
is a list, Gnus will try all the methods in the list until it finds a
match.

   Here's an example setting that will first try the current method, and
then ask Google if that fails:

     (setq gnus-refer-article-method
           '(current
             (nnweb "google" (nnweb-type google))))

   Most of the mail back ends support fetching by `Message-ID', but do
not do a particularly excellent job at it.  That is, `nnmbox',
`nnbabyl', `nnmaildir', `nnml', are able to locate articles from any
groups, while `nnfolder', and `nnimap' are only able to locate articles
that have been posted to the current group.  `nnmh' does not support
this at all.

   Fortunately, the special `nnregistry' back end is able to locate
articles in any groups, regardless of their back end (*note fetching by
`Message-ID' using the registry: Registry Article Refer Method.).


File: gnus,  Node: Alternative Approaches,  Next: Tree Display,  Prev: Finding the Parent,  Up: Summary Buffer

3.24 Alternative Approaches
===========================

Different people like to read news using different methods.  This being
Gnus, we offer a small selection of minor modes for the summary buffers.

* Menu:

* Pick and Read::               First mark articles and then read them.
* Binary Groups::               Auto-decode all articles.


File: gnus,  Node: Pick and Read,  Next: Binary Groups,  Up: Alternative Approaches

3.24.1 Pick and Read
--------------------

Some newsreaders (like `nn' and, uhm, `Netnews' on VM/CMS) use a
two-phased reading interface.  The user first marks in a summary buffer
the articles she wants to read.  Then she starts reading the articles
with just an article buffer displayed.

   Gnus provides a summary buffer minor mode that allows
this--`gnus-pick-mode'.  This basically means that a few process mark
commands become one-keystroke commands to allow easy marking, and it
provides one additional command for switching to the summary buffer.

   Here are the available keystrokes when using pick mode:

`.'
     Pick the article or thread on the current line
     (`gnus-pick-article-or-thread').  If the variable
     `gnus-thread-hide-subtree' is true, then this key selects the
     entire thread when used at the first article of the thread.
     Otherwise, it selects just the article.  If given a numerical
     prefix, go to that thread or article and pick it.  (The line
     number is normally displayed at the beginning of the summary pick
     lines.)

`SPACE'
     Scroll the summary buffer up one page (`gnus-pick-next-page').  If
     at the end of the buffer, start reading the picked articles.

`u'
     Unpick the thread or article
     (`gnus-pick-unmark-article-or-thread').  If the variable
     `gnus-thread-hide-subtree' is true, then this key unpicks the
     thread if used at the first article of the thread.  Otherwise it
     unpicks just the article.  You can give this key a numerical
     prefix to unpick the thread or article at that line.

`RET'
     Start reading the picked articles (`gnus-pick-start-reading').  If
     given a prefix, mark all unpicked articles as read first.  If
     `gnus-pick-display-summary' is non-`nil', the summary buffer will
     still be visible when you are reading.


   All the normal summary mode commands are still available in the
pick-mode, with the exception of `u'.  However `!' is available which
is mapped to the same function `gnus-summary-tick-article-forward'.

   If this sounds like a good idea to you, you could say:

     (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)

   `gnus-pick-mode-hook' is run in pick minor mode buffers.

   If `gnus-mark-unpicked-articles-as-read' is non-`nil', mark all
unpicked articles as read.  The default is `nil'.

   The summary line format in pick mode is slightly different from the
standard format.  At the beginning of each line the line number is
displayed.  The pick mode line format is controlled by the
`gnus-summary-pick-line-format' variable (*note Formatting
Variables::).  It accepts the same format specs that
`gnus-summary-line-format' does (*note Summary Buffer Lines::).


File: gnus,  Node: Binary Groups,  Prev: Pick and Read,  Up: Alternative Approaches

3.24.2 Binary Groups
--------------------

If you spend much time in binary groups, you may grow tired of hitting
`X u', `n', `RET' all the time.  `M-x gnus-binary-mode' is a minor mode
for summary buffers that makes all ordinary Gnus article selection
functions uudecode series of articles and display the result instead of
just displaying the articles the normal way.

   The only way, in fact, to see the actual articles is the `g'
command, when you have turned on this mode (`gnus-binary-show-article').

   `gnus-binary-mode-hook' is called in binary minor mode buffers.


File: gnus,  Node: Tree Display,  Next: Mail Group Commands,  Prev: Alternative Approaches,  Up: Summary Buffer

3.25 Tree Display
=================

If you don't like the normal Gnus summary display, you might try setting
`gnus-use-trees' to `t'.  This will create (by default) an additional
"tree buffer".  You can execute all summary mode commands in the tree
buffer.

   There are a few variables to customize the tree display, of course:

`gnus-tree-mode-hook'
     A hook called in all tree mode buffers.

`gnus-tree-mode-line-format'
     A format string for the mode bar in the tree mode buffers (*note
     Mode Line Formatting::).  The default is `Gnus: %%b %S %Z'.  For a
     list of valid specs, *note Summary Buffer Mode Line::.

`gnus-selected-tree-face'
     Face used for highlighting the selected article in the tree
     buffer.  The default is `modeline'.

`gnus-tree-line-format'
     A format string for the tree nodes.  The name is a bit of a
     misnomer, though--it doesn't define a line, but just the node.
     The default value is `%(%[%3,3n%]%)', which displays the first
     three characters of the name of the poster.  It is vital that all
     nodes are of the same length, so you _must_ use `%4,4n'-like
     specifiers.

     Valid specs are:

    `n'
          The name of the poster.

    `f'
          The `From' header.

    `N'
          The number of the article.

    `['
          The opening bracket.

    `]'
          The closing bracket.

    `s'
          The subject.

     *Note Formatting Variables::.

     Variables related to the display are:

    `gnus-tree-brackets'
          This is used for differentiating between "real" articles and
          "sparse" articles.  The format is
               ((REAL-OPEN . REAL-CLOSE)
                (SPARSE-OPEN . SPARSE-CLOSE)
                (DUMMY-OPEN . DUMMY-CLOSE))
          and the default is `((?[ . ?]) (?( . ?)) (?{ . ?}) (?< .
          ?>))'.

    `gnus-tree-parent-child-edges'
          This is a list that contains the characters used for
          connecting parent nodes to their children.  The default is
          `(?- ?\\ ?|)'.


`gnus-tree-minimize-window'
     If this variable is non-`nil', Gnus will try to keep the tree
     buffer as small as possible to allow more room for the other Gnus
     windows.  If this variable is a number, the tree buffer will never
     be higher than that number.  The default is `t'.  Note that if you
     have several windows displayed side-by-side in a frame and the tree
     buffer is one of these, minimizing the tree window will also
     resize all other windows displayed next to it.

     You may also wish to add the following hook to keep the window
     minimized at all times:

          (add-hook 'gnus-configure-windows-hook
                    'gnus-tree-perhaps-minimize)

`gnus-generate-tree-function'
     The function that actually generates the thread tree.  Two
     predefined functions are available:
     `gnus-generate-horizontal-tree' and `gnus-generate-vertical-tree'
     (which is the default).


   Here's an example from a horizontal tree buffer:

     {***}-(***)-[odd]-[Gun]
          |      \[Jan]
          |      \[odd]-[Eri]
          |      \(***)-[Eri]
          |            \[odd]-[Paa]
          \[Bjo]
          \[Gun]
          \[Gun]-[Jor]

   Here's the same thread displayed in a vertical tree buffer:

     {***}
       |--------------------------\-----\-----\
     (***)                         [Bjo] [Gun] [Gun]
       |--\-----\-----\                          |
     [odd] [Jan] [odd] (***)                   [Jor]
       |           |     |--\
     [Gun]       [Eri] [Eri] [odd]
                               |
                             [Paa]

   If you're using horizontal trees, it might be nice to display the
trees side-by-side with the summary buffer.  You could add something
like the following to your `~/.gnus.el' file:

     (setq gnus-use-trees t
           gnus-generate-tree-function 'gnus-generate-horizontal-tree
           gnus-tree-minimize-window nil)
     (gnus-add-configuration
      '(article
        (vertical 1.0
                  (horizontal 0.25
                              (summary 0.75 point)
                              (tree 1.0))
                  (article 1.0))))

   *Note Window Layout::.


File: gnus,  Node: Mail Group Commands,  Next: Various Summary Stuff,  Prev: Tree Display,  Up: Summary Buffer

3.26 Mail Group Commands
========================

Some commands only make sense in mail groups.  If these commands are
invalid 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 (*note Process/Prefix::).

`B e'
     Run all expirable articles in the current group through the expiry
     process (`gnus-summary-expire-articles').  That is, delete all
     expirable articles in the group that have been around for a while.
     (*note Expiring Mail::).

`B C-M-e'
     Delete all the expirable articles in the group
     (`gnus-summary-expire-articles-now').  This means that *all*
     articles eligible for expiry in the current group will disappear
     forever into that big `/dev/null' in the sky.

`B DEL'
     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').  Marks will be preserved if
     `gnus-preserve-marks' is non-`nil' (which is the default).

`B c'
     Copy the article from one group (mail group or not) to a mail group
     (`gnus-summary-copy-article').  Marks will be preserved if
     `gnus-preserve-marks' is non-`nil' (which is the default).

`B B'
     Crosspost the current article to some other group
     (`gnus-summary-crosspost-article').  This will create a new copy of
     the article in the other group, and the Xref headers of the
     article will be properly updated.

`B i'
     Import an arbitrary 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 I'
     Create an empty article in the current mail newsgroups
     (`gnus-summary-create-article').  You will be prompted for a
     `From' header and a `Subject' header.

`B r'
     Respool the mail article (`gnus-summary-respool-article').
     `gnus-summary-respool-default-method' will be used as the default
     select method when respooling.  This variable is `nil' by default,
     which means that the current group select method will be used
     instead.  Marks will be preserved if `gnus-preserve-marks' is
     non-`nil' (which is the default).

`B w'
`e'
     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').  If you give a prefix to the
     `C-c C-c' command, Gnus won't re-highlight the article.

`B q'
     If you want to re-spool an article, you might be curious as to
     what group the article will end up in before you do the
     re-spooling.  This command will tell you
     (`gnus-summary-respool-query').

`B t'
     Similarly, this command will display all fancy splitting patterns
     used when respooling, if any (`gnus-summary-respool-trace').

`B p'
     Some people have a tendency to send you "courtesy" copies when they
     follow up to articles you have posted.  These usually have a
     `Newsgroups' header in them, but not always.  This command
     (`gnus-summary-article-posted-p') will try to fetch the current
     article from your news server (or rather, from
     `gnus-refer-article-method' or `gnus-select-method') and will
     report back whether it found the article or not.  Even if it says
     that it didn't find the article, it may have been posted
     anyway--mail propagation is much faster than news propagation, and
     the news copy may just not have arrived yet.

`K E'
     Encrypt the body of an article (`gnus-article-encrypt-body').  The
     body is encrypted with the encryption protocol specified by the
     variable `gnus-article-encrypt-protocol'.


   If you move (or copy) articles regularly, you might wish to have Gnus
suggest where to put the articles.  `gnus-move-split-methods' is a
variable that uses the same syntax as `gnus-split-methods' (*note
Saving Articles::).  You may customize that variable to create
suggestions you find reasonable.  (Note that `gnus-move-split-methods'
uses group names where `gnus-split-methods' uses file names.)

     (setq gnus-move-split-methods
           '(("^From:.*Lars Magne" "nnml:junk")
             ("^Subject:.*gnus" "nnfolder:important")
             (".*" "nnml:misc")))


File: gnus,  Node: Various Summary Stuff,  Next: Exiting the Summary Buffer,  Prev: Mail Group Commands,  Up: Summary Buffer

3.27 Various Summary Stuff
==========================

* Menu:

* Summary Group Information::   Information oriented commands.
* Searching for Articles::      Multiple article commands.
* Summary Generation Commands::
* Really Various Summary Commands::  Those pesky non-conformant commands.

`gnus-summary-display-while-building'
     If non-`nil', show and update the summary buffer as it's being
     built.  If `t', update the buffer after every line is inserted.
     If the value is an integer, N, update the display every N lines.
     The default is `nil'.

`gnus-summary-display-arrow'
     If non-`nil', display an arrow in the fringe to indicate the
     current article.

`gnus-summary-mode-hook'
     This hook is called when creating a summary mode buffer.

`gnus-summary-generate-hook'
     This is called as the last thing before doing the threading and the
     generation of the summary buffer.  It's quite convenient for
     customizing the threading variables based on what data the
     newsgroup has.  This hook is called from the summary buffer after
     most summary buffer variables have been set.

`gnus-summary-prepare-hook'
     It 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.

`gnus-summary-prepared-hook'
     A hook called as the very last thing after the summary buffer has
     been generated.

`gnus-summary-ignore-duplicates'
     When Gnus discovers two articles that have the same `Message-ID',
     it has to do something drastic.  No articles are allowed to have
     the same `Message-ID', but this may happen when reading mail from
     some sources.  Gnus allows you to customize what happens with this
     variable.  If it is `nil' (which is the default), Gnus will rename
     the `Message-ID' (for display purposes only) and display the
     article as any other article.  If this variable is `t', it won't
     display the article--it'll be as if it never existed.

`gnus-alter-articles-to-read-function'
     This function, which takes two parameters (the group name and the
     list of articles to be selected), is called to allow the user to
     alter the list of articles to be selected.

     For instance, the following function adds the list of cached
     articles to the list in one particular group:

          (defun my-add-cached-articles (group articles)
            (if (string= group "some.group")
                (append gnus-newsgroup-cached articles)
              articles))

`gnus-newsgroup-variables'
     A list of newsgroup (summary buffer) local variables, or cons of
     variables and their default expressions to be evalled (when the
     default values are not `nil'), that should be made global while
     the summary buffer is active.

     Note: The default expressions will be evaluated (using function
     `eval') before assignment to the local variable rather than just
     assigned to it.  If the default expression is the symbol `global',
     that symbol will not be evaluated but the global value of the local
     variable will be used instead.

     These variables can be used to set variables in the group
     parameters while still allowing them to affect operations done in
     other buffers.  For example:

          (setq gnus-newsgroup-variables
                '(message-use-followup-to
                  (gnus-visible-headers .
           "^From:\\|^Newsgroups:\\|^Subject:\\|^Date:\\|^To:")))

     Also *note Group Parameters::.

`gnus-propagate-marks'
     If non-`nil', propagate marks to the backends for possible
     storing.  *Note NNTP marks::, and friends, for a more fine-grained
     sieve.



File: gnus,  Node: Summary Group Information,  Next: Searching for Articles,  Up: Various Summary Stuff

3.27.1 Summary Group Information
--------------------------------

`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 an extremely brief description of the most important summary
     keystrokes (`gnus-summary-describe-briefly').

`H i'
     Go to the Gnus info node (`gnus-info-find-node').


File: gnus,  Node: Searching for Articles,  Next: Summary Generation Commands,  Prev: Summary Group Information,  Up: Various Summary Stuff

3.27.2 Searching for Articles
-----------------------------

`M-s'
     Search through all subsequent (raw) articles for a regexp
     (`gnus-summary-search-article-forward').

`M-r'
     Search through all previous (raw) articles for a regexp
     (`gnus-summary-search-article-backward').

`M-S'
     Repeat the previous search forwards
     (`gnus-summary-repeat-search-article-forward').

`M-R'
     Repeat the previous search backwards
     (`gnus-summary-repeat-search-article-backward').

`&'
     This command will prompt you for a header, a regular expression to
     match on this field, and a command to be executed if the match is
     made (`gnus-summary-execute-command').  If the header is an empty
     string, the match is done on the entire article.  If given a
     prefix, search backward instead.

     For instance, `& RET some.*string RET #' will put the process mark
     on all articles that have heads or bodies that match
     `some.*string'.

`M-&'
     Perform any operation on all articles that have been marked with
     the process mark (`gnus-summary-universal-argument').


File: gnus,  Node: Summary Generation Commands,  Next: Really Various Summary Commands,  Prev: Searching for Articles,  Up: Various Summary Stuff

3.27.3 Summary Generation Commands
----------------------------------

`Y g'
     Regenerate the current summary buffer (`gnus-summary-prepare').

`Y c'
     Pull all cached articles (for the current group) into the summary
     buffer (`gnus-summary-insert-cached-articles').

`Y d'
     Pull all dormant articles (for the current group) into the summary
     buffer (`gnus-summary-insert-dormant-articles').

`Y t'
     Pull all ticked articles (for the current group) into the summary
     buffer (`gnus-summary-insert-ticked-articles').



File: gnus,  Node: Really Various Summary Commands,  Prev: Summary Generation Commands,  Up: Various Summary Stuff

3.27.4 Really Various Summary Commands
--------------------------------------

`A D'
`C-d'
     If the current article is a collection of other articles (for
     instance, a digest), you might use this command to enter a group
     based on the that article (`gnus-summary-enter-digest-group').
     Gnus will try to guess what article type is currently displayed
     unless you give a prefix to this command, which forces a "digest"
     interpretation.  Basically, whenever you see a message that is a
     collection of other messages of some format, you `C-d' and read
     these messages in a more convenient fashion.

     The variable `gnus-auto-select-on-ephemeral-exit' controls what
     article should be selected after exiting a digest group.  Valid
     values include:

    `next'
          Select the next article.

    `next-unread'
          Select the next unread article.

    `next-noselect'
          Move the cursor to the next article.  This is the default.

    `next-unread-noselect'
          Move the cursor to the next unread article.

     If it has any other value or there is no next (unread) article, the
     article selected before entering to the digest group will appear.

`C-M-d'
     This command is very similar to the one above, but lets you gather
     several documents into one biiig group
     (`gnus-summary-read-document').  It does this by opening several
     `nndoc' groups for each document, and then opening an `nnvirtual'
     group on top of these `nndoc' groups.  This command understands
     the process/prefix convention (*note Process/Prefix::).

`C-t'
     Toggle truncation of summary lines
     (`gnus-summary-toggle-truncation').  This will probably confuse the
     line centering function in the summary buffer, so it's not a good
     idea to have truncation switched off while reading articles.

`='
     Expand the summary buffer window (`gnus-summary-expand-window').
     If given a prefix, force an `article' window configuration.

`C-M-e'
     Edit the group parameters (*note Group Parameters::) of the current
     group (`gnus-summary-edit-parameters').

`C-M-a'
     Customize the group parameters (*note Group Parameters::) of the
     current group (`gnus-summary-customize-parameters').



File: gnus,  Node: Exiting the Summary Buffer,  Next: Crosspost Handling,  Prev: Various Summary Stuff,  Up: Summary Buffer

3.28 Exiting the Summary Buffer
===============================

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

`Z Z'
`Z Q'
`q'
     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, which calls
     `gnus-summary-expire-articles' by default.
     `gnus-summary-exit-hook' is called after finishing the exit
     process.  `gnus-group-no-more-groups-hook' is run when returning to
     group mode having no more (unread) groups.

`Z E'
`Q'
     Exit the current group without updating any information on the
     group (`gnus-summary-exit-no-update').

`Z c'
`c'
     Mark all unticked articles in the group as read and then exit
     (`gnus-summary-catchup-and-exit').

`Z C'
     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').

`Z p'
     Mark all articles as read and go to the previous group
     (`gnus-summary-catchup-and-goto-prev-group').

`Z R'
`C-x C-s'
     Exit this group, and then enter it again
     (`gnus-summary-reselect-current-group').  If given a prefix, select
     all articles, both read and unread.

`Z G'
`M-g'
     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.

`Z N'
     Exit the group and go to the next group
     (`gnus-summary-next-group').

`Z P'
     Exit the group and go to the previous group
     (`gnus-summary-prev-group').

`Z s'
     Save the current number of read/marked articles in the dribble
     buffer and then save the dribble buffer
     (`gnus-summary-save-newsrc').  If given a prefix, also save the
     `.newsrc' file(s).  Using this command will make exit without
     updating (the `Q' command) worthless.

   `gnus-exit-group-hook' is called when you exit the current group
with an "updating" exit.  For instance `Q'
(`gnus-summary-exit-no-update') does not call this hook.

   If you're in the habit of exiting groups, and then changing your mind
about it, you might set `gnus-kill-summary-on-exit' to `nil'.  If you
do that, Gnus won't kill the summary buffer when you exit it.  (Quelle
surprise!)  Instead it will change the name of the buffer to something
like `*Dead Summary ... *' and install a minor mode called
`gnus-dead-summary-mode'.  Now, if you switch back to this buffer,
you'll find that all keys are mapped to a function called
`gnus-summary-wake-up-the-dead'.  So tapping any keys in a dead summary
buffer will result in a live, normal summary buffer.

   There will never be more than one dead summary buffer at any one
time.

   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'
(which is the default), 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 (*note Crosspost Handling::).


File: gnus,  Node: Crosspost Handling,  Next: Duplicate Suppression,  Prev: Exiting the Summary Buffer,  Up: Summary Buffer

3.29 Crosspost Handling
=======================

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.  Massive cross-posting (aka.
"velveeta") is to be avoided at all costs, and you can even use the
`gnus-summary-mail-crosspost-complaint' command to complain about
excessive crossposting (*note Summary Mail Commands::).

   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.

   To check whether your NNTP server includes the `Xref' header in its
overview files, try `telnet your.nntp.server nntp', `MODE READER' on
`inn' servers, and then say `LIST overview.fmt'.  This may not work,
but if it does, and the last line you get does not read `Xref:full',
then you should shout and whine at your news admin until she includes
the `Xref' header in the overview files.

   If you want Gnus to get the `Xref's right all the time, you have to
set `nntp-nov-is-evil' to `t', which slows things down considerably.
Also *note Slow/Expensive Connection::.

   C'est la vie.

   For an alternative approach, *note Duplicate Suppression::.


File: gnus,  Node: Duplicate Suppression,  Next: Security,  Prev: Crosspost Handling,  Up: Summary Buffer

3.30 Duplicate Suppression
==========================

By default, Gnus tries to make sure that you don't have to read the same
article more than once by utilizing the crossposting mechanism (*note
Crosspost Handling::).  However, that simple and efficient approach may
not work satisfactory for some users for various reasons.

  1. The NNTP server may fail to generate the `Xref' header.  This is
     evil and not very common.

  2. The NNTP server may fail to include the `Xref' header in the
     `.overview' data bases.  This is evil and all too common, alas.

  3. You may be reading the same group (or several related groups) from
     different NNTP servers.

  4. You may be getting mail that duplicates articles posted to groups.

   I'm sure there are other situations where `Xref' handling fails as
well, but these four are the most common situations.

   If, and only if, `Xref' handling fails for you, then you may
consider switching on "duplicate suppression".  If you do so, Gnus will
remember the `Message-ID's of all articles you have read or otherwise
marked as read, and then, as if by magic, mark them as read all
subsequent times you see them--in _all_ groups.  Using this mechanism
is quite likely to be somewhat inefficient, but not overly so.  It's
certainly preferable to reading the same articles more than once.

   Duplicate suppression is not a very subtle instrument.  It's more
like a sledge hammer than anything else.  It works in a very simple
fashion--if you have marked an article as read, it adds this Message-ID
to a cache.  The next time it sees this Message-ID, it will mark the
article as read with the `M' mark.  It doesn't care what group it saw
the article in.

`gnus-suppress-duplicates'
     If non-`nil', suppress duplicates.

`gnus-save-duplicate-list'
     If non-`nil', save the list of duplicates to a file.  This will
     make startup and shutdown take longer, so the default is `nil'.
     However, this means that only duplicate articles read in a single
     Gnus session are suppressed.

`gnus-duplicate-list-length'
     This variable says how many `Message-ID's to keep in the duplicate
     suppression list.  The default is 10000.

`gnus-duplicate-file'
     The name of the file to store the duplicate suppression list in.
     The default is `~/News/suppression'.

   If you have a tendency to stop and start Gnus often, setting
`gnus-save-duplicate-list' to `t' is probably a good idea.  If you
leave Gnus running for weeks on end, you may have it `nil'.  On the
other hand, saving the list makes startup and shutdown much slower, so
that means that if you stop and start Gnus often, you should set
`gnus-save-duplicate-list' to `nil'.  Uhm.  I'll leave this up to you
to figure out, I think.


File: gnus,  Node: Security,  Next: Mailing List,  Prev: Duplicate Suppression,  Up: Summary Buffer

3.31 Security
=============

Gnus is able to verify signed messages or decrypt encrypted messages.
The formats that are supported are PGP, PGP/MIME and S/MIME, however
you need some external programs to get things to work:

  1. To handle PGP and PGP/MIME messages, you have to install an
     OpenPGP implementation such as GnuPG.  The Lisp interface to GnuPG
     included with Emacs is called EasyPG (*note EasyPG: (epa)Top.),
     but PGG (*note PGG: (pgg)Top.), and Mailcrypt are also supported.

  2. To handle S/MIME message, you need to install OpenSSL.  OpenSSL
     0.9.6 or newer is recommended.


   The variables that control security functionality on
reading/composing messages include:

`mm-verify-option'
     Option of verifying signed parts.  `never', not verify; `always',
     always verify; `known', only verify known protocols.  Otherwise,
     ask user.

`mm-decrypt-option'
     Option of decrypting encrypted parts.  `never', no decryption;
     `always', always decrypt; `known', only decrypt known protocols.
     Otherwise, ask user.

`mm-sign-option'
     Option of creating signed parts.  `nil', use default signing keys;
     `guided', ask user to select signing keys from the menu.

`mm-encrypt-option'
     Option of creating encrypted parts.  `nil', use the first
     public-key matching the `From:' header as the recipient; `guided',
     ask user to select recipient keys from the menu.

`mml1991-use'
     Symbol indicating elisp interface to OpenPGP implementation for
     PGP messages.  The default is `epg', but `pgg', and `mailcrypt'
     are also supported although deprecated.  By default, Gnus uses the
     first available interface in this order.

`mml2015-use'
     Symbol indicating elisp interface to OpenPGP implementation for
     PGP/MIME messages.  The default is `epg', but `pgg', and
     `mailcrypt' are also supported although deprecated.  By default,
     Gnus uses the first available interface in this order.


   By default the buttons that display security information are not
shown, because they clutter reading the actual e-mail.  You can type `K
b' manually to display the information.  Use the
`gnus-buttonized-mime-types' and `gnus-unbuttonized-mime-types'
variables to control this permanently.  *note MIME Commands:: for
further details, and hints on how to customize these variables to
always display security information.

   Snarfing OpenPGP keys (i.e., importing keys from articles into your
key ring) is not supported explicitly through a menu item or command,
rather Gnus do detect and label keys as `application/pgp-keys',
allowing you to specify whatever action you think is appropriate
through the usual MIME infrastructure.  You can use a `~/.mailcap'
entry (*note mailcap: (emacs-mime)mailcap.) such as the following to
import keys using GNU Privacy Guard when you click on the MIME button
(*note Using MIME::).

     application/pgp-keys; gpg --import --interactive --verbose; needsterminal
   This happens to also be the default action defined in
`mailcap-mime-data'.

   More information on how to set things for sending outgoing signed and
encrypted messages up can be found in the message manual (*note
Security: (message)Security.).


File: gnus,  Node: Mailing List,  Prev: Security,  Up: Summary Buffer

3.32 Mailing List
=================

Gnus understands some mailing list fields of RFC 2369.  To enable it,
add a `to-list' group parameter (*note Group Parameters::), possibly
using `A M' (`gnus-mailing-list-insinuate') in the summary buffer.

   That enables the following commands to the summary buffer:

`C-c C-n h'
     Send a message to fetch mailing list help, if List-Help field
     exists.

`C-c C-n s'
     Send a message to subscribe the mailing list, if List-Subscribe
     field exists.

`C-c C-n u'
     Send a message to unsubscribe the mailing list, if List-Unsubscribe
     field exists.

`C-c C-n p'
     Post to the mailing list, if List-Post field exists.

`C-c C-n o'
     Send a message to the mailing list owner, if List-Owner field
     exists.

`C-c C-n a'
     Browse the mailing list archive, if List-Archive field exists.



File: gnus,  Node: Article Buffer,  Next: Composing Messages,  Prev: Summary Buffer,  Up: Top

4 Article Buffer
****************

The articles are displayed in the article buffer, of which there is only
one.  All the summary buffers share the same article buffer unless you
tell Gnus otherwise.

* Menu:

* Hiding Headers::              Deciding what headers should be displayed.
* Using MIME::                  Pushing articles through MIME before reading them.
* HTML::                        Reading HTML messages.
* Customizing Articles::        Tailoring the look of the articles.
* Article Keymap::              Keystrokes available in the article buffer.
* Misc Article::                Other stuff.


File: gnus,  Node: Hiding Headers,  Next: Using MIME,  Up: Article Buffer

4.1 Hiding Headers
==================

The top section of each article is the "head".  (The rest is the
"body", but you may have guessed that already.)

   There is a lot of useful information in the head: the name of the
person who wrote the article, the date it was written and the subject
of the article.  That's well and nice, but there's also lots of
information most people do not want to see--what systems the article
has passed through before reaching you, the `Message-ID', the
`References', etc. ad nauseam--and you'll probably want to get rid of
some of those lines.  If you want to keep all those lines in the
article buffer, you can set `gnus-show-all-headers' to `t'.

   Gnus provides you with two variables for sifting headers:

`gnus-visible-headers'
     If this variable is non-`nil', it should be a regular expression
     that says what headers you wish to keep in the article buffer.  All
     headers that do not match this variable will be hidden.

     For instance, if you only want to see the name of the person who
     wrote the article and the subject, you'd say:

          (setq gnus-visible-headers "^From:\\|^Subject:")

     This variable can also be a list of regexps to match headers to
     remain visible.

`gnus-ignored-headers'
     This variable is the reverse of `gnus-visible-headers'.  If this
     variable is set (and `gnus-visible-headers' is `nil'), it should
     be a regular expression that matches all lines that you want to
     hide.  All lines that do not match this variable will remain
     visible.

     For instance, if you just want to get rid of the `References' line
     and the `Xref' line, you might say:

          (setq gnus-ignored-headers "^References:\\|^Xref:")

     This variable can also be a list of regexps to match headers to be
     removed.

     Note that if `gnus-visible-headers' is non-`nil', this variable
     will have no effect.


   Gnus can also sort the headers for you.  (It does this by default.)
You can control the sorting by setting the `gnus-sorted-header-list'
variable.  It is a list of regular expressions that says in what order
the headers are to be displayed.

   For instance, if you want the name of the author of the article
first, and then the subject, you might say something like:

     (setq gnus-sorted-header-list '("^From:" "^Subject:"))

   Any headers that are to remain visible, but are not listed in this
variable, will be displayed in random order after all the headers
listed in this variable.

   You can hide further boring headers by setting
`gnus-treat-hide-boring-headers' to `head'.  What this function does
depends on the `gnus-boring-article-headers' variable.  It's a list,
but this list doesn't actually contain header names.  Instead it lists
various "boring conditions" that Gnus can check and remove from sight.

   These conditions are:
`empty'
     Remove all empty headers.

`followup-to'
     Remove the `Followup-To' header if it is identical to the
     `Newsgroups' header.

`reply-to'
     Remove the `Reply-To' header if it lists the same addresses as the
     `From' header, or if the `broken-reply-to' group parameter is set.

`newsgroups'
     Remove the `Newsgroups' header if it only contains the current
     group name.

`to-address'
     Remove the `To' header if it only contains the address identical to
     the current group's `to-address' parameter.

`to-list'
     Remove the `To' header if it only contains the address identical to
     the current group's `to-list' parameter.

`cc-list'
     Remove the `Cc' header if it only contains the address identical to
     the current group's `to-list' parameter.

`date'
     Remove the `Date' header if the article is less than three days
     old.

`long-to'
     Remove the `To' and/or `Cc' header if it is very long.

`many-to'
     Remove all `To' and/or `Cc' headers if there are more than one.

   To include these three elements, you could say something like:

     (setq gnus-boring-article-headers
           '(empty followup-to reply-to))

   This is also the default value for this variable.


File: gnus,  Node: Using MIME,  Next: HTML,  Prev: Hiding Headers,  Up: Article Buffer

4.2 Using MIME
==============

Mime is a standard for waving your hands through the air, aimlessly,
while people stand around yawning.

   MIME, however, is a standard for encoding your articles, aimlessly,
while all newsreaders die of fear.

   MIME may specify what character set the article uses, the encoding
of the characters, and it also makes it possible to embed pictures and
other naughty stuff in innocent-looking articles.

   Gnus pushes MIME articles through `gnus-display-mime-function' to
display the MIME parts.  This is `gnus-display-mime' by default, which
creates a bundle of clickable buttons that can be used to display, save
and manipulate the MIME objects.

   The following commands are available when you have placed point over
a MIME button:

`RET (Article)'
`BUTTON-2 (Article)'
     Toggle displaying of the MIME object
     (`gnus-article-press-button').  If built-in viewers can not display
     the object, Gnus resorts to external viewers in the `mailcap'
     files.  If a viewer has the `copiousoutput' specification, the
     object is displayed inline.

`M-RET (Article)'
`v (Article)'
     Prompt for a method, and then view the MIME object using this
     method (`gnus-mime-view-part').

`t (Article)'
     View the MIME object as if it were a different MIME media type
     (`gnus-mime-view-part-as-type').

`C (Article)'
     Prompt for a charset, and then view the MIME object using this
     charset (`gnus-mime-view-part-as-charset').

`o (Article)'
     Prompt for a file name, and then save the MIME object
     (`gnus-mime-save-part').

`C-o (Article)'
     Prompt for a file name, then save the MIME object and strip it from
     the article.  Then proceed to article editing, where a reasonable
     suggestion is being made on how the altered article should look
     like.  The stripped MIME object will be referred via the
     message/external-body MIME type.
     (`gnus-mime-save-part-and-strip').

`r (Article)'
     Prompt for a file name, replace the MIME object with an external
     body referring to the file via the message/external-body MIME
     type.  (`gnus-mime-replace-part').

`d (Article)'
     Delete the MIME object from the article and replace it with some
     information about the removed MIME object
     (`gnus-mime-delete-part').

`c (Article)'
     Copy the MIME object to a fresh buffer and display this buffer
     (`gnus-mime-copy-part').  If given a prefix, copy the raw contents
     without decoding.  If given a numerical prefix, you can do
     semi-manual charset stuff (see
     `gnus-summary-show-article-charset-alist' in *note Paging the
     Article::).  Compressed files like `.gz' and `.bz2' are
     automatically decompressed if `auto-compression-mode' is enabled
     (*note Accessing Compressed Files: (emacs)Compressed Files.).

`p (Article)'
     Print the MIME object (`gnus-mime-print-part').  This command
     respects the `print=' specifications in the `.mailcap' file.

`i (Article)'
     Insert the contents of the MIME object into the buffer
     (`gnus-mime-inline-part') as `text/plain'.  If given a prefix,
     insert the raw contents without decoding.  If given a numerical
     prefix, you can do semi-manual charset stuff (see
     `gnus-summary-show-article-charset-alist' in *note Paging the
     Article::).  Compressed files like `.gz' and `.bz2' are
     automatically decompressed depending on `jka-compr' regardless of
     `auto-compression-mode' (*note Accessing Compressed Files:
     (emacs)Compressed Files.).

`E (Article)'
     View the MIME object with an internal viewer.  If no internal
     viewer is available, use an external viewer
     (`gnus-mime-view-part-internally').

`e (Article)'
     View the MIME object with an external viewer.
     (`gnus-mime-view-part-externally').

`| (Article)'
     Output the MIME object to a process (`gnus-mime-pipe-part').

`. (Article)'
     Interactively run an action on the MIME object
     (`gnus-mime-action-on-part').


   Gnus will display some MIME objects automatically.  The way Gnus
determines which parts to do this with is described in the Emacs MIME
manual.

   It might be best to just use the toggling functions from the article
buffer to avoid getting nasty surprises.  (For instance, you enter the
group `alt.sing-a-long' and, before you know it, MIME has decoded the
sound file in the article and some horrible sing-a-long song comes
screaming out your speakers, and you can't find the volume button,
because there isn't one, and people are starting to look at you, and you
try to stop the program, but you can't, and you can't find the program
to control the volume, and everybody else in the room suddenly decides
to look at you disdainfully, and you'll feel rather stupid.)

   Any similarity to real events and people is purely coincidental.
Ahem.

   Also *note MIME Commands::.


File: gnus,  Node: HTML,  Next: Customizing Articles,  Prev: Using MIME,  Up: Article Buffer

4.3 HTML
========

If you have `w3m' installed on your system, Gnus can display HTML
articles in the article buffer.  There are many Gnus add-ons for doing
this, using various approaches, but there's one (sort of) built-in
method that's used by default.

   For a complete overview, consult *Note Display Customization:
(emacs-mime)Display Customization.  This section only describes the
default method.

`mm-text-html-renderer'
     If set to `gnus-article-html', Gnus will use the built-in method,
     that's based on `w3m'.

`gnus-blocked-images'
     External images that have URLs that match this regexp won't be
     fetched and displayed.  For instance, do block all URLs that have
     the string "ads" in them, do the following:

          (setq gnus-blocked-images "ads")

     This can also be a function to be evaluated.  If so, it will be
     called with the group name as the parameter.  The default value is
     `gnus-block-private-groups', which will return `"."' for anything
     that isn't a newsgroup.  This means that no external images will
     be fetched as a result of reading mail, so that nobody can use web
     bugs (and the like) to track whether you've read email.

     Also *note Misc Article:: for `gnus-inhibit-images'.

`gnus-html-cache-directory'
     Gnus will download and cache images according to how
     `gnus-blocked-images' is set.  These images will be stored in this
     directory.

`gnus-html-cache-size'
     When `gnus-html-cache-size' bytes have been used in that
     directory, the oldest files will be deleted.  The default is 500MB.

`gnus-html-frame-width'
     The width to use when rendering HTML.  The default is 70.

`gnus-max-image-proportion'
     How big pictures displayed are in relation to the window they're
     in.  A value of 0.7 (the default) means that they are allowed to
     take up 70% of the width and height of the window.  If they are
     larger than this, and Emacs supports it, then the images will be
     rescaled down to fit these criteria.


   To use this, make sure that you have `w3m' and `curl' installed.  If
you have, then Gnus should display HTML automatically.


File: gnus,  Node: Customizing Articles,  Next: Article Keymap,  Prev: HTML,  Up: Article Buffer

4.4 Customizing Articles
========================

A slew of functions for customizing how the articles are to look like
exist.  You can call these functions interactively (*note Article
Washing::), or you can have them called automatically when you select
the articles.

   To have them called automatically, you should set the corresponding
"treatment" variable.  For instance, to have headers hidden, you'd set
`gnus-treat-hide-headers'.  Below is a list of variables that can be
set, but first we discuss the values these variables can have.

   Note: Some values, while valid, make little sense.  Check the list
below for sensible values.

  1. `nil': Don't do this treatment.

  2. `t': Do this treatment on all body parts.

  3. `head': Do the treatment on the headers.

  4. `first': Do this treatment on the first body part.

  5. `last': Do this treatment on the last body part.

  6. An integer: Do this treatment on all body parts that have a length
     less than this number.

  7. A list of strings: Do this treatment on all body parts that are in
     articles that are read in groups that have names that match one of
     the regexps in the list.

  8. A list where the first element is not a string:

     The list is evaluated recursively.  The first element of the list
     is a predicate.  The following predicates are recognized: `or',
     `and', `not' and `typep'.  Here's an example:

          (or last
              (typep "text/x-vcard"))


   You may have noticed that the word "part" is used here.  This refers
to the fact that some messages are MIME multipart articles that may be
divided into several parts.  Articles that are not multiparts are
considered to contain just a single part.

   Are the treatments applied to all sorts of multipart parts?  Yes, if
you want to, but by default, only `text/plain' parts are given the
treatment.  This is controlled by the `gnus-article-treat-types'
variable, which is a list of regular expressions that are matched to the
type of the part.  This variable is ignored if the value of the
controlling variable is a predicate list, as described above.

   The following treatment options are available.  The easiest way to
customize this is to examine the `gnus-article-treat' customization
group.  Values in parenthesis are suggested sensible values.  Others are
possible but those listed are probably sufficient for most people.

`gnus-treat-buttonize (t, integer)'

`gnus-treat-buttonize-head (head)'
     *Note Article Buttons::.

`gnus-treat-capitalize-sentences (t, integer)'

`gnus-treat-overstrike (t, integer)'

`gnus-treat-strip-cr (t, integer)'

`gnus-treat-strip-headers-in-body (t, integer)'

`gnus-treat-strip-leading-blank-lines (t, first, integer)'

`gnus-treat-strip-multiple-blank-lines (t, integer)'

`gnus-treat-strip-pem (t, last, integer)'

`gnus-treat-strip-trailing-blank-lines (t, last, integer)'

`gnus-treat-unsplit-urls (t, integer)'

`gnus-treat-wash-html (t, integer)'
     *Note Article Washing::.

`gnus-treat-date (head)'
     This will transform/add date headers according to the
     `gnus-article-date-headers' variable.  This is a list of Date
     headers to display.  The formats available are:

    `ut'
          Universal time, aka GMT, aka ZULU.

    `local'
          The user's local time zone.

    `english'
          A semi-readable English sentence.

    `lapsed'
          The time elapsed since the message was posted.

    `combined-lapsed'
          Both the original date header and a (shortened) elapsed time.

    `original'
          The original date header.

    `iso8601'
          ISO8601 format, i.e., "2010-11-23T22:05:21".

    `user-defined'
          A format done according to the `gnus-article-time-format'
          variable.


     *Note Article Date::.

`gnus-treat-from-picon (head)'

`gnus-treat-mail-picon (head)'

`gnus-treat-newsgroups-picon (head)'
     *Note Picons::.

`gnus-treat-from-gravatar (head)'

`gnus-treat-mail-gravatar (head)'
     *Note Gravatars::.

`gnus-treat-display-smileys (t, integer)'

`gnus-treat-body-boundary (head)'
     Adds a delimiter between header and body, the string used as
     delimiter is controlled by `gnus-body-boundary-delimiter'.

     *Note Smileys::.

`gnus-treat-display-x-face (head)'
     *Note X-Face::.

`gnus-treat-display-face (head)'
     *Note Face::.

`gnus-treat-emphasize (t, head, integer)'

`gnus-treat-fill-article (t, integer)'

`gnus-treat-fill-long-lines (t, integer)'

`gnus-treat-hide-boring-headers (head)'

`gnus-treat-hide-citation (t, integer)'

`gnus-treat-hide-citation-maybe (t, integer)'

`gnus-treat-hide-headers (head)'

`gnus-treat-hide-signature (t, last)'

`gnus-treat-strip-banner (t, last)'

`gnus-treat-strip-list-identifiers (head)'
     *Note Article Hiding::.

`gnus-treat-highlight-citation (t, integer)'

`gnus-treat-highlight-headers (head)'

`gnus-treat-highlight-signature (t, last, integer)'
     *Note Article Highlighting::.

`gnus-treat-play-sounds'

`gnus-treat-ansi-sequences (t)'

`gnus-treat-x-pgp-sig (head)'

`gnus-treat-unfold-headers (head)'

`gnus-treat-fold-headers (head)'

`gnus-treat-fold-newsgroups (head)'

`gnus-treat-leading-whitespace (head)'
     *Note Article Header::.


   You can, of course, write your own functions to be called from
`gnus-part-display-hook'.  The functions are called narrowed to the
part, and you can do anything you like, pretty much.  There is no
information that you have to keep in the buffer--you can change
everything.


File: gnus,  Node: Article Keymap,  Next: Misc Article,  Prev: Customizing Articles,  Up: Article Buffer

4.5 Article Keymap
==================

Most of the keystrokes in the summary buffer can also be used in the
article buffer.  They should behave as if you typed them in the summary
buffer, which means that you don't actually have to have a summary
buffer displayed while reading.  You can do it all from the article
buffer.

   The key `v' is reserved for users.  You can bind it to some command
or better use it as a prefix key.

   A few additional keystrokes are available:

`SPACE'
     Scroll forwards one page (`gnus-article-next-page').  This is
     exactly the same as `h SPACE h'.

`DEL'
     Scroll backwards one page (`gnus-article-prev-page').  This is
     exactly the same as `h DEL h'.

`C-c ^'
     If point is in the neighborhood of a `Message-ID' and you press
     `C-c ^', Gnus will try to get that article from the server
     (`gnus-article-refer-article').

`C-c C-m'
     Send a reply to the address near point (`gnus-article-mail').  If
     given a prefix, include the mail.

`s'
     Reconfigure the buffers so that the summary buffer becomes visible
     (`gnus-article-show-summary').

`?'
     Give a very brief description of the available keystrokes
     (`gnus-article-describe-briefly').

`TAB'
     Go to the next button, if any (`gnus-article-next-button').  This
     only makes sense if you have buttonizing turned on.

`M-TAB'
     Go to the previous button, if any (`gnus-article-prev-button').

`R'
     Send a reply to the current article and yank the current article
     (`gnus-article-reply-with-original').  If the region is active,
     only yank the text in the region.

`S W'
     Send a wide reply to the current article and yank the current
     article (`gnus-article-wide-reply-with-original').  If the region
     is active, only yank the text in the region.

`F'
     Send a followup to the current article and yank the current article
     (`gnus-article-followup-with-original').  If the region is active,
     only yank the text in the region.



File: gnus,  Node: Misc Article,  Prev: Article Keymap,  Up: Article Buffer

4.6 Misc Article
================

`gnus-single-article-buffer'
     If non-`nil', use the same article buffer for all the groups.
     (This is the default.)  If `nil', each group will have its own
     article buffer.

`gnus-widen-article-window'
     If non-`nil', selecting the article buffer with the `h' command
     will "widen" the article window to take the entire frame.

`gnus-article-decode-hook'
     Hook used to decode MIME articles.  The default value is
     `(article-decode-charset article-decode-encoded-words)'

`gnus-article-prepare-hook'
     This hook is called right after the article has been inserted into
     the article buffer.  It is mainly intended for functions that do
     something depending on the contents; it should probably not be
     used for changing the contents of the article buffer.

`gnus-article-mode-hook'
     Hook called in article mode buffers.

`gnus-article-mode-syntax-table'
     Syntax table used in article buffers.  It is initialized from
     `text-mode-syntax-table'.

`gnus-article-over-scroll'
     If non-`nil', allow scrolling the article buffer even when there
     no more new text to scroll in.  The default is `nil'.

`gnus-article-mode-line-format'
     This variable is a format string along the same lines as
     `gnus-summary-mode-line-format' (*note Summary Buffer Mode
     Line::).  It accepts the same format specifications as that
     variable, with two extensions:

    `w'
          The "wash status" of the article.  This is a short string
          with one character for each possible article wash operation
          that may have been performed.  The characters and their
          meaning:

         `c'
               Displayed when cited text may be hidden in the article
               buffer.

         `h'
               Displayed when headers are hidden in the article buffer.

         `p'
               Displayed when article is digitally signed or encrypted,
               and Gnus has hidden the security headers.  (N.B. does
               not tell anything about security status, i.e. good or
               bad signature.)

         `s'
               Displayed when the signature has been hidden in the
               Article buffer.

         `o'
               Displayed when Gnus has treated overstrike characters in
               the article buffer.

         `e'
               Displayed when Gnus has treated emphasized strings in
               the article buffer.


    `m'
          The number of MIME parts in the article.


`gnus-break-pages'
     Controls whether "page breaking" is to take place.  If this
     variable is non-`nil', the articles will be divided into pages
     whenever a page delimiter appears in the article.  If this
     variable is `nil', paging will not be done.

`gnus-page-delimiter'
     This is the delimiter mentioned above.  By default, it is `^L'
     (formfeed).

`gnus-use-idna'
     This variable controls whether Gnus performs IDNA decoding of
     internationalized domain names inside `From', `To' and `Cc'
     headers.  *Note IDNA: (message)IDNA, for how to compose such
     messages.  This requires GNU Libidn
     (http://www.gnu.org/software/libidn/), and this variable is only
     enabled if you have installed it.

`gnus-inhibit-images'
     If this is non-`nil', inhibit displaying of images inline in the
     article body.  It is effective to images that are in articles as
     MIME parts, and images in HTML articles rendered when
     `mm-text-html-renderer' (*note Display Customization:
     (emacs-mime)Display Customization.) is `shr' or `gnus-w3m'.



File: gnus,  Node: Composing Messages,  Next: Select Methods,  Prev: Article Buffer,  Up: Top

5 Composing Messages
********************

All commands for posting and mailing will put you in a message buffer
where you can edit the article all you like, before you send the
article by pressing `C-c C-c'.  *Note Overview: (message)Top.  Where
the message will be posted/mailed to depends on your setup (*note
Posting Server::).

* Menu:

* Mail::                        Mailing and replying.
* Posting Server::              What server should you post and mail via?
* POP before SMTP::             You cannot send a mail unless you read a mail.
* Mail and Post::               Mailing and posting at the same time.
* Archived Messages::           Where Gnus stores the messages you've sent.
* Posting Styles::              An easier way to specify who you are.
* Drafts::                      Postponing messages and rejected messages.
* Rejected Articles::           What happens if the server doesn't like your article?
* Signing and encrypting::      How to compose secure messages.

   Also *note Canceling and Superseding:: for information on how to
remove articles you shouldn't have posted.


File: gnus,  Node: Mail,  Next: Posting Server,  Up: Composing Messages

5.1 Mail
========

Variables for customizing outgoing mail:

`gnus-uu-digest-headers'
     List of regexps to match headers included in digested messages.
     The headers will be included in the sequence they are matched.  If
     `nil' include all headers.

`gnus-add-to-list'
     If non-`nil', add a `to-list' group parameter to mail groups that
     have none when you do a `a'.

`gnus-confirm-mail-reply-to-news'
     If non-`nil', Gnus will ask you for a confirmation when you are
     about to reply to news articles by mail.  If it is `nil', nothing
     interferes in what you want to do.  This can also be a function
     receiving the group name as the only parameter which should return
     non-`nil' if a confirmation is needed, or a regular expression
     matching group names, where confirmation should be asked for.

     If you find yourself never wanting to reply to mail, but
     occasionally press `R' anyway, this variable might be for you.

`gnus-confirm-treat-mail-like-news'
     If non-`nil', Gnus also requests confirmation according to
     `gnus-confirm-mail-reply-to-news' when replying to mail.  This is
     useful for treating mailing lists like newsgroups.



File: gnus,  Node: Posting Server,  Next: POP before SMTP,  Prev: Mail,  Up: Composing Messages

5.2 Posting Server
==================

When you press those magical `C-c C-c' keys to ship off your latest
(extremely intelligent, of course) article, where does it go?

   Thank you for asking.  I hate you.

   It can be quite complicated.

   When posting news, Message usually invokes `message-send-news'
(*note News Variables: (message)News Variables.).  Normally, Gnus will
post using the same select method as you're reading from (which might
be convenient if you're reading lots of groups from different private
servers).  However.  If the server you're reading from doesn't allow
posting, just reading, you probably want to use some other server to
post your (extremely intelligent and fabulously interesting) articles.
You can then set the `gnus-post-method' to some other method:

     (setq gnus-post-method '(nnspool ""))

   Now, if you've done this, and then this server rejects your article,
or this server is down, what do you do then?  To override this variable
you can use a non-zero prefix to the `C-c C-c' command to force using
the "current" server, to get back the default behavior, for posting.

   If you give a zero prefix (i.e., `C-u 0 C-c C-c') to that command,
Gnus will prompt you for what method to use for posting.

   You can also set `gnus-post-method' to a list of select methods.  If
that's the case, Gnus will always prompt you for what method to use for
posting.

   Finally, if you want to always post using the native select method,
you can set this variable to `native'.

   When sending mail, Message invokes the function specified by the
variable `message-send-mail-function'.  Gnus tries to set it to a value
suitable for your system.  *Note Mail Variables: (message)Mail
Variables, for more information.


File: gnus,  Node: POP before SMTP,  Next: Mail and Post,  Prev: Posting Server,  Up: Composing Messages

5.3 POP before SMTP
===================

Does your ISP require the POP-before-SMTP authentication?  It is
whether you need to connect to the POP mail server within a certain
time before sending mails.  If so, there is a convenient way.  To do
that, put the following lines in your `~/.gnus.el' file:

     (setq message-send-mail-function 'message-smtpmail-send-it)
     (add-hook 'message-send-mail-hook 'mail-source-touch-pop)

It means to let Gnus connect to the POP mail server in advance whenever
you send a mail.  The `mail-source-touch-pop' function does only a POP
authentication according to the value of `mail-sources' without
fetching mails, just before sending a mail.  Note that you have to use
`message-smtpmail-send-it' which runs `message-send-mail-hook' rather
than `smtpmail-send-it' and set the value of `mail-sources' for a POP
connection correctly.  *Note Mail Sources::.

   If you have two or more POP mail servers set in `mail-sources', you
may want to specify one of them to `mail-source-primary-source' as the
POP mail server to be used for the POP-before-SMTP authentication.  If
it is your primary POP mail server (i.e., you are fetching mails mainly
from that server), you can set it permanently as follows:

     (setq mail-source-primary-source
           '(pop :server "pop3.mail.server"
                 :password "secret"))

Otherwise, bind it dynamically only when performing the POP-before-SMTP
authentication as follows:

     (add-hook 'message-send-mail-hook
               (lambda ()
                 (let ((mail-source-primary-source
                        '(pop :server "pop3.mail.server"
                              :password "secret")))
                   (mail-source-touch-pop))))


File: gnus,  Node: Mail and Post,  Next: Archived Messages,  Prev: POP before SMTP,  Up: Composing Messages

5.4 Mail and Post
=================

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

`gnus-mailing-list-groups'
     If your news server offers groups that are really mailing lists
     gatewayed to the NNTP server, you can read those groups without
     problems, but you can't post/followup to them without some
     difficulty.  One solution is to add a `to-address' to the group
     parameters (*note Group Parameters::).  An easier thing to do is
     set the `gnus-mailing-list-groups' to a regexp that matches the
     groups that really are mailing lists.  Then, at least, followups
     to the mailing lists will work most of the time.  Posting to these
     groups (`a') is still a pain, though.

`gnus-user-agent'
     This variable controls which information should be exposed in the
     User-Agent header.  It can be a list of symbols or a string.  Valid
     symbols are `gnus' (show Gnus version) and `emacs' (show Emacs
     version).  In addition to the Emacs version, you can add `codename'
     (show (S)XEmacs codename) or either `config' (show system
     configuration) or `type' (show system type).  If you set it to a
     string, be sure to use a valid format, see RFC 2616.


   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 'message-send-hook 'ispell-message)

   If you want to change the `ispell' dictionary based on what group
you're in, you could say something like the following:

     (add-hook 'gnus-select-group-hook
               (lambda ()
                 (cond
                  ((string-match
                    "^de\\." (gnus-group-real-name gnus-newsgroup-name))
                   (ispell-change-dictionary "deutsch"))
                  (t
                   (ispell-change-dictionary "english")))))

   Modify to suit your needs.

   If `gnus-message-highlight-citation' is t, different levels of
citations are highlighted like in Gnus article buffers also in message
mode buffers.


File: gnus,  Node: Archived Messages,  Next: Posting Styles,  Prev: Mail and Post,  Up: Composing Messages

5.5 Archived Messages
=====================

Gnus provides a few different methods for storing the mail and news you
send.  The default method is to use the "archive virtual server" to
store the messages.  If you want to disable this completely, the
`gnus-message-archive-group' variable should be `nil'.  The default is
"sent.%Y-%m", which gives you one archive group per month.

   For archiving interesting messages in a group you read, see the `B
c' (`gnus-summary-copy-article') command (*note Mail Group Commands::).

   `gnus-message-archive-method' says what virtual server Gnus is to
use to store sent messages.  The default is `"archive"', and when
actually being used it is expanded into:

     (nnfolder "archive"
               (nnfolder-directory   "~/Mail/archive")
               (nnfolder-active-file "~/Mail/archive/active")
               (nnfolder-get-new-mail nil)
               (nnfolder-inhibit-expiry t))

     Note: a server like this is saved in the `~/.newsrc.eld' file first
     so that it may be used as a real method of the server which is
     named `"archive"' (that is, for the case where
     `gnus-message-archive-method' is set to `"archive"') ever since.
     If it once has been saved, it will never be updated by default
     even if you change the value of `gnus-message-archive-method'
     afterward.  Therefore, the server `"archive"' doesn't necessarily
     mean the `nnfolder' server like this at all times.  If you want the
     saved method to reflect always the value of
     `gnus-message-archive-method', set the
     `gnus-update-message-archive-method' variable to a non-`nil'
     value.  The default value of this variable is `nil'.

   You can, however, use any mail select method (`nnml', `nnmbox',
etc.).  `nnfolder' is a quite likable select method for doing this sort
of thing, though.  If you don't like the default directory chosen, you
could say something like:

     (setq gnus-message-archive-method
           '(nnfolder "archive"
                      (nnfolder-inhibit-expiry t)
                      (nnfolder-active-file "~/News/sent-mail/active")
                      (nnfolder-directory "~/News/sent-mail/")))

   Gnus will insert `Gcc' headers in all outgoing messages that point
to one or more group(s) on that server.  Which group to use is
determined by the `gnus-message-archive-group' variable.

   This variable can be used to do the following:

a string
     Messages will be saved in that group.

     Note that you can include a select method in the group name, then
     the message will not be stored in the select method given by
     `gnus-message-archive-method', but in the select method specified
     by the group name, instead.  Suppose `gnus-message-archive-method'
     has the default value shown above.  Then setting
     `gnus-message-archive-group' to `"foo"' means that outgoing
     messages are stored in `nnfolder+archive:foo', but if you use the
     value `"nnml:foo"', then outgoing messages will be stored in
     `nnml:foo'.

a list of strings
     Messages will be saved in all those groups.

an alist of regexps, functions and forms
     When a key "matches", the result is used.

`nil'
     No message archiving will take place.

   Let's illustrate:

   Just saving to a single group called `MisK':
     (setq gnus-message-archive-group "MisK")

   Saving to two groups, `MisK' and `safe':
     (setq gnus-message-archive-group '("MisK" "safe"))

   Save to different groups based on what group you are in:
     (setq gnus-message-archive-group
           '(("^alt" "sent-to-alt")
             ("mail" "sent-to-mail")
             (".*" "sent-to-misc")))

   More complex stuff:
     (setq gnus-message-archive-group
           '((if (message-news-p)
                 "misc-news"
               "misc-mail")))

   How about storing all news messages in one file, but storing all mail
messages in one file per month:

     (setq gnus-message-archive-group
           '((if (message-news-p)
                 "misc-news"
               (concat "mail." (format-time-string "%Y-%m")))))

   Now, when you send a message off, it will be stored in the
appropriate group.  (If you want to disable storing for just one
particular message, you can just remove the `Gcc' header that has been
inserted.)  The archive group will appear in the group buffer the next
time you start Gnus, or the next time you press `F' in the group
buffer.  You can enter it and read the articles in it just like you'd
read any other group.  If the group gets really big and annoying, you
can simply rename if (using `G r' in the group buffer) to something
nice--`misc-mail-september-1995', or whatever.  New messages will
continue to be stored in the old (now empty) group.

`gnus-gcc-mark-as-read'
     If non-`nil', automatically mark `Gcc' articles as read.

`gnus-gcc-externalize-attachments'
     If `nil', attach files as normal parts in Gcc copies; if a regexp
     and matches the Gcc group name, attach files as external parts; if
     it is `all', attach local files as external parts; if it is other
     non-`nil', the behavior is the same as `all', but it may be
     changed in the future.



File: gnus,  Node: Posting Styles,  Next: Drafts,  Prev: Archived Messages,  Up: Composing Messages

5.6 Posting Styles
==================

All them variables, they make my head swim.

   So what if you want a different `Organization' and signature based
on what groups you post to?  And you post both from your home machine
and your work machine, and you want different `From' lines, and so on?

   One way to do stuff like that is to write clever hooks that change
the variables you need to have changed.  That's a bit boring, so
somebody came up with the bright idea of letting the user specify these
things in a handy alist.  Here's an example of a `gnus-posting-styles'
variable:

     ((".*"
       (signature "Peace and happiness")
       (organization "What me?"))
      ("^comp"
       (signature "Death to everybody"))
      ("comp.emacs.i-love-it"
       (organization "Emacs is it")))

   As you might surmise from this example, this alist consists of
several "styles".  Each style will be applicable if the first element
"matches", in some form or other.  The entire alist will be iterated
over, from the beginning towards the end, and each match will be
applied, which means that attributes in later styles that match override
the same attributes in earlier matching styles.  So
`comp.programming.literate' will have the `Death to everybody'
signature and the `What me?' `Organization' header.

   The first element in each style is called the `match'.  If it's a
string, then Gnus will try to regexp match it against the group name.
If it is the form `(header MATCH REGEXP)', then Gnus will look in the
original article for a header whose name is MATCH and compare that
REGEXP.  MATCH and REGEXP are strings.  (The original article is the
one you are replying or following up to.  If you are not composing a
reply or a followup, then there is nothing to match against.)  If the
`match' is a function symbol, that function will be called with no
arguments.  If it's a variable symbol, then the variable will be
referenced.  If it's a list, then that list will be `eval'ed.  In any
case, if this returns a non-`nil' value, then the style is said to
"match".

   Each style may contain an arbitrary amount of "attributes".  Each
attribute consists of a `(NAME VALUE)' pair.  In addition, you can also
use the `(NAME :file VALUE)' form or the `(NAME :value VALUE)' form.
Where `:file' signifies VALUE represents a file name and its contents
should be used as the attribute value, `:value' signifies VALUE does
not represent a file name explicitly.  The attribute name can be one of:

   * `signature'

   * `signature-file'

   * `x-face-file'

   * `address', overriding `user-mail-address'

   * `name', overriding `(user-full-name)'

   * `body'

   Note that the `signature-file' attribute honors the variable
`message-signature-directory'.

   The attribute name can also be a string or a symbol.  In that case,
this will be used as a header name, and the value will be inserted in
the headers of the article; if the value is `nil', the header name will
be removed.  If the attribute name is `eval', the form is evaluated,
and the result is thrown away.

   The attribute value can be a string, a function with zero arguments
(the return value will be used), a variable (its value will be used) or
a list (it will be `eval'ed and the return value will be used).  The
functions and sexps are called/`eval'ed in the message buffer that is
being set up.  The headers of the current article are available through
the `message-reply-headers' variable, which is a vector of the
following headers: number subject from date id references chars lines
xref extra.

   In the case of a string value, if the `match' is a regular
expression, a `gnus-match-substitute-replacement' is proceed on the
value to replace the positional parameters `\N' by the corresponding
parenthetical matches (see *Note Replacing the Text that Matched:
(elisp)Replacing Match.)

   If you wish to check whether the message you are about to compose is
meant to be a news article or a mail message, you can check the values
of the `message-news-p' and `message-mail-p' functions.

   So here's a new example:

     (setq gnus-posting-styles
           '((".*"
              (signature-file "~/.signature")
              (name "User Name")
              (x-face-file "~/.xface")
              (x-url (getenv "WWW_HOME"))
              (organization "People's Front Against MWM"))
             ("^rec.humor"
              (signature my-funny-signature-randomizer))
             ((equal (system-name) "gnarly")  ;; A form
              (signature my-quote-randomizer))
             (message-news-p        ;; A function symbol
              (signature my-news-signature))
             (window-system         ;; A value symbol
              ("X-Window-System" (format "%s" window-system)))
             ;; If I'm replying to Larsi, set the Organization header.
             ((header "from" "larsi.*org")
              (Organization "Somewhere, Inc."))
             ((posting-from-work-p) ;; A user defined function
              (signature-file "~/.work-signature")
              (address "user@bar.foo")
              (body "You are fired.\n\nSincerely, your boss.")
              (organization "Important Work, Inc"))
             ("nnml:.*"
              (From (with-current-buffer gnus-article-buffer
                      (message-fetch-field "to"))))
             ("^nn.+:"
              (signature-file "~/.mail-signature"))))

   The `nnml:.*' rule means that you use the `To' address as the `From'
address in all your outgoing replies, which might be handy if you fill
many roles.  You may also use `message-alternative-emails' instead.
*Note Message Headers: (message)Message Headers.


File: gnus,  Node: Drafts,  Next: Rejected Articles,  Prev: Posting Styles,  Up: Composing Messages

5.7 Drafts
==========

If you are writing a message (mail or news) and suddenly remember that
you have a steak in the oven (or some pesto in the food processor, you
craaazy vegetarians), you'll probably wish there was a method to save
the message you are writing so that you can continue editing it some
other day, and send it when you feel its finished.

   Well, don't worry about it.  Whenever you start composing a message
of some sort using the Gnus mail and post commands, the buffer you get
will automatically associate to an article in a special "draft" group.
If you save the buffer the normal way (`C-x C-s', for instance), the
article will be saved there.  (Auto-save files also go to the draft
group.)

   The draft group is a special group (which is implemented as an
`nndraft' group, if you absolutely have to know) called
`nndraft:drafts'.  The variable `nndraft-directory' says where
`nndraft' is to store its files.  What makes this group special is that
you can't tick any articles in it or mark any articles as read--all
articles in the group are permanently unread.

   If the group doesn't exist, it will be created and you'll be
subscribed to it.  The only way to make it disappear from the Group
buffer is to unsubscribe it.  The special properties of the draft group
comes from a group property (*note Group Parameters::), and if lost the
group behaves like any other group.  This means the commands below will
not be available.  To restore the special properties of the group, the
simplest way is to kill the group, using `C-k', and restart Gnus.  The
group is automatically created again with the correct parameters.  The
content of the group is not lost.

   When you want to continue editing the article, you simply enter the
draft group and push `D e' (`gnus-draft-edit-message') to do that.  You
will be placed in a buffer where you left off.

   Rejected articles will also be put in this draft group (*note
Rejected Articles::).

   If you have lots of rejected messages you want to post (or mail)
without doing further editing, you can use the `D s' command
(`gnus-draft-send-message').  This command understands the
process/prefix convention (*note Process/Prefix::).  The `D S' command
(`gnus-draft-send-all-messages') will ship off all messages in the
buffer.

   If you have some messages that you wish not to send, you can use the
`D t' (`gnus-draft-toggle-sending') command to mark the message as
unsendable.  This is a toggling command.

   Finally, if you want to delete a draft, use the normal `B DEL'
command (*note Mail Group Commands::).


File: gnus,  Node: Rejected Articles,  Next: Signing and encrypting,  Prev: Drafts,  Up: Composing Messages

5.8 Rejected Articles
=====================

Sometimes a news server will reject an article.  Perhaps the server
doesn't like your face.  Perhaps it just feels miserable.  Perhaps
_there be demons_.  Perhaps you have included too much cited text.
Perhaps the disk is full.  Perhaps the server is down.

   These situations are, of course, totally beyond the control of Gnus.
(Gnus, of course, loves the way you look, always feels great, has angels
fluttering around inside of it, doesn't care about how much cited text
you include, never runs full and never goes down.)  So Gnus saves these
articles until some later time when the server feels better.

   The rejected articles will automatically be put in a special draft
group (*note Drafts::).  When the server comes back up again, you'd then
typically enter that group and send all the articles off.


File: gnus,  Node: Signing and encrypting,  Prev: Rejected Articles,  Up: Composing Messages

5.9 Signing and encrypting
==========================

Gnus can digitally sign and encrypt your messages, using vanilla PGP
format or PGP/MIME or S/MIME.  For decoding such messages, see the
`mm-verify-option' and `mm-decrypt-option' options (*note Security::).

   Often, you would like to sign replies to people who send you signed
messages.  Even more often, you might want to encrypt messages which
are in reply to encrypted messages.  Gnus offers
`gnus-message-replysign' to enable the former, and
`gnus-message-replyencrypt' for the latter.  In addition, setting
`gnus-message-replysignencrypted' (on by default) will sign
automatically encrypted messages.

   Instructing MML to perform security operations on a MIME part is
done using the `C-c C-m s' key map for signing and the `C-c C-m c' key
map for encryption, as follows.

`C-c C-m s s'
     Digitally sign current message using S/MIME.

`C-c C-m s o'
     Digitally sign current message using PGP.

`C-c C-m s p'
     Digitally sign current message using PGP/MIME.

`C-c C-m c s'
     Digitally encrypt current message using S/MIME.

`C-c C-m c o'
     Digitally encrypt current message using PGP.

`C-c C-m c p'
     Digitally encrypt current message using PGP/MIME.

`C-c C-m C-n'
     Remove security related MML tags from message.


   *Note Security: (message)Security, for more information.


File: gnus,  Node: Select Methods,  Next: Scoring,  Prev: Composing Messages,  Up: Top

6 Select Methods
****************

A "foreign group" is a group not read by the usual (or default) means.
It could be, for instance, a group from a different NNTP server, it
could be a virtual group, or it could be your own personal mail group.

   A foreign group (or any group, really) is specified by a "name" and
a "select method".  To take the latter first, a select method is a list
where the first element says what back end to use (e.g. `nntp',
`nnspool', `nnml') and the second element is the "server name".  There
may be additional elements in the select method, where the value may
have special meaning for the back end in question.

   One could say that a select method defines a "virtual server"--so we
do just that (*note Server Buffer::).

   The "name" of the group is the name the back end will recognize the
group as.

   For instance, the group `soc.motss' on the NNTP server
`some.where.edu' will have the name `soc.motss' and select method
`(nntp "some.where.edu")'.  Gnus will call this group
`nntp+some.where.edu:soc.motss', even though the `nntp' back end just
knows this group as `soc.motss'.

   The different methods all have their peculiarities, of course.

* Menu:

* Server Buffer::               Making and editing virtual servers.
* Getting News::                Reading USENET news with Gnus.
* Using IMAP::                  Reading mail from IMAP.
* Getting Mail::                Reading your personal mail with Gnus.
* Browsing the Web::            Getting messages from a plethora of Web sources.
* Other Sources::               Reading directories, files.
* Combined Groups::             Combining groups into one group.
* Email Based Diary::           Using mails to manage diary events in Gnus.
* Gnus Unplugged::              Reading news and mail offline.


File: gnus,  Node: Server Buffer,  Next: Getting News,  Up: Select Methods

6.1 Server Buffer
=================

Traditionally, a "server" is a machine or a piece of software that one
connects to, and then requests information from.  Gnus does not connect
directly to any real servers, but does all transactions through one
back end or other.  But that's just putting one layer more between the
actual media and Gnus, so we might just as well say that each back end
represents a virtual server.

   For instance, the `nntp' back end may be used to connect to several
different actual NNTP servers, or, perhaps, to many different ports on
the same actual NNTP server.  You tell Gnus which back end to use, and
what parameters to set by specifying a "select method".

   These select method specifications can sometimes become quite
complicated--say, for instance, that you want to read from the NNTP
server `news.funet.fi' on port number 13, which hangs if queried for
NOV headers and has a buggy select.  Ahem.  Anyway, if you had to
specify that for each group that used this server, that would be too
much work, so Gnus offers a way of naming select methods, which is what
you do in the server buffer.

   To enter the server buffer, use the `^'
(`gnus-group-enter-server-mode') command in the group buffer.

* Menu:

* Server Buffer Format::        You can customize the look of this buffer.
* Server Commands::             Commands to manipulate servers.
* Example Methods::             Examples server specifications.
* Creating a Virtual Server::   An example session.
* Server Variables::            Which variables to set.
* Servers and Methods::         You can use server names as select methods.
* Unavailable Servers::         Some servers you try to contact may be down.

   `gnus-server-mode-hook' is run when creating the server buffer.


File: gnus,  Node: Server Buffer Format,  Next: Server Commands,  Up: Server Buffer

6.1.1 Server Buffer Format
--------------------------

You can change the look of the server buffer lines by changing the
`gnus-server-line-format' variable.  This is a `format'-like variable,
with some simple extensions:

`h'
     How the news is fetched--the back end name.

`n'
     The name of this server.

`w'
     Where the news is to be fetched from--the address.

`s'
     The opened/closed/denied status of the server.

`a'
     Whether this server is agentized.

   The mode line can also be customized by using the
`gnus-server-mode-line-format' variable (*note Mode Line Formatting::).
The following specs are understood:

`S'
     Server name.

`M'
     Server method.

   Also *note Formatting Variables::.


File: gnus,  Node: Server Commands,  Next: Example Methods,  Prev: Server Buffer Format,  Up: Server Buffer

6.1.2 Server Commands
---------------------

`v'
     The key `v' is reserved for users.  You can bind it to some
     command or better use it as a prefix key.

`a'
     Add a new server (`gnus-server-add-server').

`e'
     Edit a server (`gnus-server-edit-server').

`S'
     Show the definition of a server (`gnus-server-show-server').

`SPACE'
     Browse the current server (`gnus-server-read-server').

`q'
     Return to the group buffer (`gnus-server-exit').

`k'
     Kill the current server (`gnus-server-kill-server').

`y'
     Yank the previously killed server (`gnus-server-yank-server').

`c'
     Copy the current server (`gnus-server-copy-server').

`l'
     List all servers (`gnus-server-list-servers').

`s'
     Request that the server scan its sources for new articles
     (`gnus-server-scan-server').  This is mainly sensible with mail
     servers.

`g'
     Request that the server regenerate all its data structures
     (`gnus-server-regenerate-server').  This can be useful if you have
     a mail back end that has gotten out of sync.

`z'
     Compact all groups in the server under point
     (`gnus-server-compact-server').  Currently implemented only in
     nnml (*note Mail Spool::).  This removes gaps between article
     numbers, hence getting a correct total article count.


   Some more commands for closing, disabling, and re-opening servers are
listed in *note Unavailable Servers::.


File: gnus,  Node: Example Methods,  Next: Creating a Virtual Server,  Prev: Server Commands,  Up: Server Buffer

6.1.3 Example Methods
---------------------

Most select methods are pretty simple and self-explanatory:

     (nntp "news.funet.fi")

   Reading directly from the spool is even simpler:

     (nnspool "")

   As you can see, the first element in a select method is the name of
the back end, and the second is the "address", or "name", if you will.

   After these two elements, there may be an arbitrary number of
`(VARIABLE FORM)' pairs.

   To go back to the first example--imagine that you want to read from
port 15 on that machine.  This is what the select method should look
like then:

     (nntp "news.funet.fi" (nntp-port-number 15))

   You should read the documentation to each back end to find out what
variables are relevant, but here's an `nnmh' example:

   `nnmh' is a mail back end that reads a spool-like structure.  Say
you have two structures that you wish to access: One is your private
mail spool, and the other is a public one.  Here's the possible spec for
your private mail:

     (nnmh "private" (nnmh-directory "~/private/mail/"))

   (This server is then called `private', but you may have guessed
that.)

   Here's the method for a public spool:

     (nnmh "public"
           (nnmh-directory "/usr/information/spool/")
           (nnmh-get-new-mail nil))

   If you are behind a firewall and only have access to the NNTP server
from the firewall machine, you can instruct Gnus to `rlogin' on the
firewall machine and connect with netcat
(http://netcat.sourceforge.net/) from there to the NNTP server.  Doing
this can be rather fiddly, but your virtual server definition should
probably look something like this:

     (nntp "firewall"
           (nntp-open-connection-function nntp-open-via-rlogin-and-netcat)
           (nntp-via-address "the.firewall.machine")
           (nntp-address "the.real.nntp.host"))

   If you want to use the wonderful `ssh' program to provide a
compressed connection over the modem line, you could add the following
configuration to the example above:

           (nntp-via-rlogin-command "ssh")

   See also `nntp-via-rlogin-command-switches'.  Here's an example for
an indirect connection:

     (setq gnus-select-method
           '(nntp "indirect"
                  (nntp-address "news.server.example")
                  (nntp-via-user-name "intermediate_user_name")
                  (nntp-via-address "intermediate.host.example")
                  (nntp-via-rlogin-command "ssh")
                  (nntp-via-rlogin-command-switches ("-C"))
                  (nntp-open-connection-function nntp-open-via-rlogin-and-netcat)))

   This means that you have to have set up `ssh-agent' correctly to
provide automatic authorization, of course.

   If you're behind a firewall, but have direct access to the outside
world through a wrapper command like "runsocks", you could open a
socksified netcat connection to the news server as follows:

     (nntp "outside"
           (nntp-pre-command "runsocks")
           (nntp-open-connection-function nntp-open-netcat-stream)
           (nntp-address "the.news.server"))


File: gnus,  Node: Creating a Virtual Server,  Next: Server Variables,  Prev: Example Methods,  Up: Server Buffer

6.1.4 Creating a Virtual Server
-------------------------------

If you're saving lots of articles in the cache by using persistent
articles, you may want to create a virtual server to read the cache.

   First you need to add a new server.  The `a' command does that.  It
would probably be best to use `nnml' to read the cache.  You could also
use `nnspool' or `nnmh', though.

   Type `a nnml RET cache RET'.

   You should now have a brand new `nnml' virtual server called
`cache'.  You now need to edit it to have the right definitions.  Type
`e' to edit the server.  You'll be entered into a buffer that will
contain the following:

     (nnml "cache")

   Change that to:

     (nnml "cache"
              (nnml-directory "~/News/cache/")
              (nnml-active-file "~/News/cache/active"))

   Type `C-c C-c' to return to the server buffer.  If you now press
`RET' over this virtual server, you should be entered into a browse
buffer, and you should be able to enter any of the groups displayed.


File: gnus,  Node: Server Variables,  Next: Servers and Methods,  Prev: Creating a Virtual Server,  Up: Server Buffer

6.1.5 Server Variables
----------------------

One sticky point when defining variables (both on back ends and in Emacs
in general) is that some variables are typically initialized from other
variables when the definition of the variables is being loaded.  If you
change the "base" variable after the variables have been loaded, you
won't change the "derived" variables.

   This typically affects directory and file variables.  For instance,
`nnml-directory' is `~/Mail/' by default, and all `nnml' directory
variables are initialized from that variable, so `nnml-active-file'
will be `~/Mail/active'.  If you define a new virtual `nnml' server, it
will _not_ suffice to set just `nnml-directory'--you have to explicitly
set all the file variables to be what you want them to be.  For a
complete list of variables for each back end, see each back end's
section later in this manual, but here's an example `nnml' definition:

     (nnml "public"
           (nnml-directory "~/my-mail/")
           (nnml-active-file "~/my-mail/active")
           (nnml-newsgroups-file "~/my-mail/newsgroups"))

   Server variables are often called "server parameters".


File: gnus,  Node: Servers and Methods,  Next: Unavailable Servers,  Prev: Server Variables,  Up: Server Buffer

6.1.6 Servers and Methods
-------------------------

Wherever you would normally use a select method (e.g.
`gnus-secondary-select-method', in the group select method, when
browsing a foreign server) you can use a virtual server name instead.
This could potentially save lots of typing.  And it's nice all over.


File: gnus,  Node: Unavailable Servers,  Prev: Servers and Methods,  Up: Server Buffer

6.1.7 Unavailable Servers
-------------------------

If a server seems to be unreachable, Gnus will mark that server as
`denied'.  That means that any subsequent attempt to make contact with
that server will just be ignored.  "It can't be opened," Gnus will tell
you, without making the least effort to see whether that is actually
the case or not.

   That might seem quite naughty, but it does make sense most of the
time.  Let's say you have 10 groups subscribed to on server
`nephelococcygia.com'.  This server is located somewhere quite far away
from you and the machine is quite slow, so it takes 1 minute just to
find out that it refuses connection to you today.  If Gnus were to
attempt to do that 10 times, you'd be quite annoyed, so Gnus won't
attempt to do that.  Once it has gotten a single "connection refused",
it will regard that server as "down".

   So, what happens if the machine was only feeling unwell temporarily?
How do you test to see whether the machine has come up again?

   You jump to the server buffer (*note Server Buffer::) and poke it
with the following commands:

`O'
     Try to establish connection to the server on the current line
     (`gnus-server-open-server').

`C'
     Close the connection (if any) to the server
     (`gnus-server-close-server').

`D'
     Mark the current server as unreachable (`gnus-server-deny-server').

`M-o'
     Open the connections to all servers in the buffer
     (`gnus-server-open-all-servers').

`M-c'
     Close the connections to all servers in the buffer
     (`gnus-server-close-all-servers').

`R'
     Remove all marks to whether Gnus was denied connection from any
     servers (`gnus-server-remove-denials').

`c'
     Copy a server and give it a new name (`gnus-server-copy-server').
     This can be useful if you have a complex method definition, and
     want to use the same definition towards a different (physical)
     server.

`L'
     Set server status to offline (`gnus-server-offline-server').



File: gnus,  Node: Getting News,  Next: Using IMAP,  Prev: Server Buffer,  Up: Select Methods

6.2 Getting News
================

A newsreader is normally used for reading news.  Gnus currently provides
only two methods of getting news--it can read from an NNTP server, or
it can read from a local spool.

* Menu:

* NNTP::                        Reading news from an NNTP server.
* News Spool::                  Reading news from the local spool.


File: gnus,  Node: NNTP,  Next: News Spool,  Up: Getting News

6.2.1 NNTP
----------

Subscribing to a foreign group from an NNTP server is rather easy.  You
just specify `nntp' as method and the address of the NNTP server as
the, uhm, address.

   If the NNTP server is located at a non-standard port, setting the
third element of the select method to this port number should allow you
to connect to the right port.  You'll have to edit the group info for
that (*note Foreign Groups::).

   The name of the foreign group can be the same as a native group.  In
fact, you can subscribe to the same group from as many different servers
you feel like.  There will be no name collisions.

   The following variables can be used to create a virtual `nntp'
server:

`nntp-server-opened-hook'
     is run after a connection has been made.  It can be used to send
     commands to the NNTP server after it has been contacted.  By
     default it sends the command `MODE READER' to the server with the
     `nntp-send-mode-reader' function.  This function should always be
     present in this hook.

`nntp-authinfo-function'
     This function will be used to send `AUTHINFO' to the NNTP server.
     The default function is `nntp-send-authinfo', which looks through
     your `~/.authinfo' (or whatever you've set the
     `nntp-authinfo-file' variable to) for applicable entries.  If none
     are found, it will prompt you for a login name and a password.  The
     format of the `~/.authinfo' file is (almost) the same as the `ftp'
     `~/.netrc' file, which is defined in the `ftp' manual page, but
     here are the salient facts:

       1. The file contains one or more line, each of which define one
          server.

       2. Each line may contain an arbitrary number of token/value
          pairs.

          The valid tokens include `machine', `login', `password',
          `default'.  In addition Gnus introduces two new tokens, not
          present in the original `.netrc'/`ftp' syntax, namely `port'
          and `force'.  (This is the only way the `.authinfo' file
          format deviates from the `.netrc' file format.)  `port' is
          used to indicate what port on the server the credentials
          apply to and `force' is explained below.


     Here's an example file:

          machine news.uio.no login larsi password geheimnis
          machine nntp.ifi.uio.no login larsi force yes

     The token/value pairs may appear in any order; `machine' doesn't
     have to be first, for instance.

     In this example, both login name and password have been supplied
     for the former server, while the latter has only the login name
     listed, and the user will be prompted for the password.  The
     latter also has the `force' tag, which means that the authinfo
     will be sent to the NNTP server upon connection; the default
     (i.e., when there is not `force' tag) is to not send authinfo to
     the NNTP server until the NNTP server asks for it.

     You can also add `default' lines that will apply to all servers
     that don't have matching `machine' lines.

          default force yes

     This will force sending `AUTHINFO' commands to all servers not
     previously mentioned.

     Remember to not leave the `~/.authinfo' file world-readable.

`nntp-server-action-alist'
     This is a list of regexps to match on server types and actions to
     be taken when matches are made.  For instance, if you want Gnus to
     beep every time you connect to innd, you could say something like:

          (setq nntp-server-action-alist
                '(("innd" (ding))))

     You probably don't want to do that, though.

     The default value is

          '(("nntpd 1\\.5\\.11t"
             (remove-hook 'nntp-server-opened-hook
                          'nntp-send-mode-reader)))

     This ensures that Gnus doesn't send the `MODE READER' command to
     nntpd 1.5.11t, since that command chokes that server, I've been
     told.

`nntp-maximum-request'
     If the NNTP server doesn't support NOV headers, this back end will
     collect headers by sending a series of `head' commands.  To speed
     things up, the back end sends lots of these commands without
     waiting for reply, and then reads all the replies.  This is
     controlled by the `nntp-maximum-request' variable, and is 400 by
     default.  If your network is buggy, you should set this to 1.

`nntp-connection-timeout'
     If you have lots of foreign `nntp' groups that you connect to
     regularly, you're sure to have problems with NNTP servers not
     responding properly, or being too loaded to reply within reasonable
     time.  This is can lead to awkward problems, which can be helped
     somewhat by setting `nntp-connection-timeout'.  This is an integer
     that says how many seconds the `nntp' back end should wait for a
     connection before giving up.  If it is `nil', which is the default,
     no timeouts are done.

`nntp-nov-is-evil'
     If the NNTP server does not support NOV, you could set this
     variable to `t', but `nntp' usually checks automatically whether
     NOV can be used.

`nntp-xover-commands'
     List of strings used as commands to fetch NOV lines from a server.
     The default value of this variable is `("XOVER" "XOVERVIEW")'.

`nntp-nov-gap'
     `nntp' normally sends just one big request for NOV lines to the
     server.  The server responds with one huge list of lines.  However,
     if you have read articles 2-5000 in the group, and only want to
     read article 1 and 5001, that means that `nntp' will fetch 4999 NOV
     lines that you will not need.  This variable says how big a gap
     between two consecutive articles is allowed to be before the
     `XOVER' request is split into several request.  Note that if your
     network is fast, setting this variable to a really small number
     means that fetching will probably be slower.  If this variable is
     `nil', `nntp' will never split requests.  The default is 5.

`nntp-xref-number-is-evil'
     When Gnus refers to an article having the `Message-ID' that a user
     specifies or having the `Message-ID' of the parent article of the
     current one (*note Finding the Parent::), Gnus sends a `HEAD'
     command to the NNTP server to know where it is, and the server
     returns the data containing the pairs of a group and an article
     number in the `Xref' header.  Gnus normally uses the article
     number to refer to the article if the data shows that that article
     is in the current group, while it uses the `Message-ID' otherwise.
     However, some news servers, e.g., ones running Diablo, run
     multiple engines having the same articles but article numbers are
     not kept synchronized between them.  In that case, the article
     number that appears in the `Xref' header varies by which engine is
     chosen, so you cannot refer to the parent article that is in the
     current group, for instance.  If you connect to such a server, set
     this variable to a non-`nil' value, and Gnus never uses article
     numbers.  For example:

          (setq gnus-select-method
                '(nntp "newszilla"
                       (nntp-address "newszilla.example.com")
                       (nntp-xref-number-is-evil t)
                       ...))

     The default value of this server variable is `nil'.

`nntp-prepare-server-hook'
     A hook run before attempting to connect to an NNTP server.

`nntp-record-commands'
     If non-`nil', `nntp' will log all commands it sends to the NNTP
     server (along with a timestamp) in the `*nntp-log*' buffer.  This
     is useful if you are debugging a Gnus/NNTP connection that doesn't
     seem to work.

`nntp-open-connection-function'
     It is possible to customize how the connection to the nntp server
     will be opened.  If you specify an `nntp-open-connection-function'
     parameter, Gnus will use that function to establish the connection.
     Seven pre-made functions are supplied.  These functions can be
     grouped in two categories: direct connection functions (four
     pre-made), and indirect ones (three pre-made).

`nntp-never-echoes-commands'
     Non-`nil' means the nntp server never echoes commands.  It is
     reported that some nntps server doesn't echo commands.  So, you
     may want to set this to non-`nil' in the method for such a server
     setting `nntp-open-connection-function' to `nntp-open-ssl-stream'
     for example.  The default value is `nil'.  Note that the
     `nntp-open-connection-functions-never-echo-commands' variable
     overrides the `nil' value of this variable.

`nntp-open-connection-functions-never-echo-commands'
     List of functions that never echo commands.  Add or set a function
     which you set to `nntp-open-connection-function' to this list if
     it does not echo commands.  Note that a non-`nil' value of the
     `nntp-never-echoes-commands' variable overrides this variable.  The
     default value is `(nntp-open-network-stream)'.

`nntp-prepare-post-hook'
     A hook run just before posting an article.  If there is no
     `Message-ID' header in the article and the news server provides the
     recommended ID, it will be added to the article before running this
     hook.  It is useful to make `Cancel-Lock' headers even if you
     inhibit Gnus to add a `Message-ID' header, you could say:

          (add-hook 'nntp-prepare-post-hook 'canlock-insert-header)

     Note that not all servers support the recommended ID.  This works
     for INN versions 2.3.0 and later, for instance.

`nntp-server-list-active-group'
     If `nil', then always use `GROUP' instead of `LIST ACTIVE'.  This
     is usually slower, but on misconfigured servers that don't update
     their active files often, this can help.


* Menu:

* Direct Functions::            Connecting directly to the server.
* Indirect Functions::          Connecting indirectly to the server.
* Common Variables::            Understood by several connection functions.
* NNTP marks::                  Storing marks for NNTP servers.


File: gnus,  Node: Direct Functions,  Next: Indirect Functions,  Up: NNTP

6.2.1.1 Direct Functions
........................

These functions are called direct because they open a direct connection
between your machine and the NNTP server.  The behavior of these
functions is also affected by commonly understood variables (*note
Common Variables::).

`nntp-open-network-stream'
     This is the default, and simply connects to some port or other on
     the remote system.  If both Emacs and the server supports it, the
     connection will be upgraded to an encrypted STARTTLS connection
     automatically.

`network-only'
     The same as the above, but don't do automatic STARTTLS upgrades.

`nntp-open-tls-stream'
     Opens a connection to a server over a "secure" channel.  To use
     this you must have GnuTLS (http://www.gnu.org/software/gnutls/)
     installed.  You then define a server as follows:

          ;; "nntps" is port 563 and is predefined in our `/etc/services'
          ;; however, `gnutls-cli -p' doesn't like named ports.
          ;;
          (nntp "snews.bar.com"
                (nntp-open-connection-function nntp-open-tls-stream)
                (nntp-port-number 563)
                (nntp-address "snews.bar.com"))

`nntp-open-ssl-stream'
     Opens a connection to a server over a "secure" channel.  To use
     this you must have OpenSSL (http://www.openssl.org) or SSLeay
     (ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL) installed.  You then
     define a server as follows:

          ;; "snews" is port 563 and is predefined in our `/etc/services'
          ;; however, `openssl s_client -port' doesn't like named ports.
          ;;
          (nntp "snews.bar.com"
                (nntp-open-connection-function nntp-open-ssl-stream)
                (nntp-port-number 563)
                (nntp-address "snews.bar.com"))

`nntp-open-netcat-stream'
     Opens a connection to an NNTP server using the `netcat' program.
     You might wonder why this function exists, since we have the
     default `nntp-open-network-stream' which would do the job.  (One
     of) the reason(s) is that if you are behind a firewall but have
     direct connections to the outside world thanks to a command
     wrapper like `runsocks', you can use it like this:

          (nntp "socksified"
                (nntp-pre-command "runsocks")
                (nntp-open-connection-function nntp-open-netcat-stream)
                (nntp-address "the.news.server"))

     With the default method, you would need to wrap your whole Emacs
     session, which is not a good idea.

`nntp-open-telnet-stream'
     Like `nntp-open-netcat-stream', but uses `telnet' rather than
     `netcat'.  `telnet' is a bit less robust because of things like
     line-end-conversion, but sometimes netcat is simply not available.
     The previous example would turn into:

          (nntp "socksified"
                (nntp-pre-command "runsocks")
                (nntp-open-connection-function nntp-open-telnet-stream)
                (nntp-address "the.news.server")
                (nntp-end-of-line "\n"))


File: gnus,  Node: Indirect Functions,  Next: Common Variables,  Prev: Direct Functions,  Up: NNTP

6.2.1.2 Indirect Functions
..........................

These functions are called indirect because they connect to an
intermediate host before actually connecting to the NNTP server.  All
of these functions and related variables are also said to belong to the
"via" family of connection: they're all prefixed with "via" to make
things cleaner.  The behavior of these functions is also affected by
commonly understood variables (*note Common Variables::).

`nntp-open-via-rlogin-and-netcat'
     Does an `rlogin' on a remote system, and then uses `netcat' to
     connect to the real NNTP server from there.  This is useful for
     instance if you need to connect to a firewall machine first.

     `nntp-open-via-rlogin-and-netcat'-specific variables:

    `nntp-via-rlogin-command'
          Command used to log in on the intermediate host.  The default
          is `rsh', but `ssh' is a popular alternative.

    `nntp-via-rlogin-command-switches'
          List of strings to be used as the switches to
          `nntp-via-rlogin-command'.  The default is `nil'.  If you use
          `ssh' for `nntp-via-rlogin-command', you may set this to
          `("-C")' in order to compress all data connections.

`nntp-open-via-rlogin-and-telnet'
     Does essentially the same, but uses `telnet' instead of `netcat'
     to connect to the real NNTP server from the intermediate host.
     `telnet' is a bit less robust because of things like
     line-end-conversion, but sometimes `netcat' is simply not
     available.

     `nntp-open-via-rlogin-and-telnet'-specific variables:

    `nntp-telnet-command'
          Command used to connect to the real NNTP server from the
          intermediate host.  The default is `telnet'.

    `nntp-telnet-switches'
          List of strings to be used as the switches to the
          `nntp-telnet-command' command.  The default is `("-8")'.

    `nntp-via-rlogin-command'
          Command used to log in on the intermediate host.  The default
          is `rsh', but `ssh' is a popular alternative.

    `nntp-via-rlogin-command-switches'
          List of strings to be used as the switches to
          `nntp-via-rlogin-command'.  If you use `ssh',  you may need
          to set this to `("-t" "-e" "none")' or `("-C" "-t" "-e"
          "none")' if the telnet command requires a pseudo-tty
          allocation on an intermediate host.  The default is `nil'.

     Note that you may want to change the value for `nntp-end-of-line'
     to `\n' (*note Common Variables::).

`nntp-open-via-telnet-and-telnet'
     Does essentially the same, but uses `telnet' instead of `rlogin'
     to connect to the intermediate host.

     `nntp-open-via-telnet-and-telnet'-specific variables:

    `nntp-via-telnet-command'
          Command used to `telnet' the intermediate host.  The default
          is `telnet'.

    `nntp-via-telnet-switches'
          List of strings to be used as the switches to the
          `nntp-via-telnet-command' command.  The default is `("-8")'.

    `nntp-via-user-password'
          Password to use when logging in on the intermediate host.

    `nntp-via-envuser'
          If non-`nil', the intermediate `telnet' session (client and
          server both) will support the `ENVIRON' option and not prompt
          for login name.  This works for Solaris `telnet', for
          instance.

    `nntp-via-shell-prompt'
          Regexp matching the shell prompt on the intermediate host.
          The default is `bash\\|\$ *\r?$\\|> *\r?'.


     Note that you may want to change the value for `nntp-end-of-line'
     to `\n' (*note Common Variables::).

   Here are some additional variables that are understood by all the
above functions:

`nntp-via-user-name'
     User name to use when connecting to the intermediate host.

`nntp-via-address'
     Address of the intermediate host to connect to.



File: gnus,  Node: Common Variables,  Next: NNTP marks,  Prev: Indirect Functions,  Up: NNTP

6.2.1.3 Common Variables
........................

The following variables affect the behavior of all, or several of the
pre-made connection functions.  When not specified, all functions are
affected (the values of the following variables will be used as the
default if each virtual `nntp' server doesn't specify those server
variables individually).

`nntp-pre-command'
     A command wrapper to use when connecting through a non native
     connection function (all except `nntp-open-network-stream',
     `nntp-open-tls-stream', and `nntp-open-ssl-stream').  This is
     where you would put a `SOCKS' wrapper for instance.

`nntp-address'
     The address of the NNTP server.

`nntp-port-number'
     Port number to connect to the NNTP server.  The default is `nntp'.
     If you use NNTP over TLS/SSL, you may want to use integer ports
     rather than named ports (i.e, use `563' instead of `snews' or
     `nntps'), because external TLS/SSL tools may not work with named
     ports.

`nntp-end-of-line'
     String to use as end-of-line marker when talking to the NNTP
     server.  This is `\r\n' by default, but should be `\n' when using
     a non native telnet connection function.

`nntp-netcat-command'
     Command to use when connecting to the NNTP server through
     `netcat'.  This is _not_ for an intermediate host.  This is just
     for the real NNTP server.  The default is `nc'.

`nntp-netcat-switches'
     A list of switches to pass to `nntp-netcat-command'.  The default
     is `()'.



File: gnus,  Node: NNTP marks,  Prev: Common Variables,  Up: NNTP

6.2.1.4 NNTP marks
..................

Gnus stores marks (*note Marking Articles::) for NNTP servers in marks
files.  A marks file records what marks you have set in a group and
each file is specific to the corresponding server.  Marks files are
stored in `~/News/marks' (`nntp-marks-directory') under a classic
hierarchy resembling that of a news server, for example marks for the
group `gmane.discuss' on the news.gmane.org server will be stored in
the file `~/News/marks/news.gmane.org/gmane/discuss/.marks'.

   Marks files are useful because you can copy the `~/News/marks'
directory (using rsync, scp or whatever) to another Gnus installation,
and it will realize what articles you have read and marked.  The data
in `~/News/marks' has priority over the same data in `~/.newsrc.eld'.

   Note that marks files are very much server-specific: Gnus remembers
the article numbers so if you don't use the same servers on both
installations things are most likely to break (most NNTP servers do not
use the same article numbers as any other server).  However, if you use
servers A, B, C on one installation and servers A, D, E on the other,
you can sync the marks files for A and then you'll get synchronization
for that server between the two installations.

   Using NNTP marks can possibly incur a performance penalty so if Gnus
feels sluggish, try setting the `nntp-marks-is-evil' variable to `t'.
Marks will then be stored in `~/.newsrc.eld'.

   Related variables:

`nntp-marks-is-evil'
     If non-`nil', this back end will ignore any marks files.  The
     default is `nil'.

`nntp-marks-directory'
     The directory where marks for nntp groups will be stored.



File: gnus,  Node: News Spool,  Prev: NNTP,  Up: Getting News

6.2.2 News Spool
----------------

Subscribing to a foreign group from the local spool is extremely easy,
and might be useful, for instance, to speed up reading groups that
contain very big articles--`alt.binaries.pictures.furniture', for
instance.

   Anyway, you just specify `nnspool' as the method and `""' (or
anything else) as the address.

   If you have access to a local spool, you should probably use that as
the native select method (*note Finding the News::).  It is normally
faster than using an `nntp' select method, but might not be.  It
depends.  You just have to try to find out what's best at your site.

`nnspool-inews-program'
     Program used to post an article.

`nnspool-inews-switches'
     Parameters given to the inews program when posting an article.

`nnspool-spool-directory'
     Where `nnspool' looks for the articles.  This is normally
     `/usr/spool/news/'.

`nnspool-nov-directory'
     Where `nnspool' will look for NOV files.  This is normally
     `/usr/spool/news/over.view/'.

`nnspool-lib-dir'
     Where the news lib dir is (`/usr/lib/news/' by default).

`nnspool-active-file'
     The name of the active file.

`nnspool-newsgroups-file'
     The name of the group descriptions file.

`nnspool-history-file'
     The name of the news history file.

`nnspool-active-times-file'
     The name of the active date file.

`nnspool-nov-is-evil'
     If non-`nil', `nnspool' won't try to use any NOV files that it
     finds.

`nnspool-sift-nov-with-sed'
     If non-`nil', which is the default, use `sed' to get the relevant
     portion from the overview file.  If `nil', `nnspool' will load the
     entire file into a buffer and process it there.



File: gnus,  Node: Using IMAP,  Next: Getting Mail,  Prev: Getting News,  Up: Select Methods

6.3 Using IMAP
==============

The most popular mail backend is probably `nnimap', which provides
access to IMAP servers.  IMAP servers store mail remotely, so the
client doesn't store anything locally.  This means that it's a
convenient choice when you're reading your mail from different
locations, or with different user agents.

* Menu:

* Connecting to an IMAP Server::     Getting started with IMAP.
* Customizing the IMAP Connection::  Variables for IMAP connection.
* Client-Side IMAP Splitting::       Put mail in the correct mail box.


File: gnus,  Node: Connecting to an IMAP Server,  Next: Customizing the IMAP Connection,  Up: Using IMAP

6.3.1 Connecting to an IMAP Server
----------------------------------

Connecting to an IMAP can be very easy.  Type `B' in the group buffer,
or (if your primary interest is reading email), say something like:

     (setq gnus-select-method
           '(nnimap "imap.gmail.com"))

   You'll be prompted for a user name and password.  If you grow tired
of that, then add the following to your `~/.authinfo' file:

     machine imap.gmail.com login <username> password <password> port imap

   That should basically be it for most users.


File: gnus,  Node: Customizing the IMAP Connection,  Next: Client-Side IMAP Splitting,  Prev: Connecting to an IMAP Server,  Up: Using IMAP

6.3.2 Customizing the IMAP Connection
-------------------------------------

Here's an example method that's more complex:

     (nnimap "imap.gmail.com"
             (nnimap-inbox "INBOX")
             (nnimap-split-methods default)
             (nnimap-expunge t)
             (nnimap-stream ssl))

`nnimap-address'
     The address of the server, like `imap.gmail.com'.

`nnimap-server-port'
     If the server uses a non-standard port, that can be specified
     here.  A typical port would be `"imap"' or `"imaps"'.

`nnimap-stream'
     How `nnimap' should connect to the server.  Possible values are:

    `undecided'
          This is the default, and this first tries the `ssl' setting,
          and then tries the `network' setting.

    `ssl'
          This uses standard TLS/SSL connections.

    `network'
          Non-encrypted and unsafe straight socket connection, but will
          upgrade to encrypted STARTTLS if both Emacs and the server
          supports it.

    `starttls'
          Encrypted STARTTLS over the normal IMAP port.

    `shell'
          If you need to tunnel via other systems to connect to the
          server, you can use this option, and customize
          `nnimap-shell-program' to be what you need.


`nnimap-authenticator'
     Some IMAP servers allow anonymous logins.  In that case, this
     should be set to `anonymous'.

`nnimap-expunge'
     If non-`nil', expunge articles after deleting them.  This is
     always done if the server supports UID EXPUNGE, but it's not done
     by default on servers that doesn't support that command.

`nnimap-streaming'
     Virtually all IMAP server support fast streaming of data.  If you
     have problems connecting to the server, try setting this to `nil'.

`nnimap-fetch-partial-articles'
     If non-`nil', fetch partial articles from the server.  If set to a
     string, then it's interpreted as a regexp, and parts that have
     matching types will be fetched.  For instance, `"text/"' will
     fetch all textual parts, while leaving the rest on the server.

`nnimap-record-commands'
     If non-`nil', record all IMAP commands in the `"*imap log*"'
     buffer.



File: gnus,  Node: Client-Side IMAP Splitting,  Prev: Customizing the IMAP Connection,  Up: Using IMAP

6.3.3 Client-Side IMAP Splitting
--------------------------------

Many people prefer to do the sorting/splitting of mail into their mail
boxes on the IMAP server.  That way they don't have to download the
mail they're not all that interested in.

   If you do want to do client-side mail splitting, then the following
variables are relevant:

`nnimap-inbox'
     This is the IMAP mail box that will be scanned for new mail.

`nnimap-split-methods'
     Uses the same syntax as `nnmail-split-methods' (*note Splitting
     Mail::), except the symbol `default', which means that it should
     use the value of the `nnmail-split-methods' variable.

`nnimap-split-fancy'
     Uses the same syntax as `nnmail-split-fancy'.

`nnimap-unsplittable-articles'
     List of flag symbols to ignore when doing splitting.  That is,
     articles that have these flags won't be considered when splitting.
     The default is `(%Deleted %Seen)'.


   Here's a complete example `nnimap' backend with a client-side
"fancy" splitting method:

     (nnimap "imap.example.com"
             (nnimap-inbox "INBOX")
             (nnimap-split-methods
              (| ("MailScanner-SpamCheck" "spam" "spam.detected")
                 (to "foo@bar.com" "foo")
                 "undecided")))


File: gnus,  Node: Getting Mail,  Next: Browsing the Web,  Prev: Using IMAP,  Up: Select Methods

6.4 Getting Mail
================

Reading mail with a newsreader--isn't that just plain WeIrD? But of
course.

* Menu:

* Mail in a Newsreader::        Important introductory notes.
* Getting Started Reading Mail::  A simple cookbook example.
* Splitting Mail::              How to create mail groups.
* Mail Sources::                How to tell Gnus where to get mail from.
* Mail Back End Variables::     Variables for customizing mail handling.
* Fancy Mail Splitting::        Gnus can do hairy splitting of incoming mail.
* Group Mail Splitting::        Use group customize to drive mail splitting.
* Incorporating Old Mail::      What about the old mail you have?
* Expiring Mail::               Getting rid of unwanted mail.
* Washing Mail::                Removing cruft from the mail you get.
* Duplicates::                  Dealing with duplicated mail.
* Not Reading Mail::            Using mail back ends for reading other files.
* Choosing a Mail Back End::    Gnus can read a variety of mail formats.


File: gnus,  Node: Mail in a Newsreader,  Next: Getting Started Reading Mail,  Up: Getting Mail

6.4.1 Mail in a Newsreader
--------------------------

If you are used to traditional mail readers, but have decided to switch
to reading mail with Gnus, you may find yourself experiencing something
of a culture shock.

   Gnus does not behave like traditional mail readers.  If you want to
make it behave that way, you can, but it's an uphill battle.

   Gnus, by default, handles all its groups using the same approach.
This approach is very newsreaderly--you enter a group, see the
new/unread messages, and when you read the messages, they get marked as
read, and you don't see them any more.  (Unless you explicitly ask for
them.)

   In particular, you do not do anything explicitly to delete messages.

   Does this mean that all the messages that have been marked as read
are deleted?  How awful!

   But, no, it means that old messages are "expired" according to some
scheme or other.  For news messages, the expire process is controlled by
the news administrator; for mail, the expire process is controlled by
you.  The expire process for mail is covered in depth in *note Expiring
Mail::.

   What many Gnus users find, after using it a while for both news and
mail, is that the transport mechanism has very little to do with how
they want to treat a message.

   Many people subscribe to several mailing lists.  These are
transported via SMTP, and are therefore mail.  But we might go for
weeks without answering, or even reading these messages very carefully.
We may not need to save them because if we should need to read one
again, they are archived somewhere else.

   Some people have local news groups which have only a handful of
readers.  These are transported via NNTP, and are therefore news.  But
we may need to read and answer a large fraction of the messages very
carefully in order to do our work.  And there may not be an archive, so
we may need to save the interesting messages the same way we would
personal mail.

   The important distinction turns out to be not the transport
mechanism, but other factors such as how interested we are in the
subject matter, or how easy it is to retrieve the message if we need to
read it again.

   Gnus provides many options for sorting mail into "groups" which
behave like newsgroups, and for treating each group (whether mail or
news) differently.

   Some users never get comfortable using the Gnus (ahem) paradigm and
wish that Gnus should grow up and be a male, er, mail reader.  It is
possible to whip Gnus into a more mailreaderly being, but, as said
before, it's not easy.  People who prefer proper mail readers should
try VM instead, which is an excellent, and proper, mail reader.

   I don't mean to scare anybody off, but I want to make it clear that
you may be required to learn a new way of thinking about messages.
After you've been subjected to The Gnus Way, you will come to love it.
I can guarantee it.  (At least the guy who sold me the Emacs Subliminal
Brain-Washing Functions that I've put into Gnus did guarantee it.  You
Will Be Assimilated.  You Love Gnus.  You Love The Gnus Mail Way.  You
Do.)


File: gnus,  Node: Getting Started Reading Mail,  Next: Splitting Mail,  Prev: Mail in a Newsreader,  Up: Getting Mail

6.4.2 Getting Started Reading Mail
----------------------------------

It's quite easy to use Gnus to read your new mail.  You just plonk the
mail back end of your choice into `gnus-secondary-select-methods', and
things will happen automatically.

   For instance, if you want to use `nnml' (which is a "one file per
mail" back end), you could put the following in your `~/.gnus.el' file:

     (setq gnus-secondary-select-methods '((nnml "")))

   Now, the next time you start Gnus, this back end will be queried for
new articles, and it will move all the messages in your spool file to
its directory, which is `~/Mail/' by default.  The new group that will
be created (`mail.misc') will be subscribed, and you can read it like
any other group.

   You will probably want to split the mail into several groups, though:

     (setq nnmail-split-methods
           '(("junk" "^From:.*Lars Ingebrigtsen")
             ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
             ("other" "")))

   This will result in three new `nnml' mail groups being created:
`nnml:junk', `nnml:crazy', and `nnml:other'.  All the mail that doesn't
fit into the first two groups will be placed in the last group.

   This should be sufficient for reading mail with Gnus.  You might
want to give the other sections in this part of the manual a perusal,
though.  Especially *note Choosing a Mail Back End:: and *note Expiring
Mail::.


File: gnus,  Node: Splitting Mail,  Next: Mail Sources,  Prev: Getting Started Reading Mail,  Up: Getting Mail

6.4.3 Splitting Mail
--------------------

The `nnmail-split-methods' variable says how the incoming mail is to be
split into groups.

     (setq nnmail-split-methods
       '(("mail.junk" "^From:.*Lars Ingebrigtsen")
         ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
         ("mail.other" "")))

   This variable is a list of lists, where the first element of each of
these lists is the name of the mail group (they do not have to be called
something beginning with `mail', by the way), and the second element is
a regular expression used on the header of each mail to determine if it
belongs in this mail group.  The first string may contain `\\1' forms,
like the ones used by `replace-match' to insert sub-expressions from
the matched text.  For instance:

     ("list.\\1" "From:.* \\(.*\\)-list@majordomo.com")

In that case, `nnmail-split-lowercase-expanded' controls whether the
inserted text should be made lowercase.  *Note Fancy Mail Splitting::.

   The second element can also be a function.  In that case, it will be
called narrowed to the headers with the first element of the rule as the
argument.  It should return a non-`nil' value if it thinks that the
mail belongs in that group.

   The last of these groups should always be a general one, and the
regular expression should _always_ be `""' so that it matches any mails
that haven't been matched by any of the other regexps.  (These rules are
processed from the beginning of the alist toward the end.  The first
rule to make a match will "win", unless you have crossposting enabled.
In that case, all matching rules will "win".)  If no rule matched, the
mail will end up in the `bogus' group.  When new groups are created by
splitting mail, you may want to run `gnus-group-find-new-groups' to see
the new groups.  This also applies to the `bogus' group.

   If you like to tinker with this yourself, you can set this variable
to a function of your choice.  This function will be called without any
arguments in a buffer narrowed to the headers of an incoming mail
message.  The function should return a list of group names that it
thinks should carry this mail message.

   This variable can also be a fancy split method.  For the syntax, see
*note Fancy Mail Splitting::.

   Note that the mail back ends are free to maul the poor, innocent,
incoming headers all they want to.  They all add `Lines' headers; some
add `X-Gnus-Group' headers; most rename the Unix mbox `From<SPACE>'
line to something else.

   The mail back ends all support cross-posting.  If several regexps
match, the mail will be "cross-posted" to all those groups.
`nnmail-crosspost' says whether to use this mechanism or not.  Note
that no articles are crossposted to the general (`""') group.

   `nnmh' and `nnml' makes crossposts by creating hard links to the
crossposted articles.  However, not all file systems support hard
links.  If that's the case for you, set
`nnmail-crosspost-link-function' to `copy-file'.  (This variable is
`add-name-to-file' by default.)

   If you wish to see where the previous mail split put the messages,
you can use the `M-x nnmail-split-history' command.  If you wish to see
where re-spooling messages would put the messages, you can use
`gnus-summary-respool-trace' and related commands (*note Mail Group
Commands::).

   Header lines longer than the value of
`nnmail-split-header-length-limit' are excluded from the split function.

   By default, splitting does not decode headers, so you can not match
on non-ASCII strings.  But it is useful if you want to match articles
based on the raw header data.  To enable it, set the
`nnmail-mail-splitting-decodes' variable to a non-`nil' value.  In
addition, the value of the `nnmail-mail-splitting-charset' variable is
used for decoding non-MIME encoded string when
`nnmail-mail-splitting-decodes' is non-`nil'.  The default value is
`nil' which means not to decode non-MIME encoded string.  A suitable
value for you will be `undecided' or be the charset used normally in
mails you are interested in.

   By default, splitting is performed on all incoming messages.  If you
specify a `directory' entry for the variable `mail-sources' (*note Mail
Source Specifiers::), however, then splitting does _not_ happen by
default.  You can set the variable `nnmail-resplit-incoming' to a
non-`nil' value to make splitting happen even in this case.  (This
variable has no effect on other kinds of entries.)

   Gnus gives you all the opportunity you could possibly want for
shooting yourself in the foot.  Let's say you create a group that will
contain all the mail you get from your boss.  And then you accidentally
unsubscribe from the group.  Gnus will still put all the mail from your
boss in the unsubscribed group, and so, when your boss mails you "Have
that report ready by Monday or you're fired!", you'll never see it and,
come Tuesday, you'll still believe that you're gainfully employed while
you really should be out collecting empty bottles to save up for next
month's rent money.


File: gnus,  Node: Mail Sources,  Next: Mail Back End Variables,  Prev: Splitting Mail,  Up: Getting Mail

6.4.4 Mail Sources
------------------

Mail can be gotten from many different sources--the mail spool, from a
POP mail server, from a procmail directory, or from a maildir, for
instance.

* Menu:

* Mail Source Specifiers::      How to specify what a mail source is.
* Mail Source Customization::   Some variables that influence things.
* Fetching Mail::               Using the mail source specifiers.


File: gnus,  Node: Mail Source Specifiers,  Next: Mail Source Customization,  Up: Mail Sources

6.4.4.1 Mail Source Specifiers
..............................

You tell Gnus how to fetch mail by setting `mail-sources' (*note
Fetching Mail::) to a "mail source specifier".

   Here's an example:

     (pop :server "pop3.mailserver.com" :user "myname")

   As can be observed, a mail source specifier is a list where the first
element is a "mail source type", followed by an arbitrary number of
"keywords".  Keywords that are not explicitly specified are given
default values.

   The `mail-sources' is global for all mail groups.  You can specify
an additional mail source for a particular group by including the
`group' mail specifier in `mail-sources', and setting a `mail-source'
group parameter (*note Group Parameters::) specifying a single mail
source.  When this is used, `mail-sources' is typically just `(group)';
the `mail-source' parameter for a group might look like this:

     (mail-source . (file :path "home/user/spools/foo.spool"))

   This means that the group's (and only this group's) messages will be
fetched from the spool file `/user/spools/foo.spool'.

   The following mail source types are available:

`file'
     Get mail from a single file; typically from the mail spool.

     Keywords:

    `:path'
          The file name.  Defaults to the value of the `MAIL'
          environment variable or the value of `rmail-spool-directory'
          (usually something like `/usr/mail/spool/user-name').

    `:prescript'
    `:postscript'
          Script run before/after fetching mail.

     An example file mail source:

          (file :path "/usr/spool/mail/user-name")

     Or using the default file name:

          (file)

     If the mail spool file is not located on the local machine, it's
     best to use POP or IMAP or the like to fetch the mail.  You can
     not use ange-ftp file names here--it has no way to lock the mail
     spool while moving the mail.

     If it's impossible to set up a proper server, you can use ssh
     instead.

          (setq mail-sources
                '((file :prescript "ssh host bin/getmail >%t")))

     The `getmail' script would look something like the following:

          #!/bin/sh
          #  getmail - move mail from spool to stdout
          #  flu@iki.fi

          MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail
          TMP=$HOME/Mail/tmp
          rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP

     Alter this script to fit the `movemail' and temporary file you
     want to use.

`directory'
     Get mail from several files in a directory.  This is typically used
     when you have procmail split the incoming mail into several files.
     That is, there is a one-to-one correspondence between files in that
     directory and groups, so that mail from the file `foo.bar.spool'
     will be put in the group `foo.bar'.  (You can change the suffix to
     be used instead of `.spool'.)  Setting
     `nnmail-scan-directory-mail-source-once' to non-`nil' forces Gnus
     to scan the mail source only once.  This is particularly useful if
     you want to scan mail groups at a specified level.

     There is also the variable `nnmail-resplit-incoming', if you set
     that to a non-`nil' value, then the normal splitting process is
     applied to all the files from the directory, *note Splitting
     Mail::.

     Keywords:

    `:path'
          The name of the directory where the files are.  There is no
          default value.

    `:suffix'
          Only files ending with this suffix are used.  The default is
          `.spool'.

    `:predicate'
          Only files that have this predicate return non-`nil' are
          returned.  The default is `identity'.  This is used as an
          additional filter--only files that have the right suffix
          _and_ satisfy this predicate are considered.

    `:prescript'
    `:postscript'
          Script run before/after fetching mail.


     An example directory mail source:

          (directory :path "/home/user-name/procmail-dir/"
                     :suffix ".prcml")

`pop'
     Get mail from a POP server.

     Keywords:

    `:server'
          The name of the POP server.  The default is taken from the
          `MAILHOST' environment variable.

    `:port'
          The port number of the POP server.  This can be a number (eg,
          `:port 1234') or a string (eg, `:port "pop3"').  If it is a
          string, it should be a service name as listed in
          `/etc/services' on Unix systems.  The default is `"pop3"'.
          On some systems you might need to specify it as `"pop-3"'
          instead.

    `:user'
          The user name to give to the POP server.  The default is the
          login name.

    `:password'
          The password to give to the POP server.  If not specified,
          the user is prompted.

    `:program'
          The program to use to fetch mail from the POP server.  This
          should be a `format'-like string.  Here's an example:

               fetchmail %u@%s -P %p %t

          The valid format specifier characters are:

         `t'
               The name of the file the mail is to be moved to.  This
               must always be included in this string.

         `s'
               The name of the server.

         `P'
               The port number of the server.

         `u'
               The user name to use.

         `p'
               The password to use.

          The values used for these specs are taken from the values you
          give the corresponding keywords.

    `:prescript'
          A script to be run before fetching the mail.  The syntax is
          the same as the `:program' keyword.  This can also be a
          function to be run.

          One popular way to use this is to set up an SSH tunnel to
          access the POP server.  Here's an example:

               (pop :server "127.0.0.1"
                    :port 1234
                    :user "foo"
                    :password "secret"
                    :prescript
                    "nohup ssh -f -L 1234:pop.server:110 remote.host sleep 3600 &")

    `:postscript'
          A script to be run after fetching the mail.  The syntax is
          the same as the `:program' keyword.  This can also be a
          function to be run.

    `:function'
          The function to use to fetch mail from the POP server.  The
          function is called with one parameter--the name of the file
          where the mail should be moved to.

    `:authentication'
          This can be either the symbol `password' or the symbol `apop'
          and says what authentication scheme to use.  The default is
          `password'.


     If the `:program' and `:function' keywords aren't specified,
     `pop3-movemail' will be used.  If `pop3-leave-mail-on-server' is
     non-`nil' the mail is to be left on the POP server after fetching
     when using `pop3-movemail'.  Note that POP servers maintain no
     state information between sessions, so what the client believes is
     there and what is actually there may not match up.  If they do
     not, then you may get duplicate mails or the whole thing can fall
     apart and leave you with a corrupt mailbox.

     Here are some examples for getting mail from a POP server.  Fetch
     from the default POP server, using the default user name, and
     default fetcher:

          (pop)

     Fetch from a named server with a named user and password:

          (pop :server "my.pop.server"
               :user "user-name" :password "secret")

     Use `movemail' to move the mail:

          (pop :program "movemail po:%u %t %p")

`maildir'
     Get mail from a maildir.  This is a type of mailbox that is
     supported by at least qmail and postfix, where each file in a
     special directory contains exactly one mail.

     Keywords:

    `:path'
          The name of the directory where the mails are stored.  The
          default is taken from the `MAILDIR' environment variable or
          `~/Maildir/'.

    `:subdirs'
          The subdirectories of the Maildir.  The default is `("new"
          "cur")'.

          You can also get mails from remote hosts (because maildirs
          don't suffer from locking problems).


     Two example maildir mail sources:

          (maildir :path "/home/user-name/Maildir/"
                   :subdirs ("cur" "new"))

          (maildir :path "/user@remotehost.org:~/Maildir/"
                   :subdirs ("new"))

`imap'
     Get mail from a IMAP server.  If you don't want to use IMAP as
     intended, as a network mail reading protocol (ie with nnimap), for
     some reason or other, Gnus let you treat it similar to a POP
     server and fetches articles from a given IMAP mailbox.  *Note
     Using IMAP::, for more information.

     Keywords:

    `:server'
          The name of the IMAP server.  The default is taken from the
          `MAILHOST' environment variable.

    `:port'
          The port number of the IMAP server.  The default is `143', or
          `993' for TLS/SSL connections.

    `:user'
          The user name to give to the IMAP server.  The default is the
          login name.

    `:password'
          The password to give to the IMAP server.  If not specified,
          the user is prompted.

    `:stream'
          What stream to use for connecting to the server, this is one
          of the symbols in `imap-stream-alist'.  Right now, this means
          `gssapi', `kerberos4', `starttls', `tls', `ssl', `shell' or
          the default `network'.

    `:authentication'
          Which authenticator to use for authenticating to the server,
          this is one of the symbols in `imap-authenticator-alist'.
          Right now, this means `gssapi', `kerberos4', `digest-md5',
          `cram-md5', `anonymous' or the default `login'.

    `:program'
          When using the `shell' :stream, the contents of this variable
          is mapped into the `imap-shell-program' variable.  This
          should be a `format'-like string (or list of strings).
          Here's an example:

               ssh %s imapd

          Make sure nothing is interfering with the output of the
          program, e.g., don't forget to redirect the error output to
          the void.  The valid format specifier characters are:

         `s'
               The name of the server.

         `l'
               User name from `imap-default-user'.

         `p'
               The port number of the server.

          The values used for these specs are taken from the values you
          give the corresponding keywords.

    `:mailbox'
          The name of the mailbox to get mail from.  The default is
          `INBOX' which normally is the mailbox which receives incoming
          mail.

    `:predicate'
          The predicate used to find articles to fetch.  The default,
          `UNSEEN UNDELETED', is probably the best choice for most
          people, but if you sometimes peek in your mailbox with a IMAP
          client and mark some articles as read (or; SEEN) you might
          want to set this to `1:*'.  Then all articles in the mailbox
          is fetched, no matter what.  For a complete list of
          predicates, see RFC 2060 section 6.4.4.

    `:fetchflag'
          How to flag fetched articles on the server, the default
          `\Deleted' will mark them as deleted, an alternative would be
          `\Seen' which would simply mark them as read.  These are the
          two most likely choices, but more flags are defined in RFC
          2060 section 2.3.2.

    `:dontexpunge'
          If non-`nil', don't remove all articles marked as deleted in
          the mailbox after finishing the fetch.


     An example IMAP mail source:

          (imap :server "mail.mycorp.com"
                :stream kerberos4
                :fetchflag "\\Seen")

`group'
     Get the actual mail source from the `mail-source' group parameter,
     *Note Group Parameters::.


"Common Keywords"
     Common keywords can be used in any type of mail source.

     Keywords:

    `:plugged'
          If non-`nil', fetch the mail even when Gnus is unplugged.  If
          you use directory source to get mail, you can specify it as
          in this example:

               (setq mail-sources
                     '((directory :path "/home/pavel/.Spool/"
                                  :suffix ""
                                  :plugged t)))

          Gnus will then fetch your mail even when you are unplugged.
          This is useful when you use local mail and news.


6.4.4.2 Function Interface
..........................

Some of the above keywords specify a Lisp function to be executed.  For
each keyword `:foo', the Lisp variable `foo' is bound to the value of
the keyword while the function is executing.  For example, consider the
following mail-source setting:

     (setq mail-sources '((pop :user "jrl"
                               :server "pophost" :function fetchfunc)))

   While the function `fetchfunc' is executing, the symbol `user' is
bound to `"jrl"', and the symbol `server' is bound to `"pophost"'.  The
symbols `port', `password', `program', `prescript', `postscript',
`function', and `authentication' are also bound (to their default
values).

   See above for a list of keywords for each type of mail source.


File: gnus,  Node: Mail Source Customization,  Next: Fetching Mail,  Prev: Mail Source Specifiers,  Up: Mail Sources

6.4.4.3 Mail Source Customization
.................................

The following is a list of variables that influence how the mail is
fetched.  You would normally not need to set or change any of these
variables.

`mail-source-crash-box'
     File where mail will be stored while processing it.  The default is
     `~/.emacs-mail-crash-box'.

`mail-source-delete-incoming'
     If non-`nil', delete incoming files after handling them.  If `t',
     delete the files immediately, if `nil', never delete any files.
     If a positive number, delete files older than number of days (the
     deletion will only happen when receiving new mail).  You may also
     set `mail-source-delete-incoming' to `nil' and call
     `mail-source-delete-old-incoming' from a hook or interactively.
     `mail-source-delete-incoming' defaults to `10' in alpha Gnusae and
     `2' in released Gnusae.  *Note Gnus Development::.

`mail-source-delete-old-incoming-confirm'
     If non-`nil', ask for confirmation before deleting old incoming
     files.  This variable only applies when
     `mail-source-delete-incoming' is a positive number.

`mail-source-ignore-errors'
     If non-`nil', ignore errors when reading mail from a mail source.

`mail-source-directory'
     Directory where incoming mail source files (if any) will be
     stored.  The default is `~/Mail/'.  At present, the only thing
     this is used for is to say where the incoming files will be stored
     if the variable `mail-source-delete-incoming' is `nil' or a number.

`mail-source-incoming-file-prefix'
     Prefix for file name for storing incoming mail.  The default is
     `Incoming', in which case files will end up with names like
     `Incoming30630D_' or `Incoming298602ZD'.  This is really only
     relevant if `mail-source-delete-incoming' is `nil' or a number.

`mail-source-default-file-modes'
     All new mail files will get this file mode.  The default is
     `#o600'.

`mail-source-movemail-program'
     If non-`nil', name of program for fetching new mail.  If `nil',
     `movemail' in EXEC-DIRECTORY.



File: gnus,  Node: Fetching Mail,  Prev: Mail Source Customization,  Up: Mail Sources

6.4.4.4 Fetching Mail
.....................

The way to actually tell Gnus where to get new mail from is to set
`mail-sources' to a list of mail source specifiers (*note Mail Source
Specifiers::).

   If this variable is `nil', the mail back ends will never attempt to
fetch mail by themselves.

   If you want to fetch mail both from your local spool as well as a
POP mail server, you'd say something like:

     (setq mail-sources
           '((file)
             (pop :server "pop3.mail.server"
                  :password "secret")))

   Or, if you don't want to use any of the keyword defaults:

     (setq mail-sources
           '((file :path "/var/spool/mail/user-name")
             (pop :server "pop3.mail.server"
                  :user "user-name"
                  :port "pop3"
                  :password "secret")))

   When you use a mail back end, Gnus will slurp all your mail from your
inbox and plonk it down in your home directory.  Gnus doesn't move any
mail if you're not using a mail back end--you have to do a lot of magic
invocations first.  At the time when you have finished drawing the
pentagram, lightened the candles, and sacrificed the goat, you really
shouldn't be too surprised when Gnus moves your mail.


File: gnus,  Node: Mail Back End Variables,  Next: Fancy Mail Splitting,  Prev: Mail Sources,  Up: Getting Mail

6.4.5 Mail Back End Variables
-----------------------------

These variables are (for the most part) pertinent to all the various
mail back ends.

`nnmail-read-incoming-hook'
     The mail back ends all call this hook after reading new mail.  You
     can use this hook to notify any mail watch programs, if you want
     to.

`nnmail-split-hook'
     Hook run in the buffer where the mail headers of each message is
     kept just before the splitting based on these headers is done.
     The hook is free to modify the buffer contents in any way it sees
     fit--the buffer is discarded after the splitting has been done,
     and no changes performed in the buffer will show up in any files.
     `gnus-article-decode-encoded-words' is one likely function to add
     to this hook.

`nnmail-pre-get-new-mail-hook'
`nnmail-post-get-new-mail-hook'
     These are two useful hooks executed when treating new incoming
     mail--`nnmail-pre-get-new-mail-hook' (is called just before
     starting to handle the new mail) and
     `nnmail-post-get-new-mail-hook' (is called when the mail handling
     is done).  Here's and example of using these two hooks to change
     the default file modes the new mail files get:

          (add-hook 'nnmail-pre-get-new-mail-hook
                    (lambda () (set-default-file-modes #o700)))

          (add-hook 'nnmail-post-get-new-mail-hook
                    (lambda () (set-default-file-modes #o775)))

`nnmail-use-long-file-names'
     If non-`nil', the mail back ends will use long file and directory
     names.  Groups like `mail.misc' will end up in directories
     (assuming use of `nnml' back end) or files (assuming use of
     `nnfolder' back end) like `mail.misc'.  If it is `nil', the same
     group will end up in `mail/misc'.

`nnmail-delete-file-function'
     Function called to delete files.  It is `delete-file' by default.

`nnmail-cache-accepted-message-ids'
     If non-`nil', put the `Message-ID's of articles imported into the
     back end (via `Gcc', for instance) into the mail duplication
     discovery cache.  The default is `nil'.

`nnmail-cache-ignore-groups'
     This can be a regular expression or a list of regular expressions.
     Group names that match any of the regular expressions will never be
     recorded in the `Message-ID' cache.

     This can be useful, for example, when using Fancy Splitting (*note
     Fancy Mail Splitting::) together with the function
     `nnmail-split-fancy-with-parent'.



File: gnus,  Node: Fancy Mail Splitting,  Next: Group Mail Splitting,  Prev: Mail Back End Variables,  Up: Getting Mail

6.4.6 Fancy Mail Splitting
--------------------------

If the rather simple, standard method for specifying how to split mail
doesn't allow you to do what you want, you can set
`nnmail-split-methods' to `nnmail-split-fancy'.  Then you can play with
the `nnmail-split-fancy' variable.

   Let's look at an example value of this variable first:

     ;; Messages from the mailer daemon are not crossposted to any of
     ;; the ordinary groups.  Warnings are put in a separate group
     ;; from real errors.
     (| ("from" mail (| ("subject" "warn.*" "mail.warning")
                        "mail.misc"))
        ;; Non-error messages are crossposted to all relevant
        ;; groups, but we don't crosspost between the group for the
        ;; (ding) list and the group for other (ding) related mail.
        (& (| (any "ding@ifi\\.uio\\.no" "ding.list")
              ("subject" "ding" "ding.misc"))
           ;; Other mailing lists...
           (any "procmail@informatik\\.rwth-aachen\\.de" "procmail.list")
           (any "SmartList@informatik\\.rwth-aachen\\.de" "SmartList.list")
           ;; Both lists below have the same suffix, so prevent
           ;; cross-posting to mkpkg.list of messages posted only to
           ;; the bugs- list, but allow cross-posting when the
           ;; message was really cross-posted.
           (any "bugs-mypackage@somewhere" "mypkg.bugs")
           (any "mypackage@somewhere" - "bugs-mypackage" "mypkg.list")
           ;; People...
           (any "larsi@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen"))
        ;; Unmatched mail goes to the catch all group.
        "misc.misc")

   This variable has the format of a "split".  A split is a (possibly)
recursive structure where each split may contain other splits.  Here
are the possible split syntaxes:

`group'
     If the split is a string, that will be taken as a group name.
     Normal regexp match expansion will be done.  See below for
     examples.

`(FIELD VALUE [- RESTRICT [...] ] SPLIT [INVERT-PARTIAL])'
     The split can be a list containing at least three elements.  If the
     first element FIELD (a regexp matching a header) contains VALUE
     (also a regexp) then store the message as specified by SPLIT.

     If RESTRICT (yet another regexp) matches some string after FIELD
     and before the end of the matched VALUE, the SPLIT is ignored.  If
     none of the RESTRICT clauses match, SPLIT is processed.

     The last element INVERT-PARTIAL is optional.  If it is non-`nil',
     the match-partial-words behavior controlled by the variable
     `nnmail-split-fancy-match-partial-words' (see below) is be
     inverted.  (New in Gnus 5.10.7)

`(| SPLIT ...)'
     If the split is a list, and the first element is `|' (vertical
     bar), then process each SPLIT until one of them matches.  A SPLIT
     is said to match if it will cause the mail message to be stored in
     one or more groups.

`(& SPLIT ...)'
     If the split is a list, and the first element is `&', then process
     all SPLITs in the list.

`junk'
     If the split is the symbol `junk', then don't save (i.e., delete)
     this message.  Use with extreme caution.

`(: FUNCTION ARG1 ARG2 ...)'
     If the split is a list, and the first element is `:', then the
     second element will be called as a function with ARGS given as
     arguments.  The function should return a SPLIT.

     For instance, the following function could be used to split based
     on the body of the messages:

          (defun split-on-body ()
            (save-excursion
              (save-restriction
                (widen)
                (goto-char (point-min))
                (when (re-search-forward "Some.*string" nil t)
                  "string.group"))))

     The buffer is narrowed to the header of the message in question
     when FUNCTION is run.  That's why `(widen)' needs to be called
     after `save-excursion' and `save-restriction' in the example
     above.  Also note that with the nnimap backend, message bodies will
     not be downloaded by default.  You need to set
     `nnimap-split-download-body' to `t' to do that (*note Client-Side
     IMAP Splitting::).

`(! FUNC SPLIT)'
     If the split is a list, and the first element is `!', then SPLIT
     will be processed, and FUNC will be called as a function with the
     result of SPLIT as argument.  FUNC should return a split.

`nil'
     If the split is `nil', it is ignored.


   In these splits, FIELD must match a complete field name.

   Normally, VALUE in these splits must match a complete _word_
according to the fundamental mode syntax table.  In other words, all
VALUE's will be implicitly surrounded by `\<...\>' markers, which are
word delimiters.  Therefore, if you use the following split, for
example,

     (any "joe" "joemail")

messages sent from `joedavis@foo.org' will normally not be filed in
`joemail'.  If you want to alter this behavior, you can use any of the
following three ways:

  1. You can set the `nnmail-split-fancy-match-partial-words' variable
     to non-`nil' in order to ignore word boundaries and instead the
     match becomes more like a grep.  This variable controls whether
     partial words are matched during fancy splitting.  The default
     value is `nil'.

     Note that it influences all VALUE's in your split rules.

  2. VALUE beginning with `.*' ignores word boundaries in front of a
     word.  Similarly, if VALUE ends with `.*', word boundaries in the
     rear of a word will be ignored.  For example, the VALUE
     `"@example\\.com"' does not match `foo@example.com' but
     `".*@example\\.com"' does.

  3. You can set the INVERT-PARTIAL flag in your split rules of the
     `(FIELD VALUE ...)' types, aforementioned in this section.  If the
     flag is set, word boundaries on both sides of a word are ignored
     even if `nnmail-split-fancy-match-partial-words' is `nil'.
     Contrarily, if the flag is set, word boundaries are not ignored
     even if `nnmail-split-fancy-match-partial-words' is non-`nil'.
     (New in Gnus 5.10.7)

   FIELD and VALUE can also be Lisp symbols, in that case they are
expanded as specified by the variable `nnmail-split-abbrev-alist'.
This is an alist of cons cells, where the CAR of a cell contains the
key, and the CDR contains the associated value.  Predefined entries in
`nnmail-split-abbrev-alist' include:

`from'
     Matches the `From', `Sender' and `Resent-From' fields.

`to'
     Matches the `To', `Cc', `Apparently-To', `Resent-To' and
     `Resent-Cc' fields.

`any'
     Is the union of the `from' and `to' entries.

   `nnmail-split-fancy-syntax-table' is the syntax table in effect when
all this splitting is performed.

   If you want to have Gnus create groups dynamically based on some
information in the headers (i.e., do `replace-match'-like substitutions
in the group names), you can say things like:

     (any "debian-\\b\\(\\w+\\)@lists.debian.org" "mail.debian.\\1")

   In this example, messages sent to `debian-foo@lists.debian.org' will
be filed in `mail.debian.foo'.

   If the string contains the element `\&', then the previously matched
string will be substituted.  Similarly, the elements `\\1' up to `\\9'
will be substituted with the text matched by the groupings 1 through 9.

   Where `nnmail-split-lowercase-expanded' controls whether the
lowercase of the matched string should be used for the substitution.
Setting it as non-`nil' is useful to avoid the creation of multiple
groups when users send to an address using different case (i.e.
mailing-list@domain vs Mailing-List@Domain).  The default value is `t'.

   `nnmail-split-fancy-with-parent' is a function which allows you to
split followups into the same groups their parents are in.  Sometimes
you can't make splitting rules for all your mail.  For example, your
boss might send you personal mail regarding different projects you are
working on, and as you can't tell your boss to put a distinguishing
string into the subject line, you have to resort to manually moving the
messages into the right group.  With this function, you only have to do
it once per thread.

   To use this feature, you have to set `nnmail-treat-duplicates' and
`nnmail-cache-accepted-message-ids' to a non-`nil' value.  And then you
can include `nnmail-split-fancy-with-parent' using the colon feature,
like so:
     (setq nnmail-treat-duplicates 'warn     ; or `delete'
           nnmail-cache-accepted-message-ids t
           nnmail-split-fancy
           '(| (: nnmail-split-fancy-with-parent)
               ;; other splits go here
             ))

   This feature works as follows: when `nnmail-treat-duplicates' is
non-`nil', Gnus records the message id of every message it sees in the
file specified by the variable `nnmail-message-id-cache-file', together
with the group it is in (the group is omitted for non-mail messages).
When mail splitting is invoked, the function
`nnmail-split-fancy-with-parent' then looks at the References (and
In-Reply-To) header of each message to split and searches the file
specified by `nnmail-message-id-cache-file' for the message ids.  When
it has found a parent, it returns the corresponding group name unless
the group name matches the regexp
`nnmail-split-fancy-with-parent-ignore-groups'.  It is recommended that
you set `nnmail-message-id-cache-length' to a somewhat higher number
than the default so that the message ids are still in the cache.  (A
value of 5000 appears to create a file some 300 kBytes in size.)  When
`nnmail-cache-accepted-message-ids' is non-`nil', Gnus also records the
message ids of moved articles, so that the followup messages goes into
the new group.

   Also see the variable `nnmail-cache-ignore-groups' if you don't want
certain groups to be recorded in the cache.  For example, if all
outgoing messages are written to an "outgoing" group, you could set
`nnmail-cache-ignore-groups' to match that group name.  Otherwise,
answers to all your messages would end up in the "outgoing" group.


File: gnus,  Node: Group Mail Splitting,  Next: Incorporating Old Mail,  Prev: Fancy Mail Splitting,  Up: Getting Mail

6.4.7 Group Mail Splitting
--------------------------

If you subscribe to dozens of mailing lists but you don't want to
maintain mail splitting rules manually, group mail splitting is for you.
You just have to set `to-list' and/or `to-address' in group parameters
or group customization and set `nnmail-split-methods' to
`gnus-group-split'.  This splitting function will scan all groups for
those parameters and split mail accordingly, i.e., messages posted from
or to the addresses specified in the parameters `to-list' or
`to-address' of a mail group will be stored in that group.

   Sometimes, mailing lists have multiple addresses, and you may want
mail splitting to recognize them all: just set the `extra-aliases' group
parameter to the list of additional addresses and it's done.  If you'd
rather use a regular expression, set `split-regexp'.

   All these parameters in a group will be used to create an
`nnmail-split-fancy' split, in which the FIELD is `any', the VALUE is a
single regular expression that matches `to-list', `to-address', all of
`extra-aliases' and all matches of `split-regexp', and the SPLIT is the
name of the group.  RESTRICTs are also supported: just set the
`split-exclude' parameter to a list of regular expressions.

   If you can't get the right split to be generated using all these
parameters, or you just need something fancier, you can set the
parameter `split-spec' to an `nnmail-split-fancy' split.  In this case,
all other aforementioned parameters will be ignored by
`gnus-group-split'.  In particular, `split-spec' may be set to `nil',
in which case the group will be ignored by `gnus-group-split'.

   `gnus-group-split' will do cross-posting on all groups that match,
by defining a single `&' fancy split containing one split for each
group.  If a message doesn't match any split, it will be stored in the
group named in `gnus-group-split-default-catch-all-group', unless some
group has `split-spec' set to `catch-all', in which case that group is
used as the catch-all group.  Even though this variable is often used
just to name a group, it may also be set to an arbitrarily complex
fancy split (after all, a group name is a fancy split), and this may be
useful to split mail that doesn't go to any mailing list to personal
mail folders.  Note that this fancy split is added as the last element
of a `|' split list that also contains a `&' split with the rules
extracted from group parameters.

   It's time for an example.  Assume the following group parameters have
been defined:

     nnml:mail.bar:
     ((to-address . "bar@femail.com")
      (split-regexp . ".*@femail\\.com"))
     nnml:mail.foo:
     ((to-list . "foo@nowhere.gov")
      (extra-aliases "foo@localhost" "foo-redist@home")
      (split-exclude "bugs-foo" "rambling-foo")
      (admin-address . "foo-request@nowhere.gov"))
     nnml:mail.others:
     ((split-spec . catch-all))

   Setting `nnmail-split-methods' to `gnus-group-split' will behave as
if `nnmail-split-fancy' had been selected and variable
`nnmail-split-fancy' had been set as follows:

     (| (& (any "\\(bar@femail\\.com\\|.*@femail\\.com\\)" "mail.bar")
           (any "\\(foo@nowhere\\.gov\\|foo@localhost\\|foo-redist@home\\)"
                - "bugs-foo" - "rambling-foo" "mail.foo"))
        "mail.others")

   If you'd rather not use group splitting for all your mail groups, you
may use it for only some of them, by using `nnmail-split-fancy' splits
like this:

     (: gnus-group-split-fancy GROUPS NO-CROSSPOST CATCH-ALL)

   GROUPS may be a regular expression or a list of group names whose
parameters will be scanned to generate the output split.  NO-CROSSPOST
can be used to disable cross-posting; in this case, a single `|' split
will be output.  CATCH-ALL is the fall back fancy split, used like
`gnus-group-split-default-catch-all-group'.  If CATCH-ALL is `nil', or
if `split-regexp' matches the empty string in any selected group, no
catch-all split will be issued.  Otherwise, if some group has
`split-spec' set to `catch-all', this group will override the value of
the CATCH-ALL argument.

   Unfortunately, scanning all groups and their parameters can be quite
slow, especially considering that it has to be done for every message.
But don't despair!  The function `gnus-group-split-setup' can be used
to enable `gnus-group-split' in a much more efficient way.  It sets
`nnmail-split-methods' to `nnmail-split-fancy' and sets
`nnmail-split-fancy' to the split produced by `gnus-group-split-fancy'.
Thus, the group parameters are only scanned once, no matter how many
messages are split.

   However, if you change group parameters, you'd have to update
`nnmail-split-fancy' manually.  You can do it by running
`gnus-group-split-update'.  If you'd rather have it updated
automatically, just tell `gnus-group-split-setup' to do it for you.
For example, add to your `~/.gnus.el':

     (gnus-group-split-setup AUTO-UPDATE CATCH-ALL)

   If AUTO-UPDATE is non-`nil', `gnus-group-split-update' will be added
to `nnmail-pre-get-new-mail-hook', so you won't ever have to worry
about updating `nnmail-split-fancy' again.  If you don't omit CATCH-ALL
(it's optional, equivalent to `nil'),
`gnus-group-split-default-catch-all-group' will be set to its value.

   Because you may want to change `nnmail-split-fancy' after it is set
by `gnus-group-split-update', this function will run
`gnus-group-split-updated-hook' just before finishing.


File: gnus,  Node: Incorporating Old Mail,  Next: Expiring Mail,  Prev: Group Mail Splitting,  Up: Getting Mail

6.4.8 Incorporating Old Mail
----------------------------

Most people have lots of old mail stored in various file formats.  If
you have set up Gnus to read mail using one of the spiffy Gnus mail
back ends, you'll probably wish to have that old mail incorporated into
your mail groups.

   Doing so can be quite easy.

   To take an example: You're reading mail using `nnml' (*note Mail
Spool::), and have set `nnmail-split-methods' to a satisfactory value
(*note Splitting Mail::).  You have an old Unix mbox file filled with
important, but old, mail.  You want to move it into your `nnml' groups.

   Here's how:

  1. Go to the group buffer.

  2. Type `G f' and give the file name to the mbox file when prompted
     to create an `nndoc' group from the mbox file (*note Foreign
     Groups::).

  3. Type `SPACE' to enter the newly created group.

  4. Type `M P b' to process-mark all articles in this group's buffer
     (*note Setting Process Marks::).

  5. Type `B r' to respool all the process-marked articles, and answer
     `nnml' when prompted (*note Mail Group Commands::).

   All the mail messages in the mbox file will now also be spread out
over all your `nnml' groups.  Try entering them and check whether things
have gone without a glitch.  If things look ok, you may consider
deleting the mbox file, but I wouldn't do that unless I was absolutely
sure that all the mail has ended up where it should be.

   Respooling is also a handy thing to do if you're switching from one
mail back end to another.  Just respool all the mail in the old mail
groups using the new mail back end.


File: gnus,  Node: Expiring Mail,  Next: Washing Mail,  Prev: Incorporating Old Mail,  Up: Getting Mail

6.4.9 Expiring Mail
-------------------

Traditional mail readers have a tendency to remove mail articles when
you mark them as read, in some way.  Gnus takes a fundamentally
different approach to mail reading.

   Gnus basically considers mail just to be news that has been received
in a rather peculiar manner.  It does not think that it has the power to
actually change the mail, or delete any mail messages.  If you enter a
mail group, and mark articles as "read", or kill them in some other
fashion, the mail articles will still exist on the system.  I repeat:
Gnus will not delete your old, read mail.  Unless you ask it to, of
course.

   To make Gnus get rid of your unwanted mail, you have to mark the
articles as "expirable".  (With the default key bindings, this means
that you have to type `E'.)  This does not mean that the articles will
disappear right away, however.  In general, a mail article will be
deleted from your system if, 1) it is marked as expirable, AND 2) it is
more than one week old.  If you do not mark an article as expirable, it
will remain on your system until hell freezes over.  This bears
repeating one more time, with some spurious capitalizations: IF you do
NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.

   You do not have to mark articles as expirable by hand.  Gnus provides
two features, called "auto-expire" and "total-expire", that can help you
with this.  In a nutshell, "auto-expire" means that Gnus hits `E' for
you when you select an article.  And "total-expire" means that Gnus
considers all articles as expirable that are read.  So, in addition to
the articles marked `E', also the articles marked `r', `R', `O', `K',
`Y' (and so on) are considered expirable.  `gnus-auto-expirable-marks'
has the full list of these marks.

   When should either auto-expire or total-expire be used?  Most people
who are subscribed to mailing lists split each list into its own group
and then turn on auto-expire or total-expire for those groups.  (*Note
Splitting Mail::, for more information on splitting each list into its
own group.)

   Which one is better, auto-expire or total-expire?  It's not easy to
answer.  Generally speaking, auto-expire is probably faster.  Another
advantage of auto-expire is that you get more marks to work with: for
the articles that are supposed to stick around, you can still choose
between tick and dormant and read marks.  But with total-expire, you
only have dormant and ticked to choose from.  The advantage of
total-expire is that it works well with adaptive scoring (*note
Adaptive Scoring::).  Auto-expire works with normal scoring but not
with adaptive scoring.

   Groups that match the regular expression
`gnus-auto-expirable-newsgroups' will have all articles that you read
marked as expirable automatically.  All articles marked as expirable
have an `E' in the first column in the summary buffer.

   By default, if you have auto expiry switched on, Gnus will mark all
the articles you read as expirable, no matter if they were read or
unread before.  To avoid having articles marked as read marked as
expirable automatically, you can put something like the following in
your `~/.gnus.el' file:

     (remove-hook 'gnus-mark-article-hook
                  'gnus-summary-mark-read-and-unread-as-read)
     (add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read)

   Note that making a group auto-expirable doesn't mean that all read
articles are expired--only the articles marked as expirable will be
expired.  Also note that using the `d' command won't make articles
expirable--only semi-automatic marking of articles as read will mark
the articles as expirable in auto-expirable groups.

   Let's say you subscribe to a couple of mailing lists, and you want
the articles you have read to disappear after a while:

     (setq gnus-auto-expirable-newsgroups
           "mail.nonsense-list\\|mail.nice-list")

   Another way to have auto-expiry happen is to have the element
`auto-expire' in the group parameters of the group.

   If you use adaptive scoring (*note Adaptive Scoring::) and
auto-expiring, you'll have problems.  Auto-expiring and adaptive scoring
don't really mix very well.

   The `nnmail-expiry-wait' variable supplies the default time an
expirable article has to live.  Gnus starts counting days from when the
message _arrived_, not from when it was sent.  The default is seven
days.

   Gnus also supplies a function that lets you fine-tune how long
articles are to live, based on what group they are in.  Let's say you
want to have one month expiry period in the `mail.private' group, a one
day expiry period in the `mail.junk' group, and a six day expiry period
everywhere else:

     (setq nnmail-expiry-wait-function
           (lambda (group)
            (cond ((string= group "mail.private")
                    31)
                  ((string= group "mail.junk")
                    1)
                  ((string= group "important")
                    'never)
                  (t
                    6))))

   The group names this function is fed are "unadorned" group names--no
`nnml:' prefixes and the like.

   The `nnmail-expiry-wait' variable and `nnmail-expiry-wait-function'
function can either be a number (not necessarily an integer) or one of
the symbols `immediate' or `never'.

   You can also use the `expiry-wait' group parameter to selectively
change the expiry period (*note Group Parameters::).

   The normal action taken when expiring articles is to delete them.
However, in some circumstances it might make more sense to move them to
other groups instead of deleting them.  The variable
`nnmail-expiry-target' (and the `expiry-target' group parameter)
controls this.  The variable supplies a default value for all groups,
which can be overridden for specific groups by the group parameter.
default value is `delete', but this can also be a string (which should
be the name of the group the message should be moved to), or a function
(which will be called in a buffer narrowed to the message in question,
and with the name of the group being moved from as its parameter) which
should return a target--either a group name or `delete'.

   Here's an example for specifying a group name:
     (setq nnmail-expiry-target "nnml:expired")

   Gnus provides a function `nnmail-fancy-expiry-target' which will
expire mail to groups according to the variable
`nnmail-fancy-expiry-targets'.  Here's an example:

      (setq nnmail-expiry-target 'nnmail-fancy-expiry-target
            nnmail-fancy-expiry-targets
            '((to-from "boss" "nnfolder:Work")
              ("subject" "IMPORTANT" "nnfolder:IMPORTANT.%Y.%b")
              ("from" ".*" "nnfolder:Archive-%Y")))

   With this setup, any mail that has `IMPORTANT' in its Subject header
and was sent in the year `YYYY' and month `MMM', will get expired to
the group `nnfolder:IMPORTANT.YYYY.MMM'.  If its From or To header
contains the string `boss', it will get expired to `nnfolder:Work'.
All other mail will get expired to `nnfolder:Archive-YYYY'.

   If `nnmail-keep-last-article' is non-`nil', Gnus will never expire
the final article in a mail newsgroup.  This is to make life easier for
procmail users.

   By the way: That line up there, about Gnus never expiring
non-expirable articles, is a lie.  If you put `total-expire' in the
group parameters, articles will not be marked as expirable, but all read
articles will be put through the expiry process.  Use with extreme
caution.  Even more dangerous is the `gnus-total-expirable-newsgroups'
variable.  All groups that match this regexp will have all read
articles put through the expiry process, which means that _all_ old
mail articles in the groups in question will be deleted after a while.
Use with extreme caution, and don't come crying to me when you discover
that the regexp you used matched the wrong group and all your important
mail has disappeared.  Be a _man_!  Or a _woman_!  Whatever you feel
more comfortable with!  So there!

   Most people make most of their mail groups total-expirable, though.

   If `gnus-inhibit-user-auto-expire' is non-`nil', user marking
commands will not mark an article as expirable, even if the group has
auto-expire turned on.

   The expirable marks of articles will be removed when copying or
moving them to a group in which auto-expire is not turned on.  This is
for preventing articles from being expired unintentionally.  On the
other hand, to a group that has turned auto-expire on, the expirable
marks of articles that are copied or moved will not be changed by
default.  I.e., when copying or moving to such a group, articles that
were expirable will be left expirable and ones that were not expirable
will not be marked as expirable.  So, even though in auto-expire
groups, some articles will never get expired (unless you read them
again).  If you don't side with that behavior that unexpirable articles
may be mixed into auto-expire groups, you can set
`gnus-mark-copied-or-moved-articles-as-expirable' to a non-`nil' value.
In that case, articles that have been read will be marked as expirable
automatically when being copied or moved to a group that has
auto-expire turned on.  The default value is `nil'.


File: gnus,  Node: Washing Mail,  Next: Duplicates,  Prev: Expiring Mail,  Up: Getting Mail

6.4.10 Washing Mail
-------------------

Mailers and list servers are notorious for doing all sorts of really,
really stupid things with mail.  "Hey, RFC 822 doesn't explicitly
prohibit us from adding the string `wE aRe ElItE!!!!!1!!' to the end of
all lines passing through our server, so let's do that!!!!1!"  Yes, but
RFC 822 wasn't designed to be read by morons.  Things that were
considered to be self-evident were not discussed.  So.  Here we are.

   Case in point:  The German version of Microsoft Exchange adds `AW: '
to the subjects of replies instead of `Re: '.  I could pretend to be
shocked and dismayed by this, but I haven't got the energy.  It is to
laugh.

   Gnus provides a plethora of functions for washing articles while
displaying them, but it might be nicer to do the filtering before
storing the mail to disk.  For that purpose, we have three hooks and
various functions that can be put in these hooks.

`nnmail-prepare-incoming-hook'
     This hook is called before doing anything with the mail and is
     meant for grand, sweeping gestures.  It is called in a buffer that
     contains all the new, incoming mail.  Functions to be used include:

    `nnheader-ms-strip-cr'
          Remove trailing carriage returns from each line.  This is
          default on Emacs running on MS machines.


`nnmail-prepare-incoming-header-hook'
     This hook is called narrowed to each header.  It can be used when
     cleaning up the headers.  Functions that can be used include:

    `nnmail-remove-leading-whitespace'
          Clear leading white space that "helpful" listservs have added
          to the headers to make them look nice.  Aaah.

          (Note that this function works on both the header on the body
          of all messages, so it is a potentially dangerous function to
          use (if a body of a message contains something that looks
          like a header line).  So rather than fix the bug, it is of
          course the right solution to make it into a feature by
          documenting it.)

    `nnmail-remove-list-identifiers'
          Some list servers add an identifier--for example, `(idm)'--to
          the beginning of all `Subject' headers.  I'm sure that's nice
          for people who use stone age mail readers.  This function
          will remove strings that match the `nnmail-list-identifiers'
          regexp, which can also be a list of regexp.
          `nnmail-list-identifiers' may not contain `\\(..\\)'.

          For instance, if you want to remove the `(idm)' and the
          `nagnagnag' identifiers:

               (setq nnmail-list-identifiers
                     '("(idm)" "nagnagnag"))

          This can also be done non-destructively with
          `gnus-list-identifiers', *Note Article Hiding::.

    `nnmail-remove-tabs'
          Translate all `TAB' characters into `SPACE' characters.

    `nnmail-ignore-broken-references'
          Some mail user agents (e.g. Eudora and Pegasus) produce broken
          `References' headers, but correct `In-Reply-To' headers.  This
          function will get rid of the `References' header if the
          headers contain a line matching the regular expression
          `nnmail-broken-references-mailers'.


`nnmail-prepare-incoming-message-hook'
     This hook is called narrowed to each message.  Functions to be used
     include:

    `article-de-quoted-unreadable'
          Decode Quoted Readable encoding.



File: gnus,  Node: Duplicates,  Next: Not Reading Mail,  Prev: Washing Mail,  Up: Getting Mail

6.4.11 Duplicates
-----------------

If you are a member of a couple of mailing lists, you will sometimes
receive two copies of the same mail.  This can be quite annoying, so
`nnmail' checks for and treats any duplicates it might find.  To do
this, it keeps a cache of old `Message-ID's--
`nnmail-message-id-cache-file', which is `~/.nnmail-cache' by default.
The approximate maximum number of `Message-ID's stored there is
controlled by the `nnmail-message-id-cache-length' variable, which is
1000 by default.  (So 1000 `Message-ID's will be stored.) If all this
sounds scary to you, you can set `nnmail-treat-duplicates' to `warn'
(which is what it is by default), and `nnmail' won't delete duplicate
mails.  Instead it will insert a warning into the head of the mail
saying that it thinks that this is a duplicate of a different message.

   This variable can also be a function.  If that's the case, the
function will be called from a buffer narrowed to the message in
question with the `Message-ID' as a parameter.  The function must
return either `nil', `warn', or `delete'.

   You can turn this feature off completely by setting the variable to
`nil'.

   If you want all the duplicate mails to be put into a special
"duplicates" group, you could do that using the normal mail split
methods:

     (setq nnmail-split-fancy
           '(| ;; Messages duplicates go to a separate group.
             ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate")
             ;; Message from daemons, postmaster, and the like to another.
             (any mail "mail.misc")
             ;; Other rules.
             [...] ))
   Or something like:
     (setq nnmail-split-methods
           '(("duplicates" "^Gnus-Warning:.*duplicate")
             ;; Other rules.
             [...]))

   Here's a neat feature: If you know that the recipient reads her mail
with Gnus, and that she has `nnmail-treat-duplicates' set to `delete',
you can send her as many insults as you like, just by using a
`Message-ID' of a mail that you know that she's already received.
Think of all the fun!  She'll never see any of it!  Whee!


File: gnus,  Node: Not Reading Mail,  Next: Choosing a Mail Back End,  Prev: Duplicates,  Up: Getting Mail

6.4.12 Not Reading Mail
-----------------------

If you start using any of the mail back ends, they have the annoying
habit of assuming that you want to read mail with them.  This might not
be unreasonable, but it might not be what you want.

   If you set `mail-sources' and `nnmail-spool-file' to `nil', none of
the back ends will ever attempt to read incoming mail, which should
help.

   This might be too much, if, for instance, you are reading mail quite
happily with `nnml' and just want to peek at some old (pre-Emacs 23)
Rmail file you have stashed away with `nnbabyl'.  All back ends have
variables called back-end-`get-new-mail'.  If you want to disable the
`nnbabyl' mail reading, you edit the virtual server for the group to
have a setting where `nnbabyl-get-new-mail' to `nil'.

   All the mail back ends will call `nn'*`-prepare-save-mail-hook'
narrowed to the article to be saved before saving it when reading
incoming mail.


File: gnus,  Node: Choosing a Mail Back End,  Prev: Not Reading Mail,  Up: Getting Mail

6.4.13 Choosing a Mail Back End
-------------------------------

Gnus will read the mail spool when you activate a mail group.  The mail
file is first copied to your home directory.  What happens after that
depends on what format you want to store your mail in.

   There are six different mail back ends in the standard Gnus, and more
back ends are available separately.  The mail back end most people use
(because it is possibly the fastest) is `nnml' (*note Mail Spool::).

* Menu:

* Unix Mail Box::               Using the (quite) standard Un*x mbox.
* Babyl::                       Babyl was used by older versions of Rmail.
* Mail Spool::                  Store your mail in a private spool?
* MH Spool::                    An mhspool-like back end.
* Maildir::                     Another one-file-per-message format.
* Mail Folders::                Having one file for each group.
* Comparing Mail Back Ends::    An in-depth looks at pros and cons.


File: gnus,  Node: Unix Mail Box,  Next: Babyl,  Up: Choosing a Mail Back End

6.4.13.1 Unix Mail Box
......................

The "nnmbox" back end will use the standard Un*x mbox file to store
mail.  `nnmbox' will add extra headers to each mail article to say
which group it belongs in.

   Virtual server settings:

`nnmbox-mbox-file'
     The name of the mail box in the user's home directory.  Default is
     `~/mbox'.

`nnmbox-active-file'
     The name of the active file for the mail box.  Default is
     `~/.mbox-active'.

`nnmbox-get-new-mail'
     If non-`nil', `nnmbox' will read incoming mail and split it into
     groups.  Default is `t'.


File: gnus,  Node: Babyl,  Next: Mail Spool,  Prev: Unix Mail Box,  Up: Choosing a Mail Back End

6.4.13.2 Babyl
..............

The "nnbabyl" back end will use a Babyl mail box to store mail.
`nnbabyl' will add extra headers to each mail article to say which
group it belongs in.

   Virtual server settings:

`nnbabyl-mbox-file'
     The name of the Babyl file.  The default is `~/RMAIL'

`nnbabyl-active-file'
     The name of the active file for the Babyl file.  The default is
     `~/.rmail-active'

`nnbabyl-get-new-mail'
     If non-`nil', `nnbabyl' will read incoming mail.  Default is `t'


File: gnus,  Node: Mail Spool,  Next: MH Spool,  Prev: Babyl,  Up: Choosing a Mail Back End

6.4.13.3 Mail Spool
...................

The "nnml" spool mail format isn't compatible with any other known
format.  It should be used with some caution.

   If you use this back end, Gnus will split all incoming mail into
files, one file for each mail, and put the articles into the
corresponding directories under the directory specified by the
`nnml-directory' variable.  The default value is `~/Mail/'.

   You do not have to create any directories beforehand; Gnus will take
care of all that.

   If you have a strict limit as to how many files you are allowed to
store in your account, you should not use this back end.  As each mail
gets its own file, you might very well occupy thousands of inodes
within a few weeks.  If this is no problem for you, and it isn't a
problem for you having your friendly systems administrator walking
around, madly, shouting "Who is eating all my inodes?! Who? Who!?!",
then you should know that this is probably the fastest format to use.
You do not have to trudge through a big mbox file just to read your new
mail.

   `nnml' is probably the slowest back end when it comes to article
splitting.  It has to create lots of files, and it also generates NOV
databases for the incoming mails.  This makes it possibly the fastest
back end when it comes to reading mail.

   When the marks file is used (which it is by default), `nnml' servers
have the property that you may backup them using `tar' or similar, and
later be able to restore them into Gnus (by adding the proper `nnml'
server) and have all your marks be preserved.  Marks for a group are
usually stored in the `.marks' file (but see `nnml-marks-file-name')
within each `nnml' group's directory.  Individual `nnml' groups are
also possible to backup, use `G m' to restore the group (after
restoring the backup into the nnml directory).

   If for some reason you believe your `.marks' files are screwed up,
you can just delete them all.  Gnus will then correctly regenerate them
next time it starts.

   Virtual server settings:

`nnml-directory'
     All `nnml' directories will be placed under this directory.  The
     default is the value of `message-directory' (whose default value
     is `~/Mail').

`nnml-active-file'
     The active file for the `nnml' server.  The default is
     `~/Mail/active'.

`nnml-newsgroups-file'
     The `nnml' group descriptions file.  *Note Newsgroups File
     Format::.  The default is `~/Mail/newsgroups'.

`nnml-get-new-mail'
     If non-`nil', `nnml' will read incoming mail.  The default is `t'.

`nnml-nov-is-evil'
     If non-`nil', this back end will ignore any NOV files.  The
     default is `nil'.

`nnml-nov-file-name'
     The name of the NOV files.  The default is `.overview'.

`nnml-prepare-save-mail-hook'
     Hook run narrowed to an article before saving.

`nnml-marks-is-evil'
     If non-`nil', this back end will ignore any MARKS files.  The
     default is `nil'.

`nnml-marks-file-name'
     The name of the "marks" files.  The default is `.marks'.

`nnml-use-compressed-files'
     If non-`nil', `nnml' will allow using compressed message files.
     This requires `auto-compression-mode' to be enabled (*note
     Compressed Files: (emacs)Compressed Files.).  If the value of
     `nnml-use-compressed-files' is a string, it is used as the file
     extension specifying the compression program.  You can set it to
     `.bz2' if your Emacs supports it.  A value of `t' is equivalent to
     `.gz'.

`nnml-compressed-files-size-threshold'
     Default size threshold for compressed message files.  Message
     files with bodies larger than that many characters will be
     automatically compressed if `nnml-use-compressed-files' is
     non-`nil'.


   If your `nnml' groups and NOV files get totally out of whack, you
can do a complete update by typing `M-x nnml-generate-nov-databases'.
This command will trawl through the entire `nnml' hierarchy, looking at
each and every article, so it might take a while to complete.  A better
interface to this functionality can be found in the server buffer
(*note Server Commands::).


File: gnus,  Node: MH Spool,  Next: Maildir,  Prev: Mail Spool,  Up: Choosing a Mail Back End

6.4.13.4 MH Spool
.................

`nnmh' is just like `nnml', except that is doesn't generate NOV
databases and it doesn't keep an active file or marks file.  This makes
`nnmh' a _much_ slower back end than `nnml', but it also makes it
easier to write procmail scripts for.

   Virtual server settings:

`nnmh-directory'
     All `nnmh' directories will be located under this directory.  The
     default is the value of `message-directory' (whose default is
     `~/Mail')

`nnmh-get-new-mail'
     If non-`nil', `nnmh' will read incoming mail.  The default is `t'.

`nnmh-be-safe'
     If non-`nil', `nnmh' will go to ridiculous lengths to make sure
     that the articles in the folder are actually what Gnus thinks they
     are.  It will check date stamps and stat everything in sight, so
     setting this to `t' will mean a serious slow-down.  If you never
     use anything but Gnus to read the `nnmh' articles, you do not have
     to set this variable to `t'.  The default is `nil'.


File: gnus,  Node: Maildir,  Next: Mail Folders,  Prev: MH Spool,  Up: Choosing a Mail Back End

6.4.13.5 Maildir
................

`nnmaildir' stores mail in the maildir format, with each maildir
corresponding to a group in Gnus.  This format is documented here:
`http://cr.yp.to/proto/maildir.html' and here:
`http://www.qmail.org/man/man5/maildir.html'.  `nnmaildir' also stores
extra information in the `.nnmaildir/' directory within a maildir.

   Maildir format was designed to allow concurrent deliveries and
reading, without needing locks.  With other back ends, you would have
your mail delivered to a spool of some kind, and then you would
configure Gnus to split mail from that spool into your groups.  You can
still do that with `nnmaildir', but the more common configuration is to
have your mail delivered directly to the maildirs that appear as group
in Gnus.

   `nnmaildir' is designed to be perfectly reliable: `C-g' will never
corrupt its data in memory, and `SIGKILL' will never corrupt its data
in the filesystem.

   `nnmaildir' stores article marks and NOV data in each maildir.  So
you can copy a whole maildir from one Gnus setup to another, and you
will keep your marks.

   Virtual server settings:

`directory'
     For each of your `nnmaildir' servers (it's very unlikely that
     you'd need more than one), you need to create a directory and
     populate it with maildirs or symlinks to maildirs (and nothing
     else; do not choose a directory already used for other purposes).
     Each maildir will be represented in Gnus as a newsgroup on that
     server; the filename of the symlink will be the name of the group.
     Any filenames in the directory starting with `.' are ignored.  The
     directory is scanned when you first start Gnus, and each time you
     type `g' in the group buffer; if any maildirs have been removed or
     added, `nnmaildir' notices at these times.

     The value of the `directory' parameter should be a Lisp form which
     is processed by `eval' and `expand-file-name' to get the path of
     the directory for this server.  The form is `eval'ed only when the
     server is opened; the resulting string is used until the server is
     closed.  (If you don't know about forms and `eval', don't worry--a
     simple string will work.)  This parameter is not optional; you
     must specify it.  I don't recommend using `"~/Mail"' or a
     subdirectory of it; several other parts of Gnus use that directory
     by default for various things, and may get confused if `nnmaildir'
     uses it too.  `"~/.nnmaildir"' is a typical value.

`target-prefix'
     This should be a Lisp form which is processed by `eval' and
     `expand-file-name'.  The form is `eval'ed only when the server is
     opened; the resulting string is used until the server is closed.

     When you create a group on an `nnmaildir' server, the maildir is
     created with `target-prefix' prepended to its name, and a symlink
     pointing to that maildir is created, named with the plain group
     name.  So if `directory' is `"~/.nnmaildir"' and `target-prefix'
     is `"../maildirs/"', then when you create the group `foo',
     `nnmaildir' will create `~/.nnmaildir/../maildirs/foo' as a
     maildir, and will create `~/.nnmaildir/foo' as a symlink pointing
     to `../maildirs/foo'.

     You can set `target-prefix' to a string without any slashes to
     create both maildirs and symlinks in the same `directory'; in this
     case, any maildirs found in `directory' whose names start with
     `target-prefix' will not be listed as groups (but the symlinks
     pointing to them will be).

     As a special case, if `target-prefix' is `""' (the default), then
     when you create a group, the maildir will be created in
     `directory' without a corresponding symlink.  Beware that you
     cannot use `gnus-group-delete-group' on such groups without the
     `force' argument.

`directory-files'
     This should be a function with the same interface as
     `directory-files' (such as `directory-files' itself).  It is used
     to scan the server's `directory' for maildirs.  This parameter is
     optional; the default is `nnheader-directory-files-safe' if
     `nnheader-directory-files-is-safe' is `nil', and `directory-files'
     otherwise.  (`nnheader-directory-files-is-safe' is checked only
     once when the server is opened; if you want to check it each time
     the directory is scanned, you'll have to provide your own function
     that does that.)

`get-new-mail'
     If non-`nil', then after scanning for new mail in the group
     maildirs themselves as usual, this server will also incorporate
     mail the conventional Gnus way, from `mail-sources' according to
     `nnmail-split-methods' or `nnmail-split-fancy'.  The default value
     is `nil'.

     Do _not_ use the same maildir both in `mail-sources' and as an
     `nnmaildir' group.  The results might happen to be useful, but
     that would be by chance, not by design, and the results might be
     different in the future.  If your split rules create new groups,
     remember to supply a `create-directory' server parameter.

6.4.13.6 Group parameters
.........................

`nnmaildir' uses several group parameters.  It's safe to ignore all
this; the default behavior for `nnmaildir' is the same as the default
behavior for other mail back ends: articles are deleted after one week,
etc.  Except for the expiry parameters, all this functionality is
unique to `nnmaildir', so you can ignore it if you're just trying to
duplicate the behavior you already have with another back end.

   If the value of any of these parameters is a vector, the first
element is evaluated as a Lisp form and the result is used, rather than
the original value.  If the value is not a vector, the value itself is
evaluated as a Lisp form.  (This is why these parameters use names
different from those of other, similar parameters supported by other
back ends: they have different, though similar, meanings.)  (For
numbers, strings, `nil', and `t', you can ignore the `eval' business
again; for other values, remember to use an extra quote and wrap the
value in a vector when appropriate.)

`expire-age'
     An integer specifying the minimum age, in seconds, of an article
     before it will be expired, or the symbol `never' to specify that
     articles should never be expired.  If this parameter is not set,
     `nnmaildir' falls back to the usual
     `nnmail-expiry-wait'(`-function') variables (the `expiry-wait'
     group parameter overrides `nnmail-expiry-wait' and makes
     `nnmail-expiry-wait-function' ineffective).  If you wanted a value
     of 3 days, you could use something like `[(* 3 24 60 60)]';
     `nnmaildir' will evaluate the form and use the result.  An
     article's age is measured starting from the article file's
     modification time.  Normally, this is the same as the article's
     delivery time, but editing an article makes it younger.  Moving an
     article (other than via expiry) may also make an article younger.

`expire-group'
     If this is set to a string such as a full Gnus group name, like
          "backend+server.address.string:group.name"
     and if it is not the name of the same group that the parameter
     belongs to, then articles will be moved to the specified group
     during expiry before being deleted.  _If this is set to an
     `nnmaildir' group, the article will be just as old in the
     destination group as it was in the source group._  So be careful
     with `expire-age' in the destination group.  If this is set to the
     name of the same group that the parameter belongs to, then the
     article is not expired at all.  If you use the vector form, the
     first element is evaluated once for each article.  So that form
     can refer to `nnmaildir-article-file-name', etc., to decide where
     to put the article.  _Even if this parameter is not set,
     `nnmaildir' does not fall back to the `expiry-target' group
     parameter or the `nnmail-expiry-target' variable._

`read-only'
     If this is set to `t', `nnmaildir' will treat the articles in this
     maildir as read-only.  This means: articles are not renamed from
     `new/' into `cur/'; articles are only found in `new/', not `cur/';
     articles are never deleted; articles cannot be edited.  `new/' is
     expected to be a symlink to the `new/' directory of another
     maildir--e.g., a system-wide mailbox containing a mailing list of
     common interest.  Everything in the maildir outside `new/' is
     _not_ treated as read-only, so for a shared mailbox, you do still
     need to set up your own maildir (or have write permission to the
     shared mailbox); your maildir just won't contain extra copies of
     the articles.

`directory-files'
     A function with the same interface as `directory-files'.  It is
     used to scan the directories in the maildir corresponding to this
     group to find articles.  The default is the function specified by
     the server's `directory-files' parameter.

`distrust-Lines:'
     If non-`nil', `nnmaildir' will always count the lines of an
     article, rather than use the `Lines:' header field.  If `nil', the
     header field will be used if present.

`always-marks'
     A list of mark symbols, such as `['(read expire)]'.  Whenever Gnus
     asks `nnmaildir' for article marks, `nnmaildir' will say that all
     articles have these marks, regardless of whether the marks stored
     in the filesystem say so.  This is a proof-of-concept feature that
     will probably be removed eventually; it ought to be done in Gnus
     proper, or abandoned if it's not worthwhile.

`never-marks'
     A list of mark symbols, such as `['(tick expire)]'.  Whenever Gnus
     asks `nnmaildir' for article marks, `nnmaildir' will say that no
     articles have these marks, regardless of whether the marks stored
     in the filesystem say so.  `never-marks' overrides `always-marks'.
     This is a proof-of-concept feature that will probably be removed
     eventually; it ought to be done in Gnus proper, or abandoned if
     it's not worthwhile.

`nov-cache-size'
     An integer specifying the size of the NOV memory cache.  To speed
     things up, `nnmaildir' keeps NOV data in memory for a limited
     number of articles in each group.  (This is probably not
     worthwhile, and will probably be removed in the future.)  This
     parameter's value is noticed only the first time a group is seen
     after the server is opened--i.e., when you first start Gnus,
     typically.  The NOV cache is never resized until the server is
     closed and reopened.  The default is an estimate of the number of
     articles that would be displayed in the summary buffer: a count of
     articles that are either marked with `tick' or not marked with
     `read', plus a little extra.

6.4.13.7 Article identification
...............................

Articles are stored in the `cur/' subdirectory of each maildir.  Each
article file is named like `uniq:info', where `uniq' contains no
colons.  `nnmaildir' ignores, but preserves, the `:info' part.  (Other
maildir readers typically use this part of the filename to store
marks.)  The `uniq' part uniquely identifies the article, and is used
in various places in the `.nnmaildir/' subdirectory of the maildir to
store information about the corresponding article.  The full pathname
of an article is available in the variable
`nnmaildir-article-file-name' after you request the article in the
summary buffer.

6.4.13.8 NOV data
.................

An article identified by `uniq' has its NOV data (used to generate
lines in the summary buffer) stored in `.nnmaildir/nov/uniq'.  There is
no `nnmaildir-generate-nov-databases' function.  (There isn't much need
for it--an article's NOV data is updated automatically when the article
or `nnmail-extra-headers' has changed.)  You can force `nnmaildir' to
regenerate the NOV data for a single article simply by deleting the
corresponding NOV file, but _beware_: this will also cause `nnmaildir'
to assign a new article number for this article, which may cause trouble
with `seen' marks, the Agent, and the cache.

6.4.13.9 Article marks
......................

An article identified by `uniq' is considered to have the mark `flag'
when the file `.nnmaildir/marks/flag/uniq' exists.  When Gnus asks
`nnmaildir' for a group's marks, `nnmaildir' looks for such files and
reports the set of marks it finds.  When Gnus asks `nnmaildir' to store
a new set of marks, `nnmaildir' creates and deletes the corresponding
files as needed.  (Actually, rather than create a new file for each
mark, it just creates hard links to `.nnmaildir/markfile', to save
inodes.)

   You can invent new marks by creating a new directory in
`.nnmaildir/marks/'.  You can tar up a maildir and remove it from your
server, untar it later, and keep your marks.  You can add and remove
marks yourself by creating and deleting mark files.  If you do this
while Gnus is running and your `nnmaildir' server is open, it's best to
exit all summary buffers for `nnmaildir' groups and type `s' in the
group buffer first, and to type `g' or `M-g' in the group buffer
afterwards.  Otherwise, Gnus might not pick up the changes, and might
undo them.


File: gnus,  Node: Mail Folders,  Next: Comparing Mail Back Ends,  Prev: Maildir,  Up: Choosing a Mail Back End

6.4.13.10 Mail Folders
......................

`nnfolder' is a back end for storing each mail group in a separate
file.  Each file is in the standard Un*x mbox format.  `nnfolder' will
add extra headers to keep track of article numbers and arrival dates.

   When the marks file is used (which it is by default), `nnfolder'
servers have the property that you may backup them using `tar' or
similar, and later be able to restore them into Gnus (by adding the
proper `nnfolder' server) and have all your marks be preserved.  Marks
for a group are usually stored in a file named as the mbox file with
`.mrk' concatenated to it (but see `nnfolder-marks-file-suffix') within
the `nnfolder' directory.  Individual `nnfolder' groups are also
possible to backup, use `G m' to restore the group (after restoring the
backup into the `nnfolder' directory).

   Virtual server settings:

`nnfolder-directory'
     All the `nnfolder' mail boxes will be stored under this directory.
     The default is the value of `message-directory' (whose default is
     `~/Mail')

`nnfolder-active-file'
     The name of the active file.  The default is `~/Mail/active'.

`nnfolder-newsgroups-file'
     The name of the group descriptions file.  *Note Newsgroups File
     Format::.  The default is `~/Mail/newsgroups'

`nnfolder-get-new-mail'
     If non-`nil', `nnfolder' will read incoming mail.  The default is
     `t'

`nnfolder-save-buffer-hook'
     Hook run before saving the folders.  Note that Emacs does the
     normal backup renaming of files even with the `nnfolder' buffers.
     If you wish to switch this off, you could say something like the
     following in your `.emacs' file:

          (defun turn-off-backup ()
            (set (make-local-variable 'backup-inhibited) t))

          (add-hook 'nnfolder-save-buffer-hook 'turn-off-backup)

`nnfolder-delete-mail-hook'
     Hook run in a buffer narrowed to the message that is to be deleted.
     This function can be used to copy the message to somewhere else,
     or to extract some information from it before removing it.

`nnfolder-nov-is-evil'
     If non-`nil', this back end will ignore any NOV files.  The
     default is `nil'.

`nnfolder-nov-file-suffix'
     The extension for NOV files.  The default is `.nov'.

`nnfolder-nov-directory'
     The directory where the NOV files should be stored.  If `nil',
     `nnfolder-directory' is used.

`nnfolder-marks-is-evil'
     If non-`nil', this back end will ignore any MARKS files.  The
     default is `nil'.

`nnfolder-marks-file-suffix'
     The extension for MARKS files.  The default is `.mrk'.

`nnfolder-marks-directory'
     The directory where the MARKS files should be stored.  If `nil',
     `nnfolder-directory' is used.


   If you have lots of `nnfolder'-like files you'd like to read with
`nnfolder', you can use the `M-x nnfolder-generate-active-file' command
to make `nnfolder' aware of all likely files in `nnfolder-directory'.
This only works if you use long file names, though.


File: gnus,  Node: Comparing Mail Back Ends,  Prev: Mail Folders,  Up: Choosing a Mail Back End

6.4.13.11 Comparing Mail Back Ends
..................................

First, just for terminology, the "back end" is the common word for a
low-level access method--a transport, if you will, by which something
is acquired.  The sense is that one's mail has to come from somewhere,
and so selection of a suitable back end is required in order to get that
mail within spitting distance of Gnus.

   The same concept exists for Usenet itself: Though access to articles
is typically done by NNTP these days, once upon a midnight dreary,
everyone in the world got at Usenet by running a reader on the machine
where the articles lay (the machine which today we call an NNTP
server), and access was by the reader stepping into the articles'
directory spool area directly.  One can still select between either the
`nntp' or `nnspool' back ends, to select between these methods, if one
happens actually to live on the server (or can see its spool directly,
anyway, via NFS).

   The goal in selecting a mail back end is to pick one which
simultaneously represents a suitable way of dealing with the original
format plus leaving mail in a form that is convenient to use in the
future.  Here are some high and low points on each:

`nnmbox'
     UNIX systems have historically had a single, very common, and well-
     defined format.  All messages arrive in a single "spool file", and
     they are delineated by a line whose regular expression matches
     `^From_'.  (My notational use of `_' is to indicate a space, to
     make it clear in this instance that this is not the RFC-specified
     `From:' header.)  Because Emacs and therefore Gnus emanate
     historically from the Unix environment, it is simplest if one does
     not mess a great deal with the original mailbox format, so if one
     chooses this back end, Gnus' primary activity in getting mail from
     the real spool area to Gnus' preferred directory is simply to copy
     it, with no (appreciable) format change in the process.  It is the
     "dumbest" way to move mail into availability in the Gnus
     environment.  This makes it fast to move into place, but slow to
     parse, when Gnus has to look at what's where.

`nnbabyl'
     Once upon a time, there was the DEC-10 and DEC-20, running
     operating systems called TOPS and related things, and the usual
     (only?) mail reading environment was a thing called Babyl.  I
     don't know what format was used for mail landing on the system,
     but Babyl had its own internal format to which mail was converted,
     primarily involving creating a spool-file-like entity with a
     scheme for inserting Babyl-specific headers and status bits above
     the top of each message in the file.  Rmail was Emacs's first mail
     reader, it was written by Richard Stallman, and Stallman came out
     of that TOPS/Babyl environment, so he wrote Rmail to understand
     the mail files folks already had in existence.  Gnus (and VM, for
     that matter) continue to support this format because it's
     perceived as having some good qualities in those mailer-specific
     headers/status bits stuff.  Rmail itself still exists as well, of
     course, and is still maintained within Emacs.  Since Emacs 23, it
     uses standard mbox format rather than Babyl.

     Both of the above forms leave your mail in a single file on your
     file system, and they must parse that entire file each time you
     take a look at your mail.

`nnml'
     `nnml' is the back end which smells the most as though you were
     actually operating with an `nnspool'-accessed Usenet system.  (In
     fact, I believe `nnml' actually derived from `nnspool' code, lo
     these years ago.)  One's mail is taken from the original spool
     file, and is then cut up into individual message files, 1:1.  It
     maintains a Usenet-style active file (analogous to what one finds
     in an INN- or CNews-based news system in (for instance)
     `/var/lib/news/active', or what is returned via the `NNTP LIST'
     verb) and also creates "overview" files for efficient group entry,
     as has been defined for NNTP servers for some years now.  It is
     slower in mail-splitting, due to the creation of lots of files,
     updates to the `nnml' active file, and additions to overview files
     on a per-message basis, but it is extremely fast on access because
     of what amounts to the indexing support provided by the active
     file and overviews.

     `nnml' costs "inodes" in a big way; that is, it soaks up the
     resource which defines available places in the file system to put
     new files.  Sysadmins take a dim view of heavy inode occupation
     within tight, shared file systems.  But if you live on a personal
     machine where the file system is your own and space is not at a
     premium, `nnml' wins big.

     It is also problematic using this back end if you are living in a
     FAT16-based Windows world, since much space will be wasted on all
     these tiny files.

`nnmh'
     The Rand MH mail-reading system has been around UNIX systems for a
     very long time; it operates by splitting one's spool file of
     messages into individual files, but with little or no indexing
     support--`nnmh' is considered to be semantically equivalent to
     "`nnml' without active file or overviews".  This is arguably the
     worst choice, because one gets the slowness of individual file
     creation married to the slowness of access parsing when learning
     what's new in one's groups.

`nnfolder'
     Basically the effect of `nnfolder' is `nnmbox' (the first method
     described above) on a per-group basis.  That is, `nnmbox' itself
     puts _all_ one's mail in one file; `nnfolder' provides a little
     bit of optimization to this so that each of one's mail groups has
     a Unix mail box file.  It's faster than `nnmbox' because each group
     can be parsed separately, and still provides the simple Unix mail
     box format requiring minimal effort in moving the mail around.  In
     addition, it maintains an "active" file making it much faster for
     Gnus to figure out how many messages there are in each separate
     group.

     If you have groups that are expected to have a massive amount of
     messages, `nnfolder' is not the best choice, but if you receive
     only a moderate amount of mail, `nnfolder' is probably the most
     friendly mail back end all over.

`nnmaildir'
     For configuring expiry and other things, `nnmaildir' uses
     incompatible group parameters, slightly different from those of
     other mail back ends.

     `nnmaildir' is largely similar to `nnml', with some notable
     differences. Each message is stored in a separate file, but the
     filename is unrelated to the article number in Gnus. `nnmaildir'
     also stores the equivalent of `nnml''s overview files in one file
     per article, so it uses about twice as many inodes as `nnml'.
     (Use `df -i' to see how plentiful your inode supply is.) If this
     slows you down or takes up very much space, a non-block-structured
     file system.

     Since maildirs don't require locking for delivery, the maildirs
     you use as groups can also be the maildirs your mail is directly
     delivered to.  This means you can skip Gnus' mail splitting if
     your mail is already organized into different mailboxes during
     delivery.  A `directory' entry in `mail-sources' would have a
     similar effect, but would require one set of mailboxes for
     spooling deliveries (in mbox format, thus damaging message
     bodies), and another set to be used as groups (in whatever format
     you like).  A maildir has a built-in spool, in the `new/'
     subdirectory.  Beware that currently, mail moved from `new/' to
     `cur/' instead of via mail splitting will not undergo treatment
     such as duplicate checking.

     `nnmaildir' stores article marks for a given group in the
     corresponding maildir, in a way designed so that it's easy to
     manipulate them from outside Gnus.  You can tar up a maildir,
     unpack it somewhere else, and still have your marks.  `nnml' also
     stores marks, but it's not as easy to work with them from outside
     Gnus as with `nnmaildir'.

     `nnmaildir' uses a significant amount of memory to speed things up.
     (It keeps in memory some of the things that `nnml' stores in files
     and that `nnmh' repeatedly parses out of message files.)  If this
     is a problem for you, you can set the `nov-cache-size' group
     parameter to something small (0 would probably not work, but 1
     probably would) to make it use less memory.  This caching will
     probably be removed in the future.

     Startup is likely to be slower with `nnmaildir' than with other
     back ends.  Everything else is likely to be faster, depending in
     part on your file system.

     `nnmaildir' does not use `nnoo', so you cannot use `nnoo' to write
     an `nnmaildir'-derived back end.



File: gnus,  Node: Browsing the Web,  Next: Other Sources,  Prev: Getting Mail,  Up: Select Methods

6.5 Browsing the Web
====================

Web-based discussion forums are getting more and more popular.  On many
subjects, the web-based forums have become the most important forums,
eclipsing the importance of mailing lists and news groups.  The reason
is easy to understand--they are friendly to new users; you just point
and click, and there's the discussion.  With mailing lists, you have to
go through a cumbersome subscription procedure, and most people don't
even know what a news group is.

   The problem with this scenario is that web browsers are not very
good at being newsreaders.  They do not keep track of what articles
you've read; they do not allow you to score on subjects you're
interested in; they do not allow off-line browsing; they require you to
click around and drive you mad in the end.

   So--if web browsers suck at reading discussion forums, why not use
Gnus to do it instead?

   Gnus has been getting a bit of a collection of back ends for
providing interfaces to these sources.

* Menu:

* Archiving Mail::
* Web Searches::                Creating groups from articles that match a string.
* RSS::                         Reading RDF site summary.
* Customizing W3::              Doing stuff to Emacs/W3 from Gnus.

   All the web sources require Emacs/W3 and the url library or those
alternatives to work.

   The main caveat with all these web sources is that they probably
won't work for a very long time.  Gleaning information from the HTML
data is guesswork at best, and when the layout is altered, the Gnus
back end will fail.  If you have reasonably new versions of these back
ends, though, you should be ok.

   One thing all these Web methods have in common is that the Web
sources are often down, unavailable or just plain too slow to be fun.
In those cases, it makes a lot of sense to let the Gnus Agent (*note
Gnus Unplugged::) handle downloading articles, and then you can read
them at leisure from your local disk.  No more World Wide Wait for you.


File: gnus,  Node: Archiving Mail,  Next: Web Searches,  Up: Browsing the Web

6.5.1 Archiving Mail
--------------------

Some of the back ends, notably `nnml', `nnfolder', and `nnmaildir', now
actually store the article marks with each group.  For these servers,
archiving and restoring a group while preserving marks is fairly simple.

   (Preserving the group level and group parameters as well still
requires ritual dancing and sacrifices to the `.newsrc.eld' deity
though.)

   To archive an entire `nnml', `nnfolder', or `nnmaildir' server, take
a recursive copy of the server directory.  There is no need to shut
down Gnus, so archiving may be invoked by `cron' or similar.  You
restore the data by restoring the directory tree, and adding a server
definition pointing to that directory in Gnus.  The *note Article
Backlog::, *note Asynchronous Fetching:: and other things might
interfere with overwriting data, so you may want to shut down Gnus
before you restore the data.

   It is also possible to archive individual `nnml', `nnfolder', or
`nnmaildir' groups, while preserving marks.  For `nnml' or `nnmaildir',
you copy all files in the group's directory.  For `nnfolder' you need
to copy both the base folder file itself (`FOO', say), and the marks
file (`FOO.mrk' in this example).  Restoring the group is done with `G
m' from the Group buffer.  The last step makes Gnus notice the new
directory.  `nnmaildir' notices the new directory automatically, so `G
m' is unnecessary in that case.


File: gnus,  Node: Web Searches,  Next: RSS,  Prev: Archiving Mail,  Up: Browsing the Web

6.5.2 Web Searches
------------------

It's, like, too neat to search the Usenet for articles that match a
string, but it, like, totally _sucks_, like, totally, to use one of
those, like, Web browsers, and you, like, have to, rilly, like, look at
the commercials, so, like, with Gnus you can do _rad_, rilly, searches
without having to use a browser.

   The `nnweb' back end allows an easy interface to the mighty search
engine.  You create an `nnweb' group, enter a search pattern, and then
enter the group and read the articles like you would any normal group.
The `G w' command in the group buffer (*note Foreign Groups::) will do
this in an easy-to-use fashion.

   `nnweb' groups don't really lend themselves to being solid
groups--they have a very fleeting idea of article numbers.  In fact,
each time you enter an `nnweb' group (not even changing the search
pattern), you are likely to get the articles ordered in a different
manner.  Not even using duplicate suppression (*note Duplicate
Suppression::) will help, since `nnweb' doesn't even know the
`Message-ID' of the articles before reading them using some search
engines (Google, for instance).  The only possible way to keep track of
which articles you've read is by scoring on the `Date' header--mark all
articles posted before the last date you read the group as read.

   If the search engine changes its output substantially, `nnweb' won't
be able to parse it and will fail.  One could hardly fault the Web
providers if they were to do this--their _raison d'être_ is to make
money off of advertisements, not to provide services to the community.
Since `nnweb' washes the ads off all the articles, one might think that
the providers might be somewhat miffed.  We'll see.

   You must have the `url' and `W3' package or those alternatives (try
`customize-group' on the `mm-url' variable group) installed to be able
to use `nnweb'.

   Virtual server variables:

`nnweb-type'
     What search engine type is being used.  The currently supported
     types are `google', `dejanews', and `gmane'.  Note that `dejanews'
     is an alias to `google'.

`nnweb-search'
     The search string to feed to the search engine.

`nnweb-max-hits'
     Advisory maximum number of hits per search to display.  The
     default is 999.

`nnweb-type-definition'
     Type-to-definition alist.  This alist says what `nnweb' should do
     with the various search engine types.  The following elements must
     be present:

    `article'
          Function to decode the article and provide something that Gnus
          understands.

    `map'
          Function to create an article number to message header and
          URL alist.

    `search'
          Function to send the search string to the search engine.

    `address'
          The address the aforementioned function should send the
          search string to.

    `id'
          Format string URL to fetch an article by `Message-ID'.



File: gnus,  Node: RSS,  Next: Customizing W3,  Prev: Web Searches,  Up: Browsing the Web

6.5.3 RSS
---------

Some web sites have an RDF Site Summary (RSS).  RSS is a format for
summarizing headlines from news related sites (such as BBC or CNN).
But basically anything list-like can be presented as an RSS feed:
weblogs, changelogs or recent changes to a wiki (e.g.
`http://cliki.net/recent-changes.rdf').

   RSS has a quite regular and nice interface, and it's possible to get
the information Gnus needs to keep groups updated.

   Note: you had better use Emacs which supports the `utf-8' coding
system because RSS uses UTF-8 for encoding non-ASCII text by default.
It is also used by default for non-ASCII group names.

   Use `G R' from the group buffer to subscribe to a feed--you will be
prompted for the location, the title and the description of the feed.
The title, which allows any characters, will be used for the group name
and the name of the group data file.  The description can be omitted.

   An easy way to get started with `nnrss' is to say something like the
following in the group buffer: `B nnrss RET RET y', then subscribe to
groups.

   The `nnrss' back end saves the group data file in `nnrss-directory'
(see below) for each `nnrss' group.  File names containing non-ASCII
characters will be encoded by the coding system specified with the
`nnmail-pathname-coding-system' variable or other.  Also *Note
Non-ASCII Group Names::, for more information.

   The `nnrss' back end generates `multipart/alternative' MIME articles
in which each contains a `text/plain' part and a `text/html' part.

   You can also use the following commands to import and export your
subscriptions from a file in OPML format (Outline Processor Markup
Language).

 -- Function: nnrss-opml-import file
     Prompt for an OPML file, and subscribe to each feed in the file.

 -- Function: nnrss-opml-export
     Write your current RSS subscriptions to a buffer in OPML format.

   The following `nnrss' variables can be altered:

`nnrss-directory'
     The directory where `nnrss' stores its files.  The default is
     `~/News/rss/'.

`nnrss-file-coding-system'
     The coding system used when reading and writing the `nnrss' groups
     data files.  The default is the value of
     `mm-universal-coding-system' (which defaults to `emacs-mule' in
     Emacs or `escape-quoted' in XEmacs).

`nnrss-ignore-article-fields'
     Some feeds update constantly article fields during their
     publications, e.g. to indicate the number of comments.  However,
     if there is a difference between the local article and the distant
     one, the latter is considered to be new.  To avoid this and
     discard some fields, set this variable to the list of fields to be
     ignored.  The default is `'(slash:comments)'.

`nnrss-use-local'
     If you set `nnrss-use-local' to `t', `nnrss' will read the feeds
     from local files in `nnrss-directory'.  You can use the command
     `nnrss-generate-download-script' to generate a download script
     using `wget'.

   The following code may be helpful, if you want to show the
description in the summary buffer.

     (add-to-list 'nnmail-extra-headers nnrss-description-field)
     (setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n")

     (defun gnus-user-format-function-X (header)
       (let ((descr
              (assq nnrss-description-field (mail-header-extra header))))
         (if descr (concat "\n\t" (cdr descr)) "")))

   The following code may be useful to open an nnrss url directly from
the summary buffer.

     (require 'browse-url)

     (defun browse-nnrss-url (arg)
       (interactive "p")
       (let ((url (assq nnrss-url-field
                        (mail-header-extra
                         (gnus-data-header
                          (assq (gnus-summary-article-number)
                                gnus-newsgroup-data))))))
         (if url
             (progn
               (browse-url (cdr url))
               (gnus-summary-mark-as-read-forward 1))
           (gnus-summary-scroll-up arg))))

     (eval-after-load "gnus"
       #'(define-key gnus-summary-mode-map
           (kbd "<RET>") 'browse-nnrss-url))
     (add-to-list 'nnmail-extra-headers nnrss-url-field)

   Even if you have added `text/html' to the
`mm-discouraged-alternatives' variable (*note Display Customization:
(emacs-mime)Display Customization.) since you don't want to see HTML
parts, it might be more useful especially in `nnrss' groups to display
`text/html' parts.  Here's an example of setting
`mm-discouraged-alternatives' as a group parameter (*note Group
Parameters::) in order to display `text/html' parts only in `nnrss'
groups:

     ;; Set the default value of `mm-discouraged-alternatives'.
     (eval-after-load "gnus-sum"
       '(add-to-list
         'gnus-newsgroup-variables
         '(mm-discouraged-alternatives
           . '("text/html" "image/.*"))))

     ;; Display `text/html' parts in `nnrss' groups.
     (add-to-list
      'gnus-parameters
      '("\\`nnrss:" (mm-discouraged-alternatives nil)))


File: gnus,  Node: Customizing W3,  Prev: RSS,  Up: Browsing the Web

6.5.4 Customizing W3
--------------------

Gnus uses the url library to fetch web pages and Emacs/W3 (or those
alternatives) to display web pages.  Emacs/W3 is documented in its own
manual, but there are some things that may be more relevant for Gnus
users.

   For instance, a common question is how to make Emacs/W3 follow links
using the `browse-url' functions (which will call some external web
browser like Netscape).  Here's one way:

     (eval-after-load "w3"
       '(progn
         (fset 'w3-fetch-orig (symbol-function 'w3-fetch))
         (defun w3-fetch (&optional url target)
           (interactive (list (w3-read-url-with-default)))
           (if (eq major-mode 'gnus-article-mode)
               (browse-url url)
             (w3-fetch-orig url target)))))

   Put that in your `.emacs' file, and hitting links in W3-rendered
HTML in the Gnus article buffers will use `browse-url' to follow the
link.


File: gnus,  Node: Other Sources,  Next: Combined Groups,  Prev: Browsing the Web,  Up: Select Methods

6.6 Other Sources
=================

Gnus can do more than just read news or mail.  The methods described
below allow Gnus to view directories and files as if they were
newsgroups.

* Menu:

* Directory Groups::            You can read a directory as if it was a newsgroup.
* Anything Groups::             Dired?  Who needs dired?
* Document Groups::             Single files can be the basis of a group.
* Mail-To-News Gateways::       Posting articles via mail-to-news gateways.
* The Empty Backend::           The backend that never has any news.


File: gnus,  Node: Directory Groups,  Next: Anything Groups,  Up: Other Sources

6.6.1 Directory Groups
----------------------

If you have a directory that has lots of articles in separate files in
it, you might treat it as a newsgroup.  The files have to have numerical
names, of course.

   This might be an opportune moment to mention `ange-ftp' (and its
successor `efs'), that most wonderful of all wonderful Emacs packages.
When I wrote `nndir', I didn't think much about it--a back end to read
directories.  Big deal.

   `ange-ftp' changes that picture dramatically.  For instance, if you
enter the `ange-ftp' file name `/ftp.hpc.uh.edu:/pub/emacs/ding-list/'
as the directory name, `ange-ftp' or `efs' will actually allow you to
read this directory over at `sina' as a newsgroup.  Distributed news
ahoy!

   `nndir' will use NOV files if they are present.

   `nndir' is a "read-only" back end--you can't delete or expire
articles with this method.  You can use `nnmh' or `nnml' for whatever
you use `nndir' for, so you could switch to any of those methods if you
feel the need to have a non-read-only `nndir'.


File: gnus,  Node: Anything Groups,  Next: Document Groups,  Prev: Directory Groups,  Up: Other Sources

6.6.2 Anything Groups
---------------------

From the `nndir' back end (which reads a single spool-like directory),
it's just a hop and a skip to `nneething', which pretends that any
arbitrary directory is a newsgroup.  Strange, but true.

   When `nneething' is presented with a directory, it will scan this
directory and assign article numbers to each file.  When you enter such
a group, `nneething' must create "headers" that Gnus can use.  After
all, Gnus is a newsreader, in case you're forgetting.  `nneething' does
this in a two-step process.  First, it snoops each file in question.
If the file looks like an article (i.e., the first few lines look like
headers), it will use this as the head.  If this is just some arbitrary
file without a head (e.g. a C source file), `nneething' will cobble up
a header out of thin air.  It will use file ownership, name and date
and do whatever it can with these elements.

   All this should happen automatically for you, and you will be
presented with something that looks very much like a newsgroup.
Totally like a newsgroup, to be precise.  If you select an article, it
will be displayed in the article buffer, just as usual.

   If you select a line that represents a directory, Gnus will pop you
into a new summary buffer for this `nneething' group.  And so on.  You
can traverse the entire disk this way, if you feel like, but remember
that Gnus is not dired, really, and does not intend to be, either.

   There are two overall modes to this action--ephemeral or solid.  When
doing the ephemeral thing (i.e., `G D' from the group buffer), Gnus
will not store information on what files you have read, and what files
are new, and so on.  If you create a solid `nneething' group the normal
way with `G m', Gnus will store a mapping table between article numbers
and file names, and you can treat this group like any other groups.
When you activate a solid `nneething' group, you will be told how many
unread articles it contains, etc., etc.

   Some variables:

`nneething-map-file-directory'
     All the mapping files for solid `nneething' groups will be stored
     in this directory, which defaults to `~/.nneething/'.

`nneething-exclude-files'
     All files that match this regexp will be ignored.  Nice to use to
     exclude auto-save files and the like, which is what it does by
     default.

`nneething-include-files'
     Regexp saying what files to include in the group.  If this
     variable is non-`nil', only files matching this regexp will be
     included.

`nneething-map-file'
     Name of the map files.


File: gnus,  Node: Document Groups,  Next: Mail-To-News Gateways,  Prev: Anything Groups,  Up: Other Sources

6.6.3 Document Groups
---------------------

`nndoc' is a cute little thing that will let you read a single file as
a newsgroup.  Several files types are supported:

`babyl'
     The Babyl format.

`mbox'
     The standard Unix mbox file.

`mmdf'
     The MMDF mail box format.

`news'
     Several news articles appended into a file.

`rnews'
     The rnews batch transport format.

`nsmail'
     Netscape mail boxes.

`mime-parts'
     MIME multipart messages.

`standard-digest'
     The standard (RFC 1153) digest format.

`mime-digest'
     A MIME digest of messages.

`lanl-gov-announce'
     Announcement messages from LANL Gov Announce.

`git'
     `git' commit messages.

`rfc822-forward'
     A message forwarded according to RFC822.

`outlook'
     The Outlook mail box.

`oe-dbx'
     The Outlook Express dbx mail box.

`exim-bounce'
     A bounce message from the Exim MTA.

`forward'
     A message forwarded according to informal rules.

`rfc934'
     An RFC934-forwarded message.

`mailman'
     A mailman digest.

`clari-briefs'
     A digest of Clarinet brief news items.

`slack-digest'
     Non-standard digest format--matches most things, but does it badly.

`mail-in-mail'
     The last resort.

   You can also use the special "file type" `guess', which means that
`nndoc' will try to guess what file type it is looking at.  `digest'
means that `nndoc' should guess what digest type the file is.

   `nndoc' will not try to change the file or insert any extra headers
into it--it will simply, like, let you use the file as the basis for a
group.  And that's it.

   If you have some old archived articles that you want to insert into
your new & spiffy Gnus mail back end, `nndoc' can probably help you with
that.  Say you have an old `RMAIL' file with mail that you now want to
split into your new `nnml' groups.  You look at that file using `nndoc'
(using the `G f' command in the group buffer (*note Foreign Groups::)),
set the process mark on all the articles in the buffer (`M P b', for
instance), and then re-spool (`B r') using `nnml'.  If all goes well,
all the mail in the `RMAIL' file is now also stored in lots of `nnml'
directories, and you can delete that pesky `RMAIL' file.  If you have
the guts!

   Virtual server variables:

`nndoc-article-type'
     This should be one of `mbox', `babyl', `digest', `news', `rnews',
     `mmdf', `forward', `rfc934', `rfc822-forward', `mime-parts',
     `standard-digest', `slack-digest', `clari-briefs', `nsmail',
     `outlook', `oe-dbx', `mailman', and `mail-in-mail' or `guess'.

`nndoc-post-type'
     This variable says whether Gnus is to consider the group a news
     group or a mail group.  There are two valid values:  `mail' (the
     default) and `news'.

* Menu:

* Document Server Internals::   How to add your own document types.


File: gnus,  Node: Document Server Internals,  Up: Document Groups

6.6.3.1 Document Server Internals
.................................

Adding new document types to be recognized by `nndoc' isn't difficult.
You just have to whip up a definition of what the document looks like,
write a predicate function to recognize that document type, and then
hook into `nndoc'.

   First, here's an example document type definition:

     (mmdf
      (article-begin .  "^\^A\^A\^A\^A\n")
      (body-end .  "^\^A\^A\^A\^A\n"))

   The definition is simply a unique "name" followed by a series of
regexp pseudo-variable settings.  Below are the possible
variables--don't be daunted by the number of variables; most document
types can be defined with very few settings:

`first-article'
     If present, `nndoc' will skip past all text until it finds
     something that match this regexp.  All text before this will be
     totally ignored.

`article-begin'
     This setting has to be present in all document type definitions.
     It says what the beginning of each article looks like.  To do more
     complicated things that cannot be dealt with a simple regexp, you
     can use `article-begin-function' instead of this.

`article-begin-function'
     If present, this should be a function that moves point to the
     beginning of each article.  This setting overrides `article-begin'.

`head-begin'
     If present, this should be a regexp that matches the head of the
     article.  To do more complicated things that cannot be dealt with a
     simple regexp, you can use `head-begin-function' instead of this.

`head-begin-function'
     If present, this should be a function that moves point to the head
     of the article.  This setting overrides `head-begin'.

`head-end'
     This should match the end of the head of the article.  It defaults
     to `^$'--the empty line.

`body-begin'
     This should match the beginning of the body of the article.  It
     defaults to `^\n'.  To do more complicated things that cannot be
     dealt with a simple regexp, you can use `body-begin-function'
     instead of this.

`body-begin-function'
     If present, this function should move point to the beginning of
     the body of the article.  This setting overrides `body-begin'.

`body-end'
     If present, this should match the end of the body of the article.
     To do more complicated things that cannot be dealt with a simple
     regexp, you can use `body-end-function' instead of this.

`body-end-function'
     If present, this function should move point to the end of the body
     of the article.  This setting overrides `body-end'.

`file-begin'
     If present, this should match the beginning of the file.  All text
     before this regexp will be totally ignored.

`file-end'
     If present, this should match the end of the file.  All text after
     this regexp will be totally ignored.


   So, using these variables `nndoc' is able to dissect a document file
into a series of articles, each with a head and a body.  However, a few
more variables are needed since not all document types are all that
news-like--variables needed to transform the head or the body into
something that's palatable for Gnus:

`prepare-body-function'
     If present, this function will be called when requesting an
     article.  It will be called with point at the start of the body,
     and is useful if the document has encoded some parts of its
     contents.

`article-transform-function'
     If present, this function is called when requesting an article.
     It's meant to be used for more wide-ranging transformation of both
     head and body of the article.

`generate-head-function'
     If present, this function is called to generate a head that Gnus
     can understand.  It is called with the article number as a
     parameter, and is expected to generate a nice head for the article
     in question.  It is called when requesting the headers of all
     articles.

`generate-article-function'
     If present, this function is called to generate an entire article
     that Gnus can understand.  It is called with the article number as
     a parameter when requesting all articles.

`dissection-function'
     If present, this function is called to dissect a document by
     itself, overriding `first-article', `article-begin',
     `article-begin-function', `head-begin', `head-begin-function',
     `head-end', `body-begin', `body-begin-function', `body-end',
     `body-end-function', `file-begin', and `file-end'.


   Let's look at the most complicated example I can come up
with--standard digests:

     (standard-digest
      (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+"))
      (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+"))
      (prepare-body-function . nndoc-unquote-dashes)
      (body-end-function . nndoc-digest-body-end)
      (head-end . "^ ?$")
      (body-begin . "^ ?\n")
      (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$")
      (subtype digest guess))

   We see that all text before a 70-width line of dashes is ignored; all
text after a line that starts with that `^End of' is also ignored; each
article begins with a 30-width line of dashes; the line separating the
head from the body may contain a single space; and that the body is run
through `nndoc-unquote-dashes' before being delivered.

   To hook your own document definition into `nndoc', use the
`nndoc-add-type' function.  It takes two parameters--the first is the
definition itself and the second (optional) parameter says where in the
document type definition alist to put this definition.  The alist is
traversed sequentially, and `nndoc-TYPE-type-p' is called for a given
type TYPE.  So `nndoc-mmdf-type-p' is called to see whether a document
is of `mmdf' type, and so on.  These type predicates should return
`nil' if the document is not of the correct type; `t' if it is of the
correct type; and a number if the document might be of the correct
type.  A high number means high probability; a low number means low
probability with `0' being the lowest valid number.


File: gnus,  Node: Mail-To-News Gateways,  Next: The Empty Backend,  Prev: Document Groups,  Up: Other Sources

6.6.4 Mail-To-News Gateways
---------------------------

If your local `nntp' server doesn't allow posting, for some reason or
other, you can post using one of the numerous mail-to-news gateways.
The `nngateway' back end provides the interface.

   Note that you can't read anything from this back end--it can only be
used to post with.

   Server variables:

`nngateway-address'
     This is the address of the mail-to-news gateway.

`nngateway-header-transformation'
     News headers often have to be transformed in some odd way or other
     for the mail-to-news gateway to accept it.  This variable says what
     transformation should be called, and defaults to
     `nngateway-simple-header-transformation'.  The function is called
     narrowed to the headers to be transformed and with one
     parameter--the gateway address.

     This default function just inserts a new `To' header based on the
     `Newsgroups' header and the gateway address.  For instance, an
     article with this `Newsgroups' header:

          Newsgroups: alt.religion.emacs

     will get this `To' header inserted:

          To: alt-religion-emacs@GATEWAY

     The following pre-defined functions exist:

    `nngateway-simple-header-transformation'
          Creates a `To' header that looks like
          NEWSGROUP@`nngateway-address'.

    `nngateway-mail2news-header-transformation'
          Creates a `To' header that looks like `nngateway-address'.


   Here's an example:

     (setq gnus-post-method
           '(nngateway
             "mail2news@replay.com"
             (nngateway-header-transformation
              nngateway-mail2news-header-transformation)))

   So, to use this, simply say something like:

     (setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))


File: gnus,  Node: The Empty Backend,  Prev: Mail-To-News Gateways,  Up: Other Sources

6.6.5 The Empty Backend
-----------------------

`nnnil' is a backend that can be used as a placeholder if you have to
specify a backend somewhere, but don't really want to.  The classical
example is if you don't want to have a primary select methods, but want
to only use secondary ones:

     (setq gnus-select-method '(nnnil ""))
     (setq gnus-secondary-select-methods
           '((nnimap "foo")
             (nnml "")))


File: gnus,  Node: Combined Groups,  Next: Email Based Diary,  Prev: Other Sources,  Up: Select Methods

6.7 Combined Groups
===================

Gnus allows combining a mixture of all the other group types into bigger
groups.

* Menu:

* Virtual Groups::              Combining articles from many groups.


File: gnus,  Node: Virtual Groups,  Up: Combined Groups

6.7.1 Virtual Groups
--------------------

An "nnvirtual group" is really nothing more than a collection of other
groups.

   For instance, if you are tired of reading many small groups, you can
put them all in one big group, and then grow tired of reading one big,
unwieldy group.  The joys of computing!

   You specify `nnvirtual' as the method.  The address should be a
regexp to match component groups.

   All marks in the virtual group will stick to the articles in the
component groups.  So if you tick an article in a virtual group, the
article will also be ticked in the component group from whence it came.
(And vice versa--marks from the component groups will also be shown in
the virtual group.).  To create an empty virtual group, run `G V'
(`gnus-group-make-empty-virtual') in the group buffer and edit the
method regexp with `M-e' (`gnus-group-edit-group-method')

   Here's an example `nnvirtual' method that collects all Andrea Dworkin
newsgroups into one, big, happy newsgroup:

     (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")

   The component groups can be native or foreign; everything should work
smoothly, but if your computer explodes, it was probably my fault.

   Collecting the same group from several servers might actually be a
good idea if users have set the Distribution header to limit
distribution.  If you would like to read `soc.motss' both from a server
in Japan and a server in Norway, you could use the following as the
group regexp:

     "^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$"

   (Remember, though, that if you're creating the group with `G m', you
shouldn't double the backslashes, and you should leave off the quote
characters at the beginning and the end of the string.)

   This should work kinda smoothly--all articles from both groups should
end up in this one, and there should be no duplicates.  Threading (and
the rest) will still work as usual, but there might be problems with the
sequence of articles.  Sorting on date might be an option here (*note
Selecting a Group::).

   One limitation, however--all groups included in a virtual group have
to be alive (i.e., subscribed or unsubscribed).  Killed or zombie
groups can't be component groups for `nnvirtual' groups.

   If the `nnvirtual-always-rescan' variable is non-`nil' (which is the
default), `nnvirtual' will always scan groups for unread articles when
entering a virtual group.  If this variable is `nil' and you read
articles in a component group after the virtual group has been
activated, the read articles from the component group will show up when
you enter the virtual group.  You'll also see this effect if you have
two virtual groups that have a component group in common.  If that's
the case, you should set this variable to `t'.  Or you can just tap
`M-g' on the virtual group every time before you enter it--it'll have
much the same effect.

   `nnvirtual' can have both mail and news groups as component groups.
When responding to articles in `nnvirtual' groups, `nnvirtual' has to
ask the back end of the component group the article comes from whether
it is a news or mail back end.  However, when you do a `^', there is
typically no sure way for the component back end to know this, and in
that case `nnvirtual' tells Gnus that the article came from a not-news
back end.  (Just to be on the safe side.)

   `C-c C-n' in the message buffer will insert the `Newsgroups' line
from the article you respond to in these cases.

   `nnvirtual' groups do not inherit anything but articles and marks
from component groups--group parameters, for instance, are not
inherited.


File: gnus,  Node: Email Based Diary,  Next: Gnus Unplugged,  Prev: Combined Groups,  Up: Select Methods

6.8 Email Based Diary
=====================

This section describes a special mail back end called `nndiary', and
its companion library `gnus-diary'.  It is "special" in the sense that
it is not meant to be one of the standard alternatives for reading mail
with Gnus.  See *note Choosing a Mail Back End:: for that.  Instead, it
is used to treat _some_ of your mails in a special way, namely, as
event reminders.

   Here is a typical scenario:

   * You've got a date with Andy Mc Dowell or Bruce Willis (select
     according to your sexual preference) in one month.  You don't want
     to forget it.

   * So you send a "reminder" message (actually, a diary one) to
     yourself.

   * You forget all about it and keep on getting and reading new mail,
     as usual.

   * From time to time, as you type `g' in the group buffer and as the
     date is getting closer, the message will pop up again to remind
     you of your appointment, just as if it were new and unread.

   * Read your "new" messages, this one included, and start dreaming
     again of the night you're gonna have.

   * Once the date is over (you actually fell asleep just after
     dinner), the message will be automatically deleted if it is marked
     as expirable.

   The Gnus Diary back end has the ability to handle regular
appointments (that wouldn't ever be deleted) as well as punctual ones,
operates as a real mail back end and is configurable in many ways.  All
of this is explained in the sections below.

* Menu:

* The NNDiary Back End::        Basic setup and usage.
* The Gnus Diary Library::      Utility toolkit on top of nndiary.
* Sending or Not Sending::      A final note on sending diary messages.


File: gnus,  Node: The NNDiary Back End,  Next: The Gnus Diary Library,  Up: Email Based Diary

6.8.1 The NNDiary Back End
--------------------------

`nndiary' is a back end very similar to `nnml' (*note Mail Spool::).
Actually, it could appear as a mix of `nnml' and `nndraft'.  If you
know `nnml', you're already familiar with the message storing scheme of
`nndiary': one file per message, one directory per group.

   Before anything, there is one requirement to be able to run
`nndiary' properly: you _must_ use the group timestamp feature of Gnus.
This adds a timestamp to each group's parameters.  *note Group
Timestamp:: to see how it's done.

* Menu:

* Diary Messages::              What makes a message valid for nndiary.
* Running NNDiary::             NNDiary has two modes of operation.
* Customizing NNDiary::         Bells and whistles.


File: gnus,  Node: Diary Messages,  Next: Running NNDiary,  Up: The NNDiary Back End

6.8.1.1 Diary Messages
......................

`nndiary' messages are just normal ones, except for the mandatory
presence of 7 special headers.  These headers are of the form
`X-Diary-<something>', `<something>' being one of `Minute', `Hour',
`Dom', `Month', `Year', `Time-Zone' and `Dow'.  `Dom' means "Day of
Month", and `dow' means "Day of Week".  These headers actually behave
like crontab specifications and define the event date(s):

   * For all headers except the `Time-Zone' one, a header value is
     either a star (meaning all possible values), or a list of fields
     (separated by a comma).

   * A field is either an integer, or a range.

   * A range is two integers separated by a dash.

   * Possible integer values are 0-59 for `Minute', 0-23 for `Hour',
     1-31 for `Dom', 1-12 for `Month', above 1971 for `Year' and 0-6
     for `Dow' (0 meaning Sunday).

   * As a special case, a star in either `Dom' or `Dow' doesn't mean
     "all possible values", but "use only the other field".  Note that
     if both are star'ed, the use of either one gives the same result.

   * The `Time-Zone' header is special in that it can only have one
     value (`GMT', for instance).  A star doesn't mean "all possible
     values" (because it makes no sense), but "the current local time
     zone".  Most of the time, you'll be using a star here.  However,
     for a list of available time zone values, see the variable
     `nndiary-headers'.

   As a concrete example, here are the diary headers to add to your
message for specifying "Each Monday and each 1st of month, at 12:00,
20:00, 21:00, 22:00, 23:00 and 24:00, from 1999 to 2010" (I'll let you
find what to do then):

     X-Diary-Minute: 0
     X-Diary-Hour: 12, 20-24
     X-Diary-Dom: 1
     X-Diary-Month: *
     X-Diary-Year: 1999-2010
     X-Diary-Dow: 1
     X-Diary-Time-Zone: *


File: gnus,  Node: Running NNDiary,  Next: Customizing NNDiary,  Prev: Diary Messages,  Up: The NNDiary Back End

6.8.1.2 Running NNDiary
.......................

`nndiary' has two modes of operation: "traditional" (the default) and
"autonomous".  In traditional mode, `nndiary' does not get new mail by
itself.  You have to move (`B m') or copy (`B c') mails from your
primary mail back end to nndiary groups in order to handle them as
diary messages.  In autonomous mode, `nndiary' retrieves its own mail
and handles it independently from your primary mail back end.

   One should note that Gnus is not inherently designed to allow several
"master" mail back ends at the same time.  However, this does make
sense with `nndiary': you really want to send and receive diary
messages to your diary groups directly.  So, `nndiary' supports being
sort of a "second primary mail back end" (to my knowledge, it is the
only back end offering this feature).  However, there is a limitation
(which I hope to fix some day): respooling doesn't work in autonomous
mode.

   In order to use `nndiary' in autonomous mode, you have several
things to do:

   * Allow `nndiary' to retrieve new mail by itself.  Put the following
     line in your `~/.gnus.el' file:

          (setq nndiary-get-new-mail t)

   * You must arrange for diary messages (those containing `X-Diary-*'
     headers) to be split in a private folder _before_ Gnus treat them.
     Again, this is needed because Gnus cannot (yet ?) properly handle
     multiple primary mail back ends.  Getting those messages from a
     separate source will compensate this misfeature to some extent.

     As an example, here's my procmailrc entry to store diary files in
     `~/.nndiary' (the default `nndiary' mail source file):

          :0 HD :
          * ^X-Diary
          .nndiary

   Once this is done, you might want to customize the following two
options that affect the diary mail retrieval and splitting processes:

 -- Variable: nndiary-mail-sources
     This is the diary-specific replacement for the standard
     `mail-sources' variable.  It obeys the same syntax, and defaults to
     `(file :path "~/.nndiary")'.

 -- Variable: nndiary-split-methods
     This is the diary-specific replacement for the standard
     `nnmail-split-methods' variable.  It obeys the same syntax.

   Finally, you may add a permanent `nndiary' virtual server (something
like `(nndiary "diary")' should do) to your
`gnus-secondary-select-methods'.

   Hopefully, almost everything (see the TODO section in `nndiary.el')
will work as expected when you restart Gnus: in autonomous mode, typing
`g' and `M-g' in the group buffer, will also get your new diary mails
and split them according to your diary-specific rules, `F' will find
your new diary groups etc.


File: gnus,  Node: Customizing NNDiary,  Prev: Running NNDiary,  Up: The NNDiary Back End

6.8.1.3 Customizing NNDiary
...........................

Now that `nndiary' is up and running, it's time to customize it.  The
custom group is called `nndiary' (no, really ?!).  You should browse it
to figure out which options you'd like to tweak.  The following two
variables are probably the only ones you will want to change:

 -- Variable: nndiary-reminders
     This is the list of times when you want to be reminded of your
     appointments (e.g. 3 weeks before, then 2 days before, then 1 hour
     before and that's it).  Remember that "being reminded" means that
     the diary message will pop up as brand new and unread again when
     you get new mail.

 -- Variable: nndiary-week-starts-on-monday
     Rather self-explanatory.  Otherwise, Sunday is assumed (this is the
     default).


File: gnus,  Node: The Gnus Diary Library,  Next: Sending or Not Sending,  Prev: The NNDiary Back End,  Up: Email Based Diary

6.8.2 The Gnus Diary Library
----------------------------

Using `nndiary' manually (I mean, writing the headers by hand and so
on) would be rather boring.  Fortunately, there is a library called
`gnus-diary' written on top of `nndiary', that does many useful things
for you.

   In order to use it, add the following line to your `~/.gnus.el' file:

     (require 'gnus-diary)

   Also, you shouldn't use any `gnus-user-format-function-[d|D]' (*note
Summary Buffer Lines::).  `gnus-diary' provides both of these (sorry if
you used them before).

* Menu:

* Diary Summary Line Format::           A nicer summary buffer line format.
* Diary Articles Sorting::              A nicer way to sort messages.
* Diary Headers Generation::            Not doing it manually.
* Diary Group Parameters::              Not handling them manually.


File: gnus,  Node: Diary Summary Line Format,  Next: Diary Articles Sorting,  Up: The Gnus Diary Library

6.8.2.1 Diary Summary Line Format
.................................

Displaying diary messages in standard summary line format (usually
something like `From Joe: Subject') is pretty useless.  Most of the
time, you're the one who wrote the message, and you mostly want to see
the event's date.

   `gnus-diary' provides two supplemental user formats to be used in
summary line formats.  `D' corresponds to a formatted time string for
the next occurrence of the event (e.g. "Sat, Sep 22 01, 12:00"), while
`d' corresponds to an approximate remaining time until the next
occurrence of the event (e.g. "in 6 months, 1 week").

   For example, here's how Joe's birthday is displayed in my
`nndiary+diary:birthdays' summary buffer (note that the message is
expirable, but will never be deleted, as it specifies a periodic event):

        E  Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week)

   In order to get something like the above, you would normally add the
following line to your diary groups'parameters:

     (gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n")

   However, `gnus-diary' does it automatically (*note Diary Group
Parameters::).  You can however customize the provided summary line
format with the following user options:

 -- Variable: gnus-diary-summary-line-format
     Defines the summary line format used for diary groups (*note
     Summary Buffer Lines::).  `gnus-diary' uses it to automatically
     update the diary groups'parameters.

 -- Variable: gnus-diary-time-format
     Defines the format to display dates in diary summary buffers.
     This is used by the `D' user format.  See the docstring for
     details.

 -- Variable: gnus-diary-delay-format-function
     Defines the format function to use for displaying delays (remaining
     times) in diary summary buffers.  This is used by the `d' user
     format.  There are currently built-in functions for English and
     French; you can also define your own.  See the docstring for
     details.


File: gnus,  Node: Diary Articles Sorting,  Next: Diary Headers Generation,  Prev: Diary Summary Line Format,  Up: The Gnus Diary Library

6.8.2.2 Diary Articles Sorting
..............................

`gnus-diary' provides new sorting functions (*note Sorting the Summary
Buffer:: ) called `gnus-summary-sort-by-schedule',
`gnus-thread-sort-by-schedule' and `gnus-article-sort-by-schedule'.
These functions let you organize your diary summary buffers from the
closest event to the farthest one.

   `gnus-diary' automatically installs `gnus-summary-sort-by-schedule'
as a menu item in the summary buffer's "sort" menu, and the two others
as the primary (hence default) sorting functions in the group
parameters (*note Diary Group Parameters::).


File: gnus,  Node: Diary Headers Generation,  Next: Diary Group Parameters,  Prev: Diary Articles Sorting,  Up: The Gnus Diary Library

6.8.2.3 Diary Headers Generation
................................

`gnus-diary' provides a function called `gnus-diary-check-message' to
help you handle the `X-Diary-*' headers.  This function ensures that
the current message contains all the required diary headers, and
prompts you for values or corrections if needed.

   This function is hooked into the `nndiary' back end, so that moving
or copying an article to a diary group will trigger it automatically.
It is also bound to `C-c C-f d' in `message-mode' and
`article-edit-mode' in order to ease the process of converting a usual
mail to a diary one.

   This function takes a prefix argument which will force prompting of
all diary headers, regardless of their presence or validity.  That way,
you can very easily reschedule an already valid diary message, for
instance.


File: gnus,  Node: Diary Group Parameters,  Prev: Diary Headers Generation,  Up: The Gnus Diary Library

6.8.2.4 Diary Group Parameters
..............................

When you create a new diary group, or visit one, `gnus-diary'
automatically checks your group parameters and if needed, sets the
summary line format to the diary-specific value, installs the
diary-specific sorting functions, and also adds the different
`X-Diary-*' headers to the group's posting-style.  It is then easier to
send a diary message, because if you use `C-u a' or `C-u m' on a diary
group to prepare a message, these headers will be inserted
automatically (although not filled with proper values yet).


File: gnus,  Node: Sending or Not Sending,  Prev: The Gnus Diary Library,  Up: Email Based Diary

6.8.3 Sending or Not Sending
----------------------------

Well, assuming you've read all of the above, here are two final notes on
mail sending with `nndiary':

   * `nndiary' is a _real_ mail back end.  You really send real diary
     messages for real.  This means for instance that you can give
     appointments to anybody (provided they use Gnus and `nndiary') by
     sending the diary message to them as well.

   * However, since `nndiary' also has a `request-post' method, you can
     also use `C-u a' instead of `C-u m' on a diary group and the
     message won't actually be sent; just stored locally in the group.
     This comes in very handy for private appointments.


File: gnus,  Node: Gnus Unplugged,  Prev: Email Based Diary,  Up: Select Methods

6.9 Gnus Unplugged
==================

In olden times (ca. February '88), people used to run their newsreaders
on big machines with permanent connections to the net.  News transport
was dealt with by news servers, and all the newsreaders had to do was to
read news.  Believe it or not.

   Nowadays most people read news and mail at home, and use some sort of
modem to connect to the net.  To avoid running up huge phone bills, it
would be nice to have a way to slurp down all the news and mail, hang up
the phone, read for several hours, and then upload any responses you
have to make.  And then you repeat the procedure.

   Of course, you can use news servers for doing this as well.  I've
used `inn' together with `slurp', `pop' and `sendmail' for some years,
but doing that's a bore.  Moving the news server functionality up to
the newsreader makes sense if you're the only person reading news on a
machine.

   Setting up Gnus as an "offline" newsreader is quite simple.  In
fact, you don't have to configure anything as the agent is now enabled
by default (*note gnus-agent: Agent Variables.).

   Of course, to use it as such, you have to learn a few new commands.

* Menu:

* Agent Basics::                How it all is supposed to work.
* Agent Categories::            How to tell the Gnus Agent what to download.
* Agent Commands::              New commands for all the buffers.
* Agent Visuals::               Ways that the agent may effect your summary buffer.
* Agent as Cache::              The Agent is a big cache too.
* Agent Expiry::                How to make old articles go away.
* Agent Regeneration::          How to recover from lost connections and other accidents.
* Agent and flags::             How the Agent maintains flags.
* Agent and IMAP::              How to use the Agent with IMAP.
* Outgoing Messages::           What happens when you post/mail something?
* Agent Variables::             Customizing is fun.
* Example Setup::               An example `~/.gnus.el' file for offline people.
* Batching Agents::             How to fetch news from a `cron' job.
* Agent Caveats::               What you think it'll do and what it does.


File: gnus,  Node: Agent Basics,  Next: Agent Categories,  Up: Gnus Unplugged

6.9.1 Agent Basics
------------------

First, let's get some terminology out of the way.

   The Gnus Agent is said to be "unplugged" when you have severed the
connection to the net (and notified the Agent that this is the case).
When the connection to the net is up again (and Gnus knows this), the
Agent is "plugged".

   The "local" machine is the one you're running on, and which isn't
connected to the net continuously.

   "Downloading" means fetching things from the net to your local
machine.  "Uploading" is doing the opposite.

   You know that Gnus gives you all the opportunity you'd ever want for
shooting yourself in the foot.  Some people call it flexibility.  Gnus
is also customizable to a great extent, which means that the user has a
say on how Gnus behaves.  Other newsreaders might unconditionally shoot
you in your foot, but with Gnus, you have a choice!

   Gnus is never really in plugged or unplugged state.  Rather, it
applies that state to each server individually.  This means that some
servers can be plugged while others can be unplugged.  Additionally,
some servers can be ignored by the Agent altogether (which means that
they're kinda like plugged always).

   So when you unplug the Agent and then wonder why is Gnus opening a
connection to the Net, the next step to do is to look whether all
servers are agentized.  If there is an unagentized server, you found
the culprit.

   Another thing is the "offline" state.  Sometimes, servers aren't
reachable.  When Gnus notices this, it asks you whether you want the
server to be switched to offline state.  If you say yes, then the
server will behave somewhat as if it was unplugged, except that Gnus
will ask you whether you want to switch it back online again.

   Let's take a typical Gnus session using the Agent.

   * You start Gnus with `gnus-unplugged'.  This brings up the Gnus
     Agent in a disconnected state.  You can read all the news that you
     have already fetched while in this mode.

   * You then decide to see whether any new news has arrived.  You
     connect your machine to the net (using PPP or whatever), and then
     hit `J j' to make Gnus become "plugged" and use `g' to check for
     new mail as usual.  To check for new mail in unplugged mode (*note
     Mail Source Specifiers::).

   * You can then read the new news immediately, or you can download the
     news onto your local machine.  If you want to do the latter, you
     press `g' to check if there are any new news and then `J s' to
     fetch all the eligible articles in all the groups.  (To let Gnus
     know which articles you want to download, *note Agent
     Categories::).

   * After fetching the articles, you press `J j' to make Gnus become
     unplugged again, and you shut down the PPP thing (or whatever).
     And then you read the news offline.

   * And then you go to step 2.

   Here are some things you should do the first time (or so) that you
use the Agent.

   * Decide which servers should be covered by the Agent.  If you have
     a mail back end, it would probably be nonsensical to have it
     covered by the Agent.  Go to the server buffer (`^' in the group
     buffer) and press `J a' on the server (or servers) that you wish
     to have covered by the Agent (*note Server Agent Commands::), or
     `J r' on automatically added servers you do not wish to have
     covered by the Agent.  By default, no servers are agentized.

   * Decide on download policy.  It's fairly simple once you decide
     whether you are going to use agent categories, topic parameters,
     and/or group parameters to implement your policy.  If you're new
     to gnus, it is probably best to start with a category, *Note Agent
     Categories::.

     Both topic parameters (*note Topic Parameters::) and agent
     categories (*note Agent Categories::) provide for setting a policy
     that applies to multiple groups.  Which you use is entirely up to
     you.  Topic parameters do override categories so, if you mix the
     two, you'll have to take that into account.  If you have a few
     groups that deviate from your policy, you can use group parameters
     (*note Group Parameters::) to configure them.

   * Uhm... that's it.


File: gnus,  Node: Agent Categories,  Next: Agent Commands,  Prev: Agent Basics,  Up: Gnus Unplugged

6.9.2 Agent Categories
----------------------

One of the main reasons to integrate the news transport layer into the
newsreader is to allow greater control over what articles to download.
There's not much point in downloading huge amounts of articles, just to
find out that you're not interested in reading any of them.  It's better
to be somewhat more conservative in choosing what to download, and then
mark the articles for downloading manually if it should turn out that
you're interested in the articles anyway.

   One of the more effective methods for controlling what is to be
downloaded is to create a "category" and then assign some (or all)
groups to this category.  Groups that do not belong in any other
category belong to the `default' category.  Gnus has its own buffer for
creating and managing categories.

   If you prefer, you can also use group parameters (*note Group
Parameters::) and topic parameters (*note Topic Parameters::) for an
alternative approach to controlling the agent.  The only real
difference is that categories are specific to the agent (so there is
less to learn) while group and topic parameters include the kitchen
sink.

   Since you can set agent parameters in several different places we
have a rule to decide which source to believe.  This rule specifies that
the parameter sources are checked in the following order: group
parameters, topic parameters, agent category, and finally customizable
variables.  So you can mix all of these sources to produce a wide range
of behavior, just don't blame me if you don't remember where you put
your settings.

* Menu:

* Category Syntax::             What a category looks like.
* Category Buffer::             A buffer for maintaining categories.
* Category Variables::          Customize'r'Us.


File: gnus,  Node: Category Syntax,  Next: Category Buffer,  Up: Agent Categories

6.9.2.1 Category Syntax
.......................

A category consists of a name, the list of groups belonging to the
category, and a number of optional parameters that override the
customizable variables.  The complete list of agent parameters are
listed below.

`agent-groups'
     The list of groups that are in this category.

`agent-predicate'
     A predicate which (generally) gives a rough outline of which
     articles are eligible for downloading; and

`agent-score'
     a score rule which (generally) gives you a finer granularity when
     deciding what articles to download.  (Note that this "download
     score" is not necessarily related to normal scores.)

`agent-enable-expiration'
     a boolean indicating whether the agent should expire old articles
     in this group.  Most groups should be expired to conserve disk
     space.  In fact, its probably safe to say that the gnus.*
     hierarchy contains the only groups that should not be expired.

`agent-days-until-old'
     an integer indicating the number of days that the agent should wait
     before deciding that a read article is safe to expire.

`agent-low-score'
     an integer that overrides the value of `gnus-agent-low-score'.

`agent-high-score'
     an integer that overrides the value of `gnus-agent-high-score'.

`agent-short-article'
     an integer that overrides the value of `gnus-agent-short-article'.

`agent-long-article'
     an integer that overrides the value of `gnus-agent-long-article'.

`agent-enable-undownloaded-faces'
     a symbol indicating whether the summary buffer should display
     undownloaded articles using the `gnus-summary-*-undownloaded-face'
     faces.  Any symbol other than `nil' will enable the use of
     undownloaded faces.

   The name of a category can not be changed once the category has been
created.

   Each category maintains a list of groups that are exclusive members
of that category.  The exclusivity rule is automatically enforced, add a
group to a new category and it is automatically removed from its old
category.

   A predicate in its simplest form can be a single predicate such as
`true' or `false'.  These two will download every available article or
nothing respectively.  In the case of these two special predicates an
additional score rule is superfluous.

   Predicates of `high' or `low' download articles in respect of their
scores in relationship to `gnus-agent-high-score' and
`gnus-agent-low-score' as described below.

   To gain even finer control of what is to be regarded eligible for
download a predicate can consist of a number of predicates with logical
operators sprinkled in between.

   Perhaps some examples are in order.

   Here's a simple predicate.  (It's the default predicate, in fact,
used for all groups that don't belong to any other category.)

     short

   Quite simple, eh?  This predicate is true if and only if the article
is short (for some value of "short").

   Here's a more complex predicate:

     (or high
         (and
          (not low)
          (not long)))

   This means that an article should be downloaded if it has a high
score, or if the score is not low and the article is not long.  You get
the drift.

   The available logical operators are `or', `and' and `not'.  (If you
prefer, you can use the more "C"-ish operators `|', `&' and `!'
instead.)

   The following predicates are pre-defined, but if none of these fit
what you want to do, you can write your own.

   When evaluating each of these predicates, the named constant will be
bound to the value determined by calling `gnus-agent-find-parameter' on
the appropriate parameter.  For example, gnus-agent-short-article will
be bound to `(gnus-agent-find-parameter group 'agent-short-article)'.
This means that you can specify a predicate in your category then tune
that predicate to individual groups.

`short'
     True if the article is shorter than `gnus-agent-short-article'
     lines; default 100.

`long'
     True if the article is longer than `gnus-agent-long-article'
     lines; default 200.

`low'
     True if the article has a download score less than
     `gnus-agent-low-score'; default 0.

`high'
     True if the article has a download score greater than
     `gnus-agent-high-score'; default 0.

`spam'
     True if the Gnus Agent guesses that the article is spam.  The
     heuristics may change over time, but at present it just computes a
     checksum and sees whether articles match.

`true'
     Always true.

`false'
     Always false.

   If you want to create your own predicate function, here's what you
have to know:  The functions are called with no parameters, but the
`gnus-headers' and `gnus-score' dynamic variables are bound to useful
values.

   For example, you could decide that you don't want to download
articles that were posted more than a certain number of days ago (e.g.
posted more than `gnus-agent-expire-days' ago) you might write a
function something along the lines of the following:

     (defun my-article-old-p ()
       "Say whether an article is old."
       (< (time-to-days (date-to-time (mail-header-date gnus-headers)))
          (- (time-to-days (current-time)) gnus-agent-expire-days)))

   with the predicate then defined as:

     (not my-article-old-p)

   or you could append your predicate to the predefined
`gnus-category-predicate-alist' in your `~/.gnus.el' or wherever.

     (require 'gnus-agent)
     (setq  gnus-category-predicate-alist
       (append gnus-category-predicate-alist
              '((old . my-article-old-p))))

   and simply specify your predicate as:

     (not old)

   If/when using something like the above, be aware that there are many
misconfigured systems/mailers out there and so an article's date is not
always a reliable indication of when it was posted.  Hell, some people
just don't give a damn.

   The above predicates apply to _all_ the groups which belong to the
category.  However, if you wish to have a specific predicate for an
individual group within a category, or you're just too lazy to set up a
new category, you can enter a group's individual predicate in its group
parameters like so:

     (agent-predicate . short)

   This is the group/topic parameter equivalent of the agent category
default.  Note that when specifying a single word predicate like this,
the `agent-predicate' specification must be in dotted pair notation.

   The equivalent of the longer example from above would be:

     (agent-predicate or high (and (not low) (not long)))

   The outer parenthesis required in the category specification are not
entered here as, not being in dotted pair notation, the value of the
predicate is assumed to be a list.

   Now, the syntax of the download score is the same as the syntax of
normal score files, except that all elements that require actually
seeing the article itself are verboten.  This means that only the
following headers can be scored on: `Subject', `From', `Date',
`Message-ID', `References', `Chars', `Lines', and `Xref'.

   As with predicates, the specification of the `download score rule'
to use in respect of a group can be in either the category definition if
it's to be applicable to all groups in therein, or a group's parameters
if it's to be specific to that group.

   In both of these places the `download score rule' can take one of
three forms:

  1. Score rule

     This has the same syntax as a normal Gnus score file except only a
     subset of scoring keywords are available as mentioned above.

     example:

        * Category specification

               (("from"
                      ("Lars Ingebrigtsen" 1000000 nil s))
               ("lines"
                      (500 -100 nil <)))

        * Group/Topic Parameter specification

               (agent-score ("from"
                                  ("Lars Ingebrigtsen" 1000000 nil s))
                            ("lines"
                                  (500 -100 nil <)))

          Again, note the omission of the outermost parenthesis here.

  2. Agent score file

     These score files must _only_ contain the permitted scoring
     keywords stated above.

     example:

        * Category specification

               ("~/News/agent.SCORE")

          or perhaps

               ("~/News/agent.SCORE" "~/News/agent.group.SCORE")

        * Group Parameter specification

               (agent-score "~/News/agent.SCORE")

          Additional score files can be specified as above.  Need I say
          anything about parenthesis?

  3. Use `normal' score files

     If you don't want to maintain two sets of scoring rules for a
     group, and your desired `downloading' criteria for a group are the
     same as your `reading' criteria then you can tell the agent to
     refer to your `normal' score files when deciding what to download.

     These directives in either the category definition or a group's
     parameters will cause the agent to read in all the applicable score
     files for a group, _filtering out_ those sections that do not
     relate to one of the permitted subset of scoring keywords.

        * Category Specification

               file

        * Group Parameter specification

               (agent-score . file)


File: gnus,  Node: Category Buffer,  Next: Category Variables,  Prev: Category Syntax,  Up: Agent Categories

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

`e'
     Use a customization buffer to set all of the selected category's
     parameters at one time (`gnus-category-customize-category').

`k'
     Kill the current category (`gnus-category-kill').

`c'
     Copy the current category (`gnus-category-copy').

`a'
     Add a new category (`gnus-category-add').

`p'
     Edit the predicate of the current category
     (`gnus-category-edit-predicate').

`g'
     Edit the list of groups belonging to the current category
     (`gnus-category-edit-groups').

`s'
     Edit the download score rule of the current category
     (`gnus-category-edit-score').

`l'
     List all the categories (`gnus-category-list').


File: gnus,  Node: Category Variables,  Prev: Category Buffer,  Up: Agent Categories

6.9.2.3 Category Variables
..........................

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

`gnus-category-line-format'
     Format of the lines in the category buffer (*note Formatting
     Variables::).  Valid elements are:

    `c'
          The name of the category.

    `g'
          The number of groups in the category.

`gnus-category-mode-line-format'
     Format of the category mode line (*note Mode Line Formatting::).

`gnus-agent-short-article'
     Articles that have fewer lines than this are short.  Default 100.

`gnus-agent-long-article'
     Articles that have more lines than this are long.  Default 200.

`gnus-agent-low-score'
     Articles that have a score lower than this have a low score.
     Default 0.

`gnus-agent-high-score'
     Articles that have a score higher than this have a high score.
     Default 0.

`gnus-agent-expire-days'
     The number of days that a `read' article must stay in the agent's
     local disk before becoming eligible for expiration (While the name
     is the same, this doesn't mean expiring the article on the server.
     It just means deleting the local copy of the article).  What is
     also important to understand is that the counter starts with the
     time the article was written to the local disk and not the time
     the article was read.  Default 7.

`gnus-agent-enable-expiration'
     Determines whether articles in a group are, by default, expired or
     retained indefinitely.  The default is `ENABLE' which means that
     you'll have to disable expiration when desired.  On the other hand,
     you could set this to `DISABLE'.  In that case, you would then
     have to enable expiration in selected groups.




Local Variables:
coding: iso-8859-1
End: