This is gnus, produced by makeinfo version 4.6 from gnus.texi. Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License" in the Emacs manual. (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license. Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License" in the Emacs manual. (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Gnus: (gnus). The newsreader Gnus. END-INFO-DIR-ENTRY  File: gnus, Node: Mail Group Commands, Next: Various Summary Stuff, Prev: Tree Display, Up: Summary Buffer Mail Group Commands =================== Some commands only make sense in mail groups. If these commands are invalid in the current group, they will raise a hell and let you know. All these commands (except the expiry and edit commands) use the process/prefix convention (*note Process/Prefix::). `B e' Run all expirable articles in the current group through the expiry process (`gnus-summary-expire-articles'). That is, delete all expirable articles in the group that have been around for a while. (*note Expiring Mail::). `B C-M-e' Delete all the expirable articles in the group (`gnus-summary-expire-articles-now'). This means that *all* articles eligible for expiry in the current group will disappear forever into that big `/dev/null' in the sky. `B DEL' Delete the mail article. This is "delete" as in "delete it from your disk forever and ever, never to return again." Use with caution. (`gnus-summary-delete-article'). `B m' Move the article from one mail group to another (`gnus-summary-move-article'). Marks will be preserved if `gnus-preserve-marks' is non-`nil' (which is the default). `B c' Copy the article from one group (mail group or not) to a mail group (`gnus-summary-copy-article'). Marks will be preserved if `gnus-preserve-marks' is non-`nil' (which is the default). `B B' Crosspost the current article to some other group (`gnus-summary-crosspost-article'). This will create a new copy of the article in the other group, and the Xref headers of the article will be properly updated. `B i' Import an arbitrary file into the current mail newsgroup (`gnus-summary-import-article'). You will be prompted for a file name, a `From' header and a `Subject' header. `B I' Create an empty article in the current mail newsgroups (`gnus-summary-create-article'). You will be prompted for a `From' header and a `Subject' header. `B r' Respool the mail article (`gnus-summary-respool-article'). `gnus-summary-respool-default-method' will be used as the default select method when respooling. This variable is `nil' by default, which means that the current group select method will be used instead. Marks will be preserved if `gnus-preserve-marks' is non-`nil' (which is the default). `B w' `e' Edit the current article (`gnus-summary-edit-article'). To finish editing and make the changes permanent, type `C-c C-c' (`gnus-summary-edit-article-done'). If you give a prefix to the `C-c C-c' command, Gnus won't re-highlight the article. `B q' If you want to re-spool an article, you might be curious as to what group the article will end up in before you do the re-spooling. This command will tell you (`gnus-summary-respool-query'). `B t' Similarly, this command will display all fancy splitting patterns used when respooling, if any (`gnus-summary-respool-trace'). `B p' Some people have a tendency to send you "courtesy" copies when they follow up to articles you have posted. These usually have a `Newsgroups' header in them, but not always. This command (`gnus-summary-article-posted-p') will try to fetch the current article from your news server (or rather, from `gnus-refer-article-method' or `gnus-select-method') and will report back whether it found the article or not. Even if it says that it didn't find the article, it may have been posted anyway--mail propagation is much faster than news propagation, and the news copy may just not have arrived yet. `K E' Encrypt the body of an article (`gnus-article-encrypt-body'). The body is encrypted with the encryption protocol specified by the variable `gnus-article-encrypt-protocol'. If you move (or copy) articles regularly, you might wish to have Gnus suggest where to put the articles. `gnus-move-split-methods' is a variable that uses the same syntax as `gnus-split-methods' (*note Saving Articles::). You may customize that variable to create suggestions you find reasonable. (Note that `gnus-move-split-methods' uses group names where `gnus-split-methods' uses file names.) (setq gnus-move-split-methods '(("^From:.*Lars Magne" "nnml:junk") ("^Subject:.*gnus" "nnfolder:important") (".*" "nnml:misc")))  File: gnus, Node: Various Summary Stuff, Next: Exiting the Summary Buffer, Prev: Mail Group Commands, Up: Summary Buffer Various Summary Stuff ===================== * Menu: * Summary Group Information:: Information oriented commands. * Searching for Articles:: Multiple article commands. * Summary Generation Commands:: * Really Various Summary Commands:: Those pesky non-conformant commands. `gnus-summary-display-while-building' If non-`nil', show and update the summary buffer as it's being built. If `t', update the buffer after every line is inserted. If the value is an integer, N, update the display every N lines. The default is `nil'. `gnus-summary-display-arrow' If non-`nil', display an arrow in the fringe to indicate the current article. `gnus-summary-mode-hook' This hook is called when creating a summary mode buffer. `gnus-summary-generate-hook' This is called as the last thing before doing the threading and the generation of the summary buffer. It's quite convenient for customizing the threading variables based on what data the newsgroup has. This hook is called from the summary buffer after most summary buffer variables have been set. `gnus-summary-prepare-hook' It is called after the summary buffer has been generated. You might use it to, for instance, highlight lines or modify the look of the buffer in some other ungodly manner. I don't care. `gnus-summary-prepared-hook' A hook called as the very last thing after the summary buffer has been generated. `gnus-summary-ignore-duplicates' When Gnus discovers two articles that have the same `Message-ID', it has to do something drastic. No articles are allowed to have the same `Message-ID', but this may happen when reading mail from some sources. Gnus allows you to customize what happens with this variable. If it is `nil' (which is the default), Gnus will rename the `Message-ID' (for display purposes only) and display the article as any other article. If this variable is `t', it won't display the article--it'll be as if it never existed. `gnus-alter-articles-to-read-function' This function, which takes two parameters (the group name and the list of articles to be selected), is called to allow the user to alter the list of articles to be selected. For instance, the following function adds the list of cached articles to the list in one particular group: (defun my-add-cached-articles (group articles) (if (string= group "some.group") (append gnus-newsgroup-cached articles) articles)) `gnus-newsgroup-variables' A list of newsgroup (summary buffer) local variables, or cons of variables and their default expressions to be evalled (when the default values are not `nil'), that should be made global while the summary buffer is active. Note: The default expressions will be evaluated (using function `eval') before assignment to the local variable rather than just assigned to it. If the default expression is the symbol `global', that symbol will not be evaluated but the global value of the local variable will be used instead. These variables can be used to set variables in the group parameters while still allowing them to affect operations done in other buffers. For example: (setq gnus-newsgroup-variables '(message-use-followup-to (gnus-visible-headers . "^From:\\|^Newsgroups:\\|^Subject:\\|^Date:\\|^To:"))) Also *note Group Parameters::.  File: gnus, Node: Summary Group Information, Next: Searching for Articles, Up: Various Summary Stuff Summary Group Information ------------------------- `H f' Try to fetch the FAQ (list of frequently asked questions) for the current group (`gnus-summary-fetch-faq'). Gnus will try to get the FAQ from `gnus-group-faq-directory', which is usually a directory on a remote machine. This variable can also be a list of directories. In that case, giving a prefix to this command will allow you to choose between the various sites. `ange-ftp' or `efs' will probably be used for fetching the file. `H d' Give a brief description of the current group (`gnus-summary-describe-group'). If given a prefix, force rereading the description from the server. `H h' Give an extremely brief description of the most important summary keystrokes (`gnus-summary-describe-briefly'). `H i' Go to the Gnus info node (`gnus-info-find-node').  File: gnus, Node: Searching for Articles, Next: Summary Generation Commands, Prev: Summary Group Information, Up: Various Summary Stuff Searching for Articles ---------------------- `M-s' Search through all subsequent (raw) articles for a regexp (`gnus-summary-search-article-forward'). `M-r' Search through all previous (raw) articles for a regexp (`gnus-summary-search-article-backward'). `&' This command will prompt you for a header, a regular expression to match on this field, and a command to be executed if the match is made (`gnus-summary-execute-command'). If the header is an empty string, the match is done on the entire article. If given a prefix, search backward instead. For instance, `& RET some.*string RET #' will put the process mark on all articles that have heads or bodies that match `some.*string'. `M-&' Perform any operation on all articles that have been marked with the process mark (`gnus-summary-universal-argument').  File: gnus, Node: Summary Generation Commands, Next: Really Various Summary Commands, Prev: Searching for Articles, Up: Various Summary Stuff Summary Generation Commands --------------------------- `Y g' Regenerate the current summary buffer (`gnus-summary-prepare'). `Y c' Pull all cached articles (for the current group) into the summary buffer (`gnus-summary-insert-cached-articles'). `Y d' Pull all dormant articles (for the current group) into the summary buffer (`gnus-summary-insert-dormant-articles').  File: gnus, Node: Really Various Summary Commands, Prev: Summary Generation Commands, Up: Various Summary Stuff Really Various Summary Commands ------------------------------- `A D' `C-d' If the current article is a collection of other articles (for instance, a digest), you might use this command to enter a group based on the that article (`gnus-summary-enter-digest-group'). Gnus will try to guess what article type is currently displayed unless you give a prefix to this command, which forces a "digest" interpretation. Basically, whenever you see a message that is a collection of other messages of some format, you `C-d' and read these messages in a more convenient fashion. `C-M-d' This command is very similar to the one above, but lets you gather several documents into one biiig group (`gnus-summary-read-document'). It does this by opening several `nndoc' groups for each document, and then opening an `nnvirtual' group on top of these `nndoc' groups. This command understands the process/prefix convention (*note Process/Prefix::). `C-t' Toggle truncation of summary lines (`gnus-summary-toggle-truncation'). This will probably confuse the line centering function in the summary buffer, so it's not a good idea to have truncation switched off while reading articles. `=' Expand the summary buffer window (`gnus-summary-expand-window'). If given a prefix, force an `article' window configuration. `C-M-e' Edit the group parameters (*note Group Parameters::) of the current group (`gnus-summary-edit-parameters'). `C-M-a' Customize the group parameters (*note Group Parameters::) of the current group (`gnus-summary-customize-parameters').  File: gnus, Node: Exiting the Summary Buffer, Next: Crosspost Handling, Prev: Various Summary Stuff, Up: Summary Buffer Exiting the Summary Buffer ========================== Exiting from the summary buffer will normally update all info on the group and return you to the group buffer. `Z Z' `Z Q' `q' Exit the current group and update all information on the group (`gnus-summary-exit'). `gnus-summary-prepare-exit-hook' is called before doing much of the exiting, which calls `gnus-summary-expire-articles' by default. `gnus-summary-exit-hook' is called after finishing the exit process. `gnus-group-no-more-groups-hook' is run when returning to group mode having no more (unread) groups. `Z E' `Q' Exit the current group without updating any information on the group (`gnus-summary-exit-no-update'). `Z c' `c' Mark all unticked articles in the group as read and then exit (`gnus-summary-catchup-and-exit'). `Z C' Mark all articles, even the ticked ones, as read and then exit (`gnus-summary-catchup-all-and-exit'). `Z n' Mark all articles as read and go to the next group (`gnus-summary-catchup-and-goto-next-group'). `Z R' `C-x C-s' Exit this group, and then enter it again (`gnus-summary-reselect-current-group'). If given a prefix, select all articles, both read and unread. `Z G' `M-g' Exit the group, check for new articles in the group, and select the group (`gnus-summary-rescan-group'). If given a prefix, select all articles, both read and unread. `Z N' Exit the group and go to the next group (`gnus-summary-next-group'). `Z P' Exit the group and go to the previous group (`gnus-summary-prev-group'). `Z s' Save the current number of read/marked articles in the dribble buffer and then save the dribble buffer (`gnus-summary-save-newsrc'). If given a prefix, also save the `.newsrc' file(s). Using this command will make exit without updating (the `Q' command) worthless. `gnus-exit-group-hook' is called when you exit the current group with an "updating" exit. For instance `Q' (`gnus-summary-exit-no-update') does not call this hook. If you're in the habit of exiting groups, and then changing your mind about it, you might set `gnus-kill-summary-on-exit' to `nil'. If you do that, Gnus won't kill the summary buffer when you exit it. (Quelle surprise!) Instead it will change the name of the buffer to something like `*Dead Summary ... *' and install a minor mode called `gnus-dead-summary-mode'. Now, if you switch back to this buffer, you'll find that all keys are mapped to a function called `gnus-summary-wake-up-the-dead'. So tapping any keys in a dead summary buffer will result in a live, normal summary buffer. There will never be more than one dead summary buffer at any one time. The data on the current group will be updated (which articles you have read, which articles you have replied to, etc.) when you exit the summary buffer. If the `gnus-use-cross-reference' variable is `t' (which is the default), articles that are cross-referenced to this group and are marked as read, will also be marked as read in the other subscribed groups they were cross-posted to. If this variable is neither `nil' nor `t', the article will be marked as read in both subscribed and unsubscribed groups (*note Crosspost Handling::).  File: gnus, Node: Crosspost Handling, Next: Duplicate Suppression, Prev: Exiting the Summary Buffer, Up: Summary Buffer Crosspost Handling ================== Marking cross-posted articles as read ensures that you'll never have to read the same article more than once. Unless, of course, somebody has posted it to several groups separately. Posting the same article to several groups (not cross-posting) is called "spamming", and you are by law required to send nasty-grams to anyone who perpetrates such a heinous crime. You may want to try NoCeM handling to filter out spam (*note NoCeM::). Remember: Cross-posting is kinda ok, but posting the same article separately to several groups is not. Massive cross-posting (aka. "velveeta") is to be avoided at all costs, and you can even use the `gnus-summary-mail-crosspost-complaint' command to complain about excessive crossposting (*note Summary Mail Commands::). One thing that may cause Gnus to not do the cross-posting thing correctly is if you use an NNTP server that supports XOVER (which is very nice, because it speeds things up considerably) which does not include the `Xref' header in its NOV lines. This is Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing even with XOVER by registering the `Xref' lines of all articles you actually read, but if you kill the articles, or just mark them as read without reading them, Gnus will not get a chance to snoop the `Xref' lines out of these articles, and will be unable to use the cross reference mechanism. To check whether your NNTP server includes the `Xref' header in its overview files, try `telnet your.nntp.server nntp', `MODE READER' on `inn' servers, and then say `LIST overview.fmt'. This may not work, but if it does, and the last line you get does not read `Xref:full', then you should shout and whine at your news admin until she includes the `Xref' header in the overview files. If you want Gnus to get the `Xref's right all the time, you have to set `gnus-nov-is-evil' to `t', which slows things down considerably. C'est la vie. For an alternative approach, *note Duplicate Suppression::.  File: gnus, Node: Duplicate Suppression, Next: Security, Prev: Crosspost Handling, Up: Summary Buffer Duplicate Suppression ===================== By default, Gnus tries to make sure that you don't have to read the same article more than once by utilizing the crossposting mechanism (*note Crosspost Handling::). However, that simple and efficient approach may not work satisfactory for some users for various reasons. 1. The NNTP server may fail to generate the `Xref' header. This is evil and not very common. 2. The NNTP server may fail to include the `Xref' header in the `.overview' data bases. This is evil and all too common, alas. 3. You may be reading the same group (or several related groups) from different NNTP servers. 4. You may be getting mail that duplicates articles posted to groups. I'm sure there are other situations where `Xref' handling fails as well, but these four are the most common situations. If, and only if, `Xref' handling fails for you, then you may consider switching on "duplicate suppression". If you do so, Gnus will remember the `Message-ID's of all articles you have read or otherwise marked as read, and then, as if by magic, mark them as read all subsequent times you see them--in _all_ groups. Using this mechanism is quite likely to be somewhat inefficient, but not overly so. It's certainly preferable to reading the same articles more than once. Duplicate suppression is not a very subtle instrument. It's more like a sledge hammer than anything else. It works in a very simple fashion--if you have marked an article as read, it adds this Message-ID to a cache. The next time it sees this Message-ID, it will mark the article as read with the `M' mark. It doesn't care what group it saw the article in. `gnus-suppress-duplicates' If non-`nil', suppress duplicates. `gnus-save-duplicate-list' If non-`nil', save the list of duplicates to a file. This will make startup and shutdown take longer, so the default is `nil'. However, this means that only duplicate articles read in a single Gnus session are suppressed. `gnus-duplicate-list-length' This variable says how many `Message-ID's to keep in the duplicate suppression list. The default is 10000. `gnus-duplicate-file' The name of the file to store the duplicate suppression list in. The default is `~/News/suppression'. If you have a tendency to stop and start Gnus often, setting `gnus-save-duplicate-list' to `t' is probably a good idea. If you leave Gnus running for weeks on end, you may have it `nil'. On the other hand, saving the list makes startup and shutdown much slower, so that means that if you stop and start Gnus often, you should set `gnus-save-duplicate-list' to `nil'. Uhm. I'll leave this up to you to figure out, I think.  File: gnus, Node: Security, Next: Mailing List, Prev: Duplicate Suppression, Up: Summary Buffer Security ======== Gnus is able to verify signed messages or decrypt encrypted messages. The formats that are supported are PGP, PGP/MIME and S/MIME, however you need some external programs to get things to work: 1. To handle PGP and PGP/MIME messages, you have to install an OpenPGP implementation such as GnuPG. The Lisp interface to GnuPG included with Gnus is called PGG (*note PGG: (pgg)Top.), but Mailcrypt and gpg.el are also supported. 2. To handle S/MIME message, you need to install OpenSSL. OpenSSL 0.9.6 or newer is recommended. More information on how to set things up can be found in the message manual (*note Security: (message)Security.). `mm-verify-option' Option of verifying signed parts. `never', not verify; `always', always verify; `known', only verify known protocols. Otherwise, ask user. `mm-decrypt-option' Option of decrypting encrypted parts. `never', no decryption; `always', always decrypt; `known', only decrypt known protocols. Otherwise, ask user. `mml1991-use' Symbol indicating elisp interface to OpenPGP implementation for PGP messages. The default is `pgg', but `mailcrypt' and `gpg' are also supported although deprecated. `mml2015-use' Symbol indicating elisp interface to OpenPGP implementation for PGP/MIME messages. The default is `pgg', but `mailcrypt' and `gpg' are also supported although deprecated. Snarfing OpenPGP keys (i.e., importing keys from articles into your key ring) is not supported explicitly through a menu item or command, rather Gnus do detect and label keys as `application/pgp-keys', allowing you to specify whatever action you think is appropriate through the usual MIME infrastructure. You can use a `~/.mailcap' entry (*note mailcap: (emacs-mime)mailcap.) such as the following to import keys using GNU Privacy Guard when you click on the MIME button (*note Using MIME::). application/pgp-keys; gpg --import --interactive --verbose; needsterminal This happens to also be the default action defined in `mailcap-mime-data'.  File: gnus, Node: Mailing List, Prev: Security, Up: Summary Buffer Mailing List ============ Gnus understands some mailing list fields of RFC 2369. To enable it, add a `to-list' group parameter (*note Group Parameters::), possibly using `A M' (`gnus-mailing-list-insinuate') in the summary buffer. That enables the following commands to the summary buffer: `C-c C-n h' Send a message to fetch mailing list help, if List-Help field exists. `C-c C-n s' Send a message to subscribe the mailing list, if List-Subscribe field exists. `C-c C-n u' Send a message to unsubscribe the mailing list, if List-Unsubscribe field exists. `C-c C-n p' Post to the mailing list, if List-Post field exists. `C-c C-n o' Send a message to the mailing list owner, if List-Owner field exists. `C-c C-n a' Browse the mailing list archive, if List-Archive field exists.  File: gnus, Node: Article Buffer, Next: Composing Messages, Prev: Summary Buffer, Up: Top Article Buffer ************** The articles are displayed in the article buffer, of which there is only one. All the summary buffers share the same article buffer unless you tell Gnus otherwise. * Menu: * Hiding Headers:: Deciding what headers should be displayed. * Using MIME:: Pushing articles through MIME before reading them. * Customizing Articles:: Tailoring the look of the articles. * Article Keymap:: Keystrokes available in the article buffer. * Misc Article:: Other stuff.  File: gnus, Node: Hiding Headers, Next: Using MIME, Up: Article Buffer Hiding Headers ============== The top section of each article is the "head". (The rest is the "body", but you may have guessed that already.) There is a lot of useful information in the head: the name of the person who wrote the article, the date it was written and the subject of the article. That's well and nice, but there's also lots of information most people do not want to see--what systems the article has passed through before reaching you, the `Message-ID', the `References', etc. ad nauseam--and you'll probably want to get rid of some of those lines. If you want to keep all those lines in the article buffer, you can set `gnus-show-all-headers' to `t'. Gnus provides you with two variables for sifting headers: `gnus-visible-headers' If this variable is non-`nil', it should be a regular expression that says what headers you wish to keep in the article buffer. All headers that do not match this variable will be hidden. For instance, if you only want to see the name of the person who wrote the article and the subject, you'd say: (setq gnus-visible-headers "^From:\\|^Subject:") This variable can also be a list of regexps to match headers to remain visible. `gnus-ignored-headers' This variable is the reverse of `gnus-visible-headers'. If this variable is set (and `gnus-visible-headers' is `nil'), it should be a regular expression that matches all lines that you want to hide. All lines that do not match this variable will remain visible. For instance, if you just want to get rid of the `References' line and the `Xref' line, you might say: (setq gnus-ignored-headers "^References:\\|^Xref:") This variable can also be a list of regexps to match headers to be removed. Note that if `gnus-visible-headers' is non-`nil', this variable will have no effect. Gnus can also sort the headers for you. (It does this by default.) You can control the sorting by setting the `gnus-sorted-header-list' variable. It is a list of regular expressions that says in what order the headers are to be displayed. For instance, if you want the name of the author of the article first, and then the subject, you might say something like: (setq gnus-sorted-header-list '("^From:" "^Subject:")) Any headers that are to remain visible, but are not listed in this variable, will be displayed in random order after all the headers listed in this variable. You can hide further boring headers by setting `gnus-treat-hide-boring-headers' to `head'. What this function does depends on the `gnus-boring-article-headers' variable. It's a list, but this list doesn't actually contain header names. Instead it lists various "boring conditions" that Gnus can check and remove from sight. These conditions are: `empty' Remove all empty headers. `followup-to' Remove the `Followup-To' header if it is identical to the `Newsgroups' header. `reply-to' Remove the `Reply-To' header if it lists the same addresses as the `From' header, or if the `broken-reply-to' group parameter is set. `newsgroups' Remove the `Newsgroups' header if it only contains the current group name. `to-address' Remove the `To' header if it only contains the address identical to the current group's `to-address' parameter. `to-list' Remove the `To' header if it only contains the address identical to the current group's `to-list' parameter. `cc-list' Remove the `CC' header if it only contains the address identical to the current group's `to-list' parameter. `date' Remove the `Date' header if the article is less than three days old. `long-to' Remove the `To' header if it is very long. `many-to' Remove all `To' headers if there are more than one. To include these three elements, you could say something like: (setq gnus-boring-article-headers '(empty followup-to reply-to)) This is also the default value for this variable.  File: gnus, Node: Using MIME, Next: Customizing Articles, Prev: Hiding Headers, Up: Article Buffer Using MIME ========== Mime is a standard for waving your hands through the air, aimlessly, while people stand around yawning. MIME, however, is a standard for encoding your articles, aimlessly, while all newsreaders die of fear. MIME may specify what character set the article uses, the encoding of the characters, and it also makes it possible to embed pictures and other naughty stuff in innocent-looking articles. Gnus pushes MIME articles through `gnus-display-mime-function' to display the MIME parts. This is `gnus-display-mime' by default, which creates a bundle of clickable buttons that can be used to display, save and manipulate the MIME objects. The following commands are available when you have placed point over a MIME button: `RET (Article)' `BUTTON-2 (Article)' Toggle displaying of the MIME object (`gnus-article-press-button'). If built-in viewers can not display the object, Gnus resorts to external viewers in the `mailcap' files. If a viewer has the `copiousoutput' specification, the object is displayed inline. `M-RET (Article)' `v (Article)' Prompt for a method, and then view the MIME object using this method (`gnus-mime-view-part'). `t (Article)' View the MIME object as if it were a different MIME media type (`gnus-mime-view-part-as-type'). `C (Article)' Prompt for a charset, and then view the MIME object using this charset (`gnus-mime-view-part-as-charset'). `o (Article)' Prompt for a file name, and then save the MIME object (`gnus-mime-save-part'). `C-o (Article)' Prompt for a file name, then save the MIME object and strip it from the article. Then proceed to article editing, where a reasonable suggestion is being made on how the altered article should look like. The stripped MIME object will be referred via the message/external-body MIME type. (`gnus-mime-save-part-and-strip'). `r (Article)' Prompt for a file name, replace the MIME object with an external body refering to the file via the message/external-body MIME type. (`gnus-mime-replace-part'). `d (Article)' Delete the MIME object from the article and replace it with some information about the removed MIME object (`gnus-mime-delete-part'). `c (Article)' Copy the MIME object to a fresh buffer and display this buffer (`gnus-mime-copy-part'). If given a prefix, copy the raw contents without decoding. If given a numerical prefix, you can do semi-manual charset stuff (see `gnus-summary-show-article-charset-alist' in *Note Paging the Article::). Compressed files like `.gz' and `.bz2' are automatically decompressed if `auto-compression-mode' is enabled (*note Accessing Compressed Files: (emacs)Compressed Files.). `p (Article)' Print the MIME object (`gnus-mime-print-part'). This command respects the `print=' specifications in the `.mailcap' file. `i (Article)' Insert the contents of the MIME object into the buffer (`gnus-mime-inline-part') as text/plain. If given a prefix, insert the raw contents without decoding. If given a numerical prefix, you can do semi-manual charset stuff (see `gnus-summary-show-article-charset-alist' in *Note Paging the Article::). Compressed files like `.gz' and `.bz2' are automatically decompressed depending on `jka-compr' regardless of `auto-compression-mode' (*note Accessing Compressed Files: (emacs)Compressed Files.). `E (Article)' View the MIME object with an internal viewer. If no internal viewer is available, use an external viewer (`gnus-mime-view-part-internally'). `e (Article)' View the MIME object with an external viewer. (`gnus-mime-view-part-externally'). `| (Article)' Output the MIME object to a process (`gnus-mime-pipe-part'). `. (Article)' Interactively run an action on the MIME object (`gnus-mime-action-on-part'). Gnus will display some MIME objects automatically. The way Gnus determines which parts to do this with is described in the Emacs MIME manual. It might be best to just use the toggling functions from the article buffer to avoid getting nasty surprises. (For instance, you enter the group `alt.sing-a-long' and, before you know it, MIME has decoded the sound file in the article and some horrible sing-a-long song comes screaming out your speakers, and you can't find the volume button, because there isn't one, and people are starting to look at you, and you try to stop the program, but you can't, and you can't find the program to control the volume, and everybody else in the room suddenly decides to look at you disdainfully, and you'll feel rather stupid.) Any similarity to real events and people is purely coincidental. Ahem. Also *note MIME Commands::.  File: gnus, Node: Customizing Articles, Next: Article Keymap, Prev: Using MIME, Up: Article Buffer Customizing Articles ==================== A slew of functions for customizing how the articles are to look like exist. You can call these functions interactively (*note Article Washing::), or you can have them called automatically when you select the articles. To have them called automatically, you should set the corresponding "treatment" variable. For instance, to have headers hidden, you'd set `gnus-treat-hide-headers'. Below is a list of variables that can be set, but first we discuss the values these variables can have. Note: Some values, while valid, make little sense. Check the list below for sensible values. 1. `nil': Don't do this treatment. 2. `t': Do this treatment on all body parts. 3. `head': Do the treatment on the headers. 4. `last': Do this treatment on the last part. 5. An integer: Do this treatment on all body parts that have a length less than this number. 6. A list of strings: Do this treatment on all body parts that are in articles that are read in groups that have names that match one of the regexps in the list. 7. A list where the first element is not a string: The list is evaluated recursively. The first element of the list is a predicate. The following predicates are recognized: `or', `and', `not' and `typep'. Here's an example: (or last (typep "text/x-vcard")) You may have noticed that the word "part" is used here. This refers to the fact that some messages are MIME multipart articles that may be divided into several parts. Articles that are not multiparts are considered to contain just a single part. Are the treatments applied to all sorts of multipart parts? Yes, if you want to, but by default, only `text/plain' parts are given the treatment. This is controlled by the `gnus-article-treat-types' variable, which is a list of regular expressions that are matched to the type of the part. This variable is ignored if the value of the controlling variable is a predicate list, as described above. The following treatment options are available. The easiest way to customize this is to examine the `gnus-article-treat' customization group. Values in parenthesis are suggested sensible values. Others are possible but those listed are probably sufficient for most people. `gnus-treat-buttonize (t, integer)' `gnus-treat-buttonize-head (head)' *Note Article Buttons::. `gnus-treat-capitalize-sentences (t, integer)' `gnus-treat-overstrike (t, integer)' `gnus-treat-strip-cr (t, integer)' `gnus-treat-strip-headers-in-body (t, integer)' `gnus-treat-strip-leading-blank-lines (t, integer)' `gnus-treat-strip-multiple-blank-lines (t, integer)' `gnus-treat-strip-pem (t, last, integer)' `gnus-treat-strip-trailing-blank-lines (t, last, integer)' `gnus-treat-unsplit-urls (t, integer)' `gnus-treat-wash-html (t, integer)' *Note Article Washing::. `gnus-treat-date-english (head)' `gnus-treat-date-iso8601 (head)' `gnus-treat-date-lapsed (head)' `gnus-treat-date-local (head)' `gnus-treat-date-original (head)' `gnus-treat-date-user-defined (head)' `gnus-treat-date-ut (head)' *Note Article Date::. `gnus-treat-from-picon (head)' `gnus-treat-mail-picon (head)' `gnus-treat-newsgroups-picon (head)' *Note Picons::. `gnus-treat-display-smileys (t, integer)' `gnus-treat-body-boundary (head)' Adds a delimiter between header and body, the string used as delimiter is controlled by `gnus-body-boundary-delimiter'. *Note Smileys::. `gnus-treat-display-x-face (head)' *Note X-Face::. `gnus-treat-display-face (head)' *Note Face::. `gnus-treat-emphasize (t, head, integer)' `gnus-treat-fill-article (t, integer)' `gnus-treat-fill-long-lines (t, integer)' `gnus-treat-hide-boring-headers (head)' `gnus-treat-hide-citation (t, integer)' `gnus-treat-hide-citation-maybe (t, integer)' `gnus-treat-hide-headers (head)' `gnus-treat-hide-signature (t, last)' `gnus-treat-strip-banner (t, last)' `gnus-treat-strip-list-identifiers (head)' *Note Article Hiding::. `gnus-treat-highlight-citation (t, integer)' `gnus-treat-highlight-headers (head)' `gnus-treat-highlight-signature (t, last, integer)' *Note Article Highlighting::. `gnus-treat-play-sounds' `gnus-treat-translate' `gnus-treat-ansi-sequences (t)' `gnus-treat-x-pgp-sig (head)' `gnus-treat-unfold-headers (head)' `gnus-treat-fold-headers (head)' `gnus-treat-fold-newsgroups (head)' `gnus-treat-leading-whitespace (head)' *Note Article Header::. You can, of course, write your own functions to be called from `gnus-part-display-hook'. The functions are called narrowed to the part, and you can do anything you like, pretty much. There is no information that you have to keep in the buffer--you can change everything.  File: gnus, Node: Article Keymap, Next: Misc Article, Prev: Customizing Articles, Up: Article Buffer Article Keymap ============== Most of the keystrokes in the summary buffer can also be used in the article buffer. They should behave as if you typed them in the summary buffer, which means that you don't actually have to have a summary buffer displayed while reading. You can do it all from the article buffer. A few additional keystrokes are available: `SPACE' Scroll forwards one page (`gnus-article-next-page'). This is exactly the same as `h SPACE h'. `DEL' Scroll backwards one page (`gnus-article-prev-page'). This is exactly the same as `h DEL h'. `C-c ^' If point is in the neighborhood of a `Message-ID' and you press `C-c ^', Gnus will try to get that article from the server (`gnus-article-refer-article'). `C-c C-m' Send a reply to the address near point (`gnus-article-mail'). If given a prefix, include the mail. `s' Reconfigure the buffers so that the summary buffer becomes visible (`gnus-article-show-summary'). `?' Give a very brief description of the available keystrokes (`gnus-article-describe-briefly'). `TAB' Go to the next button, if any (`gnus-article-next-button'). This only makes sense if you have buttonizing turned on. `M-TAB' Go to the previous button, if any (`gnus-article-prev-button'). `R' Send a reply to the current article and yank the current article (`gnus-article-reply-with-original'). If given a prefix, make a wide reply. If the region is active, only yank the text in the region. `F' Send a followup to the current article and yank the current article (`gnus-article-followup-with-original'). If given a prefix, make a wide reply. If the region is active, only yank the text in the region.  File: gnus, Node: Misc Article, Prev: Article Keymap, Up: Article Buffer Misc Article ============ `gnus-single-article-buffer' If non-`nil', use the same article buffer for all the groups. (This is the default.) If `nil', each group will have its own article buffer. `gnus-article-decode-hook' Hook used to decode MIME articles. The default value is `(article-decode-charset article-decode-encoded-words)' `gnus-article-prepare-hook' This hook is called right after the article has been inserted into the article buffer. It is mainly intended for functions that do something depending on the contents; it should probably not be used for changing the contents of the article buffer. `gnus-article-mode-hook' Hook called in article mode buffers. `gnus-article-mode-syntax-table' Syntax table used in article buffers. It is initialized from `text-mode-syntax-table'. `gnus-article-over-scroll' If non-`nil', allow scrolling the article buffer even when there no more new text to scroll in. The default is `nil'. `gnus-article-mode-line-format' This variable is a format string along the same lines as `gnus-summary-mode-line-format' (*note Summary Buffer Mode Line::). It accepts the same format specifications as that variable, with two extensions: `w' The "wash status" of the article. This is a short string with one character for each possible article wash operation that may have been performed. The characters and their meaning: `c' Displayed when cited text may be hidden in the article buffer. `h' Displayed when headers are hidden in the article buffer. `p' Displayed when article is digitally signed or encrypted, and Gnus has hidden the security headers. (N.B. does not tell anything about security status, i.e. good or bad signature.) `s' Displayed when the signature has been hidden in the Article buffer. `o' Displayed when Gnus has treated overstrike characters in the article buffer. `e' Displayed when Gnus has treated emphasised strings in the article buffer. `m' The number of MIME parts in the article. `gnus-break-pages' Controls whether "page breaking" is to take place. If this variable is non-`nil', the articles will be divided into pages whenever a page delimiter appears in the article. If this variable is `nil', paging will not be done. `gnus-page-delimiter' This is the delimiter mentioned above. By default, it is `^L' (formfeed). `gnus-use-idna' This variable controls whether Gnus performs IDNA decoding of internationalized domain names inside `From', `To' and `Cc' headers. *Note IDNA: (message)IDNA, for how to compose such messages. This requires GNU Libidn (http://www.gnu.org/software/libidn/), and this variable is only enabled if you have installed it.  File: gnus, Node: Composing Messages, Next: Select Methods, Prev: Article Buffer, Up: Top Composing Messages ****************** All commands for posting and mailing will put you in a message buffer where you can edit the article all you like, before you send the article by pressing `C-c C-c'. *Note Overview: (message)Top. Where the message will be posted/mailed to depends on your setup (*note Posting Server::). * Menu: * Mail:: Mailing and replying. * Posting Server:: What server should you post and mail via? * POP before SMTP:: You cannot send a mail unless you read a mail. * Mail and Post:: Mailing and posting at the same time. * Archived Messages:: Where Gnus stores the messages you've sent. * Posting Styles:: An easier way to specify who you are. * Drafts:: Postponing messages and rejected messages. * Rejected Articles:: What happens if the server doesn't like your article? * Signing and encrypting:: How to compose secure messages. Also *note Canceling and Superseding:: for information on how to remove articles you shouldn't have posted.  File: gnus, Node: Mail, Next: Posting Server, Up: Composing Messages Mail ==== Variables for customizing outgoing mail: `gnus-uu-digest-headers' List of regexps to match headers included in digested messages. The headers will be included in the sequence they are matched. If `nil' include all headers. `gnus-add-to-list' If non-`nil', add a `to-list' group parameter to mail groups that have none when you do a `a'. `gnus-confirm-mail-reply-to-news' If non-`nil', Gnus will ask you for a confirmation when you are about to reply to news articles by mail. If it is `nil', nothing interferes in what you want to do. This can also be a function receiving the group name as the only parameter which should return non-`nil' if a confirmation is needed, or a regular expression matching group names, where confirmation should be asked for. If you find yourself never wanting to reply to mail, but occasionally press `R' anyway, this variable might be for you. `gnus-confirm-treat-mail-like-news' If non-`nil', Gnus also requests confirmation according to `gnus-confirm-mail-reply-to-news' when replying to mail. This is useful for treating mailing lists like newsgroups.  File: gnus, Node: Posting Server, Next: POP before SMTP, Prev: Mail, Up: Composing Messages Posting Server ============== When you press those magical `C-c C-c' keys to ship off your latest (extremely intelligent, of course) article, where does it go? Thank you for asking. I hate you. It can be quite complicated. When posting news, Message usually invokes `message-send-news' (*note News Variables: (message)News Variables.). Normally, Gnus will post using the same select method as you're reading from (which might be convenient if you're reading lots of groups from different private servers). However. If the server you're reading from doesn't allow posting, just reading, you probably want to use some other server to post your (extremely intelligent and fabulously interesting) articles. You can then set the `gnus-post-method' to some other method: (setq gnus-post-method '(nnspool "")) Now, if you've done this, and then this server rejects your article, or this server is down, what do you do then? To override this variable you can use a non-zero prefix to the `C-c C-c' command to force using the "current" server, to get back the default behavior, for posting. If you give a zero prefix (i.e., `C-u 0 C-c C-c') to that command, Gnus will prompt you for what method to use for posting. You can also set `gnus-post-method' to a list of select methods. If that's the case, Gnus will always prompt you for what method to use for posting. Finally, if you want to always post using the native select method, you can set this variable to `native'. When sending mail, Message invokes `message-send-mail-function'. The default function, `message-send-mail-with-sendmail', pipes your article to the `sendmail' binary for further queuing and sending. When your local system is not configured for sending mail using `sendmail', and you have access to a remote SMTP server, you can set `message-send-mail-function' to `smtpmail-send-it' and make sure to setup the `smtpmail' package correctly. An example: (setq message-send-mail-function 'smtpmail-send-it smtpmail-default-smtp-server "YOUR SMTP HOST") To the thing similar to this, there is `message-smtpmail-send-it'. It is useful if your ISP requires the POP-before-SMTP authentication. *Note POP before SMTP::. Other possible choices for `message-send-mail-function' includes `message-send-mail-with-mh', `message-send-mail-with-qmail', and `feedmail-send-it'.  File: gnus, Node: POP before SMTP, Next: Mail and Post, Prev: Posting Server, Up: Composing Messages POP before SMTP =============== Does your ISP require the POP-before-SMTP authentication? It is whether you need to connect to the POP mail server within a certain time before sending mails. If so, there is a convenient way. To do that, put the following lines in your `~/.gnus.el' file: (setq message-send-mail-function 'message-smtpmail-send-it) (add-hook 'message-send-mail-hook 'mail-source-touch-pop) It means to let Gnus connect to the POP mail server in advance whenever you send a mail. The `mail-source-touch-pop' function does only a POP authentication according to the value of `mail-sources' without fetching mails, just before sending a mail. Note that you have to use `message-smtpmail-send-it' which runs `message-send-mail-hook' rather than `smtpmail-send-it' and set the value of `mail-sources' for a POP connection correctly. *Note Mail Sources::. If you have two or more POP mail servers set in `mail-sources', you may want to specify one of them to `mail-source-primary-source' as the POP mail server to be used for the POP-before-SMTP authentication. If it is your primary POP mail server (i.e., you are fetching mails mainly from that server), you can set it permanently as follows: (setq mail-source-primary-source '(pop :server "pop3.mail.server" :password "secret")) Otherwise, bind it dynamically only when performing the POP-before-SMTP authentication as follows: (add-hook 'message-send-mail-hook (lambda () (let ((mail-source-primary-source '(pop :server "pop3.mail.server" :password "secret"))) (mail-source-touch-pop))))  File: gnus, Node: Mail and Post, Next: Archived Messages, Prev: POP before SMTP, Up: Composing Messages Mail and Post ============= Here's a list of variables relevant to both mailing and posting: `gnus-mailing-list-groups' If your news server offers groups that are really mailing lists gatewayed to the NNTP server, you can read those groups without problems, but you can't post/followup to them without some difficulty. One solution is to add a `to-address' to the group parameters (*note Group Parameters::). An easier thing to do is set the `gnus-mailing-list-groups' to a regexp that matches the groups that really are mailing lists. Then, at least, followups to the mailing lists will work most of the time. Posting to these groups (`a') is still a pain, though. `gnus-user-agent' This variable controls which information should be exposed in the User-Agent header. It can be one of the symbols `gnus' (show only Gnus version), `emacs-gnus' (show only Emacs and Gnus versions), `emacs-gnus-config' (same as `emacs-gnus' plus system configuration), `emacs-gnus-type' (same as `emacs-gnus' plus system type) or a custom string. If you set it to a string, be sure to use a valid format, see RFC 2616. You may want to do spell-checking on messages that you send out. Or, if you don't want to spell-check by hand, you could add automatic spell-checking via the `ispell' package: (add-hook 'message-send-hook 'ispell-message) If you want to change the `ispell' dictionary based on what group you're in, you could say something like the following: (add-hook 'gnus-select-group-hook (lambda () (cond ((string-match "^de\\." (gnus-group-real-name gnus-newsgroup-name)) (ispell-change-dictionary "deutsch")) (t (ispell-change-dictionary "english"))))) Modify to suit your needs.  File: gnus, Node: Archived Messages, Next: Posting Styles, Prev: Mail and Post, Up: Composing Messages Archived Messages ================= Gnus provides a few different methods for storing the mail and news you send. The default method is to use the "archive virtual server" to store the messages. If you want to disable this completely, the `gnus-message-archive-group' variable should be `nil', which is the default. For archiving interesting messages in a group you read, see the `B c' (`gnus-summary-copy-article') command (*note Mail Group Commands::). `gnus-message-archive-method' says what virtual server Gnus is to use to store sent messages. The default is: (nnfolder "archive" (nnfolder-directory "~/Mail/archive") (nnfolder-active-file "~/Mail/archive/active") (nnfolder-get-new-mail nil) (nnfolder-inhibit-expiry t)) You can, however, use any mail select method (`nnml', `nnmbox', etc.). `nnfolder' is a quite likable select method for doing this sort of thing, though. If you don't like the default directory chosen, you could say something like: (setq gnus-message-archive-method '(nnfolder "archive" (nnfolder-inhibit-expiry t) (nnfolder-active-file "~/News/sent-mail/active") (nnfolder-directory "~/News/sent-mail/"))) Gnus will insert `Gcc' headers in all outgoing messages that point to one or more group(s) on that server. Which group to use is determined by the `gnus-message-archive-group' variable. This variable can be used to do the following: a string Messages will be saved in that group. Note that you can include a select method in the group name, then the message will not be stored in the select method given by `gnus-message-archive-method', but in the select method specified by the group name, instead. Suppose `gnus-message-archive-method' has the default value shown above. Then setting `gnus-message-archive-group' to `"foo"' means that outgoing messages are stored in `nnfolder+archive:foo', but if you use the value `"nnml:foo"', then outgoing messages will be stored in `nnml:foo'. a list of strings Messages will be saved in all those groups. an alist of regexps, functions and forms When a key "matches", the result is used. `nil' No message archiving will take place. This is the default. Let's illustrate: Just saving to a single group called `MisK': (setq gnus-message-archive-group "MisK") Saving to two groups, `MisK' and `safe': (setq gnus-message-archive-group '("MisK" "safe")) Save to different groups based on what group you are in: (setq gnus-message-archive-group '(("^alt" "sent-to-alt") ("mail" "sent-to-mail") (".*" "sent-to-misc"))) More complex stuff: (setq gnus-message-archive-group '((if (message-news-p) "misc-news" "misc-mail"))) How about storing all news messages in one file, but storing all mail messages in one file per month: (setq gnus-message-archive-group '((if (message-news-p) "misc-news" (concat "mail." (format-time-string "%Y-%m"))))) Now, when you send a message off, it will be stored in the appropriate group. (If you want to disable storing for just one particular message, you can just remove the `Gcc' header that has been inserted.) The archive group will appear in the group buffer the next time you start Gnus, or the next time you press `F' in the group buffer. You can enter it and read the articles in it just like you'd read any other group. If the group gets really big and annoying, you can simply rename if (using `G r' in the group buffer) to something nice--`misc-mail-september-1995', or whatever. New messages will continue to be stored in the old (now empty) group. That's the default method of archiving sent messages. Gnus offers a different way for the people who don't like the default method. In that case you should set `gnus-message-archive-group' to `nil'; this will disable archiving. `gnus-outgoing-message-group' All outgoing messages will be put in this group. If you want to store all your outgoing mail and articles in the group `nnml:archive', you set this variable to that value. This variable can also be a list of group names. If you want to have greater control over what group to put each message in, you can set this variable to a function that checks the current newsgroup name and then returns a suitable group name (or list of names). This variable can be used instead of `gnus-message-archive-group', but the latter is the preferred method. `gnus-gcc-mark-as-read' If non-`nil', automatically mark `Gcc' articles as read. `gnus-gcc-externalize-attachments' If `nil', attach files as normal parts in Gcc copies; if a regexp and matches the Gcc group name, attach files as external parts; if it is `all', attach local files as external parts; if it is other non-`nil', the behavior is the same as `all', but it may be changed in the future.  File: gnus, Node: Posting Styles, Next: Drafts, Prev: Archived Messages, Up: Composing Messages Posting Styles ============== All them variables, they make my head swim. So what if you want a different `Organization' and signature based on what groups you post to? And you post both from your home machine and your work machine, and you want different `From' lines, and so on? One way to do stuff like that is to write clever hooks that change the variables you need to have changed. That's a bit boring, so somebody came up with the bright idea of letting the user specify these things in a handy alist. Here's an example of a `gnus-posting-styles' variable: ((".*" (signature "Peace and happiness") (organization "What me?")) ("^comp" (signature "Death to everybody")) ("comp.emacs.i-love-it" (organization "Emacs is it"))) As you might surmise from this example, this alist consists of several "styles". Each style will be applicable if the first element "matches", in some form or other. The entire alist will be iterated over, from the beginning towards the end, and each match will be applied, which means that attributes in later styles that match override the same attributes in earlier matching styles. So `comp.programming.literate' will have the `Death to everybody' signature and the `What me?' `Organization' header. The first element in each style is called the `match'. If it's a string, then Gnus will try to regexp match it against the group name. If it is the form `(header MATCH REGEXP)', then Gnus will look in the original article for a header whose name is MATCH and compare that REGEXP. MATCH and REGEXP are strings. (The original article is the one you are replying or following up to. If you are not composing a reply or a followup, then there is nothing to match against.) If the `match' is a function symbol, that function will be called with no arguments. If it's a variable symbol, then the variable will be referenced. If it's a list, then that list will be `eval'ed. In any case, if this returns a non-`nil' value, then the style is said to "match". Each style may contain an arbitrary amount of "attributes". Each attribute consists of a `(NAME VALUE)' pair. In addition, you can also use the `(NAME :file VALUE)' form or the `(NAME :value VALUE)' form. Where `:file' signifies VALUE represents a file name and its contents should be used as the attribute value, `:value' signifies VALUE does not represent a file name explicitly. The attribute name can be one of: * `signature' * `signature-file' * `x-face-file' * `address', overriding `user-mail-address' * `name', overriding `(user-full-name)' * `body' The attribute name can also be a string or a symbol. In that case, this will be used as a header name, and the value will be inserted in the headers of the article; if the value is `nil', the header name will be removed. If the attribute name is `eval', the form is evaluated, and the result is thrown away. The attribute value can be a string (used verbatim), a function with zero arguments (the return value will be used), a variable (its value will be used) or a list (it will be `eval'ed and the return value will be used). The functions and sexps are called/`eval'ed in the message buffer that is being set up. The headers of the current article are available through the `message-reply-headers' variable, which is a vector of the following headers: number subject from date id references chars lines xref extra. If you wish to check whether the message you are about to compose is meant to be a news article or a mail message, you can check the values of the `message-news-p' and `message-mail-p' functions. So here's a new example: (setq gnus-posting-styles '((".*" (signature-file "~/.signature") (name "User Name") ("X-Home-Page" (getenv "WWW_HOME")) (organization "People's Front Against MWM")) ("^rec.humor" (signature my-funny-signature-randomizer)) ((equal (system-name) "gnarly") ;; A form (signature my-quote-randomizer)) (message-news-p ;; A function symbol (signature my-news-signature)) (window-system ;; A value symbol ("X-Window-System" (format "%s" window-system))) ;; If I'm replying to Larsi, set the Organization header. ((header "from" "larsi.*org") (Organization "Somewhere, Inc.")) ((posting-from-work-p) ;; A user defined function (signature-file "~/.work-signature") (address "user@bar.foo") (body "You are fired.\n\nSincerely, your boss.") (organization "Important Work, Inc")) ("nnml:.*" (From (save-excursion (set-buffer gnus-article-buffer) (message-fetch-field "to")))) ("^nn.+:" (signature-file "~/.mail-signature")))) The `nnml:.*' rule means that you use the `To' address as the `From' address in all your outgoing replies, which might be handy if you fill many roles.  File: gnus, Node: Drafts, Next: Rejected Articles, Prev: Posting Styles, Up: Composing Messages Drafts ====== If you are writing a message (mail or news) and suddenly remember that you have a steak in the oven (or some pesto in the food processor, you craaazy vegetarians), you'll probably wish there was a method to save the message you are writing so that you can continue editing it some other day, and send it when you feel its finished. Well, don't worry about it. Whenever you start composing a message of some sort using the Gnus mail and post commands, the buffer you get will automatically associate to an article in a special "draft" group. If you save the buffer the normal way (`C-x C-s', for instance), the article will be saved there. (Auto-save files also go to the draft group.) The draft group is a special group (which is implemented as an `nndraft' group, if you absolutely have to know) called `nndraft:drafts'. The variable `nndraft-directory' says where `nndraft' is to store its files. What makes this group special is that you can't tick any articles in it or mark any articles as read--all articles in the group are permanently unread. If the group doesn't exist, it will be created and you'll be subscribed to it. The only way to make it disappear from the Group buffer is to unsubscribe it. The special properties of the draft group comes from a group property (*note Group Parameters::), and if lost the group behaves like any other group. This means the commands below will not be available. To restore the special properties of the group, the simplest way is to kill the group, using `C-k', and restart Gnus. The group is automatically created again with the correct parameters. The content of the group is not lost. When you want to continue editing the article, you simply enter the draft group and push `D e' (`gnus-draft-edit-message') to do that. You will be placed in a buffer where you left off. Rejected articles will also be put in this draft group (*note Rejected Articles::). If you have lots of rejected messages you want to post (or mail) without doing further editing, you can use the `D s' command (`gnus-draft-send-message'). This command understands the process/prefix convention (*note Process/Prefix::). The `D S' command (`gnus-draft-send-all-messages') will ship off all messages in the buffer. If you have some messages that you wish not to send, you can use the `D t' (`gnus-draft-toggle-sending') command to mark the message as unsendable. This is a toggling command.  File: gnus, Node: Rejected Articles, Next: Signing and encrypting, Prev: Drafts, Up: Composing Messages Rejected Articles ================= Sometimes a news server will reject an article. Perhaps the server doesn't like your face. Perhaps it just feels miserable. Perhaps _there be demons_. Perhaps you have included too much cited text. Perhaps the disk is full. Perhaps the server is down. These situations are, of course, totally beyond the control of Gnus. (Gnus, of course, loves the way you look, always feels great, has angels fluttering around inside of it, doesn't care about how much cited text you include, never runs full and never goes down.) So Gnus saves these articles until some later time when the server feels better. The rejected articles will automatically be put in a special draft group (*note Drafts::). When the server comes back up again, you'd then typically enter that group and send all the articles off.  File: gnus, Node: Signing and encrypting, Prev: Rejected Articles, Up: Composing Messages Signing and encrypting ====================== Gnus can digitally sign and encrypt your messages, using vanilla PGP format or PGP/MIME or S/MIME. For decoding such messages, see the `mm-verify-option' and `mm-decrypt-option' options (*note Security::). Often, you would like to sign replies to people who send you signed messages. Even more often, you might want to encrypt messages which are in reply to encrypted messages. Gnus offers `gnus-message-replysign' to enable the former, and `gnus-message-replyencrypt' for the latter. In addition, setting `gnus-message-replysignencrypted' (on by default) will sign automatically encrypted messages. Instructing MML to perform security operations on a MIME part is done using the `C-c C-m s' key map for signing and the `C-c C-m c' key map for encryption, as follows. `C-c C-m s s' Digitally sign current message using S/MIME. `C-c C-m s o' Digitally sign current message using PGP. `C-c C-m s p' Digitally sign current message using PGP/MIME. `C-c C-m c s' Digitally encrypt current message using S/MIME. `C-c C-m c o' Digitally encrypt current message using PGP. `C-c C-m c p' Digitally encrypt current message using PGP/MIME. `C-c C-m C-n' Remove security related MML tags from message. *Note Security: (message)Security, for more information.  File: gnus, Node: Select Methods, Next: Scoring, Prev: Composing Messages, Up: Top Select Methods ************** A "foreign group" is a group not read by the usual (or default) means. It could be, for instance, a group from a different NNTP server, it could be a virtual group, or it could be your own personal mail group. A foreign group (or any group, really) is specified by a "name" and a "select method". To take the latter first, a select method is a list where the first element says what back end to use (e.g. `nntp', `nnspool', `nnml') and the second element is the "server name". There may be additional elements in the select method, where the value may have special meaning for the back end in question. One could say that a select method defines a "virtual server"--so we do just that (*note Server Buffer::). The "name" of the group is the name the back end will recognize the group as. For instance, the group `soc.motss' on the NNTP server `some.where.edu' will have the name `soc.motss' and select method `(nntp "some.where.edu")'. Gnus will call this group `nntp+some.where.edu:soc.motss', even though the `nntp' back end just knows this group as `soc.motss'. The different methods all have their peculiarities, of course. * Menu: * Server Buffer:: Making and editing virtual servers. * Getting News:: Reading USENET news with Gnus. * Getting Mail:: Reading your personal mail with Gnus. * Browsing the Web:: Getting messages from a plethora of Web sources. * IMAP:: Using Gnus as a IMAP client. * Other Sources:: Reading directories, files, SOUP packets. * Combined Groups:: Combining groups into one group. * Email Based Diary:: Using mails to manage diary events in Gnus. * Gnus Unplugged:: Reading news and mail offline.  File: gnus, Node: Server Buffer, Next: Getting News, Up: Select Methods Server Buffer ============= Traditionally, a "server" is a machine or a piece of software that one connects to, and then requests information from. Gnus does not connect directly to any real servers, but does all transactions through one back end or other. But that's just putting one layer more between the actual media and Gnus, so we might just as well say that each back end represents a virtual server. For instance, the `nntp' back end may be used to connect to several different actual NNTP servers, or, perhaps, to many different ports on the same actual NNTP server. You tell Gnus which back end to use, and what parameters to set by specifying a "select method". These select method specifications can sometimes become quite complicated--say, for instance, that you want to read from the NNTP server `news.funet.fi' on port number 13, which hangs if queried for NOV headers and has a buggy select. Ahem. Anyway, if you had to specify that for each group that used this server, that would be too much work, so Gnus offers a way of naming select methods, which is what you do in the server buffer. To enter the server buffer, use the `^' (`gnus-group-enter-server-mode') command in the group buffer. * Menu: * Server Buffer Format:: You can customize the look of this buffer. * Server Commands:: Commands to manipulate servers. * Example Methods:: Examples server specifications. * Creating a Virtual Server:: An example session. * Server Variables:: Which variables to set. * Servers and Methods:: You can use server names as select methods. * Unavailable Servers:: Some servers you try to contact may be down. `gnus-server-mode-hook' is run when creating the server buffer.  File: gnus, Node: Server Buffer Format, Next: Server Commands, Up: Server Buffer Server Buffer Format -------------------- You can change the look of the server buffer lines by changing the `gnus-server-line-format' variable. This is a `format'-like variable, with some simple extensions: `h' How the news is fetched--the back end name. `n' The name of this server. `w' Where the news is to be fetched from--the address. `s' The opened/closed/denied status of the server. `a' Whether this server is agentized. The mode line can also be customized by using the `gnus-server-mode-line-format' variable (*note Mode Line Formatting::). The following specs are understood: `S' Server name. `M' Server method. Also *note Formatting Variables::.  File: gnus, Node: Server Commands, Next: Example Methods, Prev: Server Buffer Format, Up: Server Buffer Server Commands --------------- `a' Add a new server (`gnus-server-add-server'). `e' Edit a server (`gnus-server-edit-server'). `SPACE' Browse the current server (`gnus-server-read-server'). `q' Return to the group buffer (`gnus-server-exit'). `k' Kill the current server (`gnus-server-kill-server'). `y' Yank the previously killed server (`gnus-server-yank-server'). `c' Copy the current server (`gnus-server-copy-server'). `l' List all servers (`gnus-server-list-servers'). `s' Request that the server scan its sources for new articles (`gnus-server-scan-server'). This is mainly sensible with mail servers. `g' Request that the server regenerate all its data structures (`gnus-server-regenerate-server'). This can be useful if you have a mail back end that has gotten out of sync.  File: gnus, Node: Example Methods, Next: Creating a Virtual Server, Prev: Server Commands, Up: Server Buffer Example Methods --------------- Most select methods are pretty simple and self-explanatory: (nntp "news.funet.fi") Reading directly from the spool is even simpler: (nnspool "") As you can see, the first element in a select method is the name of the back end, and the second is the "address", or "name", if you will. After these two elements, there may be an arbitrary number of `(VARIABLE FORM)' pairs. To go back to the first example--imagine that you want to read from port 15 on that machine. This is what the select method should look like then: (nntp "news.funet.fi" (nntp-port-number 15)) You should read the documentation to each back end to find out what variables are relevant, but here's an `nnmh' example: `nnmh' is a mail back end that reads a spool-like structure. Say you have two structures that you wish to access: One is your private mail spool, and the other is a public one. Here's the possible spec for your private mail: (nnmh "private" (nnmh-directory "~/private/mail/")) (This server is then called `private', but you may have guessed that.) Here's the method for a public spool: (nnmh "public" (nnmh-directory "/usr/information/spool/") (nnmh-get-new-mail nil)) If you are behind a firewall and only have access to the NNTP server from the firewall machine, you can instruct Gnus to `rlogin' on the firewall machine and telnet from there to the NNTP server. Doing this can be rather fiddly, but your virtual server definition should probably look something like this: (nntp "firewall" (nntp-open-connection-function nntp-open-via-rlogin-and-telnet) (nntp-via-address "the.firewall.machine") (nntp-address "the.real.nntp.host") (nntp-end-of-line "\n")) If you want to use the wonderful `ssh' program to provide a compressed connection over the modem line, you could add the following configuration to the example above: (nntp-via-rlogin-command "ssh") See also `nntp-via-rlogin-command-switches'. If you're behind a firewall, but have direct access to the outside world through a wrapper command like "runsocks", you could open a socksified telnet connection to the news server as follows: (nntp "outside" (nntp-pre-command "runsocks") (nntp-open-connection-function nntp-open-via-telnet) (nntp-address "the.news.server") (nntp-end-of-line "\n")) This means that you have to have set up `ssh-agent' correctly to provide automatic authorization, of course. And to get a compressed connection, you have to have the `Compression' option in the `ssh' `config' file.  File: gnus, Node: Creating a Virtual Server, Next: Server Variables, Prev: Example Methods, Up: Server Buffer Creating a Virtual Server ------------------------- If you're saving lots of articles in the cache by using persistent articles, you may want to create a virtual server to read the cache. First you need to add a new server. The `a' command does that. It would probably be best to use `nnml' to read the cache. You could also use `nnspool' or `nnmh', though. Type `a nnml RET cache RET'. You should now have a brand new `nnml' virtual server called `cache'. You now need to edit it to have the right definitions. Type `e' to edit the server. You'll be entered into a buffer that will contain the following: (nnml "cache") Change that to: (nnml "cache" (nnml-directory "~/News/cache/") (nnml-active-file "~/News/cache/active")) Type `C-c C-c' to return to the server buffer. If you now press `RET' over this virtual server, you should be entered into a browse buffer, and you should be able to enter any of the groups displayed.  File: gnus, Node: Server Variables, Next: Servers and Methods, Prev: Creating a Virtual Server, Up: Server Buffer Server Variables ---------------- One sticky point when defining variables (both on back ends and in Emacs in general) is that some variables are typically initialized from other variables when the definition of the variables is being loaded. If you change the "base" variable after the variables have been loaded, you won't change the "derived" variables. This typically affects directory and file variables. For instance, `nnml-directory' is `~/Mail/' by default, and all `nnml' directory variables are initialized from that variable, so `nnml-active-file' will be `~/Mail/active'. If you define a new virtual `nnml' server, it will _not_ suffice to set just `nnml-directory'--you have to explicitly set all the file variables to be what you want them to be. For a complete list of variables for each back end, see each back end's section later in this manual, but here's an example `nnml' definition: (nnml "public" (nnml-directory "~/my-mail/") (nnml-active-file "~/my-mail/active") (nnml-newsgroups-file "~/my-mail/newsgroups")) Server variables are often called "server parameters".  File: gnus, Node: Servers and Methods, Next: Unavailable Servers, Prev: Server Variables, Up: Server Buffer Servers and Methods ------------------- Wherever you would normally use a select method (e.g. `gnus-secondary-select-method', in the group select method, when browsing a foreign server) you can use a virtual server name instead. This could potentially save lots of typing. And it's nice all over.  File: gnus, Node: Unavailable Servers, Prev: Servers and Methods, Up: Server Buffer Unavailable Servers ------------------- If a server seems to be unreachable, Gnus will mark that server as `denied'. That means that any subsequent attempt to make contact with that server will just be ignored. "It can't be opened," Gnus will tell you, without making the least effort to see whether that is actually the case or not. That might seem quite naughty, but it does make sense most of the time. Let's say you have 10 groups subscribed to on server `nephelococcygia.com'. This server is located somewhere quite far away from you and the machine is quite slow, so it takes 1 minute just to find out that it refuses connection to you today. If Gnus were to attempt to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do that. Once it has gotten a single "connection refused", it will regard that server as "down". So, what happens if the machine was only feeling unwell temporarily? How do you test to see whether the machine has come up again? You jump to the server buffer (*note Server Buffer::) and poke it with the following commands: `O' Try to establish connection to the server on the current line (`gnus-server-open-server'). `C' Close the connection (if any) to the server (`gnus-server-close-server'). `D' Mark the current server as unreachable (`gnus-server-deny-server'). `M-o' Open the connections to all servers in the buffer (`gnus-server-open-all-servers'). `M-c' Close the connections to all servers in the buffer (`gnus-server-close-all-servers'). `R' Remove all marks to whether Gnus was denied connection from any servers (`gnus-server-remove-denials'). `L' Set server status to offline (`gnus-server-offline-server').  File: gnus, Node: Getting News, Next: Getting Mail, Prev: Server Buffer, Up: Select Methods Getting News ============ A newsreader is normally used for reading news. Gnus currently provides only two methods of getting news--it can read from an NNTP server, or it can read from a local spool. * Menu: * NNTP:: Reading news from an NNTP server. * News Spool:: Reading news from the local spool.  File: gnus, Node: NNTP, Next: News Spool, Up: Getting News NNTP ---- Subscribing to a foreign group from an NNTP server is rather easy. You just specify `nntp' as method and the address of the NNTP server as the, uhm, address. If the NNTP server is located at a non-standard port, setting the third element of the select method to this port number should allow you to connect to the right port. You'll have to edit the group info for that (*note Foreign Groups::). The name of the foreign group can be the same as a native group. In fact, you can subscribe to the same group from as many different servers you feel like. There will be no name collisions. The following variables can be used to create a virtual `nntp' server: `nntp-server-opened-hook' is run after a connection has been made. It can be used to send commands to the NNTP server after it has been contacted. By default it sends the command `MODE READER' to the server with the `nntp-send-mode-reader' function. This function should always be present in this hook. `nntp-authinfo-function' This function will be used to send `AUTHINFO' to the NNTP server. The default function is `nntp-send-authinfo', which looks through your `~/.authinfo' (or whatever you've set the `nntp-authinfo-file' variable to) for applicable entries. If none are found, it will prompt you for a login name and a password. The format of the `~/.authinfo' file is (almost) the same as the `ftp' `~/.netrc' file, which is defined in the `ftp' manual page, but here are the salient facts: 1. The file contains one or more line, each of which define one server. 2. Each line may contain an arbitrary number of token/value pairs. The valid tokens include `machine', `login', `password', `default'. In addition Gnus introduces two new tokens, not present in the original `.netrc'/`ftp' syntax, namely `port' and `force'. (This is the only way the `.authinfo' file format deviates from the `.netrc' file format.) `port' is used to indicate what port on the server the credentials apply to and `force' is explained below. Here's an example file: machine news.uio.no login larsi password geheimnis machine nntp.ifi.uio.no login larsi force yes The token/value pairs may appear in any order; `machine' doesn't have to be first, for instance. In this example, both login name and password have been supplied for the former server, while the latter has only the login name listed, and the user will be prompted for the password. The latter also has the `force' tag, which means that the authinfo will be sent to the NNTP server upon connection; the default (i.e., when there is not `force' tag) is to not send authinfo to the NNTP server until the NNTP server asks for it. You can also add `default' lines that will apply to all servers that don't have matching `machine' lines. default force yes This will force sending `AUTHINFO' commands to all servers not previously mentioned. Remember to not leave the `~/.authinfo' file world-readable. `nntp-server-action-alist' This is a list of regexps to match on server types and actions to be taken when matches are made. For instance, if you want Gnus to beep every time you connect to innd, you could say something like: (setq nntp-server-action-alist '(("innd" (ding)))) You probably don't want to do that, though. The default value is '(("nntpd 1\\.5\\.11t" (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader))) This ensures that Gnus doesn't send the `MODE READER' command to nntpd 1.5.11t, since that command chokes that server, I've been told. `nntp-maximum-request' If the NNTP server doesn't support NOV headers, this back end will collect headers by sending a series of `head' commands. To speed things up, the back end sends lots of these commands without waiting for reply, and then reads all the replies. This is controlled by the `nntp-maximum-request' variable, and is 400 by default. If your network is buggy, you should set this to 1. `nntp-connection-timeout' If you have lots of foreign `nntp' groups that you connect to regularly, you're sure to have problems with NNTP servers not responding properly, or being too loaded to reply within reasonable time. This is can lead to awkward problems, which can be helped somewhat by setting `nntp-connection-timeout'. This is an integer that says how many seconds the `nntp' back end should wait for a connection before giving up. If it is `nil', which is the default, no timeouts are done. `nntp-nov-is-evil' If the NNTP server does not support NOV, you could set this variable to `t', but `nntp' usually checks automatically whether NOV can be used. `nntp-xover-commands' List of strings used as commands to fetch NOV lines from a server. The default value of this variable is `("XOVER" "XOVERVIEW")'. `nntp-nov-gap' `nntp' normally sends just one big request for NOV lines to the server. The server responds with one huge list of lines. However, if you have read articles 2-5000 in the group, and only want to read article 1 and 5001, that means that `nntp' will fetch 4999 NOV lines that you will not need. This variable says how big a gap between two consecutive articles is allowed to be before the `XOVER' request is split into several request. Note that if your network is fast, setting this variable to a really small number means that fetching will probably be slower. If this variable is `nil', `nntp' will never split requests. The default is 5. `nntp-prepare-server-hook' A hook run before attempting to connect to an NNTP server. `nntp-record-commands' If non-`nil', `nntp' will log all commands it sends to the NNTP server (along with a timestamp) in the `*nntp-log*' buffer. This is useful if you are debugging a Gnus/NNTP connection that doesn't seem to work. `nntp-open-connection-function' It is possible to customize how the connection to the nntp server will be opened. If you specify an `nntp-open-connection-function' parameter, Gnus will use that function to establish the connection. Seven pre-made functions are supplied. These functions can be grouped in two categories: direct connection functions (four pre-made), and indirect ones (three pre-made). `nntp-prepare-post-hook' A hook run just before posting an article. If there is no `Message-ID' header in the article and the news server provides the recommended ID, it will be added to the article before running this hook. It is useful to make `Cancel-Lock' headers even if you inhibit Gnus to add a `Message-ID' header, you could say: (add-hook 'nntp-prepare-post-hook 'canlock-insert-header) Note that not all servers support the recommended ID. This works for INN versions 2.3.0 and later, for instance. * Menu: * Direct Functions:: Connecting directly to the server. * Indirect Functions:: Connecting indirectly to the server. * Common Variables:: Understood by several connection functions. * NNTP marks:: Storing marks for NNTP servers.  File: gnus, Node: Direct Functions, Next: Indirect Functions, Up: NNTP Direct Functions ................ These functions are called direct because they open a direct connection between your machine and the NNTP server. The behavior of these functions is also affected by commonly understood variables (*note Common Variables::). `nntp-open-network-stream' This is the default, and simply connects to some port or other on the remote system. `nntp-open-tls-stream' Opens a connection to a server over a "secure" channel. To use this you must have GNUTLS (http://www.gnu.org/software/gnutls/) installed. You then define a server as follows: ;; "nntps" is port 563 and is predefined in our `/etc/services' ;; however, `gnutls-cli -p' doesn't like named ports. ;; (nntp "snews.bar.com" (nntp-open-connection-function nntp-open-tls-stream) (nntp-port-number ) (nntp-address "snews.bar.com")) `nntp-open-ssl-stream' Opens a connection to a server over a "secure" channel. To use this you must have OpenSSL (http://www.openssl.org) or SSLeay (ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL) installed. You then define a server as follows: ;; "snews" is port 563 and is predefined in our `/etc/services' ;; however, `openssl s_client -port' doesn't like named ports. ;; (nntp "snews.bar.com" (nntp-open-connection-function nntp-open-ssl-stream) (nntp-port-number 563) (nntp-address "snews.bar.com")) `nntp-open-telnet-stream' Opens a connection to an NNTP server by simply `telnet''ing it. You might wonder why this function exists, since we have the default `nntp-open-network-stream' which would do the job. (One of) the reason(s) is that if you are behind a firewall but have direct connections to the outside world thanks to a command wrapper like `runsocks', you can use it like this: (nntp "socksified" (nntp-pre-command "runsocks") (nntp-open-connection-function nntp-open-telnet-stream) (nntp-address "the.news.server")) With the default method, you would need to wrap your whole Emacs session, which is not a good idea.  File: gnus, Node: Indirect Functions, Next: Common Variables, Prev: Direct Functions, Up: NNTP Indirect Functions .................. These functions are called indirect because they connect to an intermediate host before actually connecting to the NNTP server. All of these functions and related variables are also said to belong to the "via" family of connection: they're all prefixed with "via" to make things cleaner. The behavior of these functions is also affected by commonly understood variables (*note Common Variables::). `nntp-open-via-rlogin-and-telnet' Does an `rlogin' on a remote system, and then does a `telnet' to the real NNTP server from there. This is useful for instance if you need to connect to a firewall machine first. `nntp-open-via-rlogin-and-telnet'-specific variables: `nntp-via-rlogin-command' Command used to log in on the intermediate host. The default is `rsh', but `ssh' is a popular alternative. `nntp-via-rlogin-command-switches' List of strings to be used as the switches to `nntp-via-rlogin-command'. The default is `nil'. If you use `ssh' for `nntp-via-rlogin-command', you may set this to `("-C")' in order to compress all data connections, otherwise set this to `("-t" "-e" "none")' or `("-C" "-t" "-e" "none")' if the telnet command requires a pseudo-tty allocation on an intermediate host. Note that you may want to change the value for `nntp-end-of-line' to `\n' (*note Common Variables::). `nntp-open-via-rlogin-and-netcat' Does essentially the same, but uses netcat (http://netcat.sourceforge.net/) instead of `telnet' to connect to the real NNTP server from the intermediate host. `nntp-open-via-rlogin-and-netcat'-specific variables: `nntp-via-netcat-command' Command used to connect to the real NNTP server from the intermediate host. The default is `nc'. You can also use other programs like connect (http://www.imasy.or.jp/~gotoh/ssh/connect.html) instead. `nntp-via-netcat-switches' List of strings to be used as the switches to the `nntp-via-telnet-command' command. The default is `nil'. `nntp-via-rlogin-command' Command used to log in on the intermediate host. The default is `rsh', but `ssh' is a popular alternative. `nntp-via-rlogin-command-switches' List of strings to be used as the switches to `nntp-via-rlogin-command'. The default is `nil'. `nntp-open-via-telnet-and-telnet' Does essentially also the same, but uses `telnet' instead of `rlogin' to connect to the intermediate host. `nntp-open-via-telnet-and-telnet'-specific variables: `nntp-via-telnet-command' Command used to `telnet' the intermediate host. The default is `telnet'. `nntp-via-telnet-switches' List of strings to be used as the switches to the `nntp-via-telnet-command' command. The default is `("-8")'. `nntp-via-user-password' Password to use when logging in on the intermediate host. `nntp-via-envuser' If non-`nil', the intermediate `telnet' session (client and server both) will support the `ENVIRON' option and not prompt for login name. This works for Solaris `telnet', for instance. `nntp-via-shell-prompt' Regexp matching the shell prompt on the intermediate host. The default is `bash\\|\$ *\r?$\\|> *\r?'. Note that you may want to change the value for `nntp-end-of-line' to `\n' (*note Common Variables::). Here are some additional variables that are understood by all the above functions: `nntp-via-user-name' User name to use when connecting to the intermediate host. `nntp-via-address' Address of the intermediate host to connect to.  File: gnus, Node: Common Variables, Next: NNTP marks, Prev: Indirect Functions, Up: NNTP Common Variables ................ The following variables affect the behavior of all, or several of the pre-made connection functions. When not specified, all functions are affected (the values of the following variables will be used as the default if each virtual `nntp' server doesn't specify those server variables individually). `nntp-pre-command' A command wrapper to use when connecting through a non native connection function (all except `nntp-open-network-stream', `nntp-open-tls-stream', and `nntp-open-ssl-stream'). This is where you would put a `SOCKS' wrapper for instance. `nntp-address' The address of the NNTP server. `nntp-port-number' Port number to connect to the NNTP server. The default is `nntp'. If you use NNTP over TLS/SSL, you may want to use integer ports rather than named ports (i.e, use `563' instead of `snews' or `nntps'), because external TLS/SSL tools may not work with named ports. `nntp-end-of-line' String to use as end-of-line marker when talking to the NNTP server. This is `\r\n' by default, but should be `\n' when using a non native telnet connection function. `nntp-telnet-command' Command to use when connecting to the NNTP server through `telnet'. This is _not_ for an intermediate host. This is just for the real NNTP server. The default is `telnet'. `nntp-telnet-switches' A list of switches to pass to `nntp-telnet-command'. The default is `("-8")'.  File: gnus, Node: NNTP marks, Prev: Common Variables, Up: NNTP NNTP marks .......... Gnus stores marks (*note Marking Articles::) for NNTP servers in marks files. A marks file records what marks you have set in a group and each file is specific to the corresponding server. Marks files are stored in `~/News/marks' (`nntp-marks-directory') under a classic hierarchy resembling that of a news server, for example marks for the group `gmane.discuss' on the news.gmane.org server will be stored in the file `~/News/marks/news.gmane.org/gmane/discuss/.marks'. Marks files are useful because you can copy the `~/News/marks' directory (using rsync, scp or whatever) to another Gnus installation, and it will realize what articles you have read and marked. The data in `~/News/marks' has priority over the same data in `~/.newsrc.eld'. Note that marks files are very much server-specific: Gnus remembers the article numbers so if you don't use the same servers on both installations things are most likely to break (most NNTP servers do not use the same article numbers as any other server). However, if you use servers A, B, C on one installation and servers A, D, E on the other, you can sync the marks files for A and then you'll get synchronization for that server between the two installations. Using NNTP marks can possibly incur a performance penalty so if Gnus feels sluggish, try setting the `nntp-marks-is-evil' variable to `t'. Marks will then be stored in `~/.newsrc.eld'. Related variables: `nntp-marks-is-evil' If non-`nil', this back end will ignore any marks files. The default is `nil'. `nntp-marks-directory' The directory where marks for nntp groups will be stored.  File: gnus, Node: News Spool, Prev: NNTP, Up: Getting News News Spool ---------- Subscribing to a foreign group from the local spool is extremely easy, and might be useful, for instance, to speed up reading groups that contain very big articles--`alt.binaries.pictures.furniture', for instance. Anyway, you just specify `nnspool' as the method and `""' (or anything else) as the address. If you have access to a local spool, you should probably use that as the native select method (*note Finding the News::). It is normally faster than using an `nntp' select method, but might not be. It depends. You just have to try to find out what's best at your site. `nnspool-inews-program' Program used to post an article. `nnspool-inews-switches' Parameters given to the inews program when posting an article. `nnspool-spool-directory' Where `nnspool' looks for the articles. This is normally `/usr/spool/news/'. `nnspool-nov-directory' Where `nnspool' will look for NOV files. This is normally `/usr/spool/news/over.view/'. `nnspool-lib-dir' Where the news lib dir is (`/usr/lib/news/' by default). `nnspool-active-file' The name of the active file. `nnspool-newsgroups-file' The name of the group descriptions file. `nnspool-history-file' The name of the news history file. `nnspool-active-times-file' The name of the active date file. `nnspool-nov-is-evil' If non-`nil', `nnspool' won't try to use any NOV files that it finds. `nnspool-sift-nov-with-sed' If non-`nil', which is the default, use `sed' to get the relevant portion from the overview file. If `nil', `nnspool' will load the entire file into a buffer and process it there.  File: gnus, Node: Getting Mail, Next: Browsing the Web, Prev: Getting News, Up: Select Methods Getting Mail ============ Reading mail with a newsreader--isn't that just plain WeIrD? But of course. * Menu: * Mail in a Newsreader:: Important introductory notes. * Getting Started Reading Mail:: A simple cookbook example. * Splitting Mail:: How to create mail groups. * Mail Sources:: How to tell Gnus where to get mail from. * Mail Back End Variables:: Variables for customizing mail handling. * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. * Group Mail Splitting:: Use group customize to drive mail splitting. * Incorporating Old Mail:: What about the old mail you have? * Expiring Mail:: Getting rid of unwanted mail. * Washing Mail:: Removing cruft from the mail you get. * Duplicates:: Dealing with duplicated mail. * Not Reading Mail:: Using mail back ends for reading other files. * Choosing a Mail Back End:: Gnus can read a variety of mail formats.  File: gnus, Node: Mail in a Newsreader, Next: Getting Started Reading Mail, Up: Getting Mail Mail in a Newsreader -------------------- If you are used to traditional mail readers, but have decided to switch to reading mail with Gnus, you may find yourself experiencing something of a culture shock. Gnus does not behave like traditional mail readers. If you want to make it behave that way, you can, but it's an uphill battle. Gnus, by default, handles all its groups using the same approach. This approach is very newsreaderly--you enter a group, see the new/unread messages, and when you read the messages, they get marked as read, and you don't see them any more. (Unless you explicitly ask for them.) In particular, you do not do anything explicitly to delete messages. Does this mean that all the messages that have been marked as read are deleted? How awful! But, no, it means that old messages are "expired" according to some scheme or other. For news messages, the expire process is controlled by the news administrator; for mail, the expire process is controlled by you. The expire process for mail is covered in depth in *Note Expiring Mail::. What many Gnus users find, after using it a while for both news and mail, is that the transport mechanism has very little to do with how they want to treat a message. Many people subscribe to several mailing lists. These are transported via SMTP, and are therefore mail. But we might go for weeks without answering, or even reading these messages very carefully. We may not need to save them because if we should need to read one again, they are archived somewhere else. Some people have local news groups which have only a handful of readers. These are transported via NNTP, and are therefore news. But we may need to read and answer a large fraction of the messages very carefully in order to do our work. And there may not be an archive, so we may need to save the interesting messages the same way we would personal mail. The important distinction turns out to be not the transport mechanism, but other factors such as how interested we are in the subject matter, or how easy it is to retrieve the message if we need to read it again. Gnus provides many options for sorting mail into "groups" which behave like newsgroups, and for treating each group (whether mail or news) differently. Some users never get comfortable using the Gnus (ahem) paradigm and wish that Gnus should grow up and be a male, er, mail reader. It is possible to whip Gnus into a more mailreaderly being, but, as said before, it's not easy. People who prefer proper mail readers should try VM instead, which is an excellent, and proper, mail reader. I don't mean to scare anybody off, but I want to make it clear that you may be required to learn a new way of thinking about messages. After you've been subjected to The Gnus Way, you will come to love it. I can guarantee it. (At least the guy who sold me the Emacs Subliminal Brain-Washing Functions that I've put into Gnus did guarantee it. You Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way. You Do.)  File: gnus, Node: Getting Started Reading Mail, Next: Splitting Mail, Prev: Mail in a Newsreader, Up: Getting Mail Getting Started Reading Mail ---------------------------- It's quite easy to use Gnus to read your new mail. You just plonk the mail back end of your choice into `gnus-secondary-select-methods', and things will happen automatically. For instance, if you want to use `nnml' (which is a "one file per mail" back end), you could put the following in your `~/.gnus.el' file: (setq gnus-secondary-select-methods '((nnml ""))) Now, the next time you start Gnus, this back end will be queried for new articles, and it will move all the messages in your spool file to its directory, which is `~/Mail/' by default. The new group that will be created (`mail.misc') will be subscribed, and you can read it like any other group. You will probably want to split the mail into several groups, though: (setq nnmail-split-methods '(("junk" "^From:.*Lars Ingebrigtsen") ("crazy" "^Subject:.*die\\|^Organization:.*flabby") ("other" ""))) This will result in three new `nnml' mail groups being created: `nnml:junk', `nnml:crazy', and `nnml:other'. All the mail that doesn't fit into the first two groups will be placed in the last group. This should be sufficient for reading mail with Gnus. You might want to give the other sections in this part of the manual a perusal, though. Especially *note Choosing a Mail Back End:: and *note Expiring Mail::.  File: gnus, Node: Splitting Mail, Next: Mail Sources, Prev: Getting Started Reading Mail, Up: Getting Mail Splitting Mail -------------- The `nnmail-split-methods' variable says how the incoming mail is to be split into groups. (setq nnmail-split-methods '(("mail.junk" "^From:.*Lars Ingebrigtsen") ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") ("mail.other" ""))) This variable is a list of lists, where the first element of each of these lists is the name of the mail group (they do not have to be called something beginning with `mail', by the way), and the second element is a regular expression used on the header of each mail to determine if it belongs in this mail group. The first string may contain `\\1' forms, like the ones used by `replace-match' to insert sub-expressions from the matched text. For instance: ("list.\\1" "From:.* \\(.*\\)-list@majordomo.com") In that case, `nnmail-split-lowercase-expanded' controls whether the inserted text should be made lowercase. *Note Fancy Mail Splitting::. The second element can also be a function. In that case, it will be called narrowed to the headers with the first element of the rule as the argument. It should return a non-`nil' value if it thinks that the mail belongs in that group. The last of these groups should always be a general one, and the regular expression should _always_ be `""' so that it matches any mails that haven't been matched by any of the other regexps. (These rules are processed from the beginning of the alist toward the end. The first rule to make a match will "win", unless you have crossposting enabled. In that case, all matching rules will "win".) If no rule matched, the mail will end up in the `bogus' group. When new groups are created by splitting mail, you may want to run `gnus-group-find-new-groups' to see the new groups. This also applies to the `bogus' group. If you like to tinker with this yourself, you can set this variable to a function of your choice. This function will be called without any arguments in a buffer narrowed to the headers of an incoming mail message. The function should return a list of group names that it thinks should carry this mail message. Note that the mail back ends are free to maul the poor, innocent, incoming headers all they want to. They all add `Lines' headers; some add `X-Gnus-Group' headers; most rename the Unix mbox `From' line to something else. The mail back ends all support cross-posting. If several regexps match, the mail will be "cross-posted" to all those groups. `nnmail-crosspost' says whether to use this mechanism or not. Note that no articles are crossposted to the general (`""') group. `nnmh' and `nnml' makes crossposts by creating hard links to the crossposted articles. However, not all file systems support hard links. If that's the case for you, set `nnmail-crosspost-link-function' to `copy-file'. (This variable is `add-name-to-file' by default.) If you wish to see where the previous mail split put the messages, you can use the `M-x nnmail-split-history' command. If you wish to see where re-spooling messages would put the messages, you can use `gnus-summary-respool-trace' and related commands (*note Mail Group Commands::). Header lines longer than the value of `nnmail-split-header-length-limit' are excluded from the split function. By default the splitting codes MIME decodes headers so you can match on non-ASCII strings. The `nnmail-mail-splitting-charset' variable specifies the default charset for decoding. The behavior can be turned off completely by binding `nnmail-mail-splitting-decodes' to `nil', which is useful if you want to match articles based on the raw header data. By default, splitting is performed on all incoming messages. If you specify a `directory' entry for the variable `mail-sources' (*note Mail Source Specifiers::), however, then splitting does _not_ happen by default. You can set the variable `nnmail-resplit-incoming' to a non-`nil' value to make splitting happen even in this case. (This variable has no effect on other kinds of entries.) Gnus gives you all the opportunity you could possibly want for shooting yourself in the foot. Let's say you create a group that will contain all the mail you get from your boss. And then you accidentally unsubscribe from the group. Gnus will still put all the mail from your boss in the unsubscribed group, and so, when your boss mails you "Have that report ready by Monday or you're fired!", you'll never see it and, come Tuesday, you'll still believe that you're gainfully employed while you really should be out collecting empty bottles to save up for next month's rent money.  File: gnus, Node: Mail Sources, Next: Mail Back End Variables, Prev: Splitting Mail, Up: Getting Mail Mail Sources ------------ Mail can be gotten from many different sources--the mail spool, from a POP mail server, from a procmail directory, or from a maildir, for instance. * Menu: * Mail Source Specifiers:: How to specify what a mail source is. * Mail Source Customization:: Some variables that influence things. * Fetching Mail:: Using the mail source specifiers.  File: gnus, Node: Mail Source Specifiers, Next: Mail Source Customization, Up: Mail Sources Mail Source Specifiers ...................... You tell Gnus how to fetch mail by setting `mail-sources' (*note Fetching Mail::) to a "mail source specifier". Here's an example: (pop :server "pop3.mailserver.com" :user "myname") As can be observed, a mail source specifier is a list where the first element is a "mail source type", followed by an arbitrary number of "keywords". Keywords that are not explicitly specified are given default values. The following mail source types are available: `file' Get mail from a single file; typically from the mail spool. Keywords: `:path' The file name. Defaults to the value of the `MAIL' environment variable or the value of `rmail-spool-directory' (usually something like `/usr/mail/spool/user-name'). `:prescript' `:postscript' Script run before/after fetching mail. An example file mail source: (file :path "/usr/spool/mail/user-name") Or using the default file name: (file) If the mail spool file is not located on the local machine, it's best to use POP or IMAP or the like to fetch the mail. You can not use ange-ftp file names here--it has no way to lock the mail spool while moving the mail. If it's impossible to set up a proper server, you can use ssh instead. (setq mail-sources '((file :prescript "ssh host bin/getmail >%t"))) The `getmail' script would look something like the following: #!/bin/sh # getmail - move mail from spool to stdout # flu@iki.fi MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail TMP=$HOME/Mail/tmp rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP Alter this script to fit find the `movemail' you want to use. `directory' Get mail from several files in a directory. This is typically used when you have procmail split the incoming mail into several files. That is, there is a one-to-one correspondence between files in that directory and groups, so that mail from the file `foo.bar.spool' will be put in the group `foo.bar'. (You can change the suffix to be used instead of `.spool'.) Setting `nnmail-scan-directory-mail-source-once' to non-`nil' forces Gnus to scan the mail source only once. This is particularly useful if you want to scan mail groups at a specified level. There is also the variable `nnmail-resplit-incoming', if you set that to a non-`nil' value, then the normal splitting process is applied to all the files from the directory, *Note Splitting Mail::. Keywords: `:path' The name of the directory where the files are. There is no default value. `:suffix' Only files ending with this suffix are used. The default is `.spool'. `:predicate' Only files that have this predicate return non-`nil' are returned. The default is `identity'. This is used as an additional filter--only files that have the right suffix _and_ satisfy this predicate are considered. `:prescript' `:postscript' Script run before/after fetching mail. An example directory mail source: (directory :path "/home/user-name/procmail-dir/" :suffix ".prcml") `pop' Get mail from a POP server. Keywords: `:server' The name of the POP server. The default is taken from the `MAILHOST' environment variable. `:port' The port number of the POP server. This can be a number (eg, `:port 1234') or a string (eg, `:port "pop3"'). If it is a string, it should be a service name as listed in `/etc/services' on Unix systems. The default is `"pop3"'. On some systems you might need to specify it as `"pop-3"' instead. `:user' The user name to give to the POP server. The default is the login name. `:password' The password to give to the POP server. If not specified, the user is prompted. `:program' The program to use to fetch mail from the POP server. This should be a `format'-like string. Here's an example: fetchmail %u@%s -P %p %t The valid format specifier characters are: `t' The name of the file the mail is to be moved to. This must always be included in this string. `s' The name of the server. `P' The port number of the server. `u' The user name to use. `p' The password to use. The values used for these specs are taken from the values you give the corresponding keywords. `:prescript' A script to be run before fetching the mail. The syntax is the same as the `:program' keyword. This can also be a function to be run. `:postscript' A script to be run after fetching the mail. The syntax is the same as the `:program' keyword. This can also be a function to be run. `:function' The function to use to fetch mail from the POP server. The function is called with one parameter--the name of the file where the mail should be moved to. `:authentication' This can be either the symbol `password' or the symbol `apop' and says what authentication scheme to use. The default is `password'. If the `:program' and `:function' keywords aren't specified, `pop3-movemail' will be used. If the `pop3-leave-mail-on-server' is non-`nil' the mail is to be left on the POP server after fetching when using `pop3-movemail'. Note that POP servers maintain no state information between sessions, so what the client believes is there and what is actually there may not match up. If they do not, then the whole thing can fall apart and leave you with a corrupt mailbox. Here are some examples. Fetch from the default POP server, using the default user name, and default fetcher: (pop) Fetch from a named server with a named user and password: (pop :server "my.pop.server" :user "user-name" :password "secret") Use `movemail' to move the mail: (pop :program "movemail po:%u %t %p") `maildir' Get mail from a maildir. This is a type of mailbox that is supported by at least qmail and postfix, where each file in a special directory contains exactly one mail. Keywords: `:path' The name of the directory where the mails are stored. The default is taken from the `MAILDIR' environment variable or `~/Maildir/'. `:subdirs' The subdirectories of the Maildir. The default is `("new" "cur")'. You can also get mails from remote hosts (because maildirs don't suffer from locking problems). Two example maildir mail sources: (maildir :path "/home/user-name/Maildir/" :subdirs ("cur" "new")) (maildir :path "/user@remotehost.org:~/Maildir/" :subdirs ("new")) `imap' Get mail from a IMAP server. If you don't want to use IMAP as intended, as a network mail reading protocol (ie with nnimap), for some reason or other, Gnus let you treat it similar to a POP server and fetches articles from a given IMAP mailbox. *Note IMAP::, for more information. Note that for the Kerberos, GSSAPI, TLS/SSL and STARTTLS support you may need external programs and libraries, *Note IMAP::. Keywords: `:server' The name of the IMAP server. The default is taken from the `MAILHOST' environment variable. `:port' The port number of the IMAP server. The default is `143', or `993' for TLS/SSL connections. `:user' The user name to give to the IMAP server. The default is the login name. `:password' The password to give to the IMAP server. If not specified, the user is prompted. `:stream' What stream to use for connecting to the server, this is one of the symbols in `imap-stream-alist'. Right now, this means `gssapi', `kerberos4', `starttls', `tls', `ssl', `shell' or the default `network'. `:authentication' Which authenticator to use for authenticating to the server, this is one of the symbols in `imap-authenticator-alist'. Right now, this means `gssapi', `kerberos4', `digest-md5', `cram-md5', `anonymous' or the default `login'. `:program' When using the `shell' :stream, the contents of this variable is mapped into the `imap-shell-program' variable. This should be a `format'-like string (or list of strings). Here's an example: ssh %s imapd The valid format specifier characters are: `s' The name of the server. `l' User name from `imap-default-user'. `p' The port number of the server. The values used for these specs are taken from the values you give the corresponding keywords. `:mailbox' The name of the mailbox to get mail from. The default is `INBOX' which normally is the mailbox which receive incoming mail. `:predicate' The predicate used to find articles to fetch. The default, `UNSEEN UNDELETED', is probably the best choice for most people, but if you sometimes peek in your mailbox with a IMAP client and mark some articles as read (or; SEEN) you might want to set this to `1:*'. Then all articles in the mailbox is fetched, no matter what. For a complete list of predicates, see RFC 2060 section 6.4.4. `:fetchflag' How to flag fetched articles on the server, the default `\Deleted' will mark them as deleted, an alternative would be `\Seen' which would simply mark them as read. These are the two most likely choices, but more flags are defined in RFC 2060 section 2.3.2. `:dontexpunge' If non-`nil', don't remove all articles marked as deleted in the mailbox after finishing the fetch. An example IMAP mail source: (imap :server "mail.mycorp.com" :stream kerberos4 :fetchflag "\\Seen") `webmail' Get mail from a webmail server, such as `http://www.hotmail.com/', `http://webmail.netscape.com/', `http://www.netaddress.com/', `http://mail.yahoo.com/'. NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is required for url "4.0pre.46". WARNING: Mails may be lost. NO WARRANTY. Keywords: `:subtype' The type of the webmail server. The default is `hotmail'. The alternatives are `netscape', `netaddress', `my-deja'. `:user' The user name to give to the webmail server. The default is the login name. `:password' The password to give to the webmail server. If not specified, the user is prompted. `:dontexpunge' If non-`nil', only fetch unread articles and don't move them to trash folder after finishing the fetch. An example webmail source: (webmail :subtype 'hotmail :user "user-name" :password "secret") "Common Keywords" Common keywords can be used in any type of mail source. Keywords: `:plugged' If non-`nil', fetch the mail even when Gnus is unplugged. If you use directory source to get mail, you can specify it as in this example: (setq mail-sources '((directory :path "/home/pavel/.Spool/" :suffix "" :plugged t))) Gnus will then fetch your mail even when you are unplugged. This is useful when you use local mail and news. Function Interface .................. Some of the above keywords specify a Lisp function to be executed. For each keyword `:foo', the Lisp variable `foo' is bound to the value of the keyword while the function is executing. For example, consider the following mail-source setting: (setq mail-sources '((pop :user "jrl" :server "pophost" :function fetchfunc))) While the function `fetchfunc' is executing, the symbol `user' is bound to `"jrl"', and the symbol `server' is bound to `"pophost"'. The symbols `port', `password', `program', `prescript', `postscript', `function', and `authentication' are also bound (to their default values). See above for a list of keywords for each type of mail source.  File: gnus, Node: Mail Source Customization, Next: Fetching Mail, Prev: Mail Source Specifiers, Up: Mail Sources Mail Source Customization ......................... The following is a list of variables that influence how the mail is fetched. You would normally not need to set or change any of these variables. `mail-source-crash-box' File where mail will be stored while processing it. The default is `~/.emacs-mail-crash-box'. `mail-source-delete-incoming' If non-`nil', delete incoming files after handling them. If `t', delete the files immediately, if `nil', never delete any files. If a positive number, delete files older than number of days (This will only happen, when receiving new mail). You may also set `mail-source-delete-incoming' to `nil' and call `mail-source-delete-old-incoming' from a hook or interactively. `mail-source-delete-old-incoming-confirm' If non-`nil', ask for for confirmation before deleting old incoming files. This variable only applies when `mail-source-delete-incoming' is a positive number. `mail-source-ignore-errors' If non-`nil', ignore errors when reading mail from a mail source. `mail-source-directory' Directory where incoming mail source files (if any) will be stored. The default is `~/Mail/'. At present, the only thing this is used for is to say where the incoming files will be stored if the variable `mail-source-delete-incoming' is `nil' or a number. `mail-source-incoming-file-prefix' Prefix for file name for storing incoming mail. The default is `Incoming', in which case files will end up with names like `Incoming30630D_' or `Incoming298602ZD'. This is really only relevant if `mail-source-delete-incoming' is `nil' or a number. `mail-source-default-file-modes' All new mail files will get this file mode. The default is 384. `mail-source-movemail-program' If non-`nil', name of program for fetching new mail. If `nil', `movemail' in EXEC-DIRECTORY.  File: gnus, Node: Fetching Mail, Prev: Mail Source Customization, Up: Mail Sources Fetching Mail ............. The way to actually tell Gnus where to get new mail from is to set `mail-sources' to a list of mail source specifiers (*note Mail Source Specifiers::). If this variable (and the obsolescent `nnmail-spool-file') is `nil', the mail back ends will never attempt to fetch mail by themselves. If you want to fetch mail both from your local spool as well as a POP mail server, you'd say something like: (setq mail-sources '((file) (pop :server "pop3.mail.server" :password "secret"))) Or, if you don't want to use any of the keyword defaults: (setq mail-sources '((file :path "/var/spool/mail/user-name") (pop :server "pop3.mail.server" :user "user-name" :port "pop3" :password "secret"))) When you use a mail back end, Gnus will slurp all your mail from your inbox and plonk it down in your home directory. Gnus doesn't move any mail if you're not using a mail back end--you have to do a lot of magic invocations first. At the time when you have finished drawing the pentagram, lightened the candles, and sacrificed the goat, you really shouldn't be too surprised when Gnus moves your mail.  File: gnus, Node: Mail Back End Variables, Next: Fancy Mail Splitting, Prev: Mail Sources, Up: Getting Mail Mail Back End Variables ----------------------- These variables are (for the most part) pertinent to all the various mail back ends. `nnmail-read-incoming-hook' The mail back ends all call this hook after reading new mail. You can use this hook to notify any mail watch programs, if you want to. `nnmail-split-hook' Hook run in the buffer where the mail headers of each message is kept just before the splitting based on these headers is done. The hook is free to modify the buffer contents in any way it sees fit--the buffer is discarded after the splitting has been done, and no changes performed in the buffer will show up in any files. `gnus-article-decode-encoded-words' is one likely function to add to this hook. `nnmail-pre-get-new-mail-hook' `nnmail-post-get-new-mail-hook' These are two useful hooks executed when treating new incoming mail--`nnmail-pre-get-new-mail-hook' (is called just before starting to handle the new mail) and `nnmail-post-get-new-mail-hook' (is called when the mail handling is done). Here's and example of using these two hooks to change the default file modes the new mail files get: (add-hook 'nnmail-pre-get-new-mail-hook (lambda () (set-default-file-modes 511))) (add-hook 'nnmail-post-get-new-mail-hook (lambda () (set-default-file-modes 551))) `nnmail-use-long-file-names' If non-`nil', the mail back ends will use long file and directory names. Groups like `mail.misc' will end up in directories (assuming use of `nnml' back end) or files (assuming use of `nnfolder' back end) like `mail.misc'. If it is `nil', the same group will end up in `mail/misc'. `nnmail-delete-file-function' Function called to delete files. It is `delete-file' by default. `nnmail-cache-accepted-message-ids' If non-`nil', put the `Message-ID's of articles imported into the back end (via `Gcc', for instance) into the mail duplication discovery cache. The default is `nil'. `nnmail-cache-ignore-groups' This can be a regular expression or a list of regular expressions. Group names that match any of the regular expressions will never be recorded in the `Message-ID' cache. This can be useful, for example, when using Fancy Splitting (*note Fancy Mail Splitting::) together with the function `nnmail-split-fancy-with-parent'.  File: gnus, Node: Fancy Mail Splitting, Next: Group Mail Splitting, Prev: Mail Back End Variables, Up: Getting Mail Fancy Mail Splitting -------------------- If the rather simple, standard method for specifying how to split mail doesn't allow you to do what you want, you can set `nnmail-split-methods' to `nnmail-split-fancy'. Then you can play with the `nnmail-split-fancy' variable. Let's look at an example value of this variable first: ;; Messages from the mailer daemon are not crossposted to any of ;; the ordinary groups. Warnings are put in a separate group ;; from real errors. (| ("from" mail (| ("subject" "warn.*" "mail.warning") "mail.misc")) ;; Non-error messages are crossposted to all relevant ;; groups, but we don't crosspost between the group for the ;; (ding) list and the group for other (ding) related mail. (& (| (any "ding@ifi\\.uio\\.no" "ding.list") ("subject" "ding" "ding.misc")) ;; Other mailing lists... (any "procmail@informatik\\.rwth-aachen\\.de" "procmail.list") (any "SmartList@informatik\\.rwth-aachen\\.de" "SmartList.list") ;; Both lists below have the same suffix, so prevent ;; cross-posting to mkpkg.list of messages posted only to ;; the bugs- list, but allow cross-posting when the ;; message was really cross-posted. (any "bugs-mypackage@somewhere" "mypkg.bugs") (any "mypackage@somewhere" - "bugs-mypackage" "mypkg.list") ;; People... (any "larsi@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) ;; Unmatched mail goes to the catch all group. "misc.misc") This variable has the format of a "split". A split is a (possibly) recursive structure where each split may contain other splits. Here are the possible split syntaxes: `group' If the split is a string, that will be taken as a group name. Normal regexp match expansion will be done. See below for examples. `(FIELD VALUE [- RESTRICT [...] ] SPLIT)' If the split is a list, the first element of which is a string, then store the message as specified by SPLIT, if header FIELD (a regexp) contains VALUE (also a regexp). If RESTRICT (yet another regexp) matches some string after FIELD and before the end of the matched VALUE, the SPLIT is ignored. If none of the RESTRICT clauses match, SPLIT is processed. `(| SPLIT ...)' If the split is a list, and the first element is `|' (vertical bar), then process each SPLIT until one of them matches. A SPLIT is said to match if it will cause the mail message to be stored in one or more groups. `(& SPLIT ...)' If the split is a list, and the first element is `&', then process all SPLITs in the list. `junk' If the split is the symbol `junk', then don't save (i.e., delete) this message. Use with extreme caution. `(: FUNCTION ARG1 ARG2 ...)' If the split is a list, and the first element is `:', then the second element will be called as a function with ARGS given as arguments. The function should return a SPLIT. For instance, the following function could be used to split based on the body of the messages: (defun split-on-body () (save-excursion (save-restriction (widen) (goto-char (point-min)) (when (re-search-forward "Some.*string" nil t) "string.group")))) The buffer is narrowed to the message in question when FUNCTION is run. That's why `(widen)' needs to be called after `save-excursion' and `save-restriction' in the example above. Also note that with the nnimap back end, message bodies will not be downloaded by default. You need to set `nnimap-split-download-body' to `t' to do that (*note Splitting in IMAP::). `(! FUNC SPLIT)' If the split is a list, and the first element is `!', then SPLIT will be processed, and FUNC will be called as a function with the result of SPLIT as argument. FUNC should return a split. `nil' If the split is `nil', it is ignored. In these splits, FIELD must match a complete field name. VALUE must match a complete word according to the fundamental mode syntax table. You can use `.*' in the regexps to match partial field names or words. In other words, all VALUE's are wrapped in `\<' and `\>' pairs. FIELD and VALUE can also be Lisp symbols, in that case they are expanded as specified by the variable `nnmail-split-abbrev-alist'. This is an alist of cons cells, where the CAR of a cell contains the key, and the CDR contains the associated value. Predefined entries in `nnmail-split-abbrev-alist' include: `from' Matches the `From', `Sender' and `Resent-From' fields. `to' Matches the `To', `Cc', `Apparently-To', `Resent-To' and `Resent-Cc' fields. `any' Is the union of the `from' and `to' entries. `nnmail-split-fancy-syntax-table' is the syntax table in effect when all this splitting is performed. If you want to have Gnus create groups dynamically based on some information in the headers (i.e., do `replace-match'-like substitutions in the group names), you can say things like: (any "debian-\\b\\(\\w+\\)@lists.debian.org" "mail.debian.\\1") In this example, messages sent to `debian-foo@lists.debian.org' will be filed in `mail.debian.foo'. If the string contains the element `\&', then the previously matched string will be substituted. Similarly, the elements `\\1' up to `\\9' will be substituted with the text matched by the groupings 1 through 9. Where `nnmail-split-lowercase-expanded' controls whether the lowercase of the matched string should be used for the substitution. Setting it as non-`nil' is useful to avoid the creation of multiple groups when users send to an address using different case (i.e. mailing-list@domain vs Mailing-List@Domain). The default value is `t'. `nnmail-split-fancy-match-partial-words' controls whether partial words are matched during fancy splitting. Normally, regular expressions given in `nnmail-split-fancy' are implicitly surrounded by `\<...\>' markers, which are word delimiters. If this variable is true, they are not implicitly surrounded by anything. (any "joe" "joemail") In this example, messages sent from `joedavis@foo.org' will normally not be filed in `joemail'. With `nnmail-split-fancy-match-partial-words' set to `t', however, the match will happen. In effect, the requirement of a word boundary is removed and instead the match becomes more like a grep. `nnmail-split-fancy-with-parent' is a function which allows you to split followups into the same groups their parents are in. Sometimes you can't make splitting rules for all your mail. For example, your boss might send you personal mail regarding different projects you are working on, and as you can't tell your boss to put a distinguishing string into the subject line, you have to resort to manually moving the messages into the right group. With this function, you only have to do it once per thread. To use this feature, you have to set `nnmail-treat-duplicates' and `nnmail-cache-accepted-message-ids' to a non-`nil' value. And then you can include `nnmail-split-fancy-with-parent' using the colon feature, like so: (setq nnmail-treat-duplicates 'warn ; or `delete' nnmail-cache-accepted-message-ids t nnmail-split-fancy '(| (: nnmail-split-fancy-with-parent) ;; other splits go here )) This feature works as follows: when `nnmail-treat-duplicates' is non-`nil', Gnus records the message id of every message it sees in the file specified by the variable `nnmail-message-id-cache-file', together with the group it is in (the group is omitted for non-mail messages). When mail splitting is invoked, the function `nnmail-split-fancy-with-parent' then looks at the References (and In-Reply-To) header of each message to split and searches the file specified by `nnmail-message-id-cache-file' for the message ids. When it has found a parent, it returns the corresponding group name unless the group name matches the regexp `nnmail-split-fancy-with-parent-ignore-groups'. It is recommended that you set `nnmail-message-id-cache-length' to a somewhat higher number than the default so that the message ids are still in the cache. (A value of 5000 appears to create a file some 300 kBytes in size.) When `nnmail-cache-accepted-message-ids' is non-`nil', Gnus also records the message ids of moved articles, so that the followup messages goes into the new group. Also see the variable `nnmail-cache-ignore-groups' if you don't want certain groups to be recorded in the cache. For example, if all outgoing messages are written to an "outgoing" group, you could set `nnmail-cache-ignore-groups' to match that group name. Otherwise, answers to all your messages would end up in the "outgoing" group.  File: gnus, Node: Group Mail Splitting, Next: Incorporating Old Mail, Prev: Fancy Mail Splitting, Up: Getting Mail Group Mail Splitting -------------------- If you subscribe to dozens of mailing lists but you don't want to maintain mail splitting rules manually, group mail splitting is for you. You just have to set `to-list' and/or `to-address' in group parameters or group customization and set `nnmail-split-methods' to `gnus-group-split'. This splitting function will scan all groups for those parameters and split mail accordingly, i.e., messages posted from or to the addresses specified in the parameters `to-list' or `to-address' of a mail group will be stored in that group. Sometimes, mailing lists have multiple addresses, and you may want mail splitting to recognize them all: just set the `extra-aliases' group parameter to the list of additional addresses and it's done. If you'd rather use a regular expression, set `split-regexp'. All these parameters in a group will be used to create an `nnmail-split-fancy' split, in which the FIELD is `any', the VALUE is a single regular expression that matches `to-list', `to-address', all of `extra-aliases' and all matches of `split-regexp', and the SPLIT is the name of the group. RESTRICTs are also supported: just set the `split-exclude' parameter to a list of regular expressions. If you can't get the right split to be generated using all these parameters, or you just need something fancier, you can set the parameter `split-spec' to an `nnmail-split-fancy' split. In this case, all other aforementioned parameters will be ignored by `gnus-group-split'. In particular, `split-spec' may be set to `nil', in which case the group will be ignored by `gnus-group-split'. `gnus-group-split' will do cross-posting on all groups that match, by defining a single `&' fancy split containing one split for each group. If a message doesn't match any split, it will be stored in the group named in `gnus-group-split-default-catch-all-group', unless some group has `split-spec' set to `catch-all', in which case that group is used as the catch-all group. Even though this variable is often used just to name a group, it may also be set to an arbitrarily complex fancy split (after all, a group name is a fancy split), and this may be useful to split mail that doesn't go to any mailing list to personal mail folders. Note that this fancy split is added as the last element of a `|' split list that also contains a `&' split with the rules extracted from group parameters. It's time for an example. Assume the following group parameters have been defined: nnml:mail.bar: ((to-address . "bar@femail.com") (split-regexp . ".*@femail\\.com")) nnml:mail.foo: ((to-list . "foo@nowhere.gov") (extra-aliases "foo@localhost" "foo-redist@home") (split-exclude "bugs-foo" "rambling-foo") (admin-address . "foo-request@nowhere.gov")) nnml:mail.others: ((split-spec . catch-all)) Setting `nnmail-split-methods' to `gnus-group-split' will behave as if `nnmail-split-fancy' had been selected and variable `nnmail-split-fancy' had been set as follows: (| (& (any "\\(bar@femail\\.com\\|.*@femail\\.com\\)" "mail.bar") (any "\\(foo@nowhere\\.gov\\|foo@localhost\\|foo-redist@home\\)" - "bugs-foo" - "rambling-foo" "mail.foo")) "mail.others") If you'd rather not use group splitting for all your mail groups, you may use it for only some of them, by using `nnmail-split-fancy' splits like this: (: gnus-group-split-fancy GROUPS NO-CROSSPOST CATCH-ALL) GROUPS may be a regular expression or a list of group names whose parameters will be scanned to generate the output split. NO-CROSSPOST can be used to disable cross-posting; in this case, a single `|' split will be output. CATCH-ALL is the fall back fancy split, used like `gnus-group-split-default-catch-all-group'. If CATCH-ALL is `nil', or if `split-regexp' matches the empty string in any selected group, no catch-all split will be issued. Otherwise, if some group has `split-spec' set to `catch-all', this group will override the value of the CATCH-ALL argument. Unfortunately, scanning all groups and their parameters can be quite slow, especially considering that it has to be done for every message. But don't despair! The function `gnus-group-split-setup' can be used to enable `gnus-group-split' in a much more efficient way. It sets `nnmail-split-methods' to `nnmail-split-fancy' and sets `nnmail-split-fancy' to the split produced by `gnus-group-split-fancy'. Thus, the group parameters are only scanned once, no matter how many messages are split. However, if you change group parameters, you'd have to update `nnmail-split-fancy' manually. You can do it by running `gnus-group-split-update'. If you'd rather have it updated automatically, just tell `gnus-group-split-setup' to do it for you. For example, add to your `~/.gnus.el': (gnus-group-split-setup AUTO-UPDATE CATCH-ALL) If AUTO-UPDATE is non-`nil', `gnus-group-split-update' will be added to `nnmail-pre-get-new-mail-hook', so you won't ever have to worry about updating `nnmail-split-fancy' again. If you don't omit CATCH-ALL (it's optional, equivalent to `nil'), `gnus-group-split-default-catch-all-group' will be set to its value. Because you may want to change `nnmail-split-fancy' after it is set by `gnus-group-split-update', this function will run `gnus-group-split-updated-hook' just before finishing.  File: gnus, Node: Incorporating Old Mail, Next: Expiring Mail, Prev: Group Mail Splitting, Up: Getting Mail Incorporating Old Mail ---------------------- Most people have lots of old mail stored in various file formats. If you have set up Gnus to read mail using one of the spiffy Gnus mail back ends, you'll probably wish to have that old mail incorporated into your mail groups. Doing so can be quite easy. To take an example: You're reading mail using `nnml' (*note Mail Spool::), and have set `nnmail-split-methods' to a satisfactory value (*note Splitting Mail::). You have an old Unix mbox file filled with important, but old, mail. You want to move it into your `nnml' groups. Here's how: 1. Go to the group buffer. 2. Type `G f' and give the file name to the mbox file when prompted to create an `nndoc' group from the mbox file (*note Foreign Groups::). 3. Type `SPACE' to enter the newly created group. 4. Type `M P b' to process-mark all articles in this group's buffer (*note Setting Process Marks::). 5. Type `B r' to respool all the process-marked articles, and answer `nnml' when prompted (*note Mail Group Commands::). All the mail messages in the mbox file will now also be spread out over all your `nnml' groups. Try entering them and check whether things have gone without a glitch. If things look ok, you may consider deleting the mbox file, but I wouldn't do that unless I was absolutely sure that all the mail has ended up where it should be. Respooling is also a handy thing to do if you're switching from one mail back end to another. Just respool all the mail in the old mail groups using the new mail back end.  File: gnus, Node: Expiring Mail, Next: Washing Mail, Prev: Incorporating Old Mail, Up: Getting Mail Expiring Mail ------------- Traditional mail readers have a tendency to remove mail articles when you mark them as read, in some way. Gnus takes a fundamentally different approach to mail reading. Gnus basically considers mail just to be news that has been received in a rather peculiar manner. It does not think that it has the power to actually change the mail, or delete any mail messages. If you enter a mail group, and mark articles as "read", or kill them in some other fashion, the mail articles will still exist on the system. I repeat: Gnus will not delete your old, read mail. Unless you ask it to, of course. To make Gnus get rid of your unwanted mail, you have to mark the articles as "expirable". (With the default key bindings, this means that you have to type `E'.) This does not mean that the articles will disappear right away, however. In general, a mail article will be deleted from your system if, 1) it is marked as expirable, AND 2) it is more than one week old. If you do not mark an article as expirable, it will remain on your system until hell freezes over. This bears repeating one more time, with some spurious capitalizations: IF you do NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. You do not have to mark articles as expirable by hand. Gnus provides two features, called "auto-expire" and "total-expire", that can help you with this. In a nutshell, "auto-expire" means that Gnus hits `E' for you when you select an article. And "total-expire" means that Gnus considers all articles as expirable that are read. So, in addition to the articles marked `E', also the articles marked `r', `R', `O', `K', `Y' and so on are considered expirable. When should either auto-expire or total-expire be used? Most people who are subscribed to mailing lists split each list into its own group and then turn on auto-expire or total-expire for those groups. (*Note Splitting Mail::, for more information on splitting each list into its own group.) Which one is better, auto-expire or total-expire? It's not easy to answer. Generally speaking, auto-expire is probably faster. Another advantage of auto-expire is that you get more marks to work with: for the articles that are supposed to stick around, you can still choose between tick and dormant and read marks. But with total-expire, you only have dormant and ticked to choose from. The advantage of total-expire is that it works well with adaptive scoring (*note Adaptive Scoring::). Auto-expire works with normal scoring but not with adaptive scoring. Groups that match the regular expression `gnus-auto-expirable-newsgroups' will have all articles that you read marked as expirable automatically. All articles marked as expirable have an `E' in the first column in the summary buffer. By default, if you have auto expiry switched on, Gnus will mark all the articles you read as expirable, no matter if they were read or unread before. To avoid having articles marked as read marked as expirable automatically, you can put something like the following in your `~/.gnus.el' file: (remove-hook 'gnus-mark-article-hook 'gnus-summary-mark-read-and-unread-as-read) (add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) Note that making a group auto-expirable doesn't mean that all read articles are expired--only the articles marked as expirable will be expired. Also note that using the `d' command won't make articles expirable--only semi-automatic marking of articles as read will mark the articles as expirable in auto-expirable groups. Let's say you subscribe to a couple of mailing lists, and you want the articles you have read to disappear after a while: (setq gnus-auto-expirable-newsgroups "mail.nonsense-list\\|mail.nice-list") Another way to have auto-expiry happen is to have the element `auto-expire' in the group parameters of the group. If you use adaptive scoring (*note Adaptive Scoring::) and auto-expiring, you'll have problems. Auto-expiring and adaptive scoring don't really mix very well. The `nnmail-expiry-wait' variable supplies the default time an expirable article has to live. Gnus starts counting days from when the message _arrived_, not from when it was sent. The default is seven days. Gnus also supplies a function that lets you fine-tune how long articles are to live, based on what group they are in. Let's say you want to have one month expiry period in the `mail.private' group, a one day expiry period in the `mail.junk' group, and a six day expiry period everywhere else: (setq nnmail-expiry-wait-function (lambda (group) (cond ((string= group "mail.private") 31) ((string= group "mail.junk") 1) ((string= group "important") 'never) (t 6)))) The group names this function is fed are "unadorned" group names--no `nnml:' prefixes and the like. The `nnmail-expiry-wait' variable and `nnmail-expiry-wait-function' function can either be a number (not necessarily an integer) or one of the symbols `immediate' or `never'. You can also use the `expiry-wait' group parameter to selectively change the expiry period (*note Group Parameters::). The normal action taken when expiring articles is to delete them. However, in some circumstances it might make more sense to move them to other groups instead of deleting them. The variable `nnmail-expiry-target' (and the `expiry-target' group parameter) controls this. The variable supplies a default value for all groups, which can be overridden for specific groups by the group parameter. default value is `delete', but this can also be a string (which should be the name of the group the message should be moved to), or a function (which will be called in a buffer narrowed to the message in question, and with the name of the group being moved from as its parameter) which should return a target--either a group name or `delete'. Here's an example for specifying a group name: (setq nnmail-expiry-target "nnml:expired") Gnus provides a function `nnmail-fancy-expiry-target' which will expire mail to groups according to the variable `nnmail-fancy-expiry-targets'. Here's an example: (setq nnmail-expiry-target 'nnmail-fancy-expiry-target nnmail-fancy-expiry-targets '((to-from "boss" "nnfolder:Work") ("subject" "IMPORTANT" "nnfolder:IMPORTANT.%Y.%b") ("from" ".*" "nnfolder:Archive-%Y"))) With this setup, any mail that has `IMPORTANT' in its Subject header and was sent in the year `YYYY' and month `MMM', will get expired to the group `nnfolder:IMPORTANT.YYYY.MMM'. If its From or To header contains the string `boss', it will get expired to `nnfolder:Work'. All other mail will get expired to `nnfolder:Archive-YYYY'. If `nnmail-keep-last-article' is non-`nil', Gnus will never expire the final article in a mail newsgroup. This is to make life easier for procmail users. By the way: That line up there, about Gnus never expiring non-expirable articles, is a lie. If you put `total-expire' in the group parameters, articles will not be marked as expirable, but all read articles will be put through the expiry process. Use with extreme caution. Even more dangerous is the `gnus-total-expirable-newsgroups' variable. All groups that match this regexp will have all read articles put through the expiry process, which means that _all_ old mail articles in the groups in question will be deleted after a while. Use with extreme caution, and don't come crying to me when you discover that the regexp you used matched the wrong group and all your important mail has disappeared. Be a _man_! Or a _woman_! Whatever you feel more comfortable with! So there! Most people make most of their mail groups total-expirable, though. If `gnus-inhibit-user-auto-expire' is non-`nil', user marking commands will not mark an article as expirable, even if the group has auto-expire turned on.  File: gnus, Node: Washing Mail, Next: Duplicates, Prev: Expiring Mail, Up: Getting Mail Washing Mail ------------ Mailers and list servers are notorious for doing all sorts of really, really stupid things with mail. "Hey, RFC 822 doesn't explicitly prohibit us from adding the string `wE aRe ElItE!!!!!1!!' to the end of all lines passing through our server, so let's do that!!!!1!" Yes, but RFC 822 wasn't designed to be read by morons. Things that were considered to be self-evident were not discussed. So. Here we are. Case in point: The German version of Microsoft Exchange adds `AW: ' to the subjects of replies instead of `Re: '. I could pretend to be shocked and dismayed by this, but I haven't got the energy. It is to laugh. Gnus provides a plethora of functions for washing articles while displaying them, but it might be nicer to do the filtering before storing the mail to disk. For that purpose, we have three hooks and various functions that can be put in these hooks. `nnmail-prepare-incoming-hook' This hook is called before doing anything with the mail and is meant for grand, sweeping gestures. It is called in a buffer that contains all the new, incoming mail. Functions to be used include: `nnheader-ms-strip-cr' Remove trailing carriage returns from each line. This is default on Emacs running on MS machines. `nnmail-prepare-incoming-header-hook' This hook is called narrowed to each header. It can be used when cleaning up the headers. Functions that can be used include: `nnmail-remove-leading-whitespace' Clear leading white space that "helpful" listservs have added to the headers to make them look nice. Aaah. (Note that this function works on both the header on the body of all messages, so it is a potentially dangerous function to use (if a body of a message contains something that looks like a header line). So rather than fix the bug, it is of course the right solution to make it into a feature by documenting it.) `nnmail-remove-list-identifiers' Some list servers add an identifier--for example, `(idm)'--to the beginning of all `Subject' headers. I'm sure that's nice for people who use stone age mail readers. This function will remove strings that match the `nnmail-list-identifiers' regexp, which can also be a list of regexp. `nnmail-list-identifiers' may not contain `\\(..\\)'. For instance, if you want to remove the `(idm)' and the `nagnagnag' identifiers: (setq nnmail-list-identifiers '("(idm)" "nagnagnag")) This can also be done non-destructively with `gnus-list-identifiers', *Note Article Hiding::. `nnmail-remove-tabs' Translate all `TAB' characters into `SPACE' characters. `nnmail-fix-eudora-headers' Eudora produces broken `References' headers, but OK `In-Reply-To' headers. This function will get rid of the `References' headers. `nnmail-prepare-incoming-message-hook' This hook is called narrowed to each message. Functions to be used include: `article-de-quoted-unreadable' Decode Quoted Readable encoding.  File: gnus, Node: Duplicates, Next: Not Reading Mail, Prev: Washing Mail, Up: Getting Mail Duplicates ---------- If you are a member of a couple of mailing lists, you will sometimes receive two copies of the same mail. This can be quite annoying, so `nnmail' checks for and treats any duplicates it might find. To do this, it keeps a cache of old `Message-ID's-- `nnmail-message-id-cache-file', which is `~/.nnmail-cache' by default. The approximate maximum number of `Message-ID's stored there is controlled by the `nnmail-message-id-cache-length' variable, which is 1000 by default. (So 1000 `Message-ID's will be stored.) If all this sounds scary to you, you can set `nnmail-treat-duplicates' to `warn' (which is what it is by default), and `nnmail' won't delete duplicate mails. Instead it will insert a warning into the head of the mail saying that it thinks that this is a duplicate of a different message. This variable can also be a function. If that's the case, the function will be called from a buffer narrowed to the message in question with the `Message-ID' as a parameter. The function must return either `nil', `warn', or `delete'. You can turn this feature off completely by setting the variable to `nil'. If you want all the duplicate mails to be put into a special "duplicates" group, you could do that using the normal mail split methods: (setq nnmail-split-fancy '(| ;; Messages duplicates go to a separate group. ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate") ;; Message from daemons, postmaster, and the like to another. (any mail "mail.misc") ;; Other rules. [...] )) Or something like: (setq nnmail-split-methods '(("duplicates" "^Gnus-Warning:.*duplicate") ;; Other rules. [...])) Here's a neat feature: If you know that the recipient reads her mail with Gnus, and that she has `nnmail-treat-duplicates' set to `delete', you can send her as many insults as you like, just by using a `Message-ID' of a mail that you know that she's already received. Think of all the fun! She'll never see any of it! Whee!  File: gnus, Node: Not Reading Mail, Next: Choosing a Mail Back End, Prev: Duplicates, Up: Getting Mail Not Reading Mail ---------------- If you start using any of the mail back ends, they have the annoying habit of assuming that you want to read mail with them. This might not be unreasonable, but it might not be what you want. If you set `mail-sources' and `nnmail-spool-file' to `nil', none of the back ends will ever attempt to read incoming mail, which should help. This might be too much, if, for instance, you are reading mail quite happily with `nnml' and just want to peek at some old Rmail file you have stashed away with `nnbabyl'. All back ends have variables called back-end-`get-new-mail'. If you want to disable the `nnbabyl' mail reading, you edit the virtual server for the group to have a setting where `nnbabyl-get-new-mail' to `nil'. All the mail back ends will call `nn'*`-prepare-save-mail-hook' narrowed to the article to be saved before saving it when reading incoming mail.  File: gnus, Node: Choosing a Mail Back End, Prev: Not Reading Mail, Up: Getting Mail Choosing a Mail Back End ------------------------ Gnus will read the mail spool when you activate a mail group. The mail file is first copied to your home directory. What happens after that depends on what format you want to store your mail in. There are six different mail back ends in the standard Gnus, and more back ends are available separately. The mail back end most people use (because it is possibly the fastest) is `nnml' (*note Mail Spool::). * Menu: * Unix Mail Box:: Using the (quite) standard Un*x mbox. * Rmail Babyl:: Emacs programs use the Rmail Babyl format. * Mail Spool:: Store your mail in a private spool? * MH Spool:: An mhspool-like back end. * Maildir:: Another one-file-per-message format. * Mail Folders:: Having one file for each group. * Comparing Mail Back Ends:: An in-depth looks at pros and cons.  File: gnus, Node: Unix Mail Box, Next: Rmail Babyl, Up: Choosing a Mail Back End Unix Mail Box ............. The "nnmbox" back end will use the standard Un*x mbox file to store mail. `nnmbox' will add extra headers to each mail article to say which group it belongs in. Virtual server settings: `nnmbox-mbox-file' The name of the mail box in the user's home directory. Default is `~/mbox'. `nnmbox-active-file' The name of the active file for the mail box. Default is `~/.mbox-active'. `nnmbox-get-new-mail' If non-`nil', `nnmbox' will read incoming mail and split it into groups. Default is `t'.  File: gnus, Node: Rmail Babyl, Next: Mail Spool, Prev: Unix Mail Box, Up: Choosing a Mail Back End Rmail Babyl ........... The "nnbabyl" back end will use a Babyl mail box (aka. "Rmail mbox") to store mail. `nnbabyl' will add extra headers to each mail article to say which group it belongs in. Virtual server settings: `nnbabyl-mbox-file' The name of the Rmail mbox file. The default is `~/RMAIL' `nnbabyl-active-file' The name of the active file for the rmail box. The default is `~/.rmail-active' `nnbabyl-get-new-mail' If non-`nil', `nnbabyl' will read incoming mail. Default is `t'  File: gnus, Node: Mail Spool, Next: MH Spool, Prev: Rmail Babyl, Up: Choosing a Mail Back End Mail Spool .......... The "nnml" spool mail format isn't compatible with any other known format. It should be used with some caution. If you use this back end, Gnus will split all incoming mail into files, one file for each mail, and put the articles into the corresponding directories under the directory specified by the `nnml-directory' variable. The default value is `~/Mail/'. You do not have to create any directories beforehand; Gnus will take care of all that. If you have a strict limit as to how many files you are allowed to store in your account, you should not use this back end. As each mail gets its own file, you might very well occupy thousands of inodes within a few weeks. If this is no problem for you, and it isn't a problem for you having your friendly systems administrator walking around, madly, shouting "Who is eating all my inodes?! Who? Who!?!", then you should know that this is probably the fastest format to use. You do not have to trudge through a big mbox file just to read your new mail. `nnml' is probably the slowest back end when it comes to article splitting. It has to create lots of files, and it also generates NOV databases for the incoming mails. This makes it possibly the fastest back end when it comes to reading mail. When the marks file is used (which it is by default), `nnml' servers have the property that you may backup them using `tar' or similar, and later be able to restore them into Gnus (by adding the proper `nnml' server) and have all your marks be preserved. Marks for a group is usually stored in the `.marks' file (but see `nnml-marks-file-name') within each `nnml' group's directory. Individual `nnml' groups are also possible to backup, use `G m' to restore the group (after restoring the backup into the nnml directory). If for some reason you believe your `.marks' files are screwed up, you can just delete them all. Gnus will then correctly regenerate them next time it starts. Virtual server settings: `nnml-directory' All `nnml' directories will be placed under this directory. The default is the value of `message-directory' (whose default value is `~/Mail'). `nnml-active-file' The active file for the `nnml' server. The default is `~/Mail/active'. `nnml-newsgroups-file' The `nnml' group descriptions file. *Note Newsgroups File Format::. The default is `~/Mail/newsgroups'. `nnml-get-new-mail' If non-`nil', `nnml' will read incoming mail. The default is `t'. `nnml-nov-is-evil' If non-`nil', this back end will ignore any NOV files. The default is `nil'. `nnml-nov-file-name' The name of the NOV files. The default is `.overview'. `nnml-prepare-save-mail-hook' Hook run narrowed to an article before saving. `nnml-marks-is-evil' If non-`nil', this back end will ignore any MARKS files. The default is `nil'. `nnml-marks-file-name' The name of the "marks" files. The default is `.marks'. `nnml-use-compressed-files' If non-`nil', `nnml' will allow using compressed message files. This variable requires `auto-compression-mode' to be enabled (*note Compressed Files: (emacs)Compressed Files.) `nnml-compressed-files-size-threshold' Default size threshold for compressed message files. Message files with bodies larger than that many characters will be automatically compressed if `nnml-use-compressed-files' is non-nil. If your `nnml' groups and NOV files get totally out of whack, you can do a complete update by typing `M-x nnml-generate-nov-databases'. This command will trawl through the entire `nnml' hierarchy, looking at each and every article, so it might take a while to complete. A better interface to this functionality can be found in the server buffer (*note Server Commands::).  File: gnus, Node: MH Spool, Next: Maildir, Prev: Mail Spool, Up: Choosing a Mail Back End MH Spool ........ `nnmh' is just like `nnml', except that is doesn't generate NOV databases and it doesn't keep an active file or marks file. This makes `nnmh' a _much_ slower back end than `nnml', but it also makes it easier to write procmail scripts for. Virtual server settings: `nnmh-directory' All `nnmh' directories will be located under this directory. The default is the value of `message-directory' (whose default is `~/Mail') `nnmh-get-new-mail' If non-`nil', `nnmh' will read incoming mail. The default is `t'. `nnmh-be-safe' If non-`nil', `nnmh' will go to ridiculous lengths to make sure that the articles in the folder are actually what Gnus thinks they are. It will check date stamps and stat everything in sight, so setting this to `t' will mean a serious slow-down. If you never use anything but Gnus to read the `nnmh' articles, you do not have to set this variable to `t'. The default is `nil'.  File: gnus, Node: Maildir, Next: Mail Folders, Prev: MH Spool, Up: Choosing a Mail Back End Maildir ....... `nnmaildir' stores mail in the maildir format, with each maildir corresponding to a group in Gnus. This format is documented here: `http://cr.yp.to/proto/maildir.html' and here: `http://www.qmail.org/man/man5/maildir.html'. `nnmaildir' also stores extra information in the `.nnmaildir/' directory within a maildir. Maildir format was designed to allow concurrent deliveries and reading, without needing locks. With other back ends, you would have your mail delivered to a spool of some kind, and then you would configure Gnus to split mail from that spool into your groups. You can still do that with `nnmaildir', but the more common configuration is to have your mail delivered directly to the maildirs that appear as group in Gnus. `nnmaildir' is designed to be perfectly reliable: `C-g' will never corrupt its data in memory, and `SIGKILL' will never corrupt its data in the filesystem. `nnmaildir' stores article marks and NOV data in each maildir. So you can copy a whole maildir from one Gnus setup to another, and you will keep your marks. Virtual server settings: `directory' For each of your `nnmaildir' servers (it's very unlikely that you'd need more than one), you need to create a directory and populate it with maildirs or symlinks to maildirs (and nothing else; do not choose a directory already used for other purposes). Each maildir will be represented in Gnus as a newsgroup on that server; the filename of the symlink will be the name of the group. Any filenames in the directory starting with `.' are ignored. The directory is scanned when you first start Gnus, and each time you type `g' in the group buffer; if any maildirs have been removed or added, `nnmaildir' notices at these times. The value of the `directory' parameter should be a Lisp form which is processed by `eval' and `expand-file-name' to get the path of the directory for this server. The form is `eval'ed only when the server is opened; the resulting string is used until the server is closed. (If you don't know about forms and `eval', don't worry--a simple string will work.) This parameter is not optional; you must specify it. I don't recommend using `"~/Mail"' or a subdirectory of it; several other parts of Gnus use that directory by default for various things, and may get confused if `nnmaildir' uses it too. `"~/.nnmaildir"' is a typical value. `target-prefix' This should be a Lisp form which is processed by `eval' and `expand-file-name'. The form is `eval'ed only when the server is opened; the resulting string is used until the server is closed. When you create a group on an `nnmaildir' server, the maildir is created with `target-prefix' prepended to its name, and a symlink pointing to that maildir is created, named with the plain group name. So if `directory' is `"~/.nnmaildir"' and `target-prefix' is `"../maildirs/"', then when you create the group `foo', `nnmaildir' will create `~/.nnmaildir/../maildirs/foo' as a maildir, and will create `~/.nnmaildir/foo' as a symlink pointing to `../maildirs/foo'. You can set `target-prefix' to a string without any slashes to create both maildirs and symlinks in the same `directory'; in this case, any maildirs found in `directory' whose names start with `target-prefix' will not be listed as groups (but the symlinks pointing to them will be). As a special case, if `target-prefix' is `""' (the default), then when you create a group, the maildir will be created in `directory' without a corresponding symlink. Beware that you cannot use `gnus-group-delete-group' on such groups without the `force' argument. `directory-files' This should be a function with the same interface as `directory-files' (such as `directory-files' itself). It is used to scan the server's `directory' for maildirs. This parameter is optional; the default is `nnheader-directory-files-safe' if `nnheader-directory-files-is-safe' is `nil', and `directory-files' otherwise. (`nnheader-directory-files-is-safe' is checked only once when the server is opened; if you want to check it each time the directory is scanned, you'll have to provide your own function that does that.) `get-new-mail' If non-`nil', then after scanning for new mail in the group maildirs themselves as usual, this server will also incorporate mail the conventional Gnus way, from `mail-sources' according to `nnmail-split-methods' or `nnmail-split-fancy'. The default value is `nil'. Do _not_ use the same maildir both in `mail-sources' and as an `nnmaildir' group. The results might happen to be useful, but that would be by chance, not by design, and the results might be different in the future. If your split rules create new groups, remember to supply a `create-directory' server parameter. Group parameters ................ `nnmaildir' uses several group parameters. It's safe to ignore all this; the default behavior for `nnmaildir' is the same as the default behavior for other mail back ends: articles are deleted after one week, etc. Except for the expiry parameters, all this functionality is unique to `nnmaildir', so you can ignore it if you're just trying to duplicate the behavior you already have with another back end. If the value of any of these parameters is a vector, the first element is evaluated as a Lisp form and the result is used, rather than the original value. If the value is not a vector, the value itself is evaluated as a Lisp form. (This is why these parameters use names different from those of other, similar parameters supported by other back ends: they have different, though similar, meanings.) (For numbers, strings, `nil', and `t', you can ignore the `eval' business again; for other values, remember to use an extra quote and wrap the value in a vector when appropriate.) `expire-age' An integer specifying the minimum age, in seconds, of an article before it will be expired, or the symbol `never' to specify that articles should never be expired. If this parameter is not set, `nnmaildir' falls back to the usual `nnmail-expiry-wait'(`-function') variables (the `expiry-wait' group parameter overrides `nnmail-expiry-wait' and makes `nnmail-expiry-wait-function' ineffective). If you wanted a value of 3 days, you could use something like `[(* 3 24 60 60)]'; `nnmaildir' will evaluate the form and use the result. An article's age is measured starting from the article file's modification time. Normally, this is the same as the article's delivery time, but editing an article makes it younger. Moving an article (other than via expiry) may also make an article younger. `expire-group' If this is set to a string such as a full Gnus group name, like "backend+server.address.string:group.name" and if it is not the name of the same group that the parameter belongs to, then articles will be moved to the specified group during expiry before being deleted. _If this is set to an `nnmaildir' group, the article will be just as old in the destination group as it was in the source group._ So be careful with `expire-age' in the destination group. If this is set to the name of the same group that the parameter belongs to, then the article is not expired at all. If you use the vector form, the first element is evaluated once for each article. So that form can refer to `nnmaildir-article-file-name', etc., to decide where to put the article. _Even if this parameter is not set, `nnmaildir' does not fall back to the `expiry-target' group parameter or the `nnmail-expiry-target' variable._ `read-only' If this is set to `t', `nnmaildir' will treat the articles in this maildir as read-only. This means: articles are not renamed from `new/' into `cur/'; articles are only found in `new/', not `cur/'; articles are never deleted; articles cannot be edited. `new/' is expected to be a symlink to the `new/' directory of another maildir--e.g., a system-wide mailbox containing a mailing list of common interest. Everything in the maildir outside `new/' is _not_ treated as read-only, so for a shared mailbox, you do still need to set up your own maildir (or have write permission to the shared mailbox); your maildir just won't contain extra copies of the articles. `directory-files' A function with the same interface as `directory-files'. It is used to scan the directories in the maildir corresponding to this group to find articles. The default is the function specified by the server's `directory-files' parameter. `distrust-Lines:' If non-`nil', `nnmaildir' will always count the lines of an article, rather than use the `Lines:' header field. If `nil', the header field will be used if present. `always-marks' A list of mark symbols, such as `['(read expire)]'. Whenever Gnus asks `nnmaildir' for article marks, `nnmaildir' will say that all articles have these marks, regardless of whether the marks stored in the filesystem say so. This is a proof-of-concept feature that will probably be removed eventually; it ought to be done in Gnus proper, or abandoned if it's not worthwhile. `never-marks' A list of mark symbols, such as `['(tick expire)]'. Whenever Gnus asks `nnmaildir' for article marks, `nnmaildir' will say that no articles have these marks, regardless of whether the marks stored in the filesystem say so. `never-marks' overrides `always-marks'. This is a proof-of-concept feature that will probably be removed eventually; it ought to be done in Gnus proper, or abandoned if it's not worthwhile. `nov-cache-size' An integer specifying the size of the NOV memory cache. To speed things up, `nnmaildir' keeps NOV data in memory for a limited number of articles in each group. (This is probably not worthwhile, and will probably be removed in the future.) This parameter's value is noticed only the first time a group is seen after the server is opened--i.e., when you first start Gnus, typically. The NOV cache is never resized until the server is closed and reopened. The default is an estimate of the number of articles that would be displayed in the summary buffer: a count of articles that are either marked with `tick' or not marked with `read', plus a little extra. Article identification ...................... Articles are stored in the `cur/' subdirectory of each maildir. Each article file is named like `uniq:info', where `uniq' contains no colons. `nnmaildir' ignores, but preserves, the `:info' part. (Other maildir readers typically use this part of the filename to store marks.) The `uniq' part uniquely identifies the article, and is used in various places in the `.nnmaildir/' subdirectory of the maildir to store information about the corresponding article. The full pathname of an article is available in the variable `nnmaildir-article-file-name' after you request the article in the summary buffer. NOV data ........ An article identified by `uniq' has its NOV data (used to generate lines in the summary buffer) stored in `.nnmaildir/nov/uniq'. There is no `nnmaildir-generate-nov-databases' function. (There isn't much need for it--an article's NOV data is updated automatically when the article or `nnmail-extra-headers' has changed.) You can force `nnmaildir' to regenerate the NOV data for a single article simply by deleting the corresponding NOV file, but _beware_: this will also cause `nnmaildir' to assign a new article number for this article, which may cause trouble with `seen' marks, the Agent, and the cache. Article marks ............. An article identified by `uniq' is considered to have the mark `flag' when the file `.nnmaildir/marks/flag/uniq' exists. When Gnus asks `nnmaildir' for a group's marks, `nnmaildir' looks for such files and reports the set of marks it finds. When Gnus asks `nnmaildir' to store a new set of marks, `nnmaildir' creates and deletes the corresponding files as needed. (Actually, rather than create a new file for each mark, it just creates hard links to `.nnmaildir/markfile', to save inodes.) You can invent new marks by creating a new directory in `.nnmaildir/marks/'. You can tar up a maildir and remove it from your server, untar it later, and keep your marks. You can add and remove marks yourself by creating and deleting mark files. If you do this while Gnus is running and your `nnmaildir' server is open, it's best to exit all summary buffers for `nnmaildir' groups and type `s' in the group buffer first, and to type `g' or `M-g' in the group buffer afterwards. Otherwise, Gnus might not pick up the changes, and might undo them.  File: gnus, Node: Mail Folders, Next: Comparing Mail Back Ends, Prev: Maildir, Up: Choosing a Mail Back End Mail Folders ............ `nnfolder' is a back end for storing each mail group in a separate file. Each file is in the standard Un*x mbox format. `nnfolder' will add extra headers to keep track of article numbers and arrival dates. When the marks file is used (which it is by default), `nnfolder' servers have the property that you may backup them using `tar' or similar, and later be able to restore them into Gnus (by adding the proper `nnfolder' server) and have all your marks be preserved. Marks for a group is usually stored in a file named as the mbox file with `.mrk' concatenated to it (but see `nnfolder-marks-file-suffix') within the `nnfolder' directory. Individual `nnfolder' groups are also possible to backup, use `G m' to restore the group (after restoring the backup into the `nnfolder' directory). Virtual server settings: `nnfolder-directory' All the `nnfolder' mail boxes will be stored under this directory. The default is the value of `message-directory' (whose default is `~/Mail') `nnfolder-active-file' The name of the active file. The default is `~/Mail/active'. `nnfolder-newsgroups-file' The name of the group descriptions file. *Note Newsgroups File Format::. The default is `~/Mail/newsgroups' `nnfolder-get-new-mail' If non-`nil', `nnfolder' will read incoming mail. The default is `t' `nnfolder-save-buffer-hook' Hook run before saving the folders. Note that Emacs does the normal backup renaming of files even with the `nnfolder' buffers. If you wish to switch this off, you could say something like the following in your `.emacs' file: (defun turn-off-backup () (set (make-local-variable 'backup-inhibited) t)) (add-hook 'nnfolder-save-buffer-hook 'turn-off-backup) `nnfolder-delete-mail-hook' Hook run in a buffer narrowed to the message that is to be deleted. This function can be used to copy the message to somewhere else, or to extract some information from it before removing it. `nnfolder-nov-is-evil' If non-`nil', this back end will ignore any NOV files. The default is `nil'. `nnfolder-nov-file-suffix' The extension for NOV files. The default is `.nov'. `nnfolder-nov-directory' The directory where the NOV files should be stored. If `nil', `nnfolder-directory' is used. `nnfolder-marks-is-evil' If non-`nil', this back end will ignore any MARKS files. The default is `nil'. `nnfolder-marks-file-suffix' The extension for MARKS files. The default is `.mrk'. `nnfolder-marks-directory' The directory where the MARKS files should be stored. If `nil', `nnfolder-directory' is used. If you have lots of `nnfolder'-like files you'd like to read with `nnfolder', you can use the `M-x nnfolder-generate-active-file' command to make `nnfolder' aware of all likely files in `nnfolder-directory'. This only works if you use long file names, though.  File: gnus, Node: Comparing Mail Back Ends, Prev: Mail Folders, Up: Choosing a Mail Back End Comparing Mail Back Ends ........................ First, just for terminology, the "back end" is the common word for a low-level access method--a transport, if you will, by which something is acquired. The sense is that one's mail has to come from somewhere, and so selection of a suitable back end is required in order to get that mail within spitting distance of Gnus. The same concept exists for Usenet itself: Though access to articles is typically done by NNTP these days, once upon a midnight dreary, everyone in the world got at Usenet by running a reader on the machine where the articles lay (the machine which today we call an NNTP server), and access was by the reader stepping into the articles' directory spool area directly. One can still select between either the `nntp' or `nnspool' back ends, to select between these methods, if one happens actually to live on the server (or can see its spool directly, anyway, via NFS). The goal in selecting a mail back end is to pick one which simultaneously represents a suitable way of dealing with the original format plus leaving mail in a form that is convenient to use in the future. Here are some high and low points on each: `nnmbox' UNIX systems have historically had a single, very common, and well- defined format. All messages arrive in a single "spool file", and they are delineated by a line whose regular expression matches `^From_'. (My notational use of `_' is to indicate a space, to make it clear in this instance that this is not the RFC-specified `From:' header.) Because Emacs and therefore Gnus emanate historically from the Unix environment, it is simplest if one does not mess a great deal with the original mailbox format, so if one chooses this back end, Gnus' primary activity in getting mail from the real spool area to Gnus' preferred directory is simply to copy it, with no (appreciable) format change in the process. It is the "dumbest" way to move mail into availability in the Gnus environment. This makes it fast to move into place, but slow to parse, when Gnus has to look at what's where. `nnbabyl' Once upon a time, there was the DEC-10 and DEC-20, running operating systems called TOPS and related things, and the usual (only?) mail reading environment was a thing called Babyl. I don't know what format was used for mail landing on the system, but Babyl had its own internal format to which mail was converted, primarily involving creating a spool-file-like entity with a scheme for inserting Babyl-specific headers and status bits above the top of each message in the file. Rmail was Emacs' first mail reader, it was written by Richard Stallman, and Stallman came out of that TOPS/Babyl environment, so he wrote Rmail to understand the mail files folks already had in existence. Gnus (and VM, for that matter) continue to support this format because it's perceived as having some good qualities in those mailer-specific headers/status bits stuff. Rmail itself still exists as well, of course, and is still maintained by Stallman. Both of the above forms leave your mail in a single file on your file system, and they must parse that entire file each time you take a look at your mail. `nnml' `nnml' is the back end which smells the most as though you were actually operating with an `nnspool'-accessed Usenet system. (In fact, I believe `nnml' actually derived from `nnspool' code, lo these years ago.) One's mail is taken from the original spool file, and is then cut up into individual message files, 1:1. It maintains a Usenet-style active file (analogous to what one finds in an INN- or CNews-based news system in (for instance) `/var/lib/news/active', or what is returned via the `NNTP LIST' verb) and also creates "overview" files for efficient group entry, as has been defined for NNTP servers for some years now. It is slower in mail-splitting, due to the creation of lots of files, updates to the `nnml' active file, and additions to overview files on a per-message basis, but it is extremely fast on access because of what amounts to the indexing support provided by the active file and overviews. `nnml' costs "inodes" in a big way; that is, it soaks up the resource which defines available places in the file system to put new files. Sysadmins take a dim view of heavy inode occupation within tight, shared file systems. But if you live on a personal machine where the file system is your own and space is not at a premium, `nnml' wins big. It is also problematic using this back end if you are living in a FAT16-based Windows world, since much space will be wasted on all these tiny files. `nnmh' The Rand MH mail-reading system has been around UNIX systems for a very long time; it operates by splitting one's spool file of messages into individual files, but with little or no indexing support--`nnmh' is considered to be semantically equivalent to "`nnml' without active file or overviews". This is arguably the worst choice, because one gets the slowness of individual file creation married to the slowness of access parsing when learning what's new in one's groups. `nnfolder' Basically the effect of `nnfolder' is `nnmbox' (the first method described above) on a per-group basis. That is, `nnmbox' itself puts _all_ one's mail in one file; `nnfolder' provides a little bit of optimization to this so that each of one's mail groups has a Unix mail box file. It's faster than `nnmbox' because each group can be parsed separately, and still provides the simple Unix mail box format requiring minimal effort in moving the mail around. In addition, it maintains an "active" file making it much faster for Gnus to figure out how many messages there are in each separate group. If you have groups that are expected to have a massive amount of messages, `nnfolder' is not the best choice, but if you receive only a moderate amount of mail, `nnfolder' is probably the most friendly mail back end all over. `nnmaildir' For configuring expiry and other things, `nnmaildir' uses incompatible group parameters, slightly different from those of other mail back ends. `nnmaildir' is largely similar to `nnml', with some notable differences. Each message is stored in a separate file, but the filename is unrelated to the article number in Gnus. `nnmaildir' also stores the equivalent of `nnml''s overview files in one file per article, so it uses about twice as many inodes as `nnml'. (Use `df -i' to see how plentiful your inode supply is.) If this slows you down or takes up very much space, consider switching to ReiserFS (http://www.namesys.com/) or another non-block-structured file system. Since maildirs don't require locking for delivery, the maildirs you use as groups can also be the maildirs your mail is directly delivered to. This means you can skip Gnus' mail splitting if your mail is already organized into different mailboxes during delivery. A `directory' entry in `mail-sources' would have a similar effect, but would require one set of mailboxes for spooling deliveries (in mbox format, thus damaging message bodies), and another set to be used as groups (in whatever format you like). A maildir has a built-in spool, in the `new/' subdirectory. Beware that currently, mail moved from `new/' to `cur/' instead of via mail splitting will not undergo treatment such as duplicate checking. `nnmaildir' stores article marks for a given group in the corresponding maildir, in a way designed so that it's easy to manipulate them from outside Gnus. You can tar up a maildir, unpack it somewhere else, and still have your marks. `nnml' also stores marks, but it's not as easy to work with them from outside Gnus as with `nnmaildir'. `nnmaildir' uses a significant amount of memory to speed things up. (It keeps in memory some of the things that `nnml' stores in files and that `nnmh' repeatedly parses out of message files.) If this is a problem for you, you can set the `nov-cache-size' group parameter to something small (0 would probably not work, but 1 probably would) to make it use less memory. This caching will probably be removed in the future. Startup is likely to be slower with `nnmaildir' than with other back ends. Everything else is likely to be faster, depending in part on your file system. `nnmaildir' does not use `nnoo', so you cannot use `nnoo' to write an `nnmaildir'-derived back end.  File: gnus, Node: Browsing the Web, Next: IMAP, Prev: Getting Mail, Up: Select Methods Browsing the Web ================ Web-based discussion forums are getting more and more popular. On many subjects, the web-based forums have become the most important forums, eclipsing the importance of mailing lists and news groups. The reason is easy to understand--they are friendly to new users; you just point and click, and there's the discussion. With mailing lists, you have to go through a cumbersome subscription procedure, and most people don't even know what a news group is. The problem with this scenario is that web browsers are not very good at being newsreaders. They do not keep track of what articles you've read; they do not allow you to score on subjects you're interested in; they do not allow off-line browsing; they require you to click around and drive you mad in the end. So--if web browsers suck at reading discussion forums, why not use Gnus to do it instead? Gnus has been getting a bit of a collection of back ends for providing interfaces to these sources. * Menu: * Archiving Mail:: * Web Searches:: Creating groups from articles that match a string. * Slashdot:: Reading the Slashdot comments. * Ultimate:: The Ultimate Bulletin Board systems. * Web Archive:: Reading mailing list archived on web. * RSS:: Reading RDF site summary. * Customizing W3:: Doing stuff to Emacs/W3 from Gnus. All the web sources require Emacs/W3 and the url library or those alternatives to work. The main caveat with all these web sources is that they probably won't work for a very long time. Gleaning information from the HTML data is guesswork at best, and when the layout is altered, the Gnus back end will fail. If you have reasonably new versions of these back ends, though, you should be ok. One thing all these Web methods have in common is that the Web sources are often down, unavailable or just plain too slow to be fun. In those cases, it makes a lot of sense to let the Gnus Agent (*note Gnus Unplugged::) handle downloading articles, and then you can read them at leisure from your local disk. No more World Wide Wait for you.  File: gnus, Node: Archiving Mail, Next: Web Searches, Up: Browsing the Web Archiving Mail -------------- Some of the back ends, notably `nnml', `nnfolder', and `nnmaildir', now actually store the article marks with each group. For these servers, archiving and restoring a group while preserving marks is fairly simple. (Preserving the group level and group parameters as well still requires ritual dancing and sacrifices to the `.newsrc.eld' deity though.) To archive an entire `nnml', `nnfolder', or `nnmaildir' server, take a recursive copy of the server directory. There is no need to shut down Gnus, so archiving may be invoked by `cron' or similar. You restore the data by restoring the directory tree, and adding a server definition pointing to that directory in Gnus. The *Note Article Backlog::, *Note Asynchronous Fetching:: and other things might interfere with overwriting data, so you may want to shut down Gnus before you restore the data. It is also possible to archive individual `nnml', `nnfolder', or `nnmaildir' groups, while preserving marks. For `nnml' or `nnmaildir', you copy all files in the group's directory. For `nnfolder' you need to copy both the base folder file itself (`FOO', say), and the marks file (`FOO.mrk' in this example). Restoring the group is done with `G m' from the Group buffer. The last step makes Gnus notice the new directory. `nnmaildir' notices the new directory automatically, so `G m' is unnecessary in that case.  File: gnus, Node: Web Searches, Next: Slashdot, Prev: Archiving Mail, Up: Browsing the Web Web Searches ------------ It's, like, too neat to search the Usenet for articles that match a string, but it, like, totally _sucks_, like, totally, to use one of those, like, Web browsers, and you, like, have to, rilly, like, look at the commercials, so, like, with Gnus you can do _rad_, rilly, searches without having to use a browser. The `nnweb' back end allows an easy interface to the mighty search engine. You create an `nnweb' group, enter a search pattern, and then enter the group and read the articles like you would any normal group. The `G w' command in the group buffer (*note Foreign Groups::) will do this in an easy-to-use fashion. `nnweb' groups don't really lend themselves to being solid groups--they have a very fleeting idea of article numbers. In fact, each time you enter an `nnweb' group (not even changing the search pattern), you are likely to get the articles ordered in a different manner. Not even using duplicate suppression (*note Duplicate Suppression::) will help, since `nnweb' doesn't even know the `Message-ID' of the articles before reading them using some search engines (Google, for instance). The only possible way to keep track of which articles you've read is by scoring on the `Date' header--mark all articles posted before the last date you read the group as read. If the search engine changes its output substantially, `nnweb' won't be able to parse it and will fail. One could hardly fault the Web providers if they were to do this--their _raison d'être_ is to make money off of advertisements, not to provide services to the community. Since `nnweb' washes the ads off all the articles, one might think that the providers might be somewhat miffed. We'll see. You must have the `url' and `W3' package or those alternatives (try `customize-group' on the `mm-url' variable group) installed to be able to use `nnweb'. Virtual server variables: `nnweb-type' What search engine type is being used. The currently supported types are `google', `dejanews', and `gmane'. Note that `dejanews' is an alias to `google'. `nnweb-search' The search string to feed to the search engine. `nnweb-max-hits' Advisory maximum number of hits per search to display. The default is 999. `nnweb-type-definition' Type-to-definition alist. This alist says what `nnweb' should do with the various search engine types. The following elements must be present: `article' Function to decode the article and provide something that Gnus understands. `map' Function to create an article number to message header and URL alist. `search' Function to send the search string to the search engine. `address' The address the aforementioned function should send the search string to. `id' Format string URL to fetch an article by `Message-ID'.  File: gnus, Node: Slashdot, Next: Ultimate, Prev: Web Searches, Up: Browsing the Web Slashdot -------- Slashdot (http://slashdot.org/) is a popular news site, with lively discussion following the news articles. `nnslashdot' will let you read this forum in a convenient manner. The easiest way to read this source is to put something like the following in your `~/.gnus.el' file: (setq gnus-secondary-select-methods '((nnslashdot ""))) This will make Gnus query the `nnslashdot' back end for new comments and groups. The `F' command will subscribe each new news article as a new Gnus group, and you can read the comments by entering these groups. (Note that the default subscription method is to subscribe new groups as zombies. Other methods are available (*note Subscription Methods::). If you want to remove an old `nnslashdot' group, the `G DEL' command is the most handy tool (*note Foreign Groups::). When following up to `nnslashdot' comments (or posting new comments), some light HTMLizations will be performed. In particular, text quoted with `> ' will be quoted with `blockquote' instead, and signatures will have `br' added to the end of each line. Other than that, you can just write HTML directly into the message buffer. Note that Slashdot filters out some HTML forms. The following variables can be altered to change its behavior: `nnslashdot-threaded' Whether `nnslashdot' should display threaded groups or not. The default is `t'. To be able to display threads, `nnslashdot' has to retrieve absolutely all comments in a group upon entry. If a threaded display is not required, `nnslashdot' will only retrieve the comments that are actually wanted by the user. Threading is nicer, but much, much slower than unthreaded. `nnslashdot-login-name' The login name to use when posting. `nnslashdot-password' The password to use when posting. `nnslashdot-directory' Where `nnslashdot' will store its files. The default is `~/News/slashdot/'. `nnslashdot-active-url' The URL format string that will be used to fetch the information on news articles and comments. The default is `http://slashdot.org/search.pl?section=&min=%d'. `nnslashdot-comments-url' The URL format string that will be used to fetch comments. `nnslashdot-article-url' The URL format string that will be used to fetch the news article. The default is `http://slashdot.org/article.pl?sid=%s&mode=nocomment'. `nnslashdot-threshold' The score threshold. The default is -1. `nnslashdot-group-number' The number of old groups, in addition to the ten latest, to keep updated. The default is 0.  File: gnus, Node: Ultimate, Next: Web Archive, Prev: Slashdot, Up: Browsing the Web Ultimate -------- The Ultimate Bulletin Board (http://www.ultimatebb.com/) is probably the most popular Web bulletin board system used. It has a quite regular and nice interface, and it's possible to get the information Gnus needs to keep groups updated. The easiest way to get started with `nnultimate' is to say something like the following in the group buffer: `B nnultimate RET http://www.tcj.com/messboard/ubbcgi/ RET'. (Substitute the URL (not including `Ultimate.cgi' or the like at the end) for a forum you're interested in; there's quite a list of them on the Ultimate web site.) Then subscribe to the groups you're interested in from the server buffer, and read them from the group buffer. The following `nnultimate' variables can be altered: `nnultimate-directory' The directory where `nnultimate' stores its files. The default is `~/News/ultimate/'.  File: gnus, Node: Web Archive, Next: RSS, Prev: Ultimate, Up: Browsing the Web 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 web sites have an RDF Site Summary (RSS). RSS is a format for summarizing headlines from news related sites (such as BBC or CNN). But basically anything list-like can be presented as an RSS feed: weblogs, changelogs or recent changes to a wiki (e.g. ). RSS has a quite regular and nice interface, and it's possible to get the information Gnus needs to keep groups updated. Note: you had better use Emacs which supports the `utf-8' coding system because RSS uses UTF-8 for encoding non-ASCII text by default. It is also used by default for non-ASCII group names. Use `G R' from the group buffer to subscribe to a feed--you will be prompted for the location, the title and the description of the feed. The title, which allows any characters, will be used for the group name and the name of the group data file. The description can be omitted. An easy way to get started with `nnrss' is to say something like the following in the group buffer: `B nnrss RET RET y', then subscribe to groups. The `nnrss' back end saves the group data file in `nnrss-directory' (see below) for each `nnrss' group. File names containing non-ASCII characters will be encoded by the coding system specified with the `nnmail-pathname-coding-system' variable. If it is `nil', in Emacs the coding system defaults to the value of `default-file-name-coding-system'. If you are using XEmacs and want to use non-ASCII group names, you should set the value for the `nnmail-pathname-coding-system' variable properly. You can also use the following commands to import and export your subscriptions from a file in OPML format (Outline Processor Markup Language). - Function: nnrss-opml-import file Prompt for an OPML file, and subscribe to each feed in the file. - Function: nnrss-opml-export Write your current RSS subscriptions to a buffer in OPML format. The following `nnrss' variables can be altered: `nnrss-directory' The directory where `nnrss' stores its files. The default is `~/News/rss/'. `nnrss-file-coding-system' The coding system used when reading and writing the `nnrss' groups data files. The default is the value of `mm-universal-coding-system' (which defaults to `emacs-mule' in Emacs or `escape-quoted' in XEmacs). `nnrss-use-local' If you set `nnrss-use-local' to `t', `nnrss' will read the feeds from local files in `nnrss-directory'. You can use the command `nnrss-generate-download-script' to generate a download script using `wget'. 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 "") '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 (or those alternatives) to display web pages. Emacs/W3 is documented in its own manual, but there are some things that may be more relevant for Gnus users. For instance, a common question is how to make Emacs/W3 follow links using the `browse-url' functions (which will call some external web browser like Netscape). Here's one way: (eval-after-load "w3" '(progn (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) (defun w3-fetch (&optional url target) (interactive (list (w3-read-url-with-default))) (if (eq major-mode 'gnus-article-mode) (browse-url url) (w3-fetch-orig url target))))) Put that in your `.emacs' file, and hitting links in W3-rendered HTML in the Gnus article buffers will use `browse-url' to follow the link.  File: gnus, Node: IMAP, Next: Other Sources, Prev: Browsing the Web, Up: Select Methods IMAP ==== IMAP is a network protocol for reading mail (or news, or ...), think of it as a modernized NNTP. Connecting to a IMAP server is much similar to connecting to a news server, you just specify the network address of the server. IMAP has two properties. First, IMAP can do everything that POP can, it can hence be viewed as a POP++. Secondly, IMAP is a mail storage protocol, similar to NNTP being a news storage protocol--however, IMAP offers more features than NNTP because news is more or less read-only whereas mail is read-write. If you want to use IMAP as a POP++, use an imap entry in `mail-sources'. With this, Gnus will fetch mails from the IMAP server and store them on the local disk. This is not the usage described in this section--*Note Mail Sources::. If you want to use IMAP as a mail storage protocol, use an nnimap entry in `gnus-secondary-select-methods'. With this, Gnus will manipulate mails stored on the IMAP server. This is the kind of usage explained in this section. A server configuration in `~/.gnus.el' with a few IMAP servers might look something like the following. (Note that for TLS/SSL, you need external programs and libraries, see below.) (setq gnus-secondary-select-methods '((nnimap "simpleserver") ; no special configuration ; perhaps a ssh port forwarded server: (nnimap "dolk" (nnimap-address "localhost") (nnimap-server-port 1430)) ; a UW server running on localhost (nnimap "barbar" (nnimap-server-port 143) (nnimap-address "localhost") (nnimap-list-pattern ("INBOX" "mail/*"))) ; anonymous public cyrus server: (nnimap "cyrus.andrew.cmu.edu" (nnimap-authenticator anonymous) (nnimap-list-pattern "archive.*") (nnimap-stream network)) ; a ssl server on a non-standard port: (nnimap "vic20" (nnimap-address "vic20.somewhere.com") (nnimap-server-port 9930) (nnimap-stream ssl)))) After defining the new server, you can subscribe to groups on the server using normal Gnus commands such as `U' in the Group Buffer (*note Subscription Commands::) or via the Server Buffer (*note Server Buffer::). The following variables can be used to create a virtual `nnimap' server: `nnimap-address' The address of the remote IMAP server. Defaults to the virtual server name if not specified. `nnimap-server-port' Port on server to contact. Defaults to port 143, or 993 for TLS/SSL. Note that this should be an integer, example server specification: (nnimap "mail.server.com" (nnimap-server-port 4711)) `nnimap-list-pattern' String or list of strings of mailboxes to limit available groups to. This is used when the server has very many mailboxes and you're only interested in a few--some servers export your home directory via IMAP, you'll probably want to limit the mailboxes to those in `~/Mail/*' then. The string can also be a cons of REFERENCE and the string as above, what REFERENCE is used for is server specific, but on the University of Washington server it's a directory that will be concatenated with the mailbox. Example server specification: (nnimap "mail.server.com" (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" ("~friend/Mail/" . "list/*")))) `nnimap-stream' The type of stream used to connect to your server. By default, nnimap will detect and automatically use all of the below, with the exception of TLS/SSL. (IMAP over TLS/SSL is being replaced by STARTTLS, which can be automatically detected, but it's not widely deployed yet.) Example server specification: (nnimap "mail.server.com" (nnimap-stream ssl)) Please note that the value of `nnimap-stream' is a symbol! * "gssapi:" Connect with GSSAPI (usually Kerberos 5). Requires the `gsasl' or `imtest' program. * "kerberos4:" Connect with Kerberos 4. Requires the `imtest' program. * "starttls:" Connect via the STARTTLS extension (similar to TLS/SSL). Requires the external library `starttls.el' and program `starttls'. * "tls:" Connect through TLS. Requires GNUTLS (the program `gnutls-cli'). * "ssl:" Connect through SSL. Requires OpenSSL (the program `openssl') or SSLeay (`s_client'). * "shell:" Use a shell command to start IMAP connection. * "network:" Plain, TCP/IP network connection. The `imtest' program is shipped with Cyrus IMAPD. If you're using `imtest' from Cyrus IMAPD < 2.0.14 (which includes version 1.5.x and 1.6.x) you need to frob `imap-process-connection-type' to make `imap.el' use a pty instead of a pipe when communicating with `imtest'. You will then suffer from a line length restrictions on IMAP commands, which might make Gnus seem to hang indefinitely if you have many articles in a mailbox. The variable `imap-kerberos4-program' contain parameters to pass to the imtest program. For TLS connection, the `gnutls-cli' program from GNUTLS is needed. It is available from `http://www.gnu.org/software/gnutls/'. This parameter specifies a list of command lines that invoke a GSSAPI authenticated IMAP stream in a subshell. They are tried sequentially until a connection is made, or the list has been exhausted. By default, `gsasl' from GNU SASL, available from `http://www.gnu.org/software/gsasl/', and the `imtest' program from Cyrus IMAPD (see `imap-kerberos4-program'), are tried. For SSL connections, the OpenSSL program is available from `http://www.openssl.org/'. OpenSSL was formerly known as SSLeay, and nnimap support it too--although the most recent versions of SSLeay, 0.9.x, are known to have serious bugs making it useless. Earlier versions, especially 0.8.x, of SSLeay are known to work. The variable `imap-ssl-program' contain parameters to pass to OpenSSL/SSLeay. For IMAP connections using the `shell' stream, the variable `imap-shell-program' specify what program to call. `nnimap-authenticator' The authenticator used to connect to the server. By default, nnimap will use the most secure authenticator your server is capable of. Example server specification: (nnimap "mail.server.com" (nnimap-authenticator anonymous)) Please note that the value of `nnimap-authenticator' is a symbol! * "gssapi:" GSSAPI (usually kerberos 5) authentication. Requires external program `gsasl' or `imtest'. * "kerberos4:" Kerberos 4 authentication. Requires external program `imtest'. * "digest-md5:" Encrypted username/password via DIGEST-MD5. Requires external library `digest-md5.el'. * "cram-md5:" Encrypted username/password via CRAM-MD5. * "login:" Plain-text username/password via LOGIN. * "anonymous:" Login as "anonymous", supplying your email address as password. `nnimap-expunge-on-close' Unlike Parmenides the IMAP designers have decided things that don't exist actually do exist. More specifically, IMAP has this concept of marking articles `Deleted' which doesn't actually delete them, and this (marking them `Deleted', that is) is what nnimap does when you delete an article in Gnus (with `B DEL' or similar). Since the articles aren't really removed when we mark them with the `Deleted' flag we'll need a way to actually delete them. Feel like running in circles yet? Traditionally, nnimap has removed all articles marked as `Deleted' when closing a mailbox but this is now configurable by this server variable. The possible options are: `always' The default behavior, delete all articles marked as "Deleted" when closing a mailbox. `never' Never actually delete articles. Currently there is no way of showing the articles marked for deletion in nnimap, but other IMAP clients may allow you to do this. If you ever want to run the EXPUNGE command manually, *Note Expunging mailboxes::. `ask' When closing mailboxes, nnimap will ask if you wish to expunge deleted articles or not. `nnimap-importantize-dormant' If non-`nil' (the default), marks dormant articles as ticked (as well), for other IMAP clients. Within Gnus, dormant articles will naturally still (only) be marked as dormant. This is to make dormant articles stand out, just like ticked articles, in other IMAP clients. (In other words, Gnus has two "Tick" marks and IMAP has only one.) Probably the only reason for frobing this would be if you're trying enable per-user persistent dormant flags, using something like: (setcdr (assq 'dormant nnimap-mark-to-flag-alist) (format "gnus-dormant-%s" (user-login-name))) (setcdr (assq 'dormant nnimap-mark-to-predicate-alist) (format "KEYWORD gnus-dormant-%s" (user-login-name))) In this case, you would not want the per-user dormant flag showing up as ticked for other users. `nnimap-expunge-search-string' This variable contain the IMAP search command sent to server when searching for articles eligible for expiring. The default is `"UID %s NOT SINCE %s"', where the first `%s' is replaced by UID set and the second `%s' is replaced by a date. Probably the only useful value to change this to is `"UID %s NOT SENTSINCE %s"', which makes nnimap use the Date: in messages instead of the internal article date. See section 6.4.4 of RFC 2060 for more information on valid strings. `nnimap-authinfo-file' A file containing credentials used to log in on servers. The format is (almost) the same as the `ftp' `~/.netrc' file. See the variable `nntp-authinfo-file' for exact syntax; also see *Note NNTP::. An example of an .authinfo line for an IMAP server, is: machine students.uio.no login larsi password geheimnis port imap Note that it should be `port imap', or `port 143', if you use a `nnimap-stream' of `tls' or `ssl', even if the actual port number used is port 993 for secured IMAP. For convenience, Gnus will accept `port imaps' as a synonym of `port imap'. `nnimap-need-unselect-to-notice-new-mail' Unselect mailboxes before looking for new mail in them. Some servers seem to need this under some circumstances; it was reported that Courier 1.7.1 did. * Menu: * Splitting in IMAP:: Splitting mail with nnimap. * Expiring in IMAP:: Expiring mail with nnimap. * Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. * Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. * A note on namespaces:: How to (not) use IMAP namespace in Gnus. * Debugging IMAP:: What to do when things don't work.  File: gnus, Node: Splitting in IMAP, Next: Expiring in IMAP, Up: IMAP Splitting in IMAP ----------------- Splitting is something Gnus users have loved and used for years, and now the rest of the world is catching up. Yeah, dream on, not many IMAP servers have server side splitting and those that have splitting seem to use some non-standard protocol. This means that IMAP support for Gnus has to do its own splitting. And it does. (Incidentally, people seem to have been dreaming on, and Sieve has gaining a market share and is supported by several IMAP servers. Fortunately, Gnus support it too, *Note Sieve Commands::.) Here are the variables of interest: `nnimap-split-crosspost' If non-`nil', do crossposting if several split methods match the mail. If `nil', the first match in `nnimap-split-rule' found will be used. Nnmail equivalent: `nnmail-crosspost'. `nnimap-split-inbox' A string or a list of strings that gives the name(s) of IMAP mailboxes to split from. Defaults to `nil', which means that splitting is disabled! (setq nnimap-split-inbox '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap")) No nnmail equivalent. `nnimap-split-rule' New mail found in `nnimap-split-inbox' will be split according to this variable. This variable contains a list of lists, where the first element in the sublist gives the name of the IMAP mailbox to move articles matching the regexp in the second element in the sublist. Got that? Neither did I, we need examples. (setq nnimap-split-rule '(("INBOX.nnimap" "^Sender: owner-nnimap@vic20.globalcom.se") ("INBOX.junk" "^Subject:.*MAKE MONEY") ("INBOX.private" ""))) This will put all articles from the nnimap mailing list into mailbox INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line into INBOX.junk and everything else in INBOX.private. The first string may contain `\\1' forms, like the ones used by replace-match to insert sub-expressions from the matched text. For instance: ("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@") The first element can also be the symbol `junk' to indicate that matching messages should simply be deleted. Use with care. The second element can also be a function. In that case, it will be called with the first element of the rule as the argument, in a buffer containing the headers of the article. It should return a non-`nil' value if it thinks that the mail belongs in that group. Nnmail users might recollect that the last regexp had to be empty to match all articles (like in the example above). This is not required in nnimap. Articles not matching any of the regexps will not be moved out of your inbox. (This might affect performance if you keep lots of unread articles in your inbox, since the splitting code would go over them every time you fetch new mail.) These rules are processed from the beginning of the alist toward the end. The first rule to make a match will "win", unless you have crossposting enabled. In that case, all matching rules will "win". This variable can also have a function as its value, the function will be called with the headers narrowed and should return a group where it thinks the article should be split to. See `nnimap-split-fancy'. The splitting code tries to create mailboxes if it needs to. To allow for different split rules on different virtual servers, and even different split rules in different inboxes on the same server, the syntax of this variable have been extended along the lines of: (setq nnimap-split-rule '(("my1server" (".*" (("ding" "ding@gnus.org") ("junk" "From:.*Simon")))) ("my2server" ("INBOX" nnimap-split-fancy)) ("my[34]server" (".*" (("private" "To:.*Simon") ("junk" my-junk-func)))))) The virtual server name is in fact a regexp, so that the same rules may apply to several servers. In the example, the servers `my3server' and `my4server' both use the same rules. Similarly, the inbox string is also a regexp. The actual splitting rules are as before, either a function, or a list with group/regexp or group/function elements. Nnmail equivalent: `nnmail-split-methods'. `nnimap-split-predicate' Mail matching this predicate in `nnimap-split-inbox' will be split, it is a string and the default is `UNSEEN UNDELETED'. This might be useful if you use another IMAP client to read mail in your inbox but would like Gnus to split all articles in the inbox regardless of readedness. Then you might change this to `UNDELETED'. `nnimap-split-fancy' It's possible to set `nnimap-split-rule' to `nnmail-split-fancy' if you want to use fancy splitting. *Note Fancy Mail Splitting::. However, to be able to have different fancy split rules for nnmail and nnimap back ends you can set `nnimap-split-rule' to `nnimap-split-fancy' and define the nnimap specific fancy split rule in `nnimap-split-fancy'. Example: (setq nnimap-split-rule 'nnimap-split-fancy nnimap-split-fancy ...) Nnmail equivalent: `nnmail-split-fancy'. `nnimap-split-download-body' Set to non-`nil' to download entire articles during splitting. This is generally not required, and will slow things down considerably. You may need it if you want to use an advanced splitting function that analyzes the body to split the article.  File: gnus, Node: Expiring in IMAP, Next: Editing IMAP ACLs, Prev: Splitting in IMAP, Up: IMAP 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, Next: Debugging IMAP, Prev: Expunging mailboxes, Up: IMAP A note on namespaces -------------------- The IMAP protocol has a concept called namespaces, described by the following text in the RFC2060: 5.1.2. Mailbox Namespace Naming Convention By convention, the first hierarchical element of any mailbox name which begins with "#" identifies the "namespace" of the remainder of the name. This makes it possible to disambiguate between different types of mailbox stores, each of which have their own namespaces. For example, implementations which offer access to USENET newsgroups MAY use the "#news" namespace to partition the USENET newsgroup namespace from that of other mailboxes. Thus, the comp.mail.misc newsgroup would have an mailbox name of "#news.comp.mail.misc", and the name "comp.mail.misc" could refer to a different object (e.g. a user's private mailbox). While there is nothing in this text that warrants concern for the IMAP implementation in Gnus, some servers use namespace prefixes in a way that does not work with how Gnus uses mailbox names. Specifically, University of Washington's IMAP server uses mailbox names like `#driver.mbx/read-mail' which are valid only in the CREATE and APPEND commands. After the mailbox is created (or a messages is appended to a mailbox), it must be accessed without the namespace prefix, i.e. `read-mail'. Since Gnus do not make it possible for the user to guarantee that user entered mailbox names will only be used with the CREATE and APPEND commands, you should simply not use the namespace prefixed mailbox names in Gnus. See the UoW IMAPD documentation for the `#driver.*/' prefix for more information on how to use the prefixes. They are a power tool and should be used only if you are sure what the effects are.  File: gnus, Node: Debugging IMAP, Prev: A note on namespaces, Up: IMAP Debugging IMAP -------------- IMAP is a complex protocol, more so than NNTP or POP3. Implementation bugs are not unlikely, and we do our best to fix them right away. If you encounter odd behavior, chances are that either the server or Gnus is buggy. If you are familiar with network protocols in general, you will probably be able to extract some clues from the protocol dump of the exchanges between Gnus and the server. Even if you are not familiar with network protocols, when you include the protocol dump in IMAP-related bug reports you are helping us with data critical to solving the problem. Therefore, we strongly encourage you to include the protocol dump when reporting IMAP bugs in Gnus. Because the protocol dump, when enabled, generates lots of data, it is disabled by default. You can enable it by setting `imap-log' as follows: (setq imap-log t) This instructs the `imap.el' package to log any exchanges with the server. The log is stored in the buffer `*imap-log*'. Look for error messages, which sometimes are tagged with the keyword `BAD'--but when submitting a bug, make sure to include all the data.  File: gnus, Node: Other Sources, Next: Combined Groups, Prev: IMAP, Up: Select Methods 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. `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. To do more complicated things that cannot be dealt with a simple regexp, you can use `article-begin-function' instead of this. `article-begin-function' If present, this should be a function that moves point to the beginning of each article. This setting overrides `article-begin'. `head-begin' If present, this should be a regexp that matches the head of the article. To do more complicated things that cannot be dealt with a simple regexp, you can use `head-begin-function' instead of this. `head-begin-function' If present, this should be a function that moves point to the head of the article. This setting overrides `head-begin'. `head-end' This should match the end of the head of the article. It defaults to `^$'--the empty line. `body-begin' This should match the beginning of the body of the article. It defaults to `^\n'. To do more complicated things that cannot be dealt with a simple regexp, you can use `body-begin-function' instead of this. `body-begin-function' If present, this function should move point to the beginning of the body of the article. This setting overrides `body-begin'. `body-end' If present, this should match the end of the body of the article. To do more complicated things that cannot be dealt with a simple regexp, you can use `body-end-function' instead of this. `body-end-function' If present, this function should move point to the end of the body of the article. This setting overrides `body-end'. `file-begin' If present, this should match the beginning of the file. All text before this regexp will be totally ignored. `file-end' If present, this should match the end of the file. All text after this regexp will be totally ignored. So, using these variables `nndoc' is able to dissect a document file into a series of articles, each with a head and a body. However, a few more variables are needed since not all document types are all that news-like--variables needed to transform the head or the body into something that's palatable for Gnus: `prepare-body-function' If present, this function will be called when requesting an article. It will be called with point at the start of the body, and is useful if the document has encoded some parts of its contents. `article-transform-function' If present, this function is called when requesting an article. It's meant to be used for more wide-ranging transformation of both head and body of the article. `generate-head-function' If present, this function is called to generate a head that Gnus can understand. It is called with the article number as a parameter, and is expected to generate a nice head for the article in question. It is called when requesting the headers of all articles. `generate-article-function' If present, this function is called to generate an entire article that Gnus can understand. It is called with the article number as a parameter when requesting all articles. `dissection-function' If present, this function is called to dissect a document by itself, overriding `first-article', `article-begin', `article-begin-function', `head-begin', `head-begin-function', `head-end', `body-begin', `body-begin-function', `body-end', `body-end-function', `file-begin', and `file-end'. Let's look at the most complicated example I can come up with--standard digests: (standard-digest (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+")) (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+")) (prepare-body-function . nndoc-unquote-dashes) (body-end-function . nndoc-digest-body-end) (head-end . "^ ?$") (body-begin . "^ ?\n") (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$") (subtype digest guess)) We see that all text before a 70-width line of dashes is ignored; all text after a line that starts with that `^End of' is also ignored; each article begins with a 30-width line of dashes; the line separating the head from the body may contain a single space; and that the body is run through `nndoc-unquote-dashes' before being delivered. To hook your own document definition into `nndoc', use the `nndoc-add-type' function. It takes two parameters--the first is the definition itself and the second (optional) parameter says where in the document type definition alist to put this definition. The alist is traversed sequentially, and `nndoc-TYPE-type-p' is called for a given type TYPE. So `nndoc-mmdf-type-p' is called to see whether a document is of `mmdf' type, and so on. These type predicates should return `nil' if the document is not of the correct type; `t' if it is of the correct type; and a number if the document might be of the correct type. A high number means high probability; a low number means low probability with `0' being the lowest valid number.  File: gnus, Node: SOUP, Next: Mail-To-News Gateways, Prev: Document Groups, Up: Other Sources 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: Email Based Diary, 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.). To create an empty virtual group, run `G V' (`gnus-group-make-empty-virtual') in the group buffer and edit the method regexp with `M-e' (`gnus-group-edit-group-method') Here's an example `nnvirtual' method that collects all Andrea Dworkin newsgroups into one, big, happy newsgroup: (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") The component groups can be native or foreign; everything should work smoothly, but if your computer explodes, it was probably my fault. Collecting the same group from several servers might actually be a good idea if users have set the Distribution header to limit distribution. If you would like to read `soc.motss' both from a server in Japan and a server in Norway, you could use the following as the group regexp: "^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" (Remember, though, that if you're creating the group with `G m', you shouldn't double the backslashes, and you should leave off the quote characters at the beginning and the end of the string.) This should work kinda smoothly--all articles from both groups should end up in this one, and there should be no duplicates. Threading (and the rest) will still work as usual, but there might be problems with the sequence of articles. Sorting on date might be an option here (*note Selecting a Group::). One limitation, however--all groups included in a virtual group have to be alive (i.e., subscribed or unsubscribed). Killed or zombie groups can't be component groups for `nnvirtual' groups. If the `nnvirtual-always-rescan' 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-n' in the message buffer will insert the `Newsgroups' line from the article you respond to in these cases. `nnvirtual' groups do not inherit anything but articles and marks from component groups--group parameters, for instance, are not inherited.  File: gnus, Node: Kibozed Groups, Prev: Virtual Groups, Up: Combined Groups Kibozed Groups -------------- "Kibozing" is defined by the OED as "grepping through (parts of) the news feed". `nnkiboze' is a back end that will do this for you. Oh joy! Now you can grind any NNTP server down to a halt with useless requests! Oh happiness! To create a kibozed group, use the `G k' command in the group buffer. The address field of the `nnkiboze' method is, as with `nnvirtual', a regexp to match groups to be "included" in the `nnkiboze' group. That's where most similarities between `nnkiboze' and `nnvirtual' end. In addition to this regexp detailing component groups, an `nnkiboze' group must have a score file to say what articles are to be included in the group (*note Scoring::). You must run `M-x nnkiboze-generate-groups' after creating the `nnkiboze' groups you want to have. This command will take time. Lots of time. Oodles and oodles of time. Gnus has to fetch the headers from all the articles in all the component groups and run them through the scoring process to determine if there are any articles in the groups that are to be part of the `nnkiboze' groups. Please limit the number of component groups by using restrictive regexps. Otherwise your sysadmin may become annoyed with you, and the NNTP site may throw you off and never let you back in again. Stranger things have happened. `nnkiboze' component groups do not have to be alive--they can be dead, and they can be foreign. No restrictions. The generation of an `nnkiboze' group means writing two files in `nnkiboze-directory', which is `~/News/kiboze/' by default. One contains the NOV header lines for all the articles in the group, and the other is an additional `.newsrc' file to store information on what groups have been searched through to find component articles. Articles marked as read in the `nnkiboze' group will have their NOV lines removed from the NOV file.  File: gnus, Node: Email Based Diary, Next: Gnus Unplugged, Prev: Combined Groups, Up: Select Methods Email Based Diary ================= This section describes a special mail back end called `nndiary', and its companion library `gnus-diary'. It is "special" in the sense that it is not meant to be one of the standard alternatives for reading mail with Gnus. See *Note Choosing a Mail Back End:: for that. Instead, it is used to treat _some_ of your mails in a special way, namely, as event reminders. Here is a typical scenario: * You've got a date with Andy Mc Dowell or Bruce Willis (select according to your sexual preference) in one month. You don't want to forget it. * So you send a "reminder" message (actually, a diary one) to yourself. * You forget all about it and keep on getting and reading new mail, as usual. * From time to time, as you type `g' in the group buffer and as the date is getting closer, the message will pop up again to remind you of your appointment, just as if it were new and unread. * Read your "new" messages, this one included, and start dreaming again of the night you're gonna have. * Once the date is over (you actually fell asleep just after dinner), the message will be automatically deleted if it is marked as expirable. The Gnus Diary back end has the ability to handle regular appointments (that wouldn't ever be deleted) as well as punctual ones, operates as a real mail back end and is configurable in many ways. All of this is explained in the sections below. * Menu: * The NNDiary Back End:: Basic setup and usage. * The Gnus Diary Library:: Utility toolkit on top of nndiary. * Sending or Not Sending:: A final note on sending diary messages.  File: gnus, Node: The NNDiary Back End, Next: The Gnus Diary Library, Up: Email Based Diary The NNDiary Back End -------------------- `nndiary' is a back end very similar to `nnml' (*note Mail Spool::). Actually, it could appear as a mix of `nnml' and `nndraft'. If you know `nnml', you're already familiar with the message storing scheme of `nndiary': one file per message, one directory per group. Before anything, there is one requirement to be able to run `nndiary' properly: you _must_ use the group timestamp feature of Gnus. This adds a timestamp to each group's parameters. *Note Group Timestamp:: to see how it's done. * Menu: * Diary Messages:: What makes a message valid for nndiary. * Running NNDiary:: NNDiary has two modes of operation. * Customizing NNDiary:: Bells and whistles.  File: gnus, Node: Diary Messages, Next: Running NNDiary, Up: The NNDiary Back End Diary Messages .............. `nndiary' messages are just normal ones, except for the mandatory presence of 7 special headers. These headers are of the form `X-Diary-', `' being one of `Minute', `Hour', `Dom', `Month', `Year', `Time-Zone' and `Dow'. `Dom' means "Day of Month", and `dow' means "Day of Week". These headers actually behave like crontab specifications and define the event date(s): * For all headers except the `Time-Zone' one, a header value is either a star (meaning all possible values), or a list of fields (separated by a comma). * A field is either an integer, or a range. * A range is two integers separated by a dash. * Possible integer values are 0-59 for `Minute', 0-23 for `Hour', 1-31 for `Dom', 1-12 for `Month', above 1971 for `Year' and 0-6 for `Dow' (0 meaning Sunday). * As a special case, a star in either `Dom' or `Dow' doesn't mean "all possible values", but "use only the other field". Note that if both are star'ed, the use of either one gives the same result. * The `Time-Zone' header is special in that it can only have one value (`GMT', for instance). A star doesn't mean "all possible values" (because it makes no sense), but "the current local time zone". Most of the time, you'll be using a star here. However, for a list of available time zone values, see the variable `nndiary-headers'. As a concrete example, here are the diary headers to add to your message for specifying "Each Monday and each 1st of month, at 12:00, 20:00, 21:00, 22:00, 23:00 and 24:00, from 1999 to 2010" (I'll let you find what to do then): X-Diary-Minute: 0 X-Diary-Hour: 12, 20-24 X-Diary-Dom: 1 X-Diary-Month: * X-Diary-Year: 1999-2010 X-Diary-Dow: 1 X-Diary-Time-Zone: *  File: gnus, Node: Running NNDiary, Next: Customizing NNDiary, Prev: Diary Messages, Up: The NNDiary Back End Running NNDiary ............... `nndiary' has two modes of operation: "traditional" (the default) and "autonomous". In traditional mode, `nndiary' does not get new mail by itself. You have to move (`B m') or copy (`B c') mails from your primary mail back end to nndiary groups in order to handle them as diary messages. In autonomous mode, `nndiary' retrieves its own mail and handles it independently from your primary mail back end. One should note that Gnus is not inherently designed to allow several "master" mail back ends at the same time. However, this does make sense with `nndiary': you really want to send and receive diary messages to your diary groups directly. So, `nndiary' supports being sort of a "second primary mail back end" (to my knowledge, it is the only back end offering this feature). However, there is a limitation (which I hope to fix some day): respooling doesn't work in autonomous mode. In order to use `nndiary' in autonomous mode, you have several things to do: * Allow `nndiary' to retrieve new mail by itself. Put the following line in your `gnusrc' file: (setq nndiary-get-new-mail t) * You must arrange for diary messages (those containing `X-Diary-*' headers) to be split in a private folder _before_ Gnus treat them. Again, this is needed because Gnus cannot (yet ?) properly handle multiple primary mail back ends. Getting those messages from a separate source will compensate this misfeature to some extent. As an example, here's my procmailrc entry to store diary files in `~/.nndiary' (the default `nndiary' mail source file): :0 HD : * ^X-Diary .nndiary Once this is done, you might want to customize the following two options that affect the diary mail retrieval and splitting processes: - Variable: nndiary-mail-sources This is the diary-specific replacement for the standard `mail-sources' variable. It obeys the same syntax, and defaults to `(file :path "~/.nndiary")'. - Variable: nndiary-split-methods This is the diary-specific replacement for the standard `nnmail-split-methods' variable. It obeys the same syntax. Finally, you may add a permanent `nndiary' virtual server (something like `(nndiary "diary")' should do) to your `gnus-secondary-select-methods'. Hopefully, almost everything (see the TODO section in `nndiary.el') will work as expected when you restart Gnus: in autonomous mode, typing `g' and `M-g' in the group buffer, will also get your new diary mails and split them according to your diary-specific rules, `F' will find your new diary groups etc.  File: gnus, Node: Customizing NNDiary, Prev: Running NNDiary, Up: The NNDiary Back End Customizing NNDiary ................... Now that `nndiary' is up and running, it's time to customize it. The custom group is called `nndiary' (no, really ?!). You should browse it to figure out which options you'd like to tweak. The following two variables are probably the only ones you will want to change: - Variable: nndiary-reminders This is the list of times when you want to be reminded of your appointements (e.g. 3 weeks before, then 2 days before, then 1 hour before and that's it). Remember that "being reminded" means that the diary message will pop up as brand new and unread again when you get new mail. - Variable: nndiary-week-starts-on-monday Rather self-explanatory. Otherwise, Sunday is assumed (this is the default).  File: gnus, Node: The Gnus Diary Library, Next: Sending or Not Sending, Prev: The NNDiary Back End, Up: Email Based Diary The Gnus Diary Library ---------------------- Using `nndiary' manually (I mean, writing the headers by hand and so on) would be rather boring. Fortunately, there is a library called `gnus-diary' written on top of `nndiary', that does many useful things for you. In order to use it, add the following line to your `gnusrc' file: (require 'gnus-diary) Also, you shouldn't use any `gnus-user-format-function-[d|D]' (*note Summary Buffer Lines::). `gnus-diary' provides both of these (sorry if you used them before). * Menu: * Diary Summary Line Format:: A nicer summary buffer line format. * Diary Articles Sorting:: A nicer way to sort messages. * Diary Headers Generation:: Not doing it manually. * Diary Group Parameters:: Not handling them manually.  File: gnus, Node: Diary Summary Line Format, Next: Diary Articles Sorting, Up: The Gnus Diary Library Diary Summary Line Format ......................... Displaying diary messages in standard summary line format (usually something like `From Joe: Subject') is pretty useless. Most of the time, you're the one who wrote the message, and you mostly want to see the event's date. `gnus-diary' provides two supplemental user formats to be used in summary line formats. `D' corresponds to a formatted time string for the next occurrence of the event (e.g. "Sat, Sep 22 01, 12:00"), while `d' corresponds to an approximative remaining time until the next occurrence of the event (e.g. "in 6 months, 1 week"). For example, here's how Joe's birthday is displayed in my `nndiary+diary:birthdays' summary buffer (note that the message is expirable, but will never be deleted, as it specifies a periodic event): E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week) In order to get something like the above, you would normally add the following line to your diary groups'parameters: (gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n") However, `gnus-diary' does it automatically (*note Diary Group Parameters::). You can however customize the provided summary line format with the following user options: - Variable: gnus-diary-summary-line-format Defines the summary line format used for diary groups (*note Summary Buffer Lines::). `gnus-diary' uses it to automatically update the diary groups'parameters. - Variable: gnus-diary-time-format Defines the format to display dates in diary summary buffers. This is used by the `D' user format. See the docstring for details. - Variable: gnus-diary-delay-format-function Defines the format function to use for displaying delays (remaining times) in diary summary buffers. This is used by the `d' user format. There are currently built-in functions for English and French; you can also define your own. See the docstring for details.  File: gnus, Node: Diary Articles Sorting, Next: Diary Headers Generation, Prev: Diary Summary Line Format, Up: The Gnus Diary Library Diary Articles Sorting ...................... `gnus-diary' provides new sorting functions (*note Sorting the Summary Buffer:: ) called `gnus-summary-sort-by-schedule', `gnus-thread-sort-by-schedule' and `gnus-article-sort-by-schedule'. These functions let you organize your diary summary buffers from the closest event to the farthest one. `gnus-diary' automatically installs `gnus-summary-sort-by-schedule' as a menu item in the summary buffer's "sort" menu, and the two others as the primary (hence default) sorting functions in the group parameters (*note Diary Group Parameters::).  File: gnus, Node: Diary Headers Generation, Next: Diary Group Parameters, Prev: Diary Articles Sorting, Up: The Gnus Diary Library Diary Headers Generation ........................ `gnus-diary' provides a function called `gnus-diary-check-message' to help you handle the `X-Diary-*' headers. This function ensures that the current message contains all the required diary headers, and prompts you for values or corrections if needed. This function is hooked into the `nndiary' back end, so that moving or copying an article to a diary group will trigger it automatically. It is also bound to `C-c D c' in `message-mode' and `article-edit-mode' in order to ease the process of converting a usual mail to a diary one. This function takes a prefix argument which will force prompting of all diary headers, regardless of their presence or validity. That way, you can very easily reschedule an already valid diary message, for instance.  File: gnus, Node: Diary Group Parameters, Prev: Diary Headers Generation, Up: The Gnus Diary Library Diary Group Parameters ...................... When you create a new diary group, or visit one, `gnus-diary' automatically checks your group parameters and if needed, sets the summary line format to the diary-specific value, installs the diary-specific sorting functions, and also adds the different `X-Diary-*' headers to the group's posting-style. It is then easier to send a diary message, because if you use `C-u a' or `C-u m' on a diary group to prepare a message, these headers will be inserted automatically (although not filled with proper values yet).  File: gnus, Node: Sending or Not Sending, Prev: The Gnus Diary Library, Up: Email Based Diary Sending or Not Sending ---------------------- Well, assuming you've read of of the above, here are two final notes on mail sending with `nndiary': * `nndiary' is a _real_ mail back end. You really send real diary messsages for real. This means for instance that you can give appointements to anybody (provided they use Gnus and `nndiary') by sending the diary message to them as well. * However, since `nndiary' also has a `request-post' method, you can also use `C-u a' instead of `C-u m' on a diary group and the message won't actually be sent; just stored locally in the group. This comes in very handy for private appointments.  File: gnus, Node: Gnus Unplugged, Prev: Email Based Diary, Up: Select Methods Gnus Unplugged ============== In olden times (ca. February '88), people used to run their newsreaders on big machines with permanent connections to the net. News transport was dealt with by news servers, and all the newsreaders had to do was to read news. Believe it or not. Nowadays most people read news and mail at home, and use some sort of modem to connect to the net. To avoid running up huge phone bills, it would be nice to have a way to slurp down all the news and mail, hang up the phone, read for several hours, and then upload any responses you have to make. And then you repeat the procedure. Of course, you can use news servers for doing this as well. I've used `inn' together with `slurp', `pop' and `sendmail' for some years, but doing that's a bore. Moving the news server functionality up to the newsreader makes sense if you're the only person reading news on a machine. Setting up Gnus as an "offline" newsreader is quite simple. In fact, you don't have to configure anything as the agent is now enabled by default (*note gnus-agent: Agent Variables.). Of course, to use it as such, you have to learn a few new commands. * Menu: * Agent Basics:: How it all is supposed to work. * Agent Categories:: How to tell the Gnus Agent what to download. * Agent Commands:: New commands for all the buffers. * Agent Visuals:: Ways that the agent may effect your summary buffer. * Agent as Cache:: The Agent is a big cache too. * Agent Expiry:: How to make old articles go away. * Agent Regeneration:: How to recover from lost connections and other accidents. * Agent and IMAP:: How to use the Agent with IMAP. * Outgoing Messages:: What happens when you post/mail something? * Agent Variables:: Customizing is fun. * Example Setup:: An example `~/.gnus.el' file for offline people. * Batching Agents:: How to fetch news from a `cron' job. * Agent Caveats:: What you think it'll do and what it does.  File: gnus, Node: Agent Basics, Next: Agent Categories, Up: Gnus Unplugged Agent Basics ------------ First, let's get some terminology out of the way. The Gnus Agent is said to be "unplugged" when you have severed the connection to the net (and notified the Agent that this is the case). When the connection to the net is up again (and Gnus knows this), the Agent is "plugged". The "local" machine is the one you're running on, and which isn't connected to the net continuously. "Downloading" means fetching things from the net to your local machine. "Uploading" is doing the opposite. You know that Gnus gives you all the opportunity you'd ever want for shooting yourself in the foot. Some people call it flexibility. Gnus is also customizable to a great extent, which means that the user has a say on how Gnus behaves. Other newsreaders might unconditionally shoot you in your foot, but with Gnus, you have a choice! Gnus is never really in plugged or unplugged state. Rather, it applies that state to each server individually. This means that some servers can be plugged while others can be unplugged. Additionally, some servers can be ignored by the Agent altogether (which means that they're kinda like plugged always). So when you unplug the Agent and then wonder why is Gnus opening a connection to the Net, the next step to do is to look whether all servers are agentized. If there is an unagentized server, you found the culprit. Another thing is the "offline" state. Sometimes, servers aren't reachable. When Gnus notices this, it asks you whether you want the server to be switched to offline state. If you say yes, then the server will behave somewhat as if it was unplugged, except that Gnus will ask you whether you want to switch it back online again. Let's take a typical Gnus session using the Agent. * You start Gnus with `gnus-unplugged'. This brings up the Gnus Agent in a disconnected state. You can read all the news that you have already fetched while in this mode. * You then decide to see whether any new news has arrived. You connect your machine to the net (using PPP or whatever), and then hit `J j' to make Gnus become "plugged" and use `g' to check for new mail as usual. To check for new mail in unplugged mode (*note Mail Source Specifiers::). * You can then read the new news immediately, or you can download the news onto your local machine. If you want to do the latter, you press `g' to check if there are any new news and then `J s' to fetch all the eligible articles in all the groups. (To let Gnus know which articles you want to download, *note Agent Categories::). * After fetching the articles, you press `J j' to make Gnus become unplugged again, and you shut down the PPP thing (or whatever). And then you read the news offline. * And then you go to step 2. Here are some things you should do the first time (or so) that you use the Agent. * Decide which servers should be covered by the Agent. If you have a mail back end, it would probably be nonsensical to have it covered by the Agent. Go to the server buffer (`^' in the group buffer) and press `J a' on the server (or servers) that you wish to have covered by the Agent (*note Server Agent Commands::), or `J r' on automatically added servers you do not wish to have covered by the Agent. By default, all `nntp' and `nnimap' servers in `gnus-select-method' and `gnus-secondary-select-methods' are agentized. * Decide on download policy. It's fairly simple once you decide whether you are going to use agent categories, topic parameters, and/or group parameters to implement your policy. If you're new to gnus, it is probably best to start with a category, *Note Agent Categories::. Both topic parameters (*note Topic Parameters::) and agent categories (*note Agent Categories::) provide for setting a policy that applies to multiple groups. Which you use is entirely up to you. Topic parameters do override categories so, if you mix the two, you'll have to take that into account. If you have a few groups that deviate from your policy, you can use group parameters (*note Group Parameters::) to configure them. * Uhm... that's it.  File: gnus, Node: Agent Categories, Next: Agent Commands, Prev: Agent Basics, Up: Gnus Unplugged Agent Categories ---------------- One of the main reasons to integrate the news transport layer into the newsreader is to allow greater control over what articles to download. There's not much point in downloading huge amounts of articles, just to find out that you're not interested in reading any of them. It's better to be somewhat more conservative in choosing what to download, and then mark the articles for downloading manually if it should turn out that you're interested in the articles anyway. One of the more effective methods for controlling what is to be downloaded is to create a "category" and then assign some (or all) groups to this category. Groups that do not belong in any other category belong to the `default' category. Gnus has its own buffer for creating and managing categories. If you prefer, you can also use group parameters (*note Group Parameters::) and topic parameters (*note Topic Parameters::) for an alternative approach to controlling the agent. The only real difference is that categories are specific to the agent (so there is less to learn) while group and topic parameters include the kitchen sink. Since you can set agent parameters in several different places we have a rule to decide which source to believe. This rule specifies that the parameter sources are checked in the following order: group parameters, topic parameters, agent category, and finally customizable variables. So you can mix all of these sources to produce a wide range of behavior, just don't blame me if you don't remember where you put your settings. * Menu: * Category Syntax:: What a category looks like. * Category Buffer:: A buffer for maintaining categories. * Category Variables:: Customize'r'Us.  File: gnus, Node: Category Syntax, Next: Category Buffer, Up: Agent Categories Category Syntax ............... A category consists of a name, the list of groups belonging to the category, and a number of optional parameters that override the customizable variables. The complete list of agent parameters are listed below. `agent-cat-name' The name of the category. `agent-groups' The list of groups that are in this category. `agent-predicate' A predicate which (generally) gives a rough outline of which articles are eligible for downloading; and `agent-score-file' a score rule which (generally) gives you a finer granularity when deciding what articles to download. (Note that this "download score" is not necessarily related to normal scores.) `agent-enable-expiration' a boolean indicating whether the agent should expire old articles in this group. Most groups should be expired to conserve disk space. In fact, its probably safe to say that the gnus.* hierarchy contains the only groups that should not be expired. `agent-days-until-old' an integer indicating the number of days that the agent should wait before deciding that a read article is safe to expire. `agent-low-score' an integer that overrides the value of `gnus-agent-low-score'. `agent-high-score' an integer that overrides the value of `gnus-agent-high-score'. `agent-length-when-short' an integer that overrides the value of `gnus-agent-short-article'. `agent-length-when-long' an integer that overrides the value of `gnus-agent-long-article'. `agent-enable-undownloaded-faces' a symbol indicating whether the summary buffer should display undownloaded articles using the `gnus-summary-*-undownloaded-face' faces. Any symbol other than `nil' will enable the use of undownloaded faces. The name of a category can not be changed once the category has been created. Each category maintains a list of groups that are exclusive members of that category. The exclusivity rule is automatically enforced, add a group to a new category and it is automatically removed from its old category. A predicate in its simplest form can be a single predicate such as `true' or `false'. These two will download every available article or nothing respectively. In the case of these two special predicates an additional score rule is superfluous. Predicates of `high' or `low' download articles in respect of their scores in relationship to `gnus-agent-high-score' and `gnus-agent-low-score' as described below. To gain even finer control of what is to be regarded eligible for download a predicate can consist of a number of predicates with logical operators sprinkled in between. Perhaps some examples are in order. Here's a simple predicate. (It's the default predicate, in fact, used for all groups that don't belong to any other category.) short Quite simple, eh? This predicate is true if and only if the article is short (for some value of "short"). Here's a more complex predicate: (or high (and (not low) (not long))) This means that an article should be downloaded if it has a high score, or if the score is not low and the article is not long. You get the drift. The available logical operators are `or', `and' and `not'. (If you prefer, you can use the more "C"-ish operators `|', `&' and `!' instead.) The following predicates are pre-defined, but if none of these fit what you want to do, you can write your own. When evaluating each of these predicates, the named constant will be bound to the value determined by calling `gnus-agent-find-parameter' on the appropriate parameter. For example, gnus-agent-short-article will be bound to `(gnus-agent-find-parameter group 'agent-short-article)'. This means that you can specify a predicate in your category then tune that predicate to individual groups. `short' True iff the article is shorter than `gnus-agent-short-article' lines; default 100. `long' True iff the article is longer than `gnus-agent-long-article' lines; default 200. `low' True iff the article has a download score less than `gnus-agent-low-score'; default 0. `high' True iff the article has a download score greater than `gnus-agent-high-score'; default 0. `spam' True iff the Gnus Agent guesses that the article is spam. The heuristics may change over time, but at present it just computes a checksum and sees whether articles match. `true' Always true. `false' Always false. If you want to create your own predicate function, here's what you have to know: The functions are called with no parameters, but the `gnus-headers' and `gnus-score' dynamic variables are bound to useful values. For example, you could decide that you don't want to download articles that were posted more than a certain number of days ago (e.g. posted more than `gnus-agent-expire-days' ago) you might write a function something along the lines of the following: (defun my-article-old-p () "Say whether an article is old." (< (time-to-days (date-to-time (mail-header-date gnus-headers))) (- (time-to-days (current-time)) gnus-agent-expire-days))) with the predicate then defined as: (not my-article-old-p) or you could append your predicate to the predefined `gnus-category-predicate-alist' in your `~/.gnus.el' or wherever. (require 'gnus-agent) (setq gnus-category-predicate-alist (append gnus-category-predicate-alist '((old . my-article-old-p)))) and simply specify your predicate as: (not old) If/when using something like the above, be aware that there are many misconfigured systems/mailers out there and so an article's date is not always a reliable indication of when it was posted. Hell, some people just don't give a damn. The above predicates apply to _all_ the groups which belong to the category. However, if you wish to have a specific predicate for an individual group within a category, or you're just too lazy to set up a new category, you can enter a group's individual predicate in its group parameters like so: (agent-predicate . short) This is the group/topic parameter equivalent of the agent category default. Note that when specifying a single word predicate like this, the `agent-predicate' specification must be in dotted pair notation. The equivalent of the longer example from above would be: (agent-predicate or high (and (not low) (not long))) The outer parenthesis required in the category specification are not entered here as, not being in dotted pair notation, the value of the predicate is assumed to be a list. Now, the syntax of the download score is the same as the syntax of normal score files, except that all elements that require actually seeing the article itself are verboten. This means that only the following headers can be scored on: `Subject', `From', `Date', `Message-ID', `References', `Chars', `Lines', and `Xref'. As with predicates, the specification of the `download score rule' to use in respect of a group can be in either the category definition if it's to be applicable to all groups in therein, or a group's parameters if it's to be specific to that group. In both of these places the `download score rule' can take one of three forms: 1. Score rule This has the same syntax as a normal Gnus score file except only a subset of scoring keywords are available as mentioned above. example: * Category specification (("from" ("Lars Ingebrigtsen" 1000000 nil s)) ("lines" (500 -100 nil <))) * Group/Topic Parameter specification (agent-score ("from" ("Lars Ingebrigtsen" 1000000 nil s)) ("lines" (500 -100 nil <))) Again, note the omission of the outermost parenthesis here. 2. Agent score file These score files must _only_ contain the permitted scoring keywords stated above. example: * Category specification ("~/News/agent.SCORE") or perhaps ("~/News/agent.SCORE" "~/News/agent.group.SCORE") * Group Parameter specification (agent-score "~/News/agent.SCORE") Additional score files can be specified as above. Need I say anything about parenthesis? 3. Use `normal' score files If you don't want to maintain two sets of scoring rules for a group, and your desired `downloading' criteria for a group are the same as your `reading' criteria then you can tell the agent to refer to your `normal' score files when deciding what to download. These directives in either the category definition or a group's parameters will cause the agent to read in all the applicable score files for a group, _filtering out_ those sections that do not relate to one of the permitted subset of scoring keywords. * Category Specification file * Group Parameter specification (agent-score . file)  File: gnus, Node: Category Buffer, Next: Category Variables, Prev: Category Syntax, Up: Agent Categories Category Buffer ............... You'd normally do all category maintenance from the category buffer. When you enter it for the first time (with the `J c' command from the group buffer), you'll only see the `default' category. The following commands are available in this buffer: `q' Return to the group buffer (`gnus-category-exit'). `e' Use a customization buffer to set all of the selected category's parameters at one time (`gnus-category-customize-category'). `k' Kill the current category (`gnus-category-kill'). `c' Copy the current category (`gnus-category-copy'). `a' Add a new category (`gnus-category-add'). `p' Edit the predicate of the current category (`gnus-category-edit-predicate'). `g' Edit the list of groups belonging to the current category (`gnus-category-edit-groups'). `s' Edit the download score rule of the current category (`gnus-category-edit-score'). `l' List all the categories (`gnus-category-list').  File: gnus, Node: Category Variables, Prev: Category Buffer, Up: Agent Categories Category Variables .................. `gnus-category-mode-hook' Hook run in category buffers. `gnus-category-line-format' Format of the lines in the category buffer (*note Formatting Variables::). Valid elements are: `c' The name of the category. `g' The number of groups in the category. `gnus-category-mode-line-format' Format of the category mode line (*note Mode Line Formatting::). `gnus-agent-short-article' Articles that have fewer lines than this are short. Default 100. `gnus-agent-long-article' Articles that have more lines than this are long. Default 200. `gnus-agent-low-score' Articles that have a score lower than this have a low score. Default 0. `gnus-agent-high-score' Articles that have a score higher than this have a high score. Default 0. `gnus-agent-expire-days' The number of days that a `read' article must stay in the agent's local disk before becoming eligible for expiration (While the name is the same, this doesn't mean expiring the article on the server. It just means deleting the local copy of the article). What is also important to understand is that the counter starts with the time the article was written to the local disk and not the time the article was read. Default 7. `gnus-agent-enable-expiration' Determines whether articles in a group are, by default, expired or retained indefinitely. The default is `ENABLE' which means that you'll have to disable expiration when desired. On the other hand, you could set this to `DISABLE'. In that case, you would then have to enable expiration in selected groups.  File: gnus, Node: Agent Commands, Next: Agent Visuals, Prev: Agent Categories, Up: Gnus Unplugged Agent Commands -------------- All the Gnus Agent commands are on the `J' submap. The `J j' (`gnus-agent-toggle-plugged') command works in all modes, and toggles the plugged/unplugged state of the Gnus Agent. * Menu: * Group Agent Commands:: Configure groups and fetch their contents. * Summary Agent Commands:: Manually select then fetch specific articles. * Server Agent Commands:: Select the servers that are supported by the agent.  Local Variables: coding: ISO-8859-1 End: