This is ../info/gnus, produced by makeinfo version 4.0 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,96,97,98,99,2000,2001 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: Slashdot, Next: Ultimate, Prev: Web Searches, Up: Browsing the Web
Slashdot
--------
Slashdot (`http://slashdot.org/') is a popular news site, with
lively discussion following the news articles. `nnslashdot' will let
you read this forum in a convenient manner.
The easiest way to read this source is to put something like the
following in your `.gnus.el' file:
(setq gnus-secondary-select-methods
'((nnslashdot "")))
This will make Gnus query the `nnslashdot' back end for new comments
and groups. The `F' command will subscribe each new news article as a
new Gnus group, and you can read the comments by entering these groups.
(Note that the default subscription method is to subscribe new groups
as zombies. Other methods are available (*note Subscription Methods::).
If you want to remove an old `nnslashdot' group, the `G <DEL>'
command is the most handy tool (*note Foreign Groups::).
When following up to `nnslashdot' comments (or posting new
comments), some light HTMLizations will be performed. In particular,
text quoted with `> ' will be quoted with `blockquote' instead, and
signatures will have `br' added to the end of each line. Other than
that, you can just write HTML directly into the message buffer. Note
that Slashdot filters out some HTML forms.
The following variables can be altered to change its behavior:
`nnslashdot-threaded'
Whether `nnslashdot' should display threaded groups or not. The
default is `t'. To be able to display threads, `nnslashdot' has
to retrieve absolutely all comments in a group upon entry. If a
threaded display is not required, `nnslashdot' will only retrieve
the comments that are actually wanted by the user. Threading is
nicer, but much, much slower than untreaded.
`nnslashdot-login-name'
The login name to use when posting.
`nnslashdot-password'
The password to use when posting.
`nnslashdot-directory'
Where `nnslashdot' will store its files. The default is
`~/News/slashdot/'.
`nnslashdot-active-url'
The URL format string that will be used to fetch the information on
news articles and comments. Default:
`http://slashdot.org/search.pl?section=&min=%d'.
`nnslashdot-comments-url'
The URL format string that will be used to fetch comments. The
default is
`http://slashdot.org/comments.pl?sid=%s&threshold=%d&commentsort=%d&mode=flat&startat=%d'.
`nnslashdot-article-url'
The URL format string that will be used to fetch the news article.
The default is
`http://slashdot.org/article.pl?sid=%s&mode=nocomment'.
`nnslashdot-threshold'
The score threshold. The default is -1.
`nnslashdot-group-number'
The number of old groups, in addition to the ten latest, to keep
updated. The default is 0.
File: gnus, Node: Ultimate, Next: Web Archive, Prev: Slashdot, Up: Browsing the Web
Ultimate
--------
The Ultimate Bulletin Board (`http://www.ultimatebb.com/') is
probably the most popular Web bulletin board system used. It has a
quite regular and nice interface, and it's possible to get the
information Gnus needs to keep groups updated.
The easiest way to get started with `nnultimate' is to say something
like the following in the group buffer: `B nnultimate <RET>
http://www.tcj.com/messboard/ubbcgi/ <RET>'. (Substitute the URL (not
including `Ultimate.cgi' or the like at the end) for a forum you're
interested in; there's quite a list of them on the Ultimate web site.)
Then subscribe to the groups you're interested in from the server
buffer, and read them from the group buffer.
The following `nnultimate' variables can be altered:
`nnultimate-directory'
The directory where `nnultimate' stores its files. The default is
`~/News/ultimate/'.
File: gnus, Node: Web Archive, Next: Customizing w3, 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: Customizing w3, Prev: Web Archive, 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: Other Sources, Next: Combined Groups, Prev: Browsing the Web, 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.
* IMAP:: Using Gnus as a IMAP client.
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.
`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 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' 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, Next: IMAP, 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 `From' 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: IMAP, Prev: Mail-To-News Gateways, Up: Other Sources
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 POP++. Secondly, IMAP is a mail storage
protocol, similar to NNTP being a news storage protocol. (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 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' with a few IMAP servers might
look something like this:
(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))))
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 SSL.
Note that this should be a 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 SSL. (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 `imtest' program.
* "kerberos4:" Connect with Kerberos 4. Requires the `imtest'
program.
* "starttls:" Connect via the STARTTLS extension (similar to
SSL). Requires the library `starttls.el' and program
`starttls'.
* "ssl:" Connect through SSL. Requires OpenSSL (the program
`openssl') or SSLeay (`s_client').
* "shell:" Use a shell command to start an IMAP connection.
* "network:" Plain, TCP/IP network connection.
The `imtest' program is shipped with Cyrus IMAPD. Nnimap supports
both `imtest' version 1.5.x and version 1.6.x. The variable
`imap-kerberos4-program' contains parameters to pass to the
`imtest' program.
For SSL connections, the OpenSSL program is available from
`http://www.openssl.org/'. OpenSSL was formerly known as SSLeay,
and nnimap supports it too. However, 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' contains parameters to pass to
OpenSSL/SSLeay.
For IMAP connections using the `shell' stream, the variable
`imap-shell-program' specifies 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 supports.
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 the external program `imtest'.
* "kerberos4:" Kerberos authentication. Requires the 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 decided that things that
don't exist actually do exist. More specifically, IMAP has the
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 a article in Gnus (with `G <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-authinfo-file'
A file containing credentials used to log in on servers. The
format is (almost) the same as the `ftp' `~/.netrc' file. See
`nntp-authinfo-file' for exact syntax.
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::.
* Menu:
* Splitting in IMAP:: Splitting mail with nnimap.
* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
* Expunging mailboxes:: Equivalent of a "compress mailbox" button.
File: gnus, Node: Splitting in IMAP, Next: Editing IMAP ACLs, 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.
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.spam and everything else in INBOX.private.
The first string may contain `\\DIGIT' 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 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
to where it thinks the article should be split. See
`nnimap-split-fancy'.
The splitting code tries to create mailboxes if it needs too.
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 has 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'.
File: gnus, Node: Editing IMAP ACLs, Next: Expunging mailboxes, Prev: Splitting 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 a ACL for a mailbox, type `G l'
(`gnus-group-edit-nnimap-acl') and you'll be presented with a 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, Prev: Editing IMAP ACLs, Up: IMAP
Expunging mailboxes
...................
If you're using the `never' setting of `nnimap-expunge-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: 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.
File: gnus, Node: Virtual Groups, Next: Kibozed Groups, Up: Combined Groups
Virtual Groups
--------------
An "nnvirtual group" is really nothing more than a collection of
other groups.
For instance, if you are tired of reading many small groups, you can
put them all in one big group, and then grow tired of reading one big,
unwieldy group. The joys of computing!
You specify `nnvirtual' as the method. The address should be a
regexp to match component groups.
All marks in the virtual group will stick to the articles in the
component groups. So if you tick an article in a virtual group, the
article will also be ticked in the component group from whence it came.
(And vice versa--marks from the component groups will also be shown in
the virtual group.)
Here's an example `nnvirtual' method that collects all Andrea Dworkin
newsgroups into one, big, happy newsgroup:
(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
The component groups can be native or foreign; everything should work
smoothly, but if your computer explodes, it was probably my fault.
Collecting the same group from several servers might actually be a
good idea if users have set the Distribution header to limit
distribution. If you would like to read `soc.motss' both from a server
in Japan and a server in Norway, you could use the following as the
group regexp:
"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$"
(Remember, though, that if you're creating the group with `G m', you
shouldn't double the backslashes, and you should leave off the quote
characters at the beginning and the end of the string.)
This should work kinda smoothly--all articles from both groups should
end up in this one, and there should be no duplicates. Threading (and
the rest) will still work as usual, but there might be problems with the
sequence of articles. Sorting on date might be an option here (*note
Selecting a Group::).
One limitation, however--all groups included in a virtual group have
to be alive (i.e., subscribed or unsubscribed). Killed or zombie
groups can't be component groups for `nnvirtual' groups.
If the `nnvirtual-always-rescan' is non-`nil', `nnvirtual' will
always scan groups for unread articles when entering a virtual group.
If this variable is `nil' (which is the default) and you read articles
in a component group after the virtual group has been activated, the
read articles from the component group will show up when you enter the
virtual group. You'll also see this effect if you have two virtual
groups that have a component group in common. If that's the case, you
should set this variable to `t'. Or you can just tap `M-g' on the
virtual group every time before you enter it--it'll have much the same
effect.
`nnvirtual' can have both mail and news groups as component groups.
When responding to articles in `nnvirtual' groups, `nnvirtual' has to
ask the back end of the component group the article comes from whether
it is a news or mail back end. However, when you do a `^', there is
typically no sure way for the component back end to know this, and in
that case `nnvirtual' tells Gnus that the article came from a not-news
back end. (Just to be on the safe side.)
`C-c C-t' in the message buffer will insert the `Newsgroups' line
from the article you respond to in these cases.
File: gnus, Node: Kibozed Groups, Prev: Virtual Groups, Up: Combined Groups
Kibozed Groups
--------------
"Kibozing" is defined by OED as "grepping through (parts of) the
news feed". `nnkiboze' is a back end that will do this for you. Oh
joy! Now you can grind any NNTP server down to a halt with useless
requests! Oh happiness!
To create a kibozed group, use the `G k' command in the group buffer.
The address field of the `nnkiboze' method is, as with `nnvirtual',
a regexp to match groups to be "included" in the `nnkiboze' group.
That's where most similarities between `nnkiboze' and `nnvirtual' end.
In addition to this regexp detailing component groups, an `nnkiboze'
group must have a score file to say what articles are to be included in
the group (*note Scoring::).
You must run `M-x nnkiboze-generate-groups' after creating the
`nnkiboze' groups you want to have. This command will take time. Lots
of time. Oodles and oodles of time. Gnus has to fetch the headers from
all the articles in all the component groups and run them through the
scoring process to determine if there are any articles in the groups
that are to be part of the `nnkiboze' groups.
Please limit the number of component groups by using restrictive
regexps. Otherwise your sysadmin may become annoyed with you, and the
NNTP site may throw you off and never let you back in again. Stranger
things have happened.
`nnkiboze' component groups do not have to be alive--they can be
dead, and they can be foreign. No restrictions.
The generation of an `nnkiboze' group means writing two files in
`nnkiboze-directory', which is `~/News/' by default. One contains the
NOV header lines for all the articles in the group, and the other is an
additional `.newsrc' file to store information on what groups have been
searched through to find component articles.
Articles marked as read in the `nnkiboze' group will have their NOV
lines removed from the NOV file.
File: gnus, Node: Gnus Unplugged, Prev: Combined Groups, Up: Select Methods
Gnus Unplugged
==============
In olden times (ca. February '88), people used to run their
newsreaders on big machines with permanent connections to the net.
News transport was dealt with by news servers, and all the newsreaders
had to do was to read news. Believe it or not.
Nowadays most people read news and mail at home, and use some sort of
modem to connect to the net. To avoid running up huge phone bills, it
would be nice to have a way to slurp down all the news and mail, hang up
the phone, read for several hours, and then upload any responses you
have to make. And then you repeat the procedure.
Of course, you can use news servers for doing this as well. I've
used `inn' together with `slurp', `pop' and `sendmail' for some years,
but doing that's a bore. Moving the news server functionality up to
the newsreader makes sense if you're the only person reading news on a
machine.
Using Gnus as an "offline" newsreader is quite simple.
* First, set up Gnus as you would do if you were running it on a
machine that has full connection to the net. Go ahead. I'll
still be waiting here.
* Then, put the following magical incantation at the end of your
`.gnus.el' file:
(gnus-agentize)
That's it. Gnus is now an "offline" newsreader.
Of course, to use it as such, you have to learn a few new commands.
* Menu:
* Agent Basics:: How it all is supposed to work.
* Agent Categories:: How to tell the Gnus Agent what to download.
* Agent Commands:: New commands for all the buffers.
* Agent Expiry:: How to make old articles go away.
* Agent and IMAP:: How to use the Agent with IMAP.
* Outgoing Messages:: What happens when you post/mail something?
* Agent Variables:: Customizing is fun.
* Example Setup:: An example `.gnus.el' file for offline people.
* Batching Agents:: How to fetch news from a `cron' job.
* Agent Caveats:: What you think it'll do and what it does.