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

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

   This file documents Gnus, the GNU Emacs newsreader.

   Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
     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.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being none, 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: Web Archive,  Next: RSS,  Prev: Ultimate,  Up: Browsing the Web

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

RSS
---

   Some sites have RDF site summary (RSS)
`http://purl.org/rss/1.0/spec'.  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 `nnrss' is to say something like
the following in the group buffer: `B nnrss RET RET', then subscribe
groups.

   The following `nnrss' variables can be altered:

`nnrss-directory'
     The directory where `nnrss' stores its files.  The default is
     `~/News/rss/'.


   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)


File: gnus,  Node: Customizing w3,  Prev: RSS,  Up: Browsing the Web

Customizing w3
--------------

   Gnus uses the url library to fetch web pages and Emacs/w3 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

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

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


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

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 analyses the body to split the article.



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

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

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

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,  Prev: Expunging mailboxes,  Up: IMAP

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

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

     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: Other Sources,  Next: Combined Groups,  Prev: IMAP,  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''.
* 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' (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

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

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.

`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

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.

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


   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

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

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

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

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

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.