This is Info file ../info/gnus, produced by Makeinfo version 1.68 from
the input file gnus.texi.

INFO-DIR-SECTION Editors
START-INFO-DIR-ENTRY
* Gnus: (gnus).		The news reader Gnus.
END-INFO-DIR-ENTRY

   This file documents Gnus, the GNU Emacs newsreader.

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

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

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

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


File: gnus,  Node: Mail Backend Variables,  Next: Fancy Mail Splitting,  Prev: Splitting Mail,  Up: Getting Mail

Mail Backend Variables
----------------------

   These variables are (for the most part) pertinent to all the various
mail backends.

`nnmail-read-incoming-hook'
     The mail backends all call this hook after reading new mail.  You
     can use this hook to notify any mail watch programs, if you want
     to.

`nnmail-spool-file'
     The backends will look for new mail in this file.  If this
     variable is `nil', the mail backends will never attempt to fetch
     mail by themselves.  If you are using a POP mail server and your
     name is `larsi', you should set this variable to `po:larsi'.  If
     your name is not `larsi', you should probably modify that
     slightly, but you may have guessed that already, you smart &
     handsome devil!  You can also set this variable to `pop', and Gnus
     will try to figure out the POP mail string by itself.  In any
     case, Gnus will call `movemail' which will contact the POP server
     named in the `MAILHOST' environment variable.  If the POP server
     needs a password, you can either set
     `nnmail-pop-password-required' to `t' and be prompted for the
     password, or set `nnmail-pop-password' to the password itself.

     `nnmail-spool-file' can also be a list of mailboxes.

     Your Emacs has to have been configured with `--with-pop' before
     compilation.  This is the default, but some installations have it
     switched off.

     When you use a mail backend, 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 backend--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.

`nnmail-use-procmail'
     If non-`nil', the mail backends will look in
     `nnmail-procmail-directory' for incoming mail.  All the files in
     that directory that have names ending in `nnmail-procmail-suffix'
     will be considered incoming mailboxes, and will be searched for new
     mail.

`nnmail-crash-box'
     When the mail backends read a spool file, it is first moved to this
     file, which is `~/.gnus-crash-box' by default.  If this file
     already exists, it will always be read (and incorporated) before
     any other spool files.

`nnmail-prepare-incoming-hook'
     This is run in a buffer that holds all the new incoming mail, and
     can be used for, well, anything, really.

`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-rfc1522' 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 'gnus-pre-get-new-mail-hook
                    (lambda () (set-default-file-modes 511)))
          
          (add-hook 'gnus-post-get-new-mail-hook
                    (lambda () (set-default-file-modes 551)))

`nnmail-tmp-directory'
     This variable says where to move the incoming mail to while
     processing it.  This is usually done in the same directory that
     the mail backend inhabits (i.e., `~/Mail/'), but if this variable
     is non-`nil', it will be used instead.

`nnmail-movemail-program'
     This program is executed to move mail from the user's inbox to her
     home directory.  The default is `movemail'.

     This can also be a function.  In that case, the function will be
     called with two parameters - the name of the inbox, and the file
     to be moved to.

`nnmail-delete-incoming'
     If non-`nil', the mail backends will delete the temporary incoming
     file after splitting mail into the proper groups.  This is `t' by
     default.

     (No Gnus release since (ding) Gnus 0.10 (or something like that)
     have lost mail, I think, but that's not the point.  (Except
     certain versions of Red Gnus.))  By not deleting the Incoming*
     files, one can be sure to not lose mail - if Gnus totally whacks
     out, one can always recover what was lost.

     Delete the `Incoming*' files at will.

`nnmail-use-long-file-names'
     If non-`nil', the mail backends will use long file and directory
     names.  Groups like `mail.misc' will end up in directories 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
     backend (via `Gcc', for instance) into the mail duplication
     discovery cache.  The default is `nil'.


File: gnus,  Node: Fancy Mail Splitting,  Next: Mail and Procmail,  Prev: Mail Backend Variables,  Up: Getting Mail

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")
           ;; 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 five possible split syntaxes:

  1. `group': If the split is a string, that will be taken as a group
     name.

  2. (FIELD VALUE SPLIT): If the split is a list, and the first element
     is a string, then that means that if header FIELD (a regexp)
     contains VALUE (also a regexp), then store the message as
     specified by SPLIT.

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

  4. (& SPLIT...): If the split is a list, and the first element is
     `&', then process all SPLITs in the list.

  5. `junk': If the split is the symbol `junk', then don't save this
     message anywhere.

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


   In these splits, FIELD must match a complete field name.  VALUE must
match a complete word according to the fundamental mode syntax table.
You can use `.*' in the regexps to match partial field names or words.
In other words, all VALUE's are wrapped in `\<' and `\>' pairs.

   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 the cells contains the
key, and the cdr contains a string.

   `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, you can say things like:

     (any "debian-\(\\w*\\)@lists.debian.org" "mail.debian.\\1")

   That is, do `replace-match'-like substitions in the group names.


File: gnus,  Node: Mail and Procmail,  Next: Incorporating Old Mail,  Prev: Fancy Mail Splitting,  Up: Getting Mail

Mail and Procmail
-----------------

   Many people use `procmail' (or some other mail filter program or
external delivery agent--`slocal', `elm', etc) to split incoming mail
into groups.  If you do that, you should set `nnmail-spool-file' to
`procmail' to ensure that the mail backends never ever try to fetch
mail by themselves.

   This also means that you probably don't want to set
`nnmail-split-methods' either, which has some, perhaps, unexpected side
effects.

   When a mail backend is queried for what groups it carries, it replies
with the contents of that variable, along with any groups it has figured
out that it carries by other means.  None of the backends (except
`nnmh') actually go out to the disk and check what groups actually
exist.  (It's not trivial to distinguish between what the user thinks is
a basis for a newsgroup and what is just a plain old file or directory.)

   This means that you have to tell Gnus (and the backends) what groups
exist by hand.

   Let's take the `nnmh' backend as an example.

   The folders are located in `nnmh-directory', say, `~/Mail/'.  There
are three folders, `foo', `bar' and `mail.baz'.

   Go to the group buffer and type `G m'.  When prompted, answer `foo'
for the name and `nnmh' for the method.  Repeat twice for the two other
groups, `bar' and `mail.baz'.  Be sure to include all your mail groups.

   That's it.  You are now set to read your mail.  An active file for
this method will be created automatically.

   If you use `nnfolder' or any other backend that store more than a
single article in each file, you should never have procmail add mails to
the file that Gnus sees.  Instead, procmail should put all incoming mail
in `nnmail-procmail-directory'.  To arrive at the file name to put the
incoming mail in, append `nnmail-procmail-suffix' to the group name.
The mail backends will read the mail from these files.

   When Gnus reads a file called `mail.misc.spool', this mail will be
put in the `mail.misc', as one would expect.  However, if you want Gnus
to split the mail the normal way, you could set
`nnmail-resplit-incoming' to `t'.

   If you use `procmail' to split things directory into an `nnmh'
directory (which you shouldn't do), you should set
`nnmail-keep-last-article' to non-`nil' to prevent Gnus from ever
expiring the final article (i. e., the article with the highest article
number) in a mail newsgroup.  This is quite, quite important.

   Here's an example setup:  The incoming spools are located in
`~/incoming/' and have `""' as suffixes (i. e., the incoming spool
files have the same names as the equivalent groups).  The `nnfolder'
backend is to be used as the mail interface, and the `nnfolder'
directory is `~/fMail/'.

     (setq nnfolder-directory "~/fMail/")
     (setq nnmail-spool-file 'procmail)
     (setq nnmail-procmail-directory "~/incoming/")
     (setq gnus-secondary-select-methods '((nnfolder "")))
     (setq nnmail-procmail-suffix "")


File: gnus,  Node: Incorporating Old Mail,  Next: Expiring Mail,  Prev: Mail and Procmail,  Up: Getting Mail

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
backends, 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 path of 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 (*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 backend to another.  Just respool all the mail in the old mail
groups using the new mail backend.


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

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".  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.  Groups that
match the regular expression `gnus-auto-expirable-newsgroups' will have
all articles that you read marked as expirable automatically.  All
articles that are marked as expirable have an `E' in the first column
in the summary buffer.

   Note that making a group auto-expirable don't mean that all read
articles are expired--only the articles that are marked as expirable
will be expired.  Also note the using the `d' command won't make groups
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
doesn'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 that 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 be either a number (not necessarily an integer) or the
symbols `immediate' or `never'.

   You can also use the `expiry-wait' group parameter to selectively
change the expiry period (*note Group Parameters::.).

   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.


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

Washing Mail
------------

   Mailers and list servers are notorious for doing all sorts of really,
really stupid things with mail.  "Hey, RFC822 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
RFC822 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 disc.  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.  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 too make them look nice.  Aaah.

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

          For instance, if you want to remove the `(idm)' and the
          `nagnagnag' identifiers:

               (setq nnmail-list-identifiers
                     '("(idm)" "nagnagnag"))

    `nnmail-remove-tabs'
          Translate all `TAB' characters into `SPACE' characters.

`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

Duplicates
----------

   If you are a member of a couple of mailing list, you will sometime
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" "duplication 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:")
             ;; 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 Backend,  Prev: Duplicates,  Up: Getting Mail

Not Reading Mail
----------------

   If you start using any of the mail backends, 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 `nnmail-spool-file' to `nil', none of the backends 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 backends have variables called
backend-`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 backends 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 Backend,  Prev: Not Reading Mail,  Up: Getting Mail

Choosing a Mail Backend
-----------------------

   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.

* 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 backend.
* Mail Folders::                Having one file for each group.


File: gnus,  Node: Unix Mail Box,  Next: Rmail Babyl,  Up: Choosing a Mail Backend

Unix Mail Box
.............

   The "nnmbox" backend 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.

`nnmbox-active-file'
     The name of the active file for the mail box.

`nnmbox-get-new-mail'
     If non-`nil', `nnmbox' will read incoming mail and split it into
     groups.


File: gnus,  Node: Rmail Babyl,  Next: Mail Spool,  Prev: Unix Mail Box,  Up: Choosing a Mail Backend

Rmail Babyl
...........

   The "nnbabyl" backend 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.

`nnbabyl-active-file'
     The name of the active file for the rmail box.

`nnbabyl-get-new-mail'
     If non-`nil', `nnbabyl' will read incoming mail.


File: gnus,  Node: Mail Spool,  Next: MH Spool,  Prev: Rmail Babyl,  Up: Choosing a Mail Backend

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 backend, Gnus will split all incoming mail into
files; one file for each mail, and put the articles into the correct
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 backend.  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 backend 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 is the fastest backend
when it comes to reading mail.

   Virtual server settings:

`nnml-directory'
     All `nnml' directories will be placed under this directory.

`nnml-active-file'
     The active file for the `nnml' server.

`nnml-newsgroups-file'
     The `nnml' group descriptions file.  *Note Newsgroups File
     Format::.

`nnml-get-new-mail'
     If non-`nil', `nnml' will read incoming mail.

`nnml-nov-is-evil'
     If non-`nil', this backend will ignore any NOV files.

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

   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: Mail Folders,  Prev: Mail Spool,  Up: Choosing a Mail Backend

MH Spool
........

   `nnmh' is just like `nnml', except that is doesn't generate NOV
databases and it doesn't keep an active file.  This makes `nnmh' a
*much* slower backend 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.

`nnmh-get-new-mail'
     If non-`nil', `nnmh' will read incoming mail.

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


File: gnus,  Node: Mail Folders,  Prev: MH Spool,  Up: Choosing a Mail Backend

Mail Folders
............

   `nnfolder' is a backend 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.

   Virtual server settings:

`nnfolder-directory'
     All the `nnfolder' mail boxes will be stored under this directory.

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

`nnfolder-newsgroups-file'
     The name of the group descriptions file.  *Note Newsgroups File
     Format::.

`nnfolder-get-new-mail'
     If non-`nil', `nnfolder' will read incoming mail.

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


File: gnus,  Node: Other Sources,  Next: Combined Groups,  Prev: Getting Mail,  Up: Select Methods

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".
* Web Searches::          Creating groups from articles that match a string.
* Mail-To-News Gateways:: Posting articles via mail-to-news gateways.


File: gnus,  Node: Directory Groups,  Next: Anything Groups,  Up: Other Sources

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', that most
wonderful of all wonderful Emacs packages.  When I wrote `nndir', I
didn't think much about it--a backend 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 the directory name, `ange-ftp' 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" backend--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

Anything Groups
---------------

   From the `nndir' backend (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-map-file'
     Name of the map files.


File: gnus,  Node: Document Groups,  Next: SOUP,  Prev: Anything Groups,  Up: Other Sources

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.

`forward'
     Forwarded articles.

`mime-digest'
     MIME (RFC 1341) digest format.

`standard-digest'
     The standard (RFC 1153) digest format.

`slack-digest'
     Non-standard digest format--matches most things, but does it badly.

   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 backend, `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', `mmdf',
     `forward', `rfc934', `rfc822-forward', `news', `rnews',
     `mime-digest', `clari-briefs', 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 legal 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

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.

`head-begin-function'
     If present, this should be a function that moves point to the head
     of the article.

`nndoc-head-begin'
     If present, this should be a regexp that matches the head of the
     article.

`nndoc-head-end'
     This should match the end of the head of the article.  It defaults
     to `^$'--the empty line.

`body-begin-function'
     If present, this function should move point to the beginning of
     the body of the article.

`body-begin'
     This should match the beginning of the body of the article.  It
     defaults to `^\n'.

`body-end-function'
     If present, this function should move point to the end of the body
     of the article.

`body-end'
     If present, this should match the end of the body of the article.

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

   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 each
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 legal number.


File: gnus,  Node: SOUP,  Next: Web Searches,  Prev: Document Groups,  Up: Other Sources

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 a 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 contains
          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' backend 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 backend 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

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

SOUP Groups
...........

   `nnsoup' is the backend 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 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 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'.


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

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.

