This is gnus, produced by makeinfo version 5.2 from gnus.texi.

Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
2004, 2005, 2006 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.2 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" in the Emacs manual.

     (a) The FSF's Back-Cover Text is: "You have freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by the
     Free Software Foundation raise funds for GNU development."

     This document is part of a collection distributed under the GNU
     Free Documentation License.  If you want to distribute this
     document separately from the collection, you can do so by adding a
     copy of the license to the document, as described in section 6 of
     the license.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Gnus: (gnus).         The newsreader Gnus.
END-INFO-DIR-ENTRY

   Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
2004, 2005, 2006 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.2 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" in the Emacs manual.

     (a) The FSF's Back-Cover Text is: "You have freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by the
     Free Software Foundation raise funds for GNU development."

     This document is part of a collection distributed under the GNU
     Free Documentation License.  If you want to distribute this
     document separately from the collection, you can do so by adding a
     copy of the license to the document, as described in section 6 of
     the license.


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

3.26 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::.


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

3.26.1 Summary Group Information
--------------------------------

'H f'
     Try to fetch the FAQ (list of frequently asked questions) for the
     current group ('gnus-summary-fetch-faq').  Gnus will try to get the
     FAQ from 'gnus-group-faq-directory', which is usually a directory
     on a remote machine.  This variable can also be a list of
     directories.  In that case, giving a prefix to this command will
     allow you to choose between the various sites.  'ange-ftp' or 'efs'
     will probably be used for fetching the file.

'H d'
     Give a brief description of the current group
     ('gnus-summary-describe-group').  If given a prefix, force
     rereading the description from the server.

'H h'
     Give 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.26.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').

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


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

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

'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.27 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 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.28 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.  You may want to try NoCeM handling to filter out spam
(*note NoCeM::).

   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 'gnus-nov-is-evil' to 't', which slows things down considerably.

   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.29 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.30 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 Gnus is called PGG (*note PGG: (pgg)Top.), but Mailcrypt and
     gpg.el 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 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.

'mml1991-use'
     Symbol indicating elisp interface to OpenPGP implementation for PGP
     messages.  The default is 'pgg', but 'mailcrypt' and 'gpg' are also
     supported although deprecated.

'mml2015-use'
     Symbol indicating elisp interface to OpenPGP implementation for
     PGP/MIME messages.  The default is 'pgg', but 'mailcrypt' and 'gpg'
     are also supported although deprecated.

   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.31 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.
* 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' header if it is very long.
'many-to'
     Remove all 'To' 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: Customizing Articles,  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').

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

'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: Customizing Articles,  Next: Article Keymap,  Prev: Using MIME,  Up: Article Buffer

4.3 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. 'last': Do this treatment on the last part.

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

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

  7. 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, 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-english (head)'
'gnus-treat-date-iso8601 (head)'
'gnus-treat-date-lapsed (head)'
'gnus-treat-date-local (head)'
'gnus-treat-date-original (head)'
'gnus-treat-date-user-defined (head)'
'gnus-treat-date-ut (head)'

     *Note Article Date::.

'gnus-treat-from-picon (head)'
'gnus-treat-mail-picon (head)'
'gnus-treat-newsgroups-picon (head)'

     *Note Picons::.

'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-translate'
'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.4 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 key to some
function 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 given a prefix, make a
     wide reply.  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 given a prefix, make a
     wide reply.  If the region is active, only yank the text in the
     region.


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

4.5 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-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 emphasised 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.  This requires GNU Libidn
     (http://www.gnu.org/software/libidn/), and this variable is only
     enabled if you have installed it.


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 'message-send-mail-function'.  The
default function, 'message-send-mail-with-sendmail', pipes your article
to the 'sendmail' binary for further queuing and sending.  When your
local system is not configured for sending mail using 'sendmail', and
you have access to a remote SMTP server, you can set
'message-send-mail-function' to 'smtpmail-send-it' and make sure to
setup the 'smtpmail' package correctly.  An example:

     (setq message-send-mail-function 'smtpmail-send-it
           smtpmail-default-smtp-server "YOUR SMTP HOST")

   To the thing similar to this, there is 'message-smtpmail-send-it'.
It is useful if your ISP requires the POP-before-SMTP authentication.
*Note POP before SMTP::.

   Other possible choices for 'message-send-mail-function' includes
'message-send-mail-with-mh', 'message-send-mail-with-qmail', and
'feedmail-send-it'.


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 one of the symbols 'gnus' (show only
     Gnus version), 'emacs-gnus' (show only Emacs and Gnus versions),
     'emacs-gnus-config' (same as 'emacs-gnus' plus system
     configuration), 'emacs-gnus-type' (same as 'emacs-gnus' plus system
     type) or a custom string.  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.


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', which is the
default.

   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:

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

   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.  This is the default.

   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.

   That's the default method of archiving sent messages.  Gnus offers a
different way for the people who don't like the default method.  In that
case you should set 'gnus-message-archive-group' to 'nil'; this will
disable archiving.

'gnus-outgoing-message-group'
     All outgoing messages will be put in this group.  If you want to
     store all your outgoing mail and articles in the group
     'nnml:archive', you set this variable to that value.  This variable
     can also be a list of group names.

     If you want to have greater control over what group to put each
     message in, you can set this variable to a function that checks the
     current newsgroup name and then returns a suitable group name (or
     list of names).

     This variable can be used instead of 'gnus-message-archive-group',
     but the latter is the preferred method.

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

   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 (used verbatim), 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.

   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 (save-excursion
                      (set-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.


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.


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.
* Getting Mail::                Reading your personal mail with Gnus.
* Browsing the Web::            Getting messages from a plethora of Web sources.
* IMAP::                        Using Gnus as a IMAP client.
* Other Sources::               Reading directories, files, SOUP packets.
* Combined Groups::             Combining groups into one group.
* 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 key to some
     function 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').

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


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 telnet 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-telnet)
           (nntp-via-address "the.firewall.machine")
           (nntp-address "the.real.nntp.host")
           (nntp-end-of-line "\n"))

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

   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 telnet connection to the news server as follows:

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

   This means that you have to have set up 'ssh-agent' correctly to
provide automatic authorization, of course.  And to get a compressed
connection, you have to have the 'Compression' option in the 'ssh'
'config' file.


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

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


File: gnus,  Node: Getting News,  Next: Getting Mail,  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-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.
     Six pre-made functions are supplied.  These functions can be
     grouped in two categories: direct connection functions (four
     pre-made), and indirect ones (two pre-made).

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

* Menu:

* Direct Functions::            Connecting directly to the server.
* Indirect Functions::          Connecting indirectly to the server.
* Common Variables::            Understood by several connection functions.


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.

'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 )
                (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-telnet-stream'
     Opens a connection to an NNTP server by simply 'telnet''ing it.
     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-telnet-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.


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-telnet'
     Does an 'rlogin' on a remote system, and then does a 'telnet' 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-telnet'-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, otherwise
          set this to '("-t" "-e" "none")' or '("-C" "-t" "-e" "none")'
          if the telnet command requires a pseudo-tty allocation on an
          intermediate host.

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

   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,  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 connection function.

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

'nntp-telnet-switches'
     A list of switches to pass to 'nntp-telnet-command'.  The default
     is '("-8")'.


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: Getting Mail,  Next: Browsing the Web,  Prev: Getting News,  Up: Select Methods

6.3 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.3.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.3.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.3.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.

   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 the splitting codes MIME decodes headers so you can match
on non-ASCII strings.  The 'nnmail-mail-splitting-charset' variable
specifies the default charset for decoding.  The behavior can be turned
off completely by binding 'nnmail-mail-splitting-decodes' to 'nil',
which is useful if you want to match articles based on the raw header
data.

   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.3.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.3.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 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 find the 'movemail' 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.

     ':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 the '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 the whole thing can fall apart and leave you with
     a corrupt mailbox.

     Here are some examples.  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 IMAP::, for
     more information.

     Note that for the Kerberos, GSSAPI, TLS/SSL and STARTTLS support
     you may need external programs and libraries, *Note IMAP::.

     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

          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 receive 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")

'webmail'
     Get mail from a webmail server, such as <http://www.hotmail.com/>,
     <http://webmail.netscape.com/>, <http://www.netaddress.com/>,
     <http://mail.yahoo.com/>.

     NOTE: Webmail largely depends on cookies.  A "one-line-cookie"
     patch is required for url "4.0pre.46".

     WARNING: Mails may be lost.  NO WARRANTY.

     Keywords:

     ':subtype'
          The type of the webmail server.  The default is 'hotmail'.
          The alternatives are 'netscape', 'netaddress', 'my-deja'.

     ':user'
          The user name to give to the webmail server.  The default is
          the login name.

     ':password'
          The password to give to the webmail server.  If not specified,
          the user is prompted.

     ':dontexpunge'
          If non-'nil', only fetch unread articles and don't move them
          to trash folder after finishing the fetch.

     An example webmail source:

          (webmail :subtype 'hotmail
                   :user "user-name"
                   :password "secret")

"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.3.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.3.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 (This
     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-old-incoming-confirm'
     If non-'nil', ask for 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 384.

'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.3.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 (and the obsolescent 'nnmail-spool-file') 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.3.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 511)))

          (add-hook 'nnmail-post-get-new-mail-hook
                    (lambda () (set-default-file-modes 551)))

'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.3.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 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 Splitting in
     IMAP::).

'(! 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.3.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.3.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.3.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.

   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.


File: gnus,  Node: Washing Mail,  Next: Duplicates,  Prev: Expiring Mail,  Up: Getting Mail

6.3.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-fix-eudora-headers'
          Eudora produces broken 'References' headers, but OK
          'In-Reply-To' headers.  This function will get rid of the
          'References' headers.

'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.3.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.3.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 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.3.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.
* Rmail Babyl::                 Emacs programs use the Rmail Babyl format.
* 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: Rmail Babyl,  Up: Choosing a Mail Back End

6.3.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: Rmail Babyl,  Next: Mail Spool,  Prev: Unix Mail Box,  Up: Choosing a Mail Back End

6.3.13.2 Rmail Babyl
....................

The "nnbabyl" back end will use a Babyl mail box (aka.  "Rmail mbox") 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 Rmail mbox file.  The default is '~/RMAIL'

'nnbabyl-active-file'
     The name of the active file for the rmail box.  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: Rmail Babyl,  Up: Choosing a Mail Back End

6.3.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 is
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.

   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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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' 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 by Stallman.

     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, consider switching to
     ReiserFS (http://www.namesys.com/) or another 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: IMAP,  Prev: Getting Mail,  Up: Select Methods

6.4 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.
* Slashdot::                    Reading the Slashdot comments.
* Ultimate::                    The Ultimate Bulletin Board systems.
* Web Archive::                 Reading mailing list archived on web.
* 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.4.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: Slashdot,  Prev: Archiving Mail,  Up: Browsing the Web

6.4.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: Slashdot,  Next: Ultimate,  Prev: Web Searches,  Up: Browsing the Web

6.4.3 Slashdot
--------------

Slashdot (http://slashdot.org/) is a popular news site, with lively
discussion following the news articles.  'nnslashdot' will let you read
this forum in a convenient manner.

   The easiest way to read this source is to put something like the
following in your '~/.gnus.el' file:

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

   This will make Gnus query the 'nnslashdot' back end for new comments
and groups.  The 'F' command will subscribe each new news article as a
new Gnus group, and you can read the comments by entering these groups.
(Note that the default subscription method is to subscribe new groups as
zombies.  Other methods are available (*note Subscription Methods::).

   If you want to remove an old 'nnslashdot' group, the 'G DEL' command
is the most handy tool (*note Foreign Groups::).

   When following up to 'nnslashdot' comments (or posting new comments),
some light HTMLizations will be performed.  In particular, text quoted
with '> ' will be quoted with 'blockquote' instead, and signatures will
have 'br' added to the end of each line.  Other than that, you can just
write HTML directly into the message buffer.  Note that Slashdot filters
out some HTML forms.

   The following variables can be altered to change its behavior:

'nnslashdot-threaded'
     Whether 'nnslashdot' should display threaded groups or not.  The
     default is 't'.  To be able to display threads, 'nnslashdot' has to
     retrieve absolutely all comments in a group upon entry.  If a
     threaded display is not required, 'nnslashdot' will only retrieve
     the comments that are actually wanted by the user.  Threading is
     nicer, but much, much slower than unthreaded.

'nnslashdot-login-name'
     The login name to use when posting.

'nnslashdot-password'
     The password to use when posting.

'nnslashdot-directory'
     Where 'nnslashdot' will store its files.  The default is
     '~/News/slashdot/'.

'nnslashdot-active-url'
     The URL format string that will be used to fetch the information on
     news articles and comments.  The default is
     'http://slashdot.org/search.pl?section=&min=%d'.

'nnslashdot-comments-url'
     The URL format string that will be used to fetch comments.

'nnslashdot-article-url'
     The URL format string that will be used to fetch the news article.
     The default is
     'http://slashdot.org/article.pl?sid=%s&mode=nocomment'.

'nnslashdot-threshold'
     The score threshold.  The default is -1.

'nnslashdot-group-number'
     The number of old groups, in addition to the ten latest, to keep
     updated.  The default is 0.


File: gnus,  Node: Ultimate,  Next: Web Archive,  Prev: Slashdot,  Up: Browsing the Web

6.4.4 Ultimate
--------------

The Ultimate Bulletin Board (http://www.ultimatebb.com/) is probably the
most popular Web bulletin board system used.  It has a quite regular and
nice interface, and it's possible to get the information Gnus needs to
keep groups updated.

   The easiest way to get started with 'nnultimate' is to say something
like the following in the group buffer: 'B nnultimate RET
http://www.tcj.com/messboard/ubbcgi/ RET'.  (Substitute the URL (not
including 'Ultimate.cgi' or the like at the end) for a forum you're
interested in; there's quite a list of them on the Ultimate web site.)
Then subscribe to the groups you're interested in from the server
buffer, and read them from the group buffer.

   The following 'nnultimate' variables can be altered:

'nnultimate-directory'
     The directory where 'nnultimate' stores its files.  The default is
     '~/News/ultimate/'.


File: gnus,  Node: Web Archive,  Next: RSS,  Prev: Ultimate,  Up: Browsing the Web

6.4.5 Web Archive
-----------------

Some mailing lists only have archives on Web servers, such as
<http://www.egroups.com/> and <http://www.mail-archive.com/>.  It has a
quite regular and nice interface, and it's possible to get the
information Gnus needs to keep groups updated.

   The easiest way to get started with 'nnwarchive' is to say something
like the following in the group buffer: 'M-x
gnus-group-make-warchive-group RET AN_EGROUP RET egroups RET
www.egroups.com RET YOUR@EMAIL.ADDRESS RET'.  (Substitute the AN_EGROUP
with the mailing list you subscribed, the YOUR@EMAIL.ADDRESS with your
email address.), or to browse the back end by 'B nnwarchive RET
mail-archive RET'.

   The following 'nnwarchive' variables can be altered:

'nnwarchive-directory'
     The directory where 'nnwarchive' stores its files.  The default is
     '~/News/warchive/'.

'nnwarchive-login'
     The account name on the web server.

'nnwarchive-passwd'
     The password for your account on the web server.


File: gnus,  Node: RSS,  Next: Customizing W3,  Prev: Web Archive,  Up: Browsing the Web

6.4.6 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.  If it is 'nil', in Emacs the
coding system defaults to the value of
'default-file-name-coding-system'.  If you are using XEmacs and want to
use non-ASCII group names, you should set the value for the
'nnmail-pathname-coding-system' variable properly.

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

'nnrss-wash-html-in-text-plain-parts'
     Non-'nil' means that 'nnrss' renders text in 'text/plain' parts as
     HTML.  The function specified by the 'mm-text-html-renderer'
     variable (*note Display Customization: (emacs-mime)Display
     Customization.) will be used to render text.  If it is 'nil', which
     is the default, text will simply be folded.  Leave it 'nil' if you
     prefer to see 'text/html' parts.

   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.4.7 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: IMAP,  Next: Other Sources,  Prev: Browsing the Web,  Up: Select Methods

6.5 IMAP
========

IMAP is a network protocol for reading mail (or news, or ...), think of
it as a modernized NNTP.  Connecting to a IMAP server is much similar to
connecting to a news server, you just specify the network address of the
server.

   IMAP has two properties.  First, IMAP can do everything that POP can,
it can hence be viewed as a POP++.  Secondly, IMAP is a mail storage
protocol, similar to NNTP being a news storage protocol--however, IMAP
offers more features than NNTP because news is more or less read-only
whereas mail is read-write.

   If you want to use IMAP as a POP++, use an imap entry in
'mail-sources'.  With this, Gnus will fetch mails from the IMAP server
and store them on the local disk.  This is not the usage described in
this section--*Note Mail Sources::.

   If you want to use IMAP as a mail storage protocol, use an nnimap
entry in 'gnus-secondary-select-methods'.  With this, Gnus will
manipulate mails stored on the IMAP server.  This is the kind of usage
explained in this section.

   A server configuration in '~/.gnus.el' with a few IMAP servers might
look something like the following.  (Note that for TLS/SSL, you need
external programs and libraries, see below.)

     (setq gnus-secondary-select-methods
           '((nnimap "simpleserver") ; no special configuration
             ; perhaps a ssh port forwarded server:
             (nnimap "dolk"
                     (nnimap-address "localhost")
                     (nnimap-server-port 1430))
             ; a UW server running on localhost
             (nnimap "barbar"
                     (nnimap-server-port 143)
                     (nnimap-address "localhost")
                     (nnimap-list-pattern ("INBOX" "mail/*")))
             ; anonymous public cyrus server:
             (nnimap "cyrus.andrew.cmu.edu"
                     (nnimap-authenticator anonymous)
                     (nnimap-list-pattern "archive.*")
                     (nnimap-stream network))
             ; a ssl server on a non-standard port:
             (nnimap "vic20"
                     (nnimap-address "vic20.somewhere.com")
                     (nnimap-server-port 9930)
                     (nnimap-stream ssl))))

   After defining the new server, you can subscribe to groups on the
server using normal Gnus commands such as 'U' in the Group Buffer (*note
Subscription Commands::) or via the Server Buffer (*note Server
Buffer::).

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

'nnimap-address'

     The address of the remote IMAP server.  Defaults to the virtual
     server name if not specified.

'nnimap-server-port'
     Port on server to contact.  Defaults to port 143, or 993 for
     TLS/SSL.

     Note that this should be an integer, example server specification:

          (nnimap "mail.server.com"
                  (nnimap-server-port 4711))

'nnimap-list-pattern'
     String or list of strings of mailboxes to limit available groups
     to.  This is used when the server has very many mailboxes and
     you're only interested in a few--some servers export your home
     directory via IMAP, you'll probably want to limit the mailboxes to
     those in '~/Mail/*' then.

     The string can also be a cons of REFERENCE and the string as above,
     what REFERENCE is used for is server specific, but on the
     University of Washington server it's a directory that will be
     concatenated with the mailbox.

     Example server specification:

          (nnimap "mail.server.com"
                  (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*"
                                         ("~friend/Mail/" . "list/*"))))

'nnimap-stream'
     The type of stream used to connect to your server.  By default,
     nnimap will detect and automatically use all of the below, with the
     exception of TLS/SSL.  (IMAP over TLS/SSL is being replaced by
     STARTTLS, which can be automatically detected, but it's not widely
     deployed yet.)

     Example server specification:

          (nnimap "mail.server.com"
                  (nnimap-stream ssl))

     Please note that the value of 'nnimap-stream' is a symbol!

        * "gssapi:" Connect with GSSAPI (usually Kerberos 5).  Requires
          the 'gsasl' or 'imtest' program.
        * "kerberos4:" Connect with Kerberos 4.  Requires the 'imtest'
          program.
        * "starttls:" Connect via the STARTTLS extension (similar to
          TLS/SSL).  Requires the external library 'starttls.el' and
          program 'starttls'.
        * "tls:" Connect through TLS.  Requires GNUTLS (the program
          'gnutls-cli').
        * "ssl:" Connect through SSL.  Requires OpenSSL (the program
          'openssl') or SSLeay ('s_client').
        * "shell:" Use a shell command to start IMAP connection.
        * "network:" Plain, TCP/IP network connection.

     The 'imtest' program is shipped with Cyrus IMAPD. If you're using
     'imtest' from Cyrus IMAPD < 2.0.14 (which includes version 1.5.x
     and 1.6.x) you need to frob 'imap-process-connection-type' to make
     'imap.el' use a pty instead of a pipe when communicating with
     'imtest'.  You will then suffer from a line length restrictions on
     IMAP commands, which might make Gnus seem to hang indefinitely if
     you have many articles in a mailbox.  The variable
     'imap-kerberos4-program' contain parameters to pass to the imtest
     program.

     For TLS connection, the 'gnutls-cli' program from GNUTLS is needed.
     It is available from <http://www.gnu.org/software/gnutls/>.

     This parameter specifies a list of command lines that invoke a
     GSSAPI authenticated IMAP stream in a subshell.  They are tried
     sequentially until a connection is made, or the list has been
     exhausted.  By default, 'gsasl' from GNU SASL, available from
     <http://www.gnu.org/software/gsasl/>, and the 'imtest' program from
     Cyrus IMAPD (see 'imap-kerberos4-program'), are tried.

     For SSL connections, the OpenSSL program is available from
     <http://www.openssl.org/>.  OpenSSL was formerly known as SSLeay,
     and nnimap support it too--although the most recent versions of
     SSLeay, 0.9.x, are known to have serious bugs making it useless.
     Earlier versions, especially 0.8.x, of SSLeay are known to work.
     The variable 'imap-ssl-program' contain parameters to pass to
     OpenSSL/SSLeay.

     For IMAP connections using the 'shell' stream, the variable
     'imap-shell-program' specify what program to call.

'nnimap-authenticator'

     The authenticator used to connect to the server.  By default,
     nnimap will use the most secure authenticator your server is
     capable of.

     Example server specification:

          (nnimap "mail.server.com"
                  (nnimap-authenticator anonymous))

     Please note that the value of 'nnimap-authenticator' is a symbol!

        * "gssapi:" GSSAPI (usually kerberos 5) authentication.
          Requires external program 'gsasl' or 'imtest'.
        * "kerberos4:" Kerberos 4 authentication.  Requires external
          program 'imtest'.
        * "digest-md5:" Encrypted username/password via DIGEST-MD5.
          Requires external library 'digest-md5.el'.
        * "cram-md5:" Encrypted username/password via CRAM-MD5.
        * "login:" Plain-text username/password via LOGIN.
        * "anonymous:" Login as "anonymous", supplying your email
          address as password.

'nnimap-expunge-on-close'
     Unlike Parmenides the IMAP designers have decided things that don't
     exist actually do exist.  More specifically, IMAP has this concept
     of marking articles 'Deleted' which doesn't actually delete them,
     and this (marking them 'Deleted', that is) is what nnimap does when
     you delete an article in Gnus (with 'B DEL' or similar).

     Since the articles aren't really removed when we mark them with the
     'Deleted' flag we'll need a way to actually delete them.  Feel like
     running in circles yet?

     Traditionally, nnimap has removed all articles marked as 'Deleted'
     when closing a mailbox but this is now configurable by this server
     variable.

     The possible options are:

     'always'
          The default behavior, delete all articles marked as "Deleted"
          when closing a mailbox.
     'never'
          Never actually delete articles.  Currently there is no way of
          showing the articles marked for deletion in nnimap, but other
          IMAP clients may allow you to do this.  If you ever want to
          run the EXPUNGE command manually, *Note Expunging mailboxes::.
     'ask'
          When closing mailboxes, nnimap will ask if you wish to expunge
          deleted articles or not.

'nnimap-importantize-dormant'

     If non-'nil' (the default), marks dormant articles as ticked (as
     well), for other IMAP clients.  Within Gnus, dormant articles will
     naturally still (only) be marked as dormant.  This is to make
     dormant articles stand out, just like ticked articles, in other
     IMAP clients.  (In other words, Gnus has two "Tick" marks and IMAP
     has only one.)

     Probably the only reason for frobing this would be if you're trying
     enable per-user persistent dormant flags, using something like:

          (setcdr (assq 'dormant nnimap-mark-to-flag-alist)
                  (format "gnus-dormant-%s" (user-login-name)))
          (setcdr (assq 'dormant nnimap-mark-to-predicate-alist)
                  (format "KEYWORD gnus-dormant-%s" (user-login-name)))

     In this case, you would not want the per-user dormant flag showing
     up as ticked for other users.

'nnimap-expunge-search-string'

     This variable contain the IMAP search command sent to server when
     searching for articles eligible for expiring.  The default is '"UID
     %s NOT SINCE %s"', where the first '%s' is replaced by UID set and
     the second '%s' is replaced by a date.

     Probably the only useful value to change this to is '"UID %s NOT
     SENTSINCE %s"', which makes nnimap use the Date: in messages
     instead of the internal article date.  See section 6.4.4 of RFC
     2060 for more information on valid strings.

'nnimap-authinfo-file'

     A file containing credentials used to log in on servers.  The
     format is (almost) the same as the 'ftp' '~/.netrc' file.  See the
     variable 'nntp-authinfo-file' for exact syntax; also see *note
     NNTP::.  An example of an .authinfo line for an IMAP server, is:

          machine students.uio.no login larsi password geheimnis port imap

     Note that it should be 'port imap', or 'port 143', if you use a
     'nnimap-stream' of 'tls' or 'ssl', even if the actual port number
     used is port 993 for secured IMAP. For convenience, Gnus will
     accept 'port imaps' as a synonym of 'port imap'.

'nnimap-need-unselect-to-notice-new-mail'

     Unselect mailboxes before looking for new mail in them.  Some
     servers seem to need this under some circumstances; it was reported
     that Courier 1.7.1 did.

* Menu:

* Splitting in IMAP::           Splitting mail with nnimap.
* Expiring in IMAP::            Expiring mail with nnimap.
* Editing IMAP ACLs::           Limiting/enabling other users access to a mailbox.
* Expunging mailboxes::         Equivalent of a "compress mailbox" button.
* A note on namespaces::        How to (not) use IMAP namespace in Gnus.
* Debugging IMAP::              What to do when things don't work.


File: gnus,  Node: Splitting in IMAP,  Next: Expiring in IMAP,  Up: IMAP

6.5.1 Splitting in IMAP
-----------------------

Splitting is something Gnus users have loved and used for years, and now
the rest of the world is catching up.  Yeah, dream on, not many IMAP
servers have server side splitting and those that have splitting seem to
use some non-standard protocol.  This means that IMAP support for Gnus
has to do its own splitting.

   And it does.

   (Incidentally, people seem to have been dreaming on, and Sieve has
gaining a market share and is supported by several IMAP servers.
Fortunately, Gnus support it too, *Note Sieve Commands::.)

   Here are the variables of interest:

'nnimap-split-crosspost'

     If non-'nil', do crossposting if several split methods match the
     mail.  If 'nil', the first match in 'nnimap-split-rule' found will
     be used.

     Nnmail equivalent: 'nnmail-crosspost'.

'nnimap-split-inbox'

     A string or a list of strings that gives the name(s) of IMAP
     mailboxes to split from.  Defaults to 'nil', which means that
     splitting is disabled!

          (setq nnimap-split-inbox
                '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))

     No nnmail equivalent.

'nnimap-split-rule'

     New mail found in 'nnimap-split-inbox' will be split according to
     this variable.

     This variable contains a list of lists, where the first element in
     the sublist gives the name of the IMAP mailbox to move articles
     matching the regexp in the second element in the sublist.  Got
     that?  Neither did I, we need examples.

          (setq nnimap-split-rule
                '(("INBOX.nnimap"
                   "^Sender: owner-nnimap@vic20.globalcom.se")
                  ("INBOX.junk"    "^Subject:.*MAKE MONEY")
                  ("INBOX.private" "")))

     This will put all articles from the nnimap mailing list into
     mailbox INBOX.nnimap, all articles containing MAKE MONEY in the
     Subject: line into INBOX.junk and everything else in INBOX.private.

     The first string may contain '\\1' forms, like the ones used by
     replace-match to insert sub-expressions from the matched text.  For
     instance:

          ("INBOX.lists.\\1"     "^Sender: owner-\\([a-z-]+\\)@")

     The first element can also be the symbol 'junk' to indicate that
     matching messages should simply be deleted.  Use with care.

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

     Nnmail users might recollect that the last regexp had to be empty
     to match all articles (like in the example above).  This is not
     required in nnimap.  Articles not matching any of the regexps will
     not be moved out of your inbox.  (This might affect performance if
     you keep lots of unread articles in your inbox, since the splitting
     code would go over them every time you fetch new mail.)

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

     This variable can also have a function as its value, the function
     will be called with the headers narrowed and should return a group
     where it thinks the article should be split to.  See
     'nnimap-split-fancy'.

     The splitting code tries to create mailboxes if it needs to.

     To allow for different split rules on different virtual servers,
     and even different split rules in different inboxes on the same
     server, the syntax of this variable have been extended along the
     lines of:

          (setq nnimap-split-rule
                '(("my1server"    (".*" (("ding"    "ding@gnus.org")
                                         ("junk"    "From:.*Simon"))))
                  ("my2server"    ("INBOX" nnimap-split-fancy))
                  ("my[34]server" (".*" (("private" "To:.*Simon")
                                         ("junk"    my-junk-func))))))

     The virtual server name is in fact a regexp, so that the same rules
     may apply to several servers.  In the example, the servers
     'my3server' and 'my4server' both use the same rules.  Similarly,
     the inbox string is also a regexp.  The actual splitting rules are
     as before, either a function, or a list with group/regexp or
     group/function elements.

     Nnmail equivalent: 'nnmail-split-methods'.

'nnimap-split-predicate'

     Mail matching this predicate in 'nnimap-split-inbox' will be split,
     it is a string and the default is 'UNSEEN UNDELETED'.

     This might be useful if you use another IMAP client to read mail in
     your inbox but would like Gnus to split all articles in the inbox
     regardless of readedness.  Then you might change this to
     'UNDELETED'.

'nnimap-split-fancy'

     It's possible to set 'nnimap-split-rule' to 'nnmail-split-fancy' if
     you want to use fancy splitting.  *Note Fancy Mail Splitting::.

     However, to be able to have different fancy split rules for nnmail
     and nnimap back ends you can set 'nnimap-split-rule' to
     'nnimap-split-fancy' and define the nnimap specific fancy split
     rule in 'nnimap-split-fancy'.

     Example:

          (setq nnimap-split-rule 'nnimap-split-fancy
                nnimap-split-fancy ...)

     Nnmail equivalent: 'nnmail-split-fancy'.

'nnimap-split-download-body'

     Set to non-'nil' to download entire articles during splitting.
     This is generally not required, and will slow things down
     considerably.  You may need it if you want to use an advanced
     splitting function that analyzes the body to split the article.


File: gnus,  Node: Expiring in IMAP,  Next: Editing IMAP ACLs,  Prev: Splitting in IMAP,  Up: IMAP

6.5.2 Expiring in IMAP
----------------------

Even though 'nnimap' is not a proper 'nnmail' derived back end, it
supports most features in regular expiring (*note Expiring Mail::).
Unlike splitting in IMAP (*note Splitting in IMAP::) it does not clone
the 'nnmail' variables (i.e., creating NNIMAP-EXPIRY-WAIT) but reuse the
'nnmail' variables.  What follows below are the variables used by the
'nnimap' expiry process.

   A note on how the expire mark is stored on the IMAP server is
appropriate here as well.  The expire mark is translated into a 'imap'
client specific mark, 'gnus-expire', and stored on the message.  This
means that likely only Gnus will understand and treat the 'gnus-expire'
mark properly, although other clients may allow you to view client
specific flags on the message.  It also means that your server must
support permanent storage of client specific flags on messages.  Most
do, fortunately.

'nnmail-expiry-wait'
'nnmail-expiry-wait-function'

     These variables are fully supported.  The expire value can be a
     number, the symbol 'immediate' or 'never'.

'nnmail-expiry-target'

     This variable is supported, and internally implemented by calling
     the 'nnmail' functions that handle this.  It contains an
     optimization that if the destination is a IMAP group on the same
     server, the article is copied instead of appended (that is,
     uploaded again).


File: gnus,  Node: Editing IMAP ACLs,  Next: Expunging mailboxes,  Prev: Expiring in IMAP,  Up: IMAP

6.5.3 Editing IMAP ACLs
-----------------------

ACL stands for Access Control List.  ACLs are used in IMAP for limiting
(or enabling) other users access to your mail boxes.  Not all IMAP
servers support this, this function will give an error if it doesn't.

   To edit an ACL for a mailbox, type 'G l'
('gnus-group-edit-nnimap-acl') and you'll be presented with an ACL
editing window with detailed instructions.

   Some possible uses:

   * Giving "anyone" the "lrs" rights (lookup, read, keep seen/unseen
     flags) on your mailing list mailboxes enables other users on the
     same server to follow the list without subscribing to it.
   * At least with the Cyrus server, you are required to give the user
     "anyone" posting ("p") capabilities to have "plussing" work (that
     is, mail sent to user+mailbox@domain ending up in the IMAP mailbox
     INBOX.mailbox).


File: gnus,  Node: Expunging mailboxes,  Next: A note on namespaces,  Prev: Editing IMAP ACLs,  Up: IMAP

6.5.4 Expunging mailboxes
-------------------------

If you're using the 'never' setting of 'nnimap-expunge-on-close', you
may want the option of expunging all deleted articles in a mailbox
manually.  This is exactly what 'G x' does.

   Currently there is no way of showing deleted articles, you can just
delete them.


File: gnus,  Node: A note on namespaces,  Next: Debugging IMAP,  Prev: Expunging mailboxes,  Up: IMAP

6.5.5 A note on namespaces
--------------------------

The IMAP protocol has a concept called namespaces, described by the
following text in the RFC2060:

     5.1.2.  Mailbox Namespace Naming Convention

        By convention, the first hierarchical element of any mailbox name
        which begins with "#" identifies the "namespace" of the remainder of
        the name.  This makes it possible to disambiguate between different
        types of mailbox stores, each of which have their own namespaces.

           For example, implementations which offer access to USENET
           newsgroups MAY use the "#news" namespace to partition the USENET
           newsgroup namespace from that of other mailboxes.  Thus, the
           comp.mail.misc newsgroup would have an mailbox name of
           "#news.comp.mail.misc", and the name "comp.mail.misc" could refer
           to a different object (e.g. a user's private mailbox).

   While there is nothing in this text that warrants concern for the
IMAP implementation in Gnus, some servers use namespace prefixes in a
way that does not work with how Gnus uses mailbox names.

   Specifically, University of Washington's IMAP server uses mailbox
names like '#driver.mbx/read-mail' which are valid only in the CREATE
and APPEND commands.  After the mailbox is created (or a messages is
appended to a mailbox), it must be accessed without the namespace
prefix, i.e.  'read-mail'.  Since Gnus do not make it possible for the
user to guarantee that user entered mailbox names will only be used with
the CREATE and APPEND commands, you should simply not use the namespace
prefixed mailbox names in Gnus.

   See the UoW IMAPD documentation for the '#driver.*/' prefix for more
information on how to use the prefixes.  They are a power tool and
should be used only if you are sure what the effects are.


File: gnus,  Node: Debugging IMAP,  Prev: A note on namespaces,  Up: IMAP

6.5.6 Debugging IMAP
--------------------

IMAP is a complex protocol, more so than NNTP or POP3.  Implementation
bugs are not unlikely, and we do our best to fix them right away.  If
you encounter odd behavior, chances are that either the server or Gnus
is buggy.

   If you are familiar with network protocols in general, you will
probably be able to extract some clues from the protocol dump of the
exchanges between Gnus and the server.  Even if you are not familiar
with network protocols, when you include the protocol dump in
IMAP-related bug reports you are helping us with data critical to
solving the problem.  Therefore, we strongly encourage you to include
the protocol dump when reporting IMAP bugs in Gnus.

   Because the protocol dump, when enabled, generates lots of data, it
is disabled by default.  You can enable it by setting 'imap-log' as
follows:

     (setq imap-log t)

   This instructs the 'imap.el' package to log any exchanges with the
server.  The log is stored in the buffer '*imap-log*'.  Look for error
messages, which sometimes are tagged with the keyword 'BAD'--but when
submitting a bug, make sure to include all the data.


File: gnus,  Node: Other Sources,  Next: Combined Groups,  Prev: IMAP,  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.
* SOUP::                        Reading SOUP packets "offline".
* Mail-To-News Gateways::       Posting articles via mail-to-news gateways.


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: SOUP,  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 (Rmail) mail box.

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

'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: SOUP,  Next: Mail-To-News Gateways,  Prev: Document Groups,  Up: Other Sources

6.6.4 SOUP
----------

In the PC world people often talk about "offline" newsreaders.  These
are thingies that are combined reader/news transport monstrosities.
With built-in modem programs.  Yecchh!

   Of course, us Unix Weenie types of human beans use things like 'uucp'
and, like, 'nntpd' and set up proper news and mail transport things like
Ghod intended.  And then we just use normal newsreaders.

   However, it can sometimes be convenient to do something that's a bit
easier on the brain if you have a very slow modem, and you're not really
that interested in doing things properly.

   A file format called SOUP has been developed for transporting news
and mail from servers to home machines and back again.  It can be a bit
fiddly.

   First some terminology:

"server"
     This is the machine that is connected to the outside world and
     where you get news and/or mail from.

"home machine"
     This is the machine that you want to do the actual reading and
     responding on.  It is typically not connected to the rest of the
     world in any way.

"packet"
     Something that contains messages and/or commands.  There are two
     kinds of packets:

     "message packets"
          These are packets made at the server, and typically contain
          lots of messages for you to read.  These are called
          'SoupoutX.tgz' by default, where X is a number.

     "response packets"
          These are packets made at the home machine, and typically
          contains replies that you've written.  These are called
          'SoupinX.tgz' by default, where X is a number.

  1. You log in on the server and create a SOUP packet.  You can either
     use a dedicated SOUP thingie (like the 'awk' program), or you can
     use Gnus to create the packet with its SOUP commands ('O s' and/or
     'G s b'; and then 'G s p') (*note SOUP Commands::).

  2. You transfer the packet home.  Rail, boat, car or modem will do
     fine.

  3. You put the packet in your home directory.

  4. You fire up Gnus on your home machine using the 'nnsoup' back end
     as the native or secondary server.

  5. You read articles and mail and answer and followup to the things
     you want (*note SOUP Replies::).

  6. You do the 'G s r' command to pack these replies into a SOUP
     packet.

  7. You transfer this packet to the server.

  8. You use Gnus to mail this packet out with the 'G s s' command.

  9. You then repeat until you die.

   So you basically have a bipartite system--you use 'nnsoup' for
reading and Gnus for packing/sending these SOUP packets.

* Menu:

* SOUP Commands::               Commands for creating and sending SOUP packets
* SOUP Groups::                 A back end for reading SOUP packets.
* SOUP Replies::                How to enable 'nnsoup' to take over mail and news.


File: gnus,  Node: SOUP Commands,  Next: SOUP Groups,  Up: SOUP

6.6.4.1 SOUP Commands
.....................

These are commands for creating and manipulating SOUP packets.

'G s b'
     Pack all unread articles in the current group
     ('gnus-group-brew-soup').  This command understands the
     process/prefix convention.

'G s w'
     Save all SOUP data files ('gnus-soup-save-areas').

'G s s'
     Send all replies from the replies packet
     ('gnus-soup-send-replies').

'G s p'
     Pack all files into a SOUP packet ('gnus-soup-pack-packet').

'G s r'
     Pack all replies into a replies packet ('nnsoup-pack-replies').

'O s'
     This summary-mode command adds the current article to a SOUP packet
     ('gnus-soup-add-article').  It understands the process/prefix
     convention (*note Process/Prefix::).

   There are a few variables to customize where Gnus will put all these
thingies:

'gnus-soup-directory'
     Directory where Gnus will save intermediate files while composing
     SOUP packets.  The default is '~/SoupBrew/'.

'gnus-soup-replies-directory'
     This is what Gnus will use as a temporary directory while sending
     our reply packets.  '~/SoupBrew/SoupReplies/' is the default.

'gnus-soup-prefix-file'
     Name of the file where Gnus stores the last used prefix.  The
     default is 'gnus-prefix'.

'gnus-soup-packer'
     A format string command for packing a SOUP packet.  The default is
     'tar cf - %s | gzip > $HOME/Soupout%d.tgz'.

'gnus-soup-unpacker'
     Format string command for unpacking a SOUP packet.  The default is
     'gunzip -c %s | tar xvf -'.

'gnus-soup-packet-directory'
     Where Gnus will look for reply packets.  The default is '~/'.

'gnus-soup-packet-regexp'
     Regular expression matching SOUP reply packets in
     'gnus-soup-packet-directory'.


File: gnus,  Node: SOUP Groups,  Next: SOUP Replies,  Prev: SOUP Commands,  Up: SOUP

6.6.4.2 SOUP Groups
...................

'nnsoup' is the back end for reading SOUP packets.  It will read
incoming packets, unpack them, and put them in a directory where you can
read them at leisure.

   These are the variables you can use to customize its behavior:

'nnsoup-tmp-directory'
     When 'nnsoup' unpacks a SOUP packet, it does it in this directory.
     ('/tmp/' by default.)

'nnsoup-directory'
     'nnsoup' then moves each message and index file to this directory.
     The default is '~/SOUP/'.

'nnsoup-replies-directory'
     All replies will be stored in this directory before being packed
     into a reply packet.  The default is '~/SOUP/replies/'.

'nnsoup-replies-format-type'
     The SOUP format of the replies packets.  The default is '?n'
     (rnews), and I don't think you should touch that variable.  I
     probably shouldn't even have documented it.  Drats!  Too late!

'nnsoup-replies-index-type'
     The index type of the replies packet.  The default is '?n', which
     means "none".  Don't fiddle with this one either!

'nnsoup-active-file'
     Where 'nnsoup' stores lots of information.  This is not an "active
     file" in the 'nntp' sense; it's an Emacs Lisp file.  If you lose
     this file or mess it up in any way, you're dead.  The default is
     '~/SOUP/active'.

'nnsoup-packer'
     Format string command for packing a reply SOUP packet.  The default
     is 'tar cf - %s | gzip > $HOME/Soupin%d.tgz'.

'nnsoup-unpacker'
     Format string command for unpacking incoming SOUP packets.  The
     default is 'gunzip -c %s | tar xvf -'.

'nnsoup-packet-directory'
     Where 'nnsoup' will look for incoming packets.  The default is
     '~/'.

'nnsoup-packet-regexp'
     Regular expression matching incoming SOUP packets.  The default is
     'Soupout'.

'nnsoup-always-save'
     If non-'nil', save the replies buffer after each posted message.


File: gnus,  Node: SOUP Replies,  Prev: SOUP Groups,  Up: SOUP

6.6.4.3 SOUP Replies
....................

Just using 'nnsoup' won't mean that your postings and mailings end up in
SOUP reply packets automagically.  You have to work a bit more for that
to happen.

   The 'nnsoup-set-variables' command will set the appropriate variables
to ensure that all your followups and replies end up in the SOUP system.

   In specific, this is what it does:

     (setq message-send-news-function 'nnsoup-request-post)
     (setq message-send-mail-function 'nnsoup-request-mail)

   And that's it, really.  If you only want news to go into the SOUP
system you just use the first line.  If you only want mail to be SOUPed
you use the second.


File: gnus,  Node: Mail-To-News Gateways,  Prev: SOUP,  Up: Other Sources

6.6.5 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: Combined Groups,  Next: Gnus Unplugged,  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.
* Kibozed Groups::              Looking through parts of the newsfeed for articles.


File: gnus,  Node: Virtual Groups,  Next: Kibozed 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: Kibozed Groups,  Prev: Virtual Groups,  Up: Combined Groups

6.7.2 Kibozed Groups
--------------------

"Kibozing" is defined by the OED as "grepping through (parts of) the
news feed".  'nnkiboze' is a back end that will do this for you.  Oh
joy!  Now you can grind any NNTP server down to a halt with useless
requests!  Oh happiness!

   To create a kibozed group, use the 'G k' command in the group buffer.

   The address field of the 'nnkiboze' method is, as with 'nnvirtual', a
regexp to match groups to be "included" in the 'nnkiboze' group.  That's
where most similarities between 'nnkiboze' and 'nnvirtual' end.

   In addition to this regexp detailing component groups, an 'nnkiboze'
group must have a score file to say what articles are to be included in
the group (*note Scoring::).

   You must run 'M-x nnkiboze-generate-groups' after creating the
'nnkiboze' groups you want to have.  This command will take time.  Lots
of time.  Oodles and oodles of time.  Gnus has to fetch the headers from
all the articles in all the component groups and run them through the
scoring process to determine if there are any articles in the groups
that are to be part of the 'nnkiboze' groups.

   Please limit the number of component groups by using restrictive
regexps.  Otherwise your sysadmin may become annoyed with you, and the
NNTP site may throw you off and never let you back in again.  Stranger
things have happened.

   'nnkiboze' component groups do not have to be alive--they can be
dead, and they can be foreign.  No restrictions.

   The generation of an 'nnkiboze' group means writing two files in
'nnkiboze-directory', which is '~/News/kiboze/' by default.  One
contains the NOV header lines for all the articles in the group, and the
other is an additional '.newsrc' file to store information on what
groups have been searched through to find component articles.

   Articles marked as read in the 'nnkiboze' group will have their NOV
lines removed from the NOV file.


File: gnus,  Node: Gnus Unplugged,  Prev: Combined Groups,  Up: Select Methods

6.8 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 even have to configure anything.

   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 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.8.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, all 'nntp' and 'nnimap' servers in
     'gnus-select-method' and 'gnus-secondary-select-methods' 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.8.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.8.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.

'gnus-agent-cat-name'
     The name of the category.

'gnus-agent-cat-groups'
     The list of groups that are in this category.

'gnus-agent-cat-predicate'
     A predicate which (generally) gives a rough outline of which
     articles are eligible for downloading; and

'gnus-agent-cat-score-file'
     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.)

'gnus-agent-cat-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.

'gnus-agent-cat-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.

'gnus-agent-cat-low-score'
     an integer that overrides the value of 'gnus-agent-low-score'.

'gnus-agent-cat-high-score'
     an integer that overrides the value of 'gnus-agent-high-score'.

'gnus-agent-cat-length-when-short'
     an integer that overrides the value of 'gnus-agent-short-article'.

'gnus-agent-cat-length-when-long'
     an integer that overrides the value of 'gnus-agent-long-article'.

'gnus-agent-cat-enable-undownloaded-faces'
     a symbol indicating whether the summary buffer should display
     undownloaded articles using the gnus-summary-*-undownloaded-face
     faces.  The symbol nil will disable the use of undownloaded faces
     while all other symbols enable them.

   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 iff the article is shorter than 'gnus-agent-short-article'
     lines; default 100.

'long'
     True iff the article is longer than 'gnus-agent-long-article'
     lines; default 200.

'low'
     True iff the article has a download score less than
     'gnus-agent-low-score'; default 0.

'high'
     True iff the article has a download score greater than
     'gnus-agent-high-score'; default 0.

'spam'
     True iff the Gnus Agent guesses that the article is spam.  The
     heuristics may change over time, but at present it just computes a
     checksum and sees whether articles match.

'true'
     Always true.

'false'
     Always false.

   If you want to create your own predicate function, here's what you
have to know: The functions are called with no parameters, but the
'gnus-headers' and 'gnus-score' dynamic variables are bound to useful
values.

   For example, you could decide that you don't want to download
articles that were posted more than a certain number of days ago (e.g.
posted more than 'gnus-agent-expire-days' ago) you might write a
function something along the lines of the following:

     (defun my-article-old-p ()
       "Say whether an article is old."
       (< (time-to-days (date-to-time (mail-header-date gnus-headers)))
          (- (time-to-days (current-time)) gnus-agent-expire-days)))

   with the predicate then defined as:

     (not my-article-old-p)

   or you could append your predicate to the predefined
'gnus-category-predicate-alist' in your '~/.gnus.el' or wherever.

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


File: gnus,  Node: Agent Commands,  Next: Agent Visuals,  Prev: Agent Categories,  Up: Gnus Unplugged

6.8.3 Agent Commands
--------------------

All the Gnus Agent commands are on the 'J' submap.  The 'J j'
('gnus-agent-toggle-plugged') command works in all modes, and toggles
the plugged/unplugged state of the Gnus Agent.

* Menu:

* Group Agent Commands::        Configure groups and fetch their contents.
* Summary Agent Commands::      Manually select then fetch specific articles.
* Server Agent Commands::       Select the servers that are supported by the agent.


File: gnus,  Node: Group Agent Commands,  Next: Summary Agent Commands,  Up: Agent Commands

6.8.3.1 Group Agent Commands
............................

'J u'
     Fetch all eligible articles in the current group
     ('gnus-agent-fetch-groups').

'J c'
     Enter the Agent category buffer ('gnus-enter-category-buffer').

'J s'
     Fetch all eligible articles in all groups
     ('gnus-agent-fetch-session').

'J S'
     Send all sendable messages in the queue group
     ('gnus-group-send-queue').  *Note Drafts::.

'J a'
     Add the current group to an Agent category
     ('gnus-agent-add-group').  This command understands the
     process/prefix convention (*note Process/Prefix::).

'J r'
     Remove the current group from its category, if any
     ('gnus-agent-remove-group').  This command understands the
     process/prefix convention (*note Process/Prefix::).

'J Y'
     Synchronize flags changed while unplugged with remote server, if
     any.


File: gnus,  Node: Summary Agent Commands,  Next: Server Agent Commands,  Prev: Group Agent Commands,  Up: Agent Commands

6.8.3.2 Summary Agent Commands
..............................

'J #'
     Mark the article for downloading ('gnus-agent-mark-article').

'J M-#'
     Remove the downloading mark from the article
     ('gnus-agent-unmark-article').

'@'
     Toggle whether to download the article ('gnus-agent-toggle-mark').
     The download mark is '%' by default.

'J c'
     Mark all articles as read ('gnus-agent-catchup') that are neither
     cached, downloaded, nor downloadable.

'J S'
     Download all eligible (*note Agent Categories::) articles in this
     group.  ('gnus-agent-fetch-group').

'J s'
     Download all processable articles in this group.
     ('gnus-agent-fetch-series').

'J u'
     Download all downloadable articles in the current group
     ('gnus-agent-summary-fetch-group').


File: gnus,  Node: Server Agent Commands,  Prev: Summary Agent Commands,  Up: Agent Commands

6.8.3.3 Server Agent Commands
.............................

'J a'
     Add the current server to the list of servers covered by the Gnus
     Agent ('gnus-agent-add-server').

'J r'
     Remove the current server from the list of servers covered by the
     Gnus Agent ('gnus-agent-remove-server').


File: gnus,  Node: Agent Visuals,  Next: Agent as Cache,  Prev: Agent Commands,  Up: Gnus Unplugged

6.8.4 Agent Visuals
-------------------

If you open a summary while unplugged and, Gnus knows from the group's
active range that there are more articles than the headers currently
stored in the Agent, you may see some articles whose subject looks
something like '[Undownloaded article #####]'.  These are placeholders
for the missing headers.  Aside from setting a mark, there is not much
that can be done with one of these placeholders.  When Gnus finally gets
a chance to fetch the group's headers, the placeholders will
automatically be replaced by the actual headers.  You can configure the
summary buffer's maneuvering to skip over the placeholders if you care
(See 'gnus-auto-goto-ignores').

   While it may be obvious to all, the only headers and articles
available while unplugged are those headers and articles that were
fetched into the Agent while previously plugged.  To put it another way,
"If you forget to fetch something while plugged, you might have a less
than satisfying unplugged session".  For this reason, the Agent adds two
visual effects to your summary buffer.  These effects display the
download status of each article so that you always know which articles
will be available when unplugged.

   The first visual effect is the '%O' spec.  If you customize
'gnus-summary-line-format' to include this specifier, you will add a
single character field that indicates an article's download status.
Articles that have been fetched into either the Agent or the Cache, will
display 'gnus-downloaded-mark' (defaults to '+').  All other articles
will display 'gnus-undownloaded-mark' (defaults to '-').  If you open a
group that has not been agentized, a space (' ') will be displayed.

   The second visual effect are the undownloaded faces.  The faces,
there are three indicating the article's score (low, normal, high), seem
to result in a love/hate response from many Gnus users.  The problem is
that the face selection is controlled by a list of condition tests and
face names (See 'gnus-summary-highlight').  Each condition is tested in
the order in which it appears in the list so early conditions have
precedence over later conditions.  All of this means that, if you tick
an undownloaded article, the article will continue to be displayed in
the undownloaded face rather than the ticked face.

   If you use the Agent as a cache (to avoid downloading the same
article each time you visit it or to minimize your connection time), the
undownloaded face will probably seem like a good idea.  The reason being
that you do all of our work (marking, reading, deleting) with downloaded
articles so the normal faces always appear.

   For occasional Agent users, the undownloaded faces may appear to be
an absolutely horrible idea.  The issue being that, since most of their
articles have not been fetched into the Agent, most of the normal faces
will be obscured by the undownloaded faces.  If this is your situation,
you have two choices available.  First, you can completely disable the
undownload faces by customizing 'gnus-summary-highlight' to delete the
three cons-cells that refer to the 'gnus-summary-*-undownloaded-face'
faces.  Second, if you prefer to take a more fine-grained approach, you
may set the 'agent-disable-undownloaded-faces' group parameter to 't'.
This parameter, like all other agent parameters, may be set on an Agent
Category (*note Agent Categories::), a Group Topic (*note Topic
Parameters::), or an individual group (*note Group Parameters::).


File: gnus,  Node: Agent as Cache,  Next: Agent Expiry,  Prev: Agent Visuals,  Up: Gnus Unplugged

6.8.5 Agent as Cache
--------------------

When Gnus is plugged, it is not efficient to download headers or
articles from the server again, if they are already stored in the Agent.
So, Gnus normally only downloads headers once, and stores them in the
Agent.  These headers are later used when generating the summary buffer,
regardless of whether you are plugged or unplugged.  Articles are not
cached in the Agent by default though (that would potentially consume
lots of disk space), but if you have already downloaded an article into
the Agent, Gnus will not download the article from the server again but
use the locally stored copy instead.

   If you so desire, you can configure the agent (see 'gnus-agent-cache'
*note Agent Variables::) to always download headers and articles while
plugged.  Gnus will almost certainly be slower, but it will be kept
synchronized with the server.  That last point probably won't make any
sense if you are using a nntp or nnimap back end.


File: gnus,  Node: Agent Expiry,  Next: Agent Regeneration,  Prev: Agent as Cache,  Up: Gnus Unplugged

6.8.6 Agent Expiry
------------------

The Agent back end, 'nnagent', doesn't handle expiry.  Well, at least it
doesn't handle it like other back ends.  Instead, there are special
'gnus-agent-expire' and 'gnus-agent-expire-group' commands that will
expire all read articles that are older than 'gnus-agent-expire-days'
days.  They can be run whenever you feel that you're running out of
space.  Neither are particularly fast or efficient, and it's not a
particularly good idea to interrupt them (with 'C-g' or anything else)
once you've started one of them.

   Note that other functions, e.g.  'gnus-request-expire-articles',
might run 'gnus-agent-expire' for you to keep the agent synchronized
with the group.

   The agent parameter 'agent-enable-expiration' may be used to prevent
expiration in selected groups.

   If 'gnus-agent-expire-all' is non-'nil', the agent expiration
commands will expire all articles--unread, read, ticked and dormant.  If
'nil' (which is the default), only read articles are eligible for
expiry, and unread, ticked and dormant articles will be kept
indefinitely.

   If you find that some articles eligible for expiry are never expired,
perhaps some Gnus Agent files are corrupted.  There's are special
commands, 'gnus-agent-regenerate' and 'gnus-agent-regenerate-group', to
fix possible problems.


File: gnus,  Node: Agent Regeneration,  Next: Agent and IMAP,  Prev: Agent Expiry,  Up: Gnus Unplugged

6.8.7 Agent Regeneration
------------------------

The local data structures used by 'nnagent' may become corrupted due to
certain exceptional conditions.  When this happens, 'nnagent'
functionality may degrade or even fail.  The solution to this problem is
to repair the local data structures by removing all internal
inconsistencies.

   For example, if your connection to your server is lost while
downloaded articles into the agent, the local data structures will not
know about articles successfully downloaded prior to the connection
failure.  Running 'gnus-agent-regenerate' or
'gnus-agent-regenerate-group' will update the data structures such that
you don't need to download these articles a second time.

   The command 'gnus-agent-regenerate' will perform
'gnus-agent-regenerate-group' on every agentized group.  While you can
run 'gnus-agent-regenerate' in any buffer, it is strongly recommended
that you first close all summary buffers.

   The command 'gnus-agent-regenerate-group' uses the local copies of
individual articles to repair the local NOV(header) database.  It then
updates the internal data structures that document which articles are
stored locally.  An optional argument will mark articles in the agent as
unread.


File: gnus,  Node: Agent and IMAP,  Next: Outgoing Messages,  Prev: Agent Regeneration,  Up: Gnus Unplugged

6.8.8 Agent and IMAP
--------------------

The Agent works with any Gnus back end, including nnimap.  However,
since there are some conceptual differences between NNTP and IMAP, this
section (should) provide you with some information to make Gnus Agent
work smoother as a IMAP Disconnected Mode client.

   The first thing to keep in mind is that all flags (read, ticked, etc)
are kept on the IMAP server, rather than in '.newsrc' as is the case for
nntp.  Thus Gnus need to remember flag changes when disconnected, and
synchronize these flags when you plug back in.

   Gnus keeps track of flag changes when reading nnimap groups under the
Agent.  When you plug back in, Gnus will check if you have any changed
any flags and ask if you wish to synchronize these with the server.  The
behavior is customizable by 'gnus-agent-synchronize-flags'.

   If 'gnus-agent-synchronize-flags' is 'nil', the Agent will never
automatically synchronize flags.  If it is 'ask', which is the default,
the Agent will check if you made any changes and if so ask if you wish
to synchronize these when you re-connect.  If it has any other value,
all flags will be synchronized automatically.

   If you do not wish to synchronize flags automatically when you
re-connect, you can do it manually with the
'gnus-agent-synchronize-flags' command that is bound to 'J Y' in the
group buffer.

   Some things are currently not implemented in the Agent that you'd
might expect from a disconnected IMAP client, including:

   * Copying/moving articles into nnimap groups when unplugged.

   * Creating/deleting nnimap groups when unplugged.

   Technical note: the synchronization algorithm does not work by
"pushing" all local flags to the server, but rather incrementally update
the server view of flags by changing only those flags that were changed
by the user.  Thus, if you set one flag on an article, quit the group
and re-select the group and remove the flag; the flag will be set and
removed from the server when you "synchronize".  The queued flag
operations can be found in the per-server 'flags' file in the Agent
directory.  It's emptied when you synchronize flags.


File: gnus,  Node: Outgoing Messages,  Next: Agent Variables,  Prev: Agent and IMAP,  Up: Gnus Unplugged

6.8.9 Outgoing Messages
-----------------------

When Gnus is unplugged, all outgoing messages (both mail and news) are
stored in the draft group "queue" (*note Drafts::).  You can view them
there after posting, and edit them at will.

   When Gnus is plugged again, you can send the messages either from the
draft group with the special commands available there, or you can use
the 'J S' command in the group buffer to send all the sendable messages
in the draft group.


File: gnus,  Node: Agent Variables,  Next: Example Setup,  Prev: Outgoing Messages,  Up: Gnus Unplugged

6.8.10 Agent Variables
----------------------

'gnus-agent-directory'
     Where the Gnus Agent will store its files.  The default is
     '~/News/agent/'.

'gnus-agent-handle-level'
     Groups on levels (*note Group Levels::) higher than this variable
     will be ignored by the Agent.  The default is
     'gnus-level-subscribed', which means that only subscribed group
     will be considered by the Agent by default.

'gnus-agent-plugged-hook'
     Hook run when connecting to the network.

'gnus-agent-unplugged-hook'
     Hook run when disconnecting from the network.

'gnus-agent-fetched-hook'
     Hook run when finished fetching articles.

'gnus-agent-cache'
     Variable to control whether use the locally stored NOV and articles
     when plugged, e.g.  essentially using the Agent as a cache.  The
     default is non-'nil', which means to use the Agent as a cache.

'gnus-agent-go-online'
     If 'gnus-agent-go-online' is 'nil', the Agent will never
     automatically switch offline servers into online status.  If it is
     'ask', the default, the Agent will ask if you wish to switch
     offline servers into online status when you re-connect.  If it has
     any other value, all offline servers will be automatically switched
     into online status.

'gnus-agent-mark-unread-after-downloaded'
     If 'gnus-agent-mark-unread-after-downloaded' is non-'nil', mark
     articles as unread after downloading.  This is usually a safe thing
     to do as the newly downloaded article has obviously not been read.
     The default is 't'.

'gnus-agent-consider-all-articles'
     If 'gnus-agent-consider-all-articles' is non-'nil', the agent will
     let the agent predicate decide whether articles need to be
     downloaded or not, for all articles.  When 'nil', the default, the
     agent will only let the predicate decide whether unread articles
     are downloaded or not.  If you enable this, you may also want to
     look into the agent expiry settings (*note Category Variables::),
     so that the agent doesn't download articles which the agent will
     later expire, over and over again.

'gnus-agent-max-fetch-size'
     The agent fetches articles into a temporary buffer prior to parsing
     them into individual files.  To avoid exceeding the max.  buffer
     size, the agent alternates between fetching and parsing until all
     articles have been fetched.  'gnus-agent-max-fetch-size' provides a
     size limit to control how often the cycling occurs.  A large value
     improves performance.  A small value minimizes the time lost should
     the connection be lost while fetching (You may need to run
     'gnus-agent-regenerate-group' to update the group's state.
     However, all articles parsed prior to loosing the connection will
     be available while unplugged).  The default is 10M so it is unusual
     to see any cycling.

'gnus-server-unopen-status'
     Perhaps not an Agent variable, but closely related to the Agent,
     this variable says what will happen if Gnus cannot open a server.
     If the Agent is enabled, the default, 'nil', makes Gnus ask the
     user whether to deny the server or whether to unplug the agent.  If
     the Agent is disabled, Gnus always simply deny the server.  Other
     choices for this variable include 'denied' and 'offline' the latter
     is only valid if the Agent is used.

'gnus-auto-goto-ignores'
     Another variable that isn't an Agent variable, yet so closely
     related that most will look for it here, this variable tells the
     summary buffer how to maneuver around undownloaded (only headers
     stored in the agent) and unfetched (neither article nor headers
     stored) articles.

     The valid values are 'nil' (maneuver to any article),
     'undownloaded' (maneuvering while unplugged ignores articles that
     have not been fetched), 'always-undownloaded' (maneuvering always
     ignores articles that have not been fetched), 'unfetched'
     (maneuvering ignores articles whose headers have not been fetched).

'gnus-agent-auto-agentize-methods'
     If you have never used the Agent before (or more technically, if
     '~/News/agent/lib/servers' does not exist), Gnus will automatically
     agentize a few servers for you.  This variable control which
     backends should be auto-agentized.  It is typically only useful to
     agentize remote backends.  The auto-agentizing has the same effect
     as running 'J a' on the servers (*note Server Agent Commands::).
     If the file exist, you must manage the servers manually by adding
     or removing them, this variable is only applicable the first time
     you start Gnus.  The default is '(nntp nnimap)'.

