This is ../../info/gnus, produced by makeinfo version 4.11 from gnus.texi. Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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.3 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". (a) The FSF's Back-Cover Text is: "You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom." INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Gnus: (gnus). The newsreader Gnus. END-INFO-DIR-ENTRY  File: gnus, Node: Article Washing, Next: Article Header, Prev: Article Hiding, Up: Article Treatment 3.18.4 Article Washing ---------------------- We call this "article washing" for a really good reason. Namely, the `A' key was taken, so we had to use the `W' key instead. "Washing" is defined by us as "changing something from something to something else", but normally results in something looking better. Cleaner, perhaps. *Note Customizing Articles::, if you want to change how Gnus displays articles by default. `C-u g' This is not really washing, it's sort of the opposite of washing. If you type this, you see the article exactly as it exists on disk or on the server. `g' Force redisplaying of the current article (`gnus-summary-show-article'). This is also not really washing. If you type this, you see the article without any previously applied interactive Washing functions but with all default treatments (*note Customizing Articles::). `W l' Remove page breaks from the current article (`gnus-summary-stop-page-breaking'). *Note Misc Article::, for page delimiters. `W r' Do a Caesar rotate (rot13) on the article buffer (`gnus-summary-caesar-message'). Unreadable articles that tell you to read them with Caesar rotate or rot13. (Typically offensive jokes and such.) It's commonly called "rot13" because each letter is rotated 13 positions in the alphabet, e. g. `B' (letter #2) -> `O' (letter #15). It is sometimes referred to as "Caesar rotate" because Caesar is rumored to have employed this form of, uh, somewhat weak encryption. `W m' Morse decode the article buffer (`gnus-summary-morse-message'). `W i' Decode IDNA encoded domain names in the current articles. IDNA encoded domain names looks like `xn--bar'. If a string remain unencoded after running invoking this, it is likely an invalid IDNA string (`xn--bar' is invalid). You must have GNU Libidn (`http://www.gnu.org/software/libidn/') installed for this command to work. `W t' `t' Toggle whether to display all headers in the article buffer (`gnus-summary-toggle-header'). `W v' Toggle whether to display all headers in the article buffer permanently (`gnus-summary-verbose-headers'). `W o' Treat overstrike (`gnus-article-treat-overstrike'). `W d' Treat M****s*** sm*rtq**t*s according to `gnus-article-dumbquotes-map' (`gnus-article-treat-dumbquotes'). Note that this function guesses whether a character is a sm*rtq**t* or not, so it should only be used interactively. Sm*rtq**t*s are M****s***'s unilateral extension to the character map in an attempt to provide more quoting characters. If you see something like `\222' or `\264' where you're expecting some kind of apostrophe or quotation mark, then try this wash. `W Y f' Full deuglify of broken Outlook (Express) articles: Treat dumbquotes, unwrap lines, repair attribution and rearrange citation. (`gnus-article-outlook-deuglify-article'). `W Y u' Unwrap lines that appear to be wrapped citation lines. You can control what lines will be unwrapped by frobbing `gnus-outlook-deuglify-unwrap-min' and `gnus-outlook-deuglify-unwrap-max', indicating the minimum and maximum length of an unwrapped citation line. (`gnus-article-outlook-unwrap-lines'). `W Y a' Repair a broken attribution line. (`gnus-article-outlook-repair-attribution'). `W Y c' Repair broken citations by rearranging the text. (`gnus-article-outlook-rearrange-citation'). `W w' Do word wrap (`gnus-article-fill-cited-article'). You can give the command a numerical prefix to specify the width to use when filling. `W Q' Fill long lines (`gnus-article-fill-long-lines'). `W C' Capitalize the first word in each sentence (`gnus-article-capitalize-sentences'). `W c' Translate CRLF pairs (i. e., `^M's on the end of the lines) into LF (this takes care of DOS line endings), and then translate any remaining CRs into LF (this takes care of Mac line endings) (`gnus-article-remove-cr'). `W q' Treat quoted-printable (`gnus-article-de-quoted-unreadable'). Quoted-Printable is one common MIME encoding employed when sending non-ASCII (i.e., 8-bit) articles. It typically makes strings like `déjà vu' look like `d=E9j=E0 vu', which doesn't look very readable to me. Note that this is usually done automatically by Gnus if the message in question has a `Content-Transfer-Encoding' header that says that this encoding has been done. If a prefix is given, a charset will be asked for. `W 6' Treat base64 (`gnus-article-de-base64-unreadable'). Base64 is one common MIME encoding employed when sending non-ASCII (i.e., 8-bit) articles. Note that this is usually done automatically by Gnus if the message in question has a `Content-Transfer-Encoding' header that says that this encoding has been done. If a prefix is given, a charset will be asked for. `W Z' Treat HZ or HZP (`gnus-article-decode-HZ'). HZ (or HZP) is one common encoding employed when sending Chinese articles. It typically makes strings look like `~{<:Ky2;S{#,NpJ)l6HK!#~}'. `W A' Translate ANSI SGR control sequences into overlays or extents (`gnus-article-treat-ansi-sequences'). ANSI sequences are used in some Chinese hierarchies for highlighting. `W u' Remove newlines from within URLs. Some mailers insert newlines into outgoing email messages to keep lines short. This reformatting can split long URLs onto multiple lines. Repair those URLs by removing the newlines (`gnus-article-unsplit-urls'). `W h' Treat HTML (`gnus-article-wash-html'). Note that this is usually done automatically by Gnus if the message in question has a `Content-Type' header that says that the message is HTML. If a prefix is given, a charset will be asked for. If it is a number, the charset defined in `gnus-summary-show-article-charset-alist' (*note Paging the Article::) will be used. The default is to use the function specified by `mm-text-html-renderer' (*note Display Customization: (emacs-mime)Display Customization.) to convert the HTML, but this is controlled by the `gnus-article-wash-function' variable. Pre-defined functions you can use include: `w3' Use Emacs/W3. `w3m' Use emacs-w3m (http://emacs-w3m.namazu.org/). `w3m-standalone' Use w3m (http://w3m.sourceforge.net/). `links' Use Links (http://links.sf.net/). `lynx' Use Lynx (http://lynx.isc.org/). `html2text' Use html2text--a simple HTML converter included with Gnus. `W b' Add clickable buttons to the article (`gnus-article-add-buttons'). *Note Article Buttons::. `W B' Add clickable buttons to the article headers (`gnus-article-add-buttons-to-head'). `W p' Verify a signed control message (`gnus-article-verify-x-pgp-sig'). Control messages such as `newgroup' and `checkgroups' are usually signed by the hierarchy maintainer. You need to add the PGP public key of the maintainer to your keyring to verify the message.(1) `W s' Verify a signed (PGP, PGP/MIME or S/MIME) message (`gnus-summary-force-verify-and-decrypt'). *Note Security::. `W a' Strip headers like the `X-No-Archive' header from the beginning of article bodies (`gnus-article-strip-headers-in-body'). `W E l' Remove all blank lines from the beginning of the article (`gnus-article-strip-leading-blank-lines'). `W E m' Replace all blank lines with empty lines and then all multiple empty lines with a single empty line. (`gnus-article-strip-multiple-blank-lines'). `W E t' Remove all blank lines at the end of the article (`gnus-article-remove-trailing-blank-lines'). `W E a' Do all the three commands above (`gnus-article-strip-blank-lines'). `W E A' Remove all blank lines (`gnus-article-strip-all-blank-lines'). `W E s' Remove all white space from the beginning of all lines of the article body (`gnus-article-strip-leading-space'). `W E e' Remove all white space from the end of all lines of the article body (`gnus-article-strip-trailing-space'). *Note Customizing Articles::, for how to wash articles automatically. ---------- Footnotes ---------- (1) PGP keys for many hierarchies are available at `ftp://ftp.isc.org/pub/pgpcontrol/README.html'  File: gnus, Node: Article Header, Next: Article Buttons, Prev: Article Washing, Up: Article Treatment 3.18.5 Article Header --------------------- These commands perform various transformations of article header. `W G u' Unfold folded header lines (`gnus-article-treat-unfold-headers'). `W G n' Fold the `Newsgroups' and `Followup-To' headers (`gnus-article-treat-fold-newsgroups'). `W G f' Fold all the message headers (`gnus-article-treat-fold-headers'). `W E w' Remove excessive whitespace from all headers (`gnus-article-remove-leading-whitespace').  File: gnus, Node: Article Buttons, Next: Article Button Levels, Prev: Article Header, Up: Article Treatment 3.18.6 Article Buttons ---------------------- People often include references to other stuff in articles, and it would be nice if Gnus could just fetch whatever it is that people talk about with the minimum of fuzz when you hit `RET' or use the middle mouse button on these references. Gnus adds "buttons" to certain standard references by default: Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and Emacs or Gnus related references. This is controlled by two variables, one that handles article bodies and one that handles article heads: `gnus-button-alist' This is an alist where each entry has this form: (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR) REGEXP All text that match this regular expression (case insensitive) will be considered an external reference. Here's a typical regexp that matches embedded URLs: `]*\\)>'. This can also be a variable containing a regexp, useful variables to use include `gnus-button-url-regexp' and `gnus-button-mid-or-mail-regexp'. BUTTON-PAR Gnus has to know which parts of the matches is to be highlighted. This is a number that says what sub-expression of the regexp is to be highlighted. If you want it all highlighted, you use 0 here. USE-P This form will be `eval'ed, and if the result is non-`nil', this is considered a match. This is useful if you want extra sifting to avoid false matches. Often variables named `gnus-button-*-level' are used here, *Note Article Button Levels::, but any other form may be used too. FUNCTION This function will be called when you click on this button. DATA-PAR As with BUTTON-PAR, this is a sub-expression number, but this one says which part of the match is to be sent as data to FUNCTION. So the full entry for buttonizing URLs is then ("]*\\)>" 0 t gnus-button-url 1) `gnus-header-button-alist' This is just like the other alist, except that it is applied to the article head only, and that each entry has an additional element that is used to say what headers to apply the buttonize coding to: (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR) HEADER is a regular expression. 3.18.6.1 Related variables and functions ........................................ `gnus-button-*-level' *Note Article Button Levels::. `gnus-button-url-regexp' A regular expression that matches embedded URLs. It is used in the default values of the variables above. `gnus-button-man-handler' The function to use for displaying man pages. It must take at least one argument with a string naming the man page. `gnus-button-mid-or-mail-regexp' Regular expression that matches a message ID or a mail address. `gnus-button-prefer-mid-or-mail' This variable determines what to do when the button on a string as `foo123@bar.invalid' is pushed. Strings like this can be either a message ID or a mail address. If it is one of the symbols `mid' or `mail', Gnus will always assume that the string is a message ID or a mail address, respectively. If this variable is set to the symbol `ask', always query the user what to do. If it is a function, this function will be called with the string as its only argument. The function must return `mid', `mail', `invalid' or `ask'. The default value is the function `gnus-button-mid-or-mail-heuristic'. `gnus-button-mid-or-mail-heuristic' Function that guesses whether its argument is a message ID or a mail address. Returns `mid' if it's a message IDs, `mail' if it's a mail address, `ask' if unsure and `invalid' if the string is invalid. `gnus-button-mid-or-mail-heuristic-alist' An alist of `(RATE . REGEXP)' pairs used by the function `gnus-button-mid-or-mail-heuristic'. `gnus-button-ctan-handler' The function to use for displaying CTAN links. It must take one argument, the string naming the URL. `gnus-ctan-url' Top directory of a CTAN (Comprehensive TeX Archive Network) archive used by `gnus-button-ctan-handler'. `gnus-article-button-face' Face used on buttons. `gnus-article-mouse-face' Face used when the mouse cursor is over a button. *Note Customizing Articles::, for how to buttonize articles automatically.  File: gnus, Node: Article Button Levels, Next: Article Date, Prev: Article Buttons, Up: Article Treatment 3.18.7 Article button levels ---------------------------- The higher the value of the variables `gnus-button-*-level', the more buttons will appear. If the level is zero, no corresponding buttons are displayed. With the default value (which is 5) you should already see quite a lot of buttons. With higher levels, you will see more buttons, but you may also get more false positives. To avoid them, you can set the variables `gnus-button-*-level' local to specific groups (*note Group Parameters::). Here's an example for the variable `gnus-parameters': ;; increase `gnus-button-*-level' in some groups: (setq gnus-parameters '(("\\<\\(emacs\\|gnus\\)\\>" (gnus-button-emacs-level 10)) ("\\" (gnus-button-man-level 10)) ("\\" (gnus-button-tex-level 10)))) `gnus-button-browse-level' Controls the display of references to message IDs, mail addresses and news URLs. Related variables and functions include `gnus-button-url-regexp', `browse-url', and `browse-url-browser-function'. `gnus-button-emacs-level' Controls the display of Emacs or Gnus references. Related functions are `gnus-button-handle-custom', `gnus-button-handle-describe-function', `gnus-button-handle-describe-variable', `gnus-button-handle-symbol', `gnus-button-handle-describe-key', `gnus-button-handle-apropos', `gnus-button-handle-apropos-command', `gnus-button-handle-apropos-variable', `gnus-button-handle-apropos-documentation', and `gnus-button-handle-library'. `gnus-button-man-level' Controls the display of references to (Unix) man pages. See `gnus-button-man-handler'. `gnus-button-message-level' Controls the display of message IDs, mail addresses and news URLs. Related variables and functions include `gnus-button-mid-or-mail-regexp', `gnus-button-prefer-mid-or-mail', `gnus-button-mid-or-mail-heuristic', and `gnus-button-mid-or-mail-heuristic-alist'. `gnus-button-tex-level' Controls the display of references to TeX or LaTeX stuff, e.g. for CTAN URLs. See the variables `gnus-ctan-url', `gnus-button-ctan-handler', `gnus-button-ctan-directory-regexp', and `gnus-button-handle-ctan-bogus-regexp'.  File: gnus, Node: Article Date, Next: Article Display, Prev: Article Button Levels, Up: Article Treatment 3.18.8 Article Date ------------------- The date is most likely generated in some obscure timezone you've never heard of, so it's quite nice to be able to find out what the time was when the article was sent. `W T u' Display the date in UT (aka. GMT, aka ZULU) (`gnus-article-date-ut'). `W T i' Display the date in international format, aka. ISO 8601 (`gnus-article-date-iso8601'). `W T l' Display the date in the local timezone (`gnus-article-date-local'). `W T p' Display the date in a format that's easily pronounceable in English (`gnus-article-date-english'). `W T s' Display the date using a user-defined format (`gnus-article-date-user'). The format is specified by the `gnus-article-time-format' variable, and is a string that's passed to `format-time-string'. See the documentation of that variable for a list of possible format specs. `W T e' Say how much time has elapsed between the article was posted and now (`gnus-article-date-lapsed'). It looks something like: X-Sent: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago The value of `gnus-article-date-lapsed-new-header' determines whether this header will just be added below the old Date one, or will replace it. An advantage of using Gnus to read mail is that it converts simple bugs into wonderful absurdities. If you want to have this line updated continually, you can put (gnus-start-date-timer) in your `~/.gnus.el' file, or you can run it off of some hook. If you want to stop the timer, you can use the `gnus-stop-date-timer' command. `W T o' Display the original date (`gnus-article-date-original'). This can be useful if you normally use some other conversion function and are worried that it might be doing something totally wrong. Say, claiming that the article was posted in 1854. Although something like that is _totally_ impossible. Don't you trust me? *titter* *Note Customizing Articles::, for how to display the date in your preferred format automatically.  File: gnus, Node: Article Display, Next: Article Signature, Prev: Article Date, Up: Article Treatment 3.18.9 Article Display ---------------------- These commands add various frivolous display gimmicks to the article buffer in Emacs versions that support them. `X-Face' headers are small black-and-white images supplied by the message headers (*note X-Face::). `Face' headers are small colored images supplied by the message headers (*note Face::). Smileys are those little `:-)' symbols that people like to litter their messages with (*note Smileys::). Picons, on the other hand, reside on your own system, and Gnus will try to match the headers to what you have (*note Picons::). All these functions are toggles--if the elements already exist, they'll be removed. `W D x' Display an `X-Face' in the `From' header. (`gnus-article-display-x-face'). `W D d' Display a `Face' in the `From' header. (`gnus-article-display-face'). `W D s' Display smileys (`gnus-treat-smiley'). `W D f' Piconify the `From' header (`gnus-treat-from-picon'). `W D m' Piconify all mail headers (i. e., `Cc', `To') (`gnus-treat-mail-picon'). `W D n' Piconify all news headers (i. e., `Newsgroups' and `Followup-To') (`gnus-treat-newsgroups-picon'). `W D D' Remove all images from the article buffer (`gnus-article-remove-images').  File: gnus, Node: Article Signature, Next: Article Miscellanea, Prev: Article Display, Up: Article Treatment 3.18.10 Article Signature ------------------------- Each article is divided into two parts--the head and the body. The body can be divided into a signature part and a text part. The variable that says what is to be considered a signature is `gnus-signature-separator'. This is normally the standard `^-- $' as mandated by son-of-RFC 1036. However, many people use non-standard signature separators, so this variable can also be a list of regular expressions to be tested, one by one. (Searches are done from the end of the body towards the beginning.) One likely value is: (setq gnus-signature-separator '("^-- $" ; The standard "^-- *$" ; A common mangling "^-------*$" ; Many people just use a looong ; line of dashes. Shame! "^ *--------*$" ; Double-shame! "^________*$" ; Underscores are also popular "^========*$")) ; Pervert! The more permissive you are, the more likely it is that you'll get false positives. `gnus-signature-limit' provides a limit to what is considered a signature when displaying articles. 1. If it is an integer, no signature may be longer (in characters) than that integer. 2. If it is a floating point number, no signature may be longer (in lines) than that number. 3. If it is a function, the function will be called without any parameters, and if it returns `nil', there is no signature in the buffer. 4. If it is a string, it will be used as a regexp. If it matches, the text in question is not a signature. This variable can also be a list where the elements may be of the types listed above. Here's an example: (setq gnus-signature-limit '(200.0 "^---*Forwarded article")) This means that if there are more than 200 lines after the signature separator, or the text after the signature separator is matched by the regular expression `^---*Forwarded article', then it isn't a signature after all.  File: gnus, Node: Article Miscellanea, Prev: Article Signature, Up: Article Treatment 3.18.11 Article Miscellanea --------------------------- `A t' Translate the article from one language to another (`gnus-article-babel').  File: gnus, Node: MIME Commands, Next: Charsets, Prev: Article Treatment, Up: Summary Buffer 3.19 MIME Commands ================== The following commands all understand the numerical prefix. For instance, `3 K v' means "view the third MIME part". `b' `K v' View the MIME part. `K o' Save the MIME part. `K O' Prompt for a file name, then save the MIME part and strip it from the article. The stripped MIME object will be referred via the message/external-body MIME type. `K r' Replace the MIME part with an external body. `K d' Delete the MIME part and add some information about the removed part. `K c' Copy the MIME part. `K e' View the MIME part externally. `K i' View the MIME part internally. `K |' Pipe the MIME part to an external command. The rest of these MIME commands do not use the numerical prefix in the same manner: `K H' View `text/html' parts of the current article with a WWW browser. The message header is added to the beginning of every html part unless the prefix argument is given. Warning: Spammers use links to images in HTML articles to verify whether you have read the message. As this command passes the HTML content to the browser without eliminating these "web bugs" you should only use it for mails from trusted senders. If you always want to display HTML parts in the browser, set `mm-text-html-renderer' to `nil'. `K b' Make all the MIME parts have buttons in front of them. This is mostly useful if you wish to save (or perform other actions) on inlined parts. `K m' Some multipart messages are transmitted with missing or faulty headers. This command will attempt to "repair" these messages so that they can be viewed in a more pleasant manner (`gnus-summary-repair-multipart'). `X m' Save all parts matching a MIME type to a directory (`gnus-summary-save-parts'). Understands the process/prefix convention (*note Process/Prefix::). `M-t' Toggle the buttonized display of the article buffer (`gnus-summary-toggle-display-buttonized'). `W M w' Decode RFC 2047-encoded words in the article headers (`gnus-article-decode-mime-words'). `W M c' Decode encoded article bodies as well as charsets (`gnus-article-decode-charset'). This command looks in the `Content-Type' header to determine the charset. If there is no such header in the article, you can give it a prefix, which will prompt for the charset to decode as. In regional groups where people post using some common encoding (but do not include MIME headers), you can set the `charset' group/topic parameter to the required charset (*note Group Parameters::). `W M v' View all the MIME parts in the current article (`gnus-mime-view-all-parts'). Relevant variables: `gnus-ignored-mime-types' This is a list of regexps. MIME types that match a regexp from this list will be completely ignored by Gnus. The default value is `nil'. To have all Vcards be ignored, you'd say something like this: (setq gnus-ignored-mime-types '("text/x-vcard")) `gnus-article-loose-mime' If non-`nil', Gnus won't require the `MIME-Version' header before interpreting the message as a MIME message. This helps when reading messages from certain broken mail user agents. The default is `t'. `gnus-article-emulate-mime' There are other, non-MIME encoding methods used. The most common is `uuencode', but yEncode is also getting to be popular. If this variable is non-`nil', Gnus will look in message bodies to see if it finds these encodings, and if so, it'll run them through the Gnus MIME machinery. The default is `t'. Only single-part yEnc encoded attachments can be decoded. There's no support for encoding in Gnus. `gnus-unbuttonized-mime-types' This is a list of regexps. MIME types that match a regexp from this list won't have MIME buttons inserted unless they aren't displayed or this variable is overridden by `gnus-buttonized-mime-types'. The default value is `(".*/.*")'. This variable is only used when `gnus-inhibit-mime-unbuttonizing' is `nil'. `gnus-buttonized-mime-types' This is a list of regexps. MIME types that match a regexp from this list will have MIME buttons inserted unless they aren't displayed. This variable overrides `gnus-unbuttonized-mime-types'. The default value is `nil'. This variable is only used when `gnus-inhibit-mime-unbuttonizing' is `nil'. To see e.g. security buttons but no other buttons, you could set this variable to `("multipart/signed")' and leave `gnus-unbuttonized-mime-types' at the default value. You could also add `"multipart/alternative"' to this list to display radio buttons that allow you to choose one of two media types those mails include. See also `mm-discouraged-alternatives' (*note Display Customization: (emacs-mime)Display Customization.). `gnus-inhibit-mime-unbuttonizing' If this is non-`nil', then all MIME parts get buttons. The default value is `nil'. `gnus-article-mime-part-function' For each MIME part, this function will be called with the MIME handle as the parameter. The function is meant to be used to allow users to gather information from the article (e. g., add Vcard info to the bbdb database) or to do actions based on parts (e. g., automatically save all jpegs into some directory). Here's an example function the does the latter: (defun my-save-all-jpeg-parts (handle) (when (equal (car (mm-handle-type handle)) "image/jpeg") (with-temp-buffer (insert (mm-get-part handle)) (write-region (point-min) (point-max) (read-file-name "Save jpeg to: "))))) (setq gnus-article-mime-part-function 'my-save-all-jpeg-parts) `gnus-mime-multipart-functions' Alist of MIME multipart types and functions to handle them. `gnus-mime-display-multipart-alternative-as-mixed' Display "multipart/alternative" parts as "multipart/mixed". `gnus-mime-display-multipart-related-as-mixed' Display "multipart/related" parts as "multipart/mixed". If displaying `text/html' is discouraged, see `mm-discouraged-alternatives', images or other material inside a "multipart/related" part might be overlooked when this variable is `nil'. *note Display Customization: (emacs-mime)Display Customization. `gnus-mime-display-multipart-as-mixed' Display "multipart" parts as "multipart/mixed". If `t', it overrides `nil' values of `gnus-mime-display-multipart-alternative-as-mixed' and `gnus-mime-display-multipart-related-as-mixed'. `mm-file-name-rewrite-functions' List of functions used for rewriting file names of MIME parts. Each function takes a file name as input and returns a file name. Ready-made functions include `mm-file-name-delete-whitespace', `mm-file-name-trim-whitespace', `mm-file-name-collapse-whitespace', and `mm-file-name-replace-whitespace'. The later uses the value of the variable `mm-file-name-replace-whitespace' to replace each whitespace character in a file name with that string; default value is `"_"' (a single underscore). The standard functions `capitalize', `downcase', `upcase', and `upcase-initials' may be useful, too. Everybody knows that whitespace characters in file names are evil, except those who don't know. If you receive lots of attachments from such unenlightened users, you can make live easier by adding (setq mm-file-name-rewrite-functions '(mm-file-name-trim-whitespace mm-file-name-collapse-whitespace mm-file-name-replace-whitespace)) to your `~/.gnus.el' file.  File: gnus, Node: Charsets, Next: Article Commands, Prev: MIME Commands, Up: Summary Buffer 3.20 Charsets ============= People use different charsets, and we have MIME to let us know what charsets they use. Or rather, we wish we had. Many people use newsreaders and mailers that do not understand or use MIME, and just send out messages without saying what character sets they use. To help a bit with this, some local news hierarchies have policies that say what character set is the default. For instance, the `fj' hierarchy uses `iso-2022-jp'. This knowledge is encoded in the `gnus-group-charset-alist' variable, which is an alist of regexps (use the first item to match full group names) and default charsets to be used when reading these groups. In addition, some people do use soi-disant MIME-aware agents that aren't. These blithely mark messages as being in `iso-8859-1' even if they really are in `koi-8'. To help here, the `gnus-newsgroup-ignored-charsets' variable can be used. The charsets that are listed here will be ignored. The variable can be set on a group-by-group basis using the group parameters (*note Group Parameters::). The default value is `(unknown-8bit x-unknown)', which includes values some agents insist on having in there. When posting, `gnus-group-posting-charset-alist' is used to determine which charsets should not be encoded using the MIME encodings. For instance, some hierarchies discourage using quoted-printable header encoding. This variable is an alist of regexps and permitted unencoded charsets for posting. Each element of the alist has the form `('TEST HEADER BODY-LIST`)', where: TEST is either a regular expression matching the newsgroup header or a variable to query, HEADER is the charset which may be left unencoded in the header (`nil' means encode all charsets), BODY-LIST is a list of charsets which may be encoded using 8bit content-transfer encoding in the body, or one of the special values `nil' (always encode using quoted-printable) or `t' (always use 8bit). *Note Encoding Customization: (emacs-mime)Encoding Customization, for additional variables that control which MIME charsets are used when sending messages. Other charset tricks that may be useful, although not Gnus-specific: If there are several MIME charsets that encode the same Emacs charset, you can choose what charset to use by saying the following: (put-charset-property 'cyrillic-iso8859-5 'preferred-coding-system 'koi8-r) This means that Russian will be encoded using `koi8-r' instead of the default `iso-8859-5' MIME charset. If you want to read messages in `koi8-u', you can cheat and say (define-coding-system-alias 'koi8-u 'koi8-r) This will almost do the right thing. And finally, to read charsets like `windows-1251', you can say something like (codepage-setup 1251) (define-coding-system-alias 'windows-1251 'cp1251)  File: gnus, Node: Article Commands, Next: Summary Sorting, Prev: Charsets, Up: Summary Buffer 3.21 Article Commands ===================== `A P' Generate and print a PostScript image of the article buffer (`gnus-summary-print-article'). `gnus-ps-print-hook' will be run just before printing the buffer. An alternative way to print article is to use Muttprint (*note Saving Articles::).  File: gnus, Node: Summary Sorting, Next: Finding the Parent, Prev: Article Commands, Up: Summary Buffer 3.22 Summary Sorting ==================== You can have the summary buffer sorted in various ways, even though I can't really see why you'd want that. `C-c C-s C-n' Sort by article number (`gnus-summary-sort-by-number'). `C-c C-s C-m C-n' Sort by most recent article number (`gnus-summary-sort-by-most-recent-number'). `C-c C-s C-a' Sort by author (`gnus-summary-sort-by-author'). `C-c C-s C-t' Sort by recipient (`gnus-summary-sort-by-recipient'). `C-c C-s C-s' Sort by subject (`gnus-summary-sort-by-subject'). `C-c C-s C-d' Sort by date (`gnus-summary-sort-by-date'). `C-c C-s C-m C-d' Sort by most recent date (`gnus-summary-sort-by-most-recent-date'). `C-c C-s C-l' Sort by lines (`gnus-summary-sort-by-lines'). `C-c C-s C-c' Sort by article length (`gnus-summary-sort-by-chars'). `C-c C-s C-i' Sort by score (`gnus-summary-sort-by-score'). `C-c C-s C-r' Randomize (`gnus-summary-sort-by-random'). `C-c C-s C-o' Sort using the default sorting method (`gnus-summary-sort-by-original'). These functions will work both when you use threading and when you don't use threading. In the latter case, all summary lines will be sorted, line by line. In the former case, sorting will be done on a root-by-root basis, which might not be what you were looking for. To toggle whether to use threading, type `T T' (*note Thread Commands::). If a prefix argument if given, the sort order is reversed.  File: gnus, Node: Finding the Parent, Next: Alternative Approaches, Prev: Summary Sorting, Up: Summary Buffer 3.23 Finding the Parent ======================= `^' If you'd like to read the parent of the current article, and it is not displayed in the summary buffer, you might still be able to. That is, if the current group is fetched by NNTP, the parent hasn't expired and the `References' in the current article are not mangled, you can just press `^' or `A r' (`gnus-summary-refer-parent-article'). If everything goes well, you'll get the parent. If the parent is already displayed in the summary buffer, point will just move to this article. If given a positive numerical prefix, fetch that many articles back into the ancestry. If given a negative numerical prefix, fetch just that ancestor. So if you say `3 ^', Gnus will fetch the parent, the grandparent and the grandgrandparent of the current article. If you say `-3 ^', Gnus will only fetch the grandgrandparent of the current article. `A R (Summary)' Fetch all articles mentioned in the `References' header of the article (`gnus-summary-refer-references'). `A T (Summary)' Display the full thread where the current article appears (`gnus-summary-refer-thread'). This command has to fetch all the headers in the current group to work, so it usually takes a while. If you do it often, you may consider setting `gnus-fetch-old-headers' to `invisible' (*note Filling In Threads::). This won't have any visible effects normally, but it'll make this command work a whole lot faster. Of course, it'll make group entry somewhat slow. The `gnus-refer-thread-limit' variable says how many old (i. e., articles before the first displayed in the current group) headers to fetch when doing this command. The default is 200. If `t', all the available headers will be fetched. This variable can be overridden by giving the `A T' command a numerical prefix. `M-^ (Summary)' You can also ask Gnus for an arbitrary article, no matter what group it belongs to. `M-^' (`gnus-summary-refer-article') will ask you for a `Message-ID', which is one of those long, hard-to-read thingies that look something like `<38o6up$6f2@hymir.ifi.uio.no>'. You have to get it all exactly right. No fuzzy searches, I'm afraid. Gnus looks for the `Message-ID' in the headers that have already been fetched, but also tries all the select methods specified by `gnus-refer-article-method' if it is not found. If the group you are reading is located on a back end that does not support fetching by `Message-ID' very well (like `nnspool'), you can set `gnus-refer-article-method' to an NNTP method. It would, perhaps, be best if the NNTP server you consult is the one updating the spool you are reading from, but that's not really necessary. It can also be a list of select methods, as well as the special symbol `current', which means to use the current select method. If it is a list, Gnus will try all the methods in the list until it finds a match. Here's an example setting that will first try the current method, and then ask Google if that fails: (setq gnus-refer-article-method '(current (nnweb "google" (nnweb-type google)))) Most of the mail back ends support fetching by `Message-ID', but do not do a particularly excellent job at it. That is, `nnmbox', `nnbabyl', `nnmaildir', `nnml', are able to locate articles from any groups, while `nnfolder', and `nnimap' are only able to locate articles that have been posted to the current group. (Anything else would be too time consuming.) `nnmh' does not support this at all.  File: gnus, Node: Alternative Approaches, Next: Tree Display, Prev: Finding the Parent, Up: Summary Buffer 3.24 Alternative Approaches =========================== Different people like to read news using different methods. This being Gnus, we offer a small selection of minor modes for the summary buffers. * Menu: * Pick and Read:: First mark articles and then read them. * Binary Groups:: Auto-decode all articles.  File: gnus, Node: Pick and Read, Next: Binary Groups, Up: Alternative Approaches 3.24.1 Pick and Read -------------------- Some newsreaders (like `nn' and, uhm, `Netnews' on VM/CMS) use a two-phased reading interface. The user first marks in a summary buffer the articles she wants to read. Then she starts reading the articles with just an article buffer displayed. Gnus provides a summary buffer minor mode that allows this--`gnus-pick-mode'. This basically means that a few process mark commands become one-keystroke commands to allow easy marking, and it provides one additional command for switching to the summary buffer. Here are the available keystrokes when using pick mode: `.' Pick the article or thread on the current line (`gnus-pick-article-or-thread'). If the variable `gnus-thread-hide-subtree' is true, then this key selects the entire thread when used at the first article of the thread. Otherwise, it selects just the article. If given a numerical prefix, go to that thread or article and pick it. (The line number is normally displayed at the beginning of the summary pick lines.) `SPACE' Scroll the summary buffer up one page (`gnus-pick-next-page'). If at the end of the buffer, start reading the picked articles. `u' Unpick the thread or article (`gnus-pick-unmark-article-or-thread'). If the variable `gnus-thread-hide-subtree' is true, then this key unpicks the thread if used at the first article of the thread. Otherwise it unpicks just the article. You can give this key a numerical prefix to unpick the thread or article at that line. `RET' Start reading the picked articles (`gnus-pick-start-reading'). If given a prefix, mark all unpicked articles as read first. If `gnus-pick-display-summary' is non-`nil', the summary buffer will still be visible when you are reading. All the normal summary mode commands are still available in the pick-mode, with the exception of `u'. However `!' is available which is mapped to the same function `gnus-summary-tick-article-forward'. If this sounds like a good idea to you, you could say: (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) `gnus-pick-mode-hook' is run in pick minor mode buffers. If `gnus-mark-unpicked-articles-as-read' is non-`nil', mark all unpicked articles as read. The default is `nil'. The summary line format in pick mode is slightly different from the standard format. At the beginning of each line the line number is displayed. The pick mode line format is controlled by the `gnus-summary-pick-line-format' variable (*note Formatting Variables::). It accepts the same format specs that `gnus-summary-line-format' does (*note Summary Buffer Lines::).  File: gnus, Node: Binary Groups, Prev: Pick and Read, Up: Alternative Approaches 3.24.2 Binary Groups -------------------- If you spend much time in binary groups, you may grow tired of hitting `X u', `n', `RET' all the time. `M-x gnus-binary-mode' is a minor mode for summary buffers that makes all ordinary Gnus article selection functions uudecode series of articles and display the result instead of just displaying the articles the normal way. The only way, in fact, to see the actual articles is the `g' command, when you have turned on this mode (`gnus-binary-show-article'). `gnus-binary-mode-hook' is called in binary minor mode buffers.  File: gnus, Node: Tree Display, Next: Mail Group Commands, Prev: Alternative Approaches, Up: Summary Buffer 3.25 Tree Display ================= If you don't like the normal Gnus summary display, you might try setting `gnus-use-trees' to `t'. This will create (by default) an additional "tree buffer". You can execute all summary mode commands in the tree buffer. There are a few variables to customize the tree display, of course: `gnus-tree-mode-hook' A hook called in all tree mode buffers. `gnus-tree-mode-line-format' A format string for the mode bar in the tree mode buffers (*note Mode Line Formatting::). The default is `Gnus: %%b %S %Z'. For a list of valid specs, *note Summary Buffer Mode Line::. `gnus-selected-tree-face' Face used for highlighting the selected article in the tree buffer. The default is `modeline'. `gnus-tree-line-format' A format string for the tree nodes. The name is a bit of a misnomer, though--it doesn't define a line, but just the node. The default value is `%(%[%3,3n%]%)', which displays the first three characters of the name of the poster. It is vital that all nodes are of the same length, so you _must_ use `%4,4n'-like specifiers. Valid specs are: `n' The name of the poster. `f' The `From' header. `N' The number of the article. `[' The opening bracket. `]' The closing bracket. `s' The subject. *Note Formatting Variables::. Variables related to the display are: `gnus-tree-brackets' This is used for differentiating between "real" articles and "sparse" articles. The format is ((REAL-OPEN . REAL-CLOSE) (SPARSE-OPEN . SPARSE-CLOSE) (DUMMY-OPEN . DUMMY-CLOSE)) and the default is `((?[ . ?]) (?( . ?)) (?{ . ?}) (?< . ?>))'. `gnus-tree-parent-child-edges' This is a list that contains the characters used for connecting parent nodes to their children. The default is `(?- ?\\ ?|)'. `gnus-tree-minimize-window' If this variable is non-`nil', Gnus will try to keep the tree buffer as small as possible to allow more room for the other Gnus windows. If this variable is a number, the tree buffer will never be higher than that number. The default is `t'. Note that if you have several windows displayed side-by-side in a frame and the tree buffer is one of these, minimizing the tree window will also resize all other windows displayed next to it. You may also wish to add the following hook to keep the window minimized at all times: (add-hook 'gnus-configure-windows-hook 'gnus-tree-perhaps-minimize) `gnus-generate-tree-function' The function that actually generates the thread tree. Two predefined functions are available: `gnus-generate-horizontal-tree' and `gnus-generate-vertical-tree' (which is the default). Here's an example from a horizontal tree buffer: {***}-(***)-[odd]-[Gun] | \[Jan] | \[odd]-[Eri] | \(***)-[Eri] | \[odd]-[Paa] \[Bjo] \[Gun] \[Gun]-[Jor] Here's the same thread displayed in a vertical tree buffer: {***} |--------------------------\-----\-----\ (***) [Bjo] [Gun] [Gun] |--\-----\-----\ | [odd] [Jan] [odd] (***) [Jor] | | |--\ [Gun] [Eri] [Eri] [odd] | [Paa] If you're using horizontal trees, it might be nice to display the trees side-by-side with the summary buffer. You could add something like the following to your `~/.gnus.el' file: (setq gnus-use-trees t gnus-generate-tree-function 'gnus-generate-horizontal-tree gnus-tree-minimize-window nil) (gnus-add-configuration '(article (vertical 1.0 (horizontal 0.25 (summary 0.75 point) (tree 1.0)) (article 1.0)))) *Note Window Layout::.  File: gnus, Node: Mail Group Commands, Next: Various Summary Stuff, Prev: Tree Display, Up: Summary Buffer 3.26 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 3.27 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::. `gnus-propagate-marks' If non-`nil', propagate marks to the backends for possible storing. *Note NNTP marks::, and friends, for a more fine-grained sieve.  File: gnus, Node: Summary Group Information, Next: Searching for Articles, Up: Various Summary Stuff 3.27.1 Summary Group Information -------------------------------- `H f' Try to fetch the FAQ (list of frequently asked questions) for the current group (`gnus-summary-fetch-faq'). Gnus will try to get the FAQ from `gnus-group-faq-directory', which is usually a directory on a remote machine. This variable can also be a list of directories. In that case, giving a prefix to this command will allow you to choose between the various sites. `ange-ftp' or `efs' will probably be used for fetching the file. `H d' Give a brief description of the current group (`gnus-summary-describe-group'). If given a prefix, force rereading the description from the server. `H h' Give an extremely brief description of the most important summary keystrokes (`gnus-summary-describe-briefly'). `H i' Go to the Gnus info node (`gnus-info-find-node').  File: gnus, Node: Searching for Articles, Next: Summary Generation Commands, Prev: Summary Group Information, Up: Various Summary Stuff 3.27.2 Searching for Articles ----------------------------- `M-s' Search through all subsequent (raw) articles for a regexp (`gnus-summary-search-article-forward'). `M-r' Search through all previous (raw) articles for a regexp (`gnus-summary-search-article-backward'). `M-S' Repeat the previous search forwards (`gnus-summary-repeat-search-article-forward'). `M-R' Repeat the previous search backwards (`gnus-summary-repeat-search-article-backward'). `&' This command will prompt you for a header, a regular expression to match on this field, and a command to be executed if the match is made (`gnus-summary-execute-command'). If the header is an empty string, the match is done on the entire article. If given a prefix, search backward instead. For instance, `& RET some.*string RET #' will put the process mark on all articles that have heads or bodies that match `some.*string'. `M-&' Perform any operation on all articles that have been marked with the process mark (`gnus-summary-universal-argument').  File: gnus, Node: Summary Generation Commands, Next: Really Various Summary Commands, Prev: Searching for Articles, Up: Various Summary Stuff 3.27.3 Summary Generation Commands ---------------------------------- `Y g' Regenerate the current summary buffer (`gnus-summary-prepare'). `Y c' Pull all cached articles (for the current group) into the summary buffer (`gnus-summary-insert-cached-articles'). `Y d' Pull all dormant articles (for the current group) into the summary buffer (`gnus-summary-insert-dormant-articles'). `Y t' Pull all ticked articles (for the current group) into the summary buffer (`gnus-summary-insert-ticked-articles').  File: gnus, Node: Really Various Summary Commands, Prev: Summary Generation Commands, Up: Various Summary Stuff 3.27.4 Really Various Summary Commands -------------------------------------- `A D' `C-d' If the current article is a collection of other articles (for instance, a digest), you might use this command to enter a group based on the that article (`gnus-summary-enter-digest-group'). Gnus will try to guess what article type is currently displayed unless you give a prefix to this command, which forces a "digest" interpretation. Basically, whenever you see a message that is a collection of other messages of some format, you `C-d' and read these messages in a more convenient fashion. The variable `gnus-auto-select-on-ephemeral-exit' controls what article should be selected after exiting a digest group. Valid values include: `next' Select the next article. `next-unread' Select the next unread article. `next-noselect' Move the cursor to the next article. This is the default. `next-unread-noselect' Move the cursor to the next unread article. If it has any other value or there is no next (unread) article, the article selected before entering to the digest group will appear. `C-M-d' This command is very similar to the one above, but lets you gather several documents into one biiig group (`gnus-summary-read-document'). It does this by opening several `nndoc' groups for each document, and then opening an `nnvirtual' group on top of these `nndoc' groups. This command understands the process/prefix convention (*note Process/Prefix::). `C-t' Toggle truncation of summary lines (`gnus-summary-toggle-truncation'). This will probably confuse the line centering function in the summary buffer, so it's not a good idea to have truncation switched off while reading articles. `=' Expand the summary buffer window (`gnus-summary-expand-window'). If given a prefix, force an `article' window configuration. `C-M-e' Edit the group parameters (*note Group Parameters::) of the current group (`gnus-summary-edit-parameters'). `C-M-a' Customize the group parameters (*note Group Parameters::) of the current group (`gnus-summary-customize-parameters').  File: gnus, Node: Exiting the Summary Buffer, Next: Crosspost Handling, Prev: Various Summary Stuff, Up: Summary Buffer 3.28 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 p' Mark all articles as read and go to the previous group (`gnus-summary-catchup-and-goto-prev-group'). `Z R' `C-x C-s' Exit this group, and then enter it again (`gnus-summary-reselect-current-group'). If given a prefix, select all articles, both read and unread. `Z G' `M-g' Exit the group, check for new articles in the group, and select the group (`gnus-summary-rescan-group'). If given a prefix, select all articles, both read and unread. `Z N' Exit the group and go to the next group (`gnus-summary-next-group'). `Z P' Exit the group and go to the previous group (`gnus-summary-prev-group'). `Z s' Save the current number of read/marked articles in the dribble buffer and then save the dribble buffer (`gnus-summary-save-newsrc'). If given a prefix, also save the `.newsrc' file(s). Using this command will make exit without updating (the `Q' command) worthless. `gnus-exit-group-hook' is called when you exit the current group with an "updating" exit. For instance `Q' (`gnus-summary-exit-no-update') does not call this hook. If you're in the habit of exiting groups, and then changing your mind about it, you might set `gnus-kill-summary-on-exit' to `nil'. If you do that, Gnus won't kill the summary buffer when you exit it. (Quelle surprise!) Instead it will change the name of the buffer to something like `*Dead Summary ... *' and install a minor mode called `gnus-dead-summary-mode'. Now, if you switch back to this buffer, you'll find that all keys are mapped to a function called `gnus-summary-wake-up-the-dead'. So tapping any keys in a dead summary buffer will result in a live, normal summary buffer. There will never be more than one dead summary buffer at any one time. The data on the current group will be updated (which articles you have read, which articles you have replied to, etc.) when you exit the summary buffer. If the `gnus-use-cross-reference' variable is `t' (which is the default), articles that are cross-referenced to this group and are marked as read, will also be marked as read in the other subscribed groups they were cross-posted to. If this variable is neither `nil' nor `t', the article will be marked as read in both subscribed and unsubscribed groups (*note Crosspost Handling::).  File: gnus, Node: Crosspost Handling, Next: Duplicate Suppression, Prev: Exiting the Summary Buffer, Up: Summary Buffer 3.29 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 `nntp-nov-is-evil' to `t', which slows things down considerably. Also *note Slow/Expensive Connection::. C'est la vie. For an alternative approach, *note Duplicate Suppression::.  File: gnus, Node: Duplicate Suppression, Next: Security, Prev: Crosspost Handling, Up: Summary Buffer 3.30 Duplicate Suppression ========================== By default, Gnus tries to make sure that you don't have to read the same article more than once by utilizing the crossposting mechanism (*note Crosspost Handling::). However, that simple and efficient approach may not work satisfactory for some users for various reasons. 1. The NNTP server may fail to generate the `Xref' header. This is evil and not very common. 2. The NNTP server may fail to include the `Xref' header in the `.overview' data bases. This is evil and all too common, alas. 3. You may be reading the same group (or several related groups) from different NNTP servers. 4. You may be getting mail that duplicates articles posted to groups. I'm sure there are other situations where `Xref' handling fails as well, but these four are the most common situations. If, and only if, `Xref' handling fails for you, then you may consider switching on "duplicate suppression". If you do so, Gnus will remember the `Message-ID's of all articles you have read or otherwise marked as read, and then, as if by magic, mark them as read all subsequent times you see them--in _all_ groups. Using this mechanism is quite likely to be somewhat inefficient, but not overly so. It's certainly preferable to reading the same articles more than once. Duplicate suppression is not a very subtle instrument. It's more like a sledge hammer than anything else. It works in a very simple fashion--if you have marked an article as read, it adds this Message-ID to a cache. The next time it sees this Message-ID, it will mark the article as read with the `M' mark. It doesn't care what group it saw the article in. `gnus-suppress-duplicates' If non-`nil', suppress duplicates. `gnus-save-duplicate-list' If non-`nil', save the list of duplicates to a file. This will make startup and shutdown take longer, so the default is `nil'. However, this means that only duplicate articles read in a single Gnus session are suppressed. `gnus-duplicate-list-length' This variable says how many `Message-ID's to keep in the duplicate suppression list. The default is 10000. `gnus-duplicate-file' The name of the file to store the duplicate suppression list in. The default is `~/News/suppression'. If you have a tendency to stop and start Gnus often, setting `gnus-save-duplicate-list' to `t' is probably a good idea. If you leave Gnus running for weeks on end, you may have it `nil'. On the other hand, saving the list makes startup and shutdown much slower, so that means that if you stop and start Gnus often, you should set `gnus-save-duplicate-list' to `nil'. Uhm. I'll leave this up to you to figure out, I think.  File: gnus, Node: Security, Next: Mailing List, Prev: Duplicate Suppression, Up: Summary Buffer 3.31 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 Emacs is called EasyPG (*note EasyPG: (epa)Top.), but PGG (*note PGG: (pgg)Top.), Mailcrypt, and gpg.el are also supported. 2. To handle S/MIME message, you need to install OpenSSL. OpenSSL 0.9.6 or newer is recommended. The variables that control security functionality on reading/composing messages include: `mm-verify-option' Option of verifying signed parts. `never', not verify; `always', always verify; `known', only verify known protocols. Otherwise, ask user. `mm-decrypt-option' Option of decrypting encrypted parts. `never', no decryption; `always', always decrypt; `known', only decrypt known protocols. Otherwise, ask user. `mm-sign-option' Option of creating signed parts. `nil', use default signing keys; `guided', ask user to select signing keys from the menu. `mm-encrypt-option' Option of creating encrypted parts. `nil', use the first public-key matching the `From:' header as the recipient; `guided', ask user to select recipient keys from the menu. `mml1991-use' Symbol indicating elisp interface to OpenPGP implementation for PGP messages. The default is `epg', but `pgg', `mailcrypt', and `gpg' are also supported although deprecated. By default, Gnus uses the first available interface in this order. `mml2015-use' Symbol indicating elisp interface to OpenPGP implementation for PGP/MIME messages. The default is `epg', but `pgg', `mailcrypt', and `gpg' are also supported although deprecated. By default, Gnus uses the first available interface in this order. By default the buttons that display security information are not shown, because they clutter reading the actual e-mail. You can type `K b' manually to display the information. Use the `gnus-buttonized-mime-types' and `gnus-unbuttonized-mime-types' variables to control this permanently. *note MIME Commands:: for further details, and hints on how to customize these variables to always display security information. Snarfing OpenPGP keys (i.e., importing keys from articles into your key ring) is not supported explicitly through a menu item or command, rather Gnus do detect and label keys as `application/pgp-keys', allowing you to specify whatever action you think is appropriate through the usual MIME infrastructure. You can use a `~/.mailcap' entry (*note mailcap: (emacs-mime)mailcap.) such as the following to import keys using GNU Privacy Guard when you click on the MIME button (*note Using MIME::). application/pgp-keys; gpg --import --interactive --verbose; needsterminal This happens to also be the default action defined in `mailcap-mime-data'. More information on how to set things for sending outgoing signed and encrypted messages up can be found in the message manual (*note Security: (message)Security.).  File: gnus, Node: Mailing List, Prev: Security, Up: Summary Buffer 3.32 Mailing List ================= Gnus understands some mailing list fields of RFC 2369. To enable it, add a `to-list' group parameter (*note Group Parameters::), possibly using `A M' (`gnus-mailing-list-insinuate') in the summary buffer. That enables the following commands to the summary buffer: `C-c C-n h' Send a message to fetch mailing list help, if List-Help field exists. `C-c C-n s' Send a message to subscribe the mailing list, if List-Subscribe field exists. `C-c C-n u' Send a message to unsubscribe the mailing list, if List-Unsubscribe field exists. `C-c C-n p' Post to the mailing list, if List-Post field exists. `C-c C-n o' Send a message to the mailing list owner, if List-Owner field exists. `C-c C-n a' Browse the mailing list archive, if List-Archive field exists.  File: gnus, Node: Article Buffer, Next: Composing Messages, Prev: Summary Buffer, Up: Top 4 Article Buffer **************** The articles are displayed in the article buffer, of which there is only one. All the summary buffers share the same article buffer unless you tell Gnus otherwise. * Menu: * Hiding Headers:: Deciding what headers should be displayed. * Using MIME:: Pushing articles through MIME before reading them. * Customizing Articles:: Tailoring the look of the articles. * Article Keymap:: Keystrokes available in the article buffer. * Misc Article:: Other stuff.  File: gnus, Node: Hiding Headers, Next: Using MIME, Up: Article Buffer 4.1 Hiding Headers ================== The top section of each article is the "head". (The rest is the "body", but you may have guessed that already.) There is a lot of useful information in the head: the name of the person who wrote the article, the date it was written and the subject of the article. That's well and nice, but there's also lots of information most people do not want to see--what systems the article has passed through before reaching you, the `Message-ID', the `References', etc. ad nauseam--and you'll probably want to get rid of some of those lines. If you want to keep all those lines in the article buffer, you can set `gnus-show-all-headers' to `t'. Gnus provides you with two variables for sifting headers: `gnus-visible-headers' If this variable is non-`nil', it should be a regular expression that says what headers you wish to keep in the article buffer. All headers that do not match this variable will be hidden. For instance, if you only want to see the name of the person who wrote the article and the subject, you'd say: (setq gnus-visible-headers "^From:\\|^Subject:") This variable can also be a list of regexps to match headers to remain visible. `gnus-ignored-headers' This variable is the reverse of `gnus-visible-headers'. If this variable is set (and `gnus-visible-headers' is `nil'), it should be a regular expression that matches all lines that you want to hide. All lines that do not match this variable will remain visible. For instance, if you just want to get rid of the `References' line and the `Xref' line, you might say: (setq gnus-ignored-headers "^References:\\|^Xref:") This variable can also be a list of regexps to match headers to be removed. Note that if `gnus-visible-headers' is non-`nil', this variable will have no effect. Gnus can also sort the headers for you. (It does this by default.) You can control the sorting by setting the `gnus-sorted-header-list' variable. It is a list of regular expressions that says in what order the headers are to be displayed. For instance, if you want the name of the author of the article first, and then the subject, you might say something like: (setq gnus-sorted-header-list '("^From:" "^Subject:")) Any headers that are to remain visible, but are not listed in this variable, will be displayed in random order after all the headers listed in this variable. You can hide further boring headers by setting `gnus-treat-hide-boring-headers' to `head'. What this function does depends on the `gnus-boring-article-headers' variable. It's a list, but this list doesn't actually contain header names. Instead it lists various "boring conditions" that Gnus can check and remove from sight. These conditions are: `empty' Remove all empty headers. `followup-to' Remove the `Followup-To' header if it is identical to the `Newsgroups' header. `reply-to' Remove the `Reply-To' header if it lists the same addresses as the `From' header, or if the `broken-reply-to' group parameter is set. `newsgroups' Remove the `Newsgroups' header if it only contains the current group name. `to-address' Remove the `To' header if it only contains the address identical to the current group's `to-address' parameter. `to-list' Remove the `To' header if it only contains the address identical to the current group's `to-list' parameter. `cc-list' Remove the `Cc' header if it only contains the address identical to the current group's `to-list' parameter. `date' Remove the `Date' header if the article is less than three days old. `long-to' Remove the `To' and/or `Cc' header if it is very long. `many-to' Remove all `To' and/or `Cc' headers if there are more than one. To include these three elements, you could say something like: (setq gnus-boring-article-headers '(empty followup-to reply-to)) This is also the default value for this variable.  File: gnus, Node: Using MIME, Next: Customizing Articles, Prev: Hiding Headers, Up: Article Buffer 4.2 Using MIME ============== Mime is a standard for waving your hands through the air, aimlessly, while people stand around yawning. MIME, however, is a standard for encoding your articles, aimlessly, while all newsreaders die of fear. MIME may specify what character set the article uses, the encoding of the characters, and it also makes it possible to embed pictures and other naughty stuff in innocent-looking articles. Gnus pushes MIME articles through `gnus-display-mime-function' to display the MIME parts. This is `gnus-display-mime' by default, which creates a bundle of clickable buttons that can be used to display, save and manipulate the MIME objects. The following commands are available when you have placed point over a MIME button: `RET (Article)' `BUTTON-2 (Article)' Toggle displaying of the MIME object (`gnus-article-press-button'). If built-in viewers can not display the object, Gnus resorts to external viewers in the `mailcap' files. If a viewer has the `copiousoutput' specification, the object is displayed inline. `M-RET (Article)' `v (Article)' Prompt for a method, and then view the MIME object using this method (`gnus-mime-view-part'). `t (Article)' View the MIME object as if it were a different MIME media type (`gnus-mime-view-part-as-type'). `C (Article)' Prompt for a charset, and then view the MIME object using this charset (`gnus-mime-view-part-as-charset'). `o (Article)' Prompt for a file name, and then save the MIME object (`gnus-mime-save-part'). `C-o (Article)' Prompt for a file name, then save the MIME object and strip it from the article. Then proceed to article editing, where a reasonable suggestion is being made on how the altered article should look like. The stripped MIME object will be referred via the message/external-body MIME type. (`gnus-mime-save-part-and-strip'). `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 4.3 Customizing Articles ======================== A slew of functions for customizing how the articles are to look like exist. You can call these functions interactively (*note Article Washing::), or you can have them called automatically when you select the articles. To have them called automatically, you should set the corresponding "treatment" variable. For instance, to have headers hidden, you'd set `gnus-treat-hide-headers'. Below is a list of variables that can be set, but first we discuss the values these variables can have. Note: Some values, while valid, make little sense. Check the list below for sensible values. 1. `nil': Don't do this treatment. 2. `t': Do this treatment on all body parts. 3. `head': Do the treatment on the headers. 4. `first': Do this treatment on the first body part. 5. `last': Do this treatment on the last body part. 6. An integer: Do this treatment on all body parts that have a length less than this number. 7. 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. 8. 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, first, 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 4.4 Article Keymap ================== Most of the keystrokes in the summary buffer can also be used in the article buffer. They should behave as if you typed them in the summary buffer, which means that you don't actually have to have a summary buffer displayed while reading. You can do it all from the article buffer. The key `v' is reserved for users. You can bind it to some command or better use it as a prefix key. A few additional keystrokes are available: `SPACE' Scroll forwards one page (`gnus-article-next-page'). This is exactly the same as `h SPACE h'. `DEL' Scroll backwards one page (`gnus-article-prev-page'). This is exactly the same as `h DEL h'. `C-c ^' If point is in the neighborhood of a `Message-ID' and you press `C-c ^', Gnus will try to get that article from the server (`gnus-article-refer-article'). `C-c C-m' Send a reply to the address near point (`gnus-article-mail'). If given a prefix, include the mail. `s' Reconfigure the buffers so that the summary buffer becomes visible (`gnus-article-show-summary'). `?' Give a very brief description of the available keystrokes (`gnus-article-describe-briefly'). `TAB' Go to the next button, if any (`gnus-article-next-button'). This only makes sense if you have buttonizing turned on. `M-TAB' Go to the previous button, if any (`gnus-article-prev-button'). `R' Send a reply to the current article and yank the current article (`gnus-article-reply-with-original'). If the region is active, only yank the text in the region. `S W' Send a wide reply to the current article and yank the current article (`gnus-article-wide-reply-with-original'). 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 the region is active, only yank the text in the region.  File: gnus, Node: Misc Article, Prev: Article Keymap, Up: Article Buffer 4.5 Misc Article ================ `gnus-single-article-buffer' If non-`nil', use the same article buffer for all the groups. (This is the default.) If `nil', each group will have its own article buffer. `gnus-article-decode-hook' Hook used to decode MIME articles. The default value is `(article-decode-charset article-decode-encoded-words)' `gnus-article-prepare-hook' This hook is called right after the article has been inserted into the article buffer. It is mainly intended for functions that do something depending on the contents; it should probably not be used for changing the contents of the article buffer. `gnus-article-mode-hook' Hook called in article mode buffers. `gnus-article-mode-syntax-table' Syntax table used in article buffers. It is initialized from `text-mode-syntax-table'. `gnus-article-over-scroll' If non-`nil', allow scrolling the article buffer even when there no more new text to scroll in. The default is `nil'. `gnus-article-mode-line-format' This variable is a format string along the same lines as `gnus-summary-mode-line-format' (*note Summary Buffer Mode Line::). It accepts the same format specifications as that variable, with two extensions: `w' The "wash status" of the article. This is a short string with one character for each possible article wash operation that may have been performed. The characters and their meaning: `c' Displayed when cited text may be hidden in the article buffer. `h' Displayed when headers are hidden in the article buffer. `p' Displayed when article is digitally signed or encrypted, and Gnus has hidden the security headers. (N.B. does not tell anything about security status, i.e. good or bad signature.) `s' Displayed when the signature has been hidden in the Article buffer. `o' Displayed when Gnus has treated overstrike characters in the article buffer. `e' Displayed when Gnus has treated emphasized 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 5 Composing Messages ******************** All commands for posting and mailing will put you in a message buffer where you can edit the article all you like, before you send the article by pressing `C-c C-c'. *Note Overview: (message)Top. Where the message will be posted/mailed to depends on your setup (*note Posting Server::). * Menu: * Mail:: Mailing and replying. * Posting Server:: What server should you post and mail via? * POP before SMTP:: You cannot send a mail unless you read a mail. * Mail and Post:: Mailing and posting at the same time. * Archived Messages:: Where Gnus stores the messages you've sent. * Posting Styles:: An easier way to specify who you are. * Drafts:: Postponing messages and rejected messages. * Rejected Articles:: What happens if the server doesn't like your article? * Signing and encrypting:: How to compose secure messages. Also *note Canceling and Superseding:: for information on how to remove articles you shouldn't have posted.  File: gnus, Node: Mail, Next: Posting Server, Up: Composing Messages 5.1 Mail ======== Variables for customizing outgoing mail: `gnus-uu-digest-headers' List of regexps to match headers included in digested messages. The headers will be included in the sequence they are matched. If `nil' include all headers. `gnus-add-to-list' If non-`nil', add a `to-list' group parameter to mail groups that have none when you do a `a'. `gnus-confirm-mail-reply-to-news' If non-`nil', Gnus will ask you for a confirmation when you are about to reply to news articles by mail. If it is `nil', nothing interferes in what you want to do. This can also be a function receiving the group name as the only parameter which should return non-`nil' if a confirmation is needed, or a regular expression matching group names, where confirmation should be asked for. If you find yourself never wanting to reply to mail, but occasionally press `R' anyway, this variable might be for you. `gnus-confirm-treat-mail-like-news' If non-`nil', Gnus also requests confirmation according to `gnus-confirm-mail-reply-to-news' when replying to mail. This is useful for treating mailing lists like newsgroups.  File: gnus, Node: Posting Server, Next: POP before SMTP, Prev: Mail, Up: Composing Messages 5.2 Posting Server ================== When you press those magical `C-c C-c' keys to ship off your latest (extremely intelligent, of course) article, where does it go? Thank you for asking. I hate you. It can be quite complicated. When posting news, Message usually invokes `message-send-news' (*note News Variables: (message)News Variables.). Normally, Gnus will post using the same select method as you're reading from (which might be convenient if you're reading lots of groups from different private servers). However. If the server you're reading from doesn't allow posting, just reading, you probably want to use some other server to post your (extremely intelligent and fabulously interesting) articles. You can then set the `gnus-post-method' to some other method: (setq gnus-post-method '(nnspool "")) Now, if you've done this, and then this server rejects your article, or this server is down, what do you do then? To override this variable you can use a non-zero prefix to the `C-c C-c' command to force using the "current" server, to get back the default behavior, for posting. If you give a zero prefix (i.e., `C-u 0 C-c C-c') to that command, Gnus will prompt you for what method to use for posting. You can also set `gnus-post-method' to a list of select methods. If that's the case, Gnus will always prompt you for what method to use for posting. Finally, if you want to always post using the native select method, you can set this variable to `native'. When sending mail, Message invokes the function specified by the variable `message-send-mail-function'. Gnus tries to set it to a value suitable for your system. *Note Mail Variables: (message)Mail Variables, for more information.  File: gnus, Node: POP before SMTP, Next: Mail and Post, Prev: Posting Server, Up: Composing Messages 5.3 POP before SMTP =================== Does your ISP require the POP-before-SMTP authentication? It is whether you need to connect to the POP mail server within a certain time before sending mails. If so, there is a convenient way. To do that, put the following lines in your `~/.gnus.el' file: (setq message-send-mail-function 'message-smtpmail-send-it) (add-hook 'message-send-mail-hook 'mail-source-touch-pop) It means to let Gnus connect to the POP mail server in advance whenever you send a mail. The `mail-source-touch-pop' function does only a POP authentication according to the value of `mail-sources' without fetching mails, just before sending a mail. Note that you have to use `message-smtpmail-send-it' which runs `message-send-mail-hook' rather than `smtpmail-send-it' and set the value of `mail-sources' for a POP connection correctly. *Note Mail Sources::. If you have two or more POP mail servers set in `mail-sources', you may want to specify one of them to `mail-source-primary-source' as the POP mail server to be used for the POP-before-SMTP authentication. If it is your primary POP mail server (i.e., you are fetching mails mainly from that server), you can set it permanently as follows: (setq mail-source-primary-source '(pop :server "pop3.mail.server" :password "secret")) Otherwise, bind it dynamically only when performing the POP-before-SMTP authentication as follows: (add-hook 'message-send-mail-hook (lambda () (let ((mail-source-primary-source '(pop :server "pop3.mail.server" :password "secret"))) (mail-source-touch-pop))))  File: gnus, Node: Mail and Post, Next: Archived Messages, Prev: POP before SMTP, Up: Composing Messages 5.4 Mail and Post ================= Here's a list of variables relevant to both mailing and posting: `gnus-mailing-list-groups' If your news server offers groups that are really mailing lists gatewayed to the NNTP server, you can read those groups without problems, but you can't post/followup to them without some difficulty. One solution is to add a `to-address' to the group parameters (*note Group Parameters::). An easier thing to do is set the `gnus-mailing-list-groups' to a regexp that matches the groups that really are mailing lists. Then, at least, followups to the mailing lists will work most of the time. Posting to these groups (`a') is still a pain, though. `gnus-user-agent' This variable controls which information should be exposed in the User-Agent header. It can be a list of symbols or a string. Valid symbols are `gnus' (show Gnus version) and `emacs' (show Emacs version). In addition to the Emacs version, you can add `codename' (show (S)XEmacs codename) or either `config' (show system configuration) or `type' (show system type). 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. If `gnus-message-highlight-citation' is t, different levels of citations are highlighted like in Gnus article buffers also in message mode buffers.  File: gnus, Node: Archived Messages, Next: Posting Styles, Prev: Mail and Post, Up: Composing Messages 5.5 Archived Messages ===================== Gnus provides a few different methods for storing the mail and news you send. The default method is to use the "archive virtual server" to store the messages. If you want to disable this completely, the `gnus-message-archive-group' variable should be `nil', which is the default. For archiving interesting messages in a group you read, see the `B c' (`gnus-summary-copy-article') command (*note Mail Group Commands::). `gnus-message-archive-method' says what virtual server Gnus is to use to store sent messages. The default is `"archive"', and when actually being used it is expanded into: (nnfolder "archive" (nnfolder-directory "~/Mail/archive") (nnfolder-active-file "~/Mail/archive/active") (nnfolder-get-new-mail nil) (nnfolder-inhibit-expiry t)) Note: a server like this is saved in the `~/.newsrc.eld' file first so that it may be used as a real method of the server which is named `"archive"' (that is, for the case where `gnus-message-archive-method' is set to `"archive"') ever since. If it once has been saved, it will never be updated by default even if you change the value of `gnus-message-archive-method' afterward. Therefore, the server `"archive"' doesn't necessarily mean the `nnfolder' server like this at all times. If you want the saved method to reflect always the value of `gnus-message-archive-method', set the `gnus-update-message-archive-method' variable to a non-`nil' value. The default value of this variable is `nil'. You can, however, use any mail select method (`nnml', `nnmbox', etc.). `nnfolder' is a quite likable select method for doing this sort of thing, though. If you don't like the default directory chosen, you could say something like: (setq gnus-message-archive-method '(nnfolder "archive" (nnfolder-inhibit-expiry t) (nnfolder-active-file "~/News/sent-mail/active") (nnfolder-directory "~/News/sent-mail/"))) Gnus will insert `Gcc' headers in all outgoing messages that point to one or more group(s) on that server. Which group to use is determined by the `gnus-message-archive-group' variable. This variable can be used to do the following: a string Messages will be saved in that group. Note that you can include a select method in the group name, then the message will not be stored in the select method given by `gnus-message-archive-method', but in the select method specified by the group name, instead. Suppose `gnus-message-archive-method' has the default value shown above. Then setting `gnus-message-archive-group' to `"foo"' means that outgoing messages are stored in `nnfolder+archive:foo', but if you use the value `"nnml:foo"', then outgoing messages will be stored in `nnml:foo'. a list of strings Messages will be saved in all those groups. an alist of regexps, functions and forms When a key "matches", the result is used. `nil' No message archiving will take place. This is the default. Let's illustrate: Just saving to a single group called `MisK': (setq gnus-message-archive-group "MisK") Saving to two groups, `MisK' and `safe': (setq gnus-message-archive-group '("MisK" "safe")) Save to different groups based on what group you are in: (setq gnus-message-archive-group '(("^alt" "sent-to-alt") ("mail" "sent-to-mail") (".*" "sent-to-misc"))) More complex stuff: (setq gnus-message-archive-group '((if (message-news-p) "misc-news" "misc-mail"))) How about storing all news messages in one file, but storing all mail messages in one file per month: (setq gnus-message-archive-group '((if (message-news-p) "misc-news" (concat "mail." (format-time-string "%Y-%m"))))) Now, when you send a message off, it will be stored in the appropriate group. (If you want to disable storing for just one particular message, you can just remove the `Gcc' header that has been inserted.) The archive group will appear in the group buffer the next time you start Gnus, or the next time you press `F' in the group buffer. You can enter it and read the articles in it just like you'd read any other group. If the group gets really big and annoying, you can simply rename if (using `G r' in the group buffer) to something nice--`misc-mail-september-1995', or whatever. New messages will continue to be stored in the old (now empty) group. That's the default method of archiving sent messages. Gnus offers a different way for the people who don't like the default method. In that case you should set `gnus-message-archive-group' to `nil'; this will disable archiving. `gnus-outgoing-message-group' All outgoing messages will be put in this group. If you want to store all your outgoing mail and articles in the group `nnml:archive', you set this variable to that value. This variable can also be a list of group names. If you want to have greater control over what group to put each message in, you can set this variable to a function that checks the current newsgroup name and then returns a suitable group name (or list of names). This variable can be used instead of `gnus-message-archive-group', but the latter is the preferred method. `gnus-gcc-mark-as-read' If non-`nil', automatically mark `Gcc' articles as read. `gnus-gcc-externalize-attachments' If `nil', attach files as normal parts in Gcc copies; if a regexp and matches the Gcc group name, attach files as external parts; if it is `all', attach local files as external parts; if it is other non-`nil', the behavior is the same as `all', but it may be changed in the future.  File: gnus, Node: Posting Styles, Next: Drafts, Prev: Archived Messages, Up: Composing Messages 5.6 Posting Styles ================== All them variables, they make my head swim. So what if you want a different `Organization' and signature based on what groups you post to? And you post both from your home machine and your work machine, and you want different `From' lines, and so on? One way to do stuff like that is to write clever hooks that change the variables you need to have changed. That's a bit boring, so somebody came up with the bright idea of letting the user specify these things in a handy alist. Here's an example of a `gnus-posting-styles' variable: ((".*" (signature "Peace and happiness") (organization "What me?")) ("^comp" (signature "Death to everybody")) ("comp.emacs.i-love-it" (organization "Emacs is it"))) As you might surmise from this example, this alist consists of several "styles". Each style will be applicable if the first element "matches", in some form or other. The entire alist will be iterated over, from the beginning towards the end, and each match will be applied, which means that attributes in later styles that match override the same attributes in earlier matching styles. So `comp.programming.literate' will have the `Death to everybody' signature and the `What me?' `Organization' header. The first element in each style is called the `match'. If it's a string, then Gnus will try to regexp match it against the group name. If it is the form `(header MATCH REGEXP)', then Gnus will look in the original article for a header whose name is MATCH and compare that REGEXP. MATCH and REGEXP are strings. (The original article is the one you are replying or following up to. If you are not composing a reply or a followup, then there is nothing to match against.) If the `match' is a function symbol, that function will be called with no arguments. If it's a variable symbol, then the variable will be referenced. If it's a list, then that list will be `eval'ed. In any case, if this returns a non-`nil' value, then the style is said to "match". Each style may contain an arbitrary amount of "attributes". Each attribute consists of a `(NAME VALUE)' pair. In addition, you can also use the `(NAME :file VALUE)' form or the `(NAME :value VALUE)' form. Where `:file' signifies VALUE represents a file name and its contents should be used as the attribute value, `:value' signifies VALUE does not represent a file name explicitly. The attribute name can be one of: * `signature' * `signature-file' * `x-face-file' * `address', overriding `user-mail-address' * `name', overriding `(user-full-name)' * `body' Note that the `signature-file' attribute honors the variable `message-signature-directory'. The attribute name can also be a string or a symbol. In that case, this will be used as a header name, and the value will be inserted in the headers of the article; if the value is `nil', the header name will be removed. If the attribute name is `eval', the form is evaluated, and the result is thrown away. The attribute value can be a string (used verbatim), a function with zero arguments (the return value will be used), a variable (its value will be used) or a list (it will be `eval'ed and the return value will be used). The functions and sexps are called/`eval'ed in the message buffer that is being set up. The headers of the current article are available through the `message-reply-headers' variable, which is a vector of the following headers: number subject from date id references chars lines xref extra. If you wish to check whether the message you are about to compose is meant to be a news article or a mail message, you can check the values of the `message-news-p' and `message-mail-p' functions. So here's a new example: (setq gnus-posting-styles '((".*" (signature-file "~/.signature") (name "User Name") (x-face-file "~/.xface") (x-url (getenv "WWW_HOME")) (organization "People's Front Against MWM")) ("^rec.humor" (signature my-funny-signature-randomizer)) ((equal (system-name) "gnarly") ;; A form (signature my-quote-randomizer)) (message-news-p ;; A function symbol (signature my-news-signature)) (window-system ;; A value symbol ("X-Window-System" (format "%s" window-system))) ;; If I'm replying to Larsi, set the Organization header. ((header "from" "larsi.*org") (Organization "Somewhere, Inc.")) ((posting-from-work-p) ;; A user defined function (signature-file "~/.work-signature") (address "user@bar.foo") (body "You are fired.\n\nSincerely, your boss.") (organization "Important Work, Inc")) ("nnml:.*" (From (with-current-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. You may also use `message-alternative-emails' instead. *Note Message Headers: (message)Message Headers.  File: gnus, Node: Drafts, Next: Rejected Articles, Prev: Posting Styles, Up: Composing Messages 5.7 Drafts ========== If you are writing a message (mail or news) and suddenly remember that you have a steak in the oven (or some pesto in the food processor, you craaazy vegetarians), you'll probably wish there was a method to save the message you are writing so that you can continue editing it some other day, and send it when you feel its finished. Well, don't worry about it. Whenever you start composing a message of some sort using the Gnus mail and post commands, the buffer you get will automatically associate to an article in a special "draft" group. If you save the buffer the normal way (`C-x C-s', for instance), the article will be saved there. (Auto-save files also go to the draft group.) The draft group is a special group (which is implemented as an `nndraft' group, if you absolutely have to know) called `nndraft:drafts'. The variable `nndraft-directory' says where `nndraft' is to store its files. What makes this group special is that you can't tick any articles in it or mark any articles as read--all articles in the group are permanently unread. If the group doesn't exist, it will be created and you'll be subscribed to it. The only way to make it disappear from the Group buffer is to unsubscribe it. The special properties of the draft group comes from a group property (*note Group Parameters::), and if lost the group behaves like any other group. This means the commands below will not be available. To restore the special properties of the group, the simplest way is to kill the group, using `C-k', and restart Gnus. The group is automatically created again with the correct parameters. The content of the group is not lost. When you want to continue editing the article, you simply enter the draft group and push `D e' (`gnus-draft-edit-message') to do that. You will be placed in a buffer where you left off. Rejected articles will also be put in this draft group (*note Rejected Articles::). If you have lots of rejected messages you want to post (or mail) without doing further editing, you can use the `D s' command (`gnus-draft-send-message'). This command understands the process/prefix convention (*note Process/Prefix::). The `D S' command (`gnus-draft-send-all-messages') will ship off all messages in the buffer. If you have some messages that you wish not to send, you can use the `D t' (`gnus-draft-toggle-sending') command to mark the message as unsendable. This is a toggling command.  File: gnus, Node: Rejected Articles, Next: Signing and encrypting, Prev: Drafts, Up: Composing Messages 5.8 Rejected Articles ===================== Sometimes a news server will reject an article. Perhaps the server doesn't like your face. Perhaps it just feels miserable. Perhaps _there be demons_. Perhaps you have included too much cited text. Perhaps the disk is full. Perhaps the server is down. These situations are, of course, totally beyond the control of Gnus. (Gnus, of course, loves the way you look, always feels great, has angels fluttering around inside of it, doesn't care about how much cited text you include, never runs full and never goes down.) So Gnus saves these articles until some later time when the server feels better. The rejected articles will automatically be put in a special draft group (*note Drafts::). When the server comes back up again, you'd then typically enter that group and send all the articles off.  File: gnus, Node: Signing and encrypting, Prev: Rejected Articles, Up: Composing Messages 5.9 Signing and encrypting ========================== Gnus can digitally sign and encrypt your messages, using vanilla PGP format or PGP/MIME or S/MIME. For decoding such messages, see the `mm-verify-option' and `mm-decrypt-option' options (*note Security::). Often, you would like to sign replies to people who send you signed messages. Even more often, you might want to encrypt messages which are in reply to encrypted messages. Gnus offers `gnus-message-replysign' to enable the former, and `gnus-message-replyencrypt' for the latter. In addition, setting `gnus-message-replysignencrypted' (on by default) will sign automatically encrypted messages. Instructing MML to perform security operations on a MIME part is done using the `C-c C-m s' key map for signing and the `C-c C-m c' key map for encryption, as follows. `C-c C-m s s' Digitally sign current message using S/MIME. `C-c C-m s o' Digitally sign current message using PGP. `C-c C-m s p' Digitally sign current message using PGP/MIME. `C-c C-m c s' Digitally encrypt current message using S/MIME. `C-c C-m c o' Digitally encrypt current message using PGP. `C-c C-m c p' Digitally encrypt current message using PGP/MIME. `C-c C-m C-n' Remove security related MML tags from message. *Note Security: (message)Security, for more information.  File: gnus, Node: Select Methods, Next: Scoring, Prev: Composing Messages, Up: Top 6 Select Methods **************** A "foreign group" is a group not read by the usual (or default) means. It could be, for instance, a group from a different NNTP server, it could be a virtual group, or it could be your own personal mail group. A foreign group (or any group, really) is specified by a "name" and a "select method". To take the latter first, a select method is a list where the first element says what back end to use (e.g. `nntp', `nnspool', `nnml') and the second element is the "server name". There may be additional elements in the select method, where the value may have special meaning for the back end in question. One could say that a select method defines a "virtual server"--so we do just that (*note Server Buffer::). The "name" of the group is the name the back end will recognize the group as. For instance, the group `soc.motss' on the NNTP server `some.where.edu' will have the name `soc.motss' and select method `(nntp "some.where.edu")'. Gnus will call this group `nntp+some.where.edu:soc.motss', even though the `nntp' back end just knows this group as `soc.motss'. The different methods all have their peculiarities, of course. * Menu: * Server Buffer:: Making and editing virtual servers. * Getting News:: Reading USENET news with Gnus. * Getting Mail:: Reading your personal mail with Gnus. * Browsing the Web:: Getting messages from a plethora of Web sources. * IMAP:: Using Gnus as a IMAP client. * Other Sources:: Reading directories, files, SOUP packets. * Combined Groups:: Combining groups into one group. * 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 6.1 Server Buffer ================= Traditionally, a "server" is a machine or a piece of software that one connects to, and then requests information from. Gnus does not connect directly to any real servers, but does all transactions through one back end or other. But that's just putting one layer more between the actual media and Gnus, so we might just as well say that each back end represents a virtual server. For instance, the `nntp' back end may be used to connect to several different actual NNTP servers, or, perhaps, to many different ports on the same actual NNTP server. You tell Gnus which back end to use, and what parameters to set by specifying a "select method". These select method specifications can sometimes become quite complicated--say, for instance, that you want to read from the NNTP server `news.funet.fi' on port number 13, which hangs if queried for NOV headers and has a buggy select. Ahem. Anyway, if you had to specify that for each group that used this server, that would be too much work, so Gnus offers a way of naming select methods, which is what you do in the server buffer. To enter the server buffer, use the `^' (`gnus-group-enter-server-mode') command in the group buffer. * Menu: * Server Buffer Format:: You can customize the look of this buffer. * Server Commands:: Commands to manipulate servers. * Example Methods:: Examples server specifications. * Creating a Virtual Server:: An example session. * Server Variables:: Which variables to set. * Servers and Methods:: You can use server names as select methods. * Unavailable Servers:: Some servers you try to contact may be down. `gnus-server-mode-hook' is run when creating the server buffer.  File: gnus, Node: Server Buffer Format, Next: Server Commands, Up: Server Buffer 6.1.1 Server Buffer Format -------------------------- You can change the look of the server buffer lines by changing the `gnus-server-line-format' variable. This is a `format'-like variable, with some simple extensions: `h' How the news is fetched--the back end name. `n' The name of this server. `w' Where the news is to be fetched from--the address. `s' The opened/closed/denied status of the server. `a' Whether this server is agentized. The mode line can also be customized by using the `gnus-server-mode-line-format' variable (*note Mode Line Formatting::). The following specs are understood: `S' Server name. `M' Server method. Also *note Formatting Variables::.  File: gnus, Node: Server Commands, Next: Example Methods, Prev: Server Buffer Format, Up: Server Buffer 6.1.2 Server Commands --------------------- `v' The key `v' is reserved for users. You can bind it to some command or better use it as a prefix key. `a' Add a new server (`gnus-server-add-server'). `e' Edit a server (`gnus-server-edit-server'). `SPACE' Browse the current server (`gnus-server-read-server'). `q' Return to the group buffer (`gnus-server-exit'). `k' Kill the current server (`gnus-server-kill-server'). `y' Yank the previously killed server (`gnus-server-yank-server'). `c' Copy the current server (`gnus-server-copy-server'). `l' List all servers (`gnus-server-list-servers'). `s' Request that the server scan its sources for new articles (`gnus-server-scan-server'). This is mainly sensible with mail servers. `g' Request that the server regenerate all its data structures (`gnus-server-regenerate-server'). This can be useful if you have a mail back end that has gotten out of sync. `z' Compact all groups in the server under point (`gnus-server-compact-server'). Currently implemented only in nnml (*note Mail Spool::). This removes gaps between article numbers, hence getting a correct total article count.  File: gnus, Node: Example Methods, Next: Creating a Virtual Server, Prev: Server Commands, Up: Server Buffer 6.1.3 Example Methods --------------------- Most select methods are pretty simple and self-explanatory: (nntp "news.funet.fi") Reading directly from the spool is even simpler: (nnspool "") As you can see, the first element in a select method is the name of the back end, and the second is the "address", or "name", if you will. After these two elements, there may be an arbitrary number of `(VARIABLE FORM)' pairs. To go back to the first example--imagine that you want to read from port 15 on that machine. This is what the select method should look like then: (nntp "news.funet.fi" (nntp-port-number 15)) You should read the documentation to each back end to find out what variables are relevant, but here's an `nnmh' example: `nnmh' is a mail back end that reads a spool-like structure. Say you have two structures that you wish to access: One is your private mail spool, and the other is a public one. Here's the possible spec for your private mail: (nnmh "private" (nnmh-directory "~/private/mail/")) (This server is then called `private', but you may have guessed that.) Here's the method for a public spool: (nnmh "public" (nnmh-directory "/usr/information/spool/") (nnmh-get-new-mail nil)) If you are behind a firewall and only have access to the NNTP server from the firewall machine, you can instruct Gnus to `rlogin' on the firewall machine and connect with netcat (http://netcat.sourceforge.net/) 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-netcat) (nntp-via-address "the.firewall.machine") (nntp-address "the.real.nntp.host")) 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'. Here's an example for an indirect connection: (setq gnus-select-method '(nntp "indirect" (nntp-address "news.server.example") (nntp-via-user-name "intermediate_user_name") (nntp-via-address "intermediate.host.example") (nntp-via-rlogin-command "ssh") (nntp-via-rlogin-command-switches ("-C")) (nntp-open-connection-function nntp-open-via-rlogin-and-netcat))) This means that you have to have set up `ssh-agent' correctly to provide automatic authorization, of course. 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 netcat connection to the news server as follows: (nntp "outside" (nntp-pre-command "runsocks") (nntp-open-connection-function nntp-open-netcat-stream) (nntp-address "the.news.server"))  File: gnus, Node: Creating a Virtual Server, Next: Server Variables, Prev: Example Methods, Up: Server Buffer 6.1.4 Creating a Virtual Server ------------------------------- If you're saving lots of articles in the cache by using persistent articles, you may want to create a virtual server to read the cache. First you need to add a new server. The `a' command does that. It would probably be best to use `nnml' to read the cache. You could also use `nnspool' or `nnmh', though. Type `a nnml RET cache RET'. You should now have a brand new `nnml' virtual server called `cache'. You now need to edit it to have the right definitions. Type `e' to edit the server. You'll be entered into a buffer that will contain the following: (nnml "cache") Change that to: (nnml "cache" (nnml-directory "~/News/cache/") (nnml-active-file "~/News/cache/active")) Type `C-c C-c' to return to the server buffer. If you now press `RET' over this virtual server, you should be entered into a browse buffer, and you should be able to enter any of the groups displayed.  File: gnus, Node: Server Variables, Next: Servers and Methods, Prev: Creating a Virtual Server, Up: Server Buffer 6.1.5 Server Variables ---------------------- One sticky point when defining variables (both on back ends and in Emacs in general) is that some variables are typically initialized from other variables when the definition of the variables is being loaded. If you change the "base" variable after the variables have been loaded, you won't change the "derived" variables. This typically affects directory and file variables. For instance, `nnml-directory' is `~/Mail/' by default, and all `nnml' directory variables are initialized from that variable, so `nnml-active-file' will be `~/Mail/active'. If you define a new virtual `nnml' server, it will _not_ suffice to set just `nnml-directory'--you have to explicitly set all the file variables to be what you want them to be. For a complete list of variables for each back end, see each back end's section later in this manual, but here's an example `nnml' definition: (nnml "public" (nnml-directory "~/my-mail/") (nnml-active-file "~/my-mail/active") (nnml-newsgroups-file "~/my-mail/newsgroups")) Server variables are often called "server parameters".  File: gnus, Node: Servers and Methods, Next: Unavailable Servers, Prev: Server Variables, Up: Server Buffer 6.1.6 Servers and Methods ------------------------- Wherever you would normally use a select method (e.g. `gnus-secondary-select-method', in the group select method, when browsing a foreign server) you can use a virtual server name instead. This could potentially save lots of typing. And it's nice all over.  File: gnus, Node: Unavailable Servers, Prev: Servers and Methods, Up: Server Buffer 6.1.7 Unavailable Servers ------------------------- If a server seems to be unreachable, Gnus will mark that server as `denied'. That means that any subsequent attempt to make contact with that server will just be ignored. "It can't be opened," Gnus will tell you, without making the least effort to see whether that is actually the case or not. That might seem quite naughty, but it does make sense most of the time. Let's say you have 10 groups subscribed to on server `nephelococcygia.com'. This server is located somewhere quite far away from you and the machine is quite slow, so it takes 1 minute just to find out that it refuses connection to you today. If Gnus were to attempt to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do that. Once it has gotten a single "connection refused", it will regard that server as "down". So, what happens if the machine was only feeling unwell temporarily? How do you test to see whether the machine has come up again? You jump to the server buffer (*note Server Buffer::) and poke it with the following commands: `O' Try to establish connection to the server on the current line (`gnus-server-open-server'). `C' Close the connection (if any) to the server (`gnus-server-close-server'). `D' Mark the current server as unreachable (`gnus-server-deny-server'). `M-o' Open the connections to all servers in the buffer (`gnus-server-open-all-servers'). `M-c' Close the connections to all servers in the buffer (`gnus-server-close-all-servers'). `R' Remove all marks to whether Gnus was denied connection from any servers (`gnus-server-remove-denials'). `L' Set server status to offline (`gnus-server-offline-server').  File: gnus, Node: Getting News, Next: Getting Mail, Prev: Server Buffer, Up: Select Methods 6.2 Getting News ================ A newsreader is normally used for reading news. Gnus currently provides only two methods of getting news--it can read from an NNTP server, or it can read from a local spool. * Menu: * NNTP:: Reading news from an NNTP server. * News Spool:: Reading news from the local spool.  File: gnus, Node: NNTP, Next: News Spool, Up: Getting News 6.2.1 NNTP ---------- Subscribing to a foreign group from an NNTP server is rather easy. You just specify `nntp' as method and the address of the NNTP server as the, uhm, address. If the NNTP server is located at a non-standard port, setting the third element of the select method to this port number should allow you to connect to the right port. You'll have to edit the group info for that (*note Foreign Groups::). The name of the foreign group can be the same as a native group. In fact, you can subscribe to the same group from as many different servers you feel like. There will be no name collisions. The following variables can be used to create a virtual `nntp' server: `nntp-server-opened-hook' is run after a connection has been made. It can be used to send commands to the NNTP server after it has been contacted. By default it sends the command `MODE READER' to the server with the `nntp-send-mode-reader' function. This function should always be present in this hook. `nntp-authinfo-function' This function will be used to send `AUTHINFO' to the NNTP server. The default function is `nntp-send-authinfo', which looks through your `~/.authinfo' (or whatever you've set the `nntp-authinfo-file' variable to) for applicable entries. If none are found, it will prompt you for a login name and a password. The format of the `~/.authinfo' file is (almost) the same as the `ftp' `~/.netrc' file, which is defined in the `ftp' manual page, but here are the salient facts: 1. The file contains one or more line, each of which define one server. 2. Each line may contain an arbitrary number of token/value pairs. The valid tokens include `machine', `login', `password', `default'. In addition Gnus introduces two new tokens, not present in the original `.netrc'/`ftp' syntax, namely `port' and `force'. (This is the only way the `.authinfo' file format deviates from the `.netrc' file format.) `port' is used to indicate what port on the server the credentials apply to and `force' is explained below. Here's an example file: machine news.uio.no login larsi password geheimnis machine nntp.ifi.uio.no login larsi force yes The token/value pairs may appear in any order; `machine' doesn't have to be first, for instance. In this example, both login name and password have been supplied for the former server, while the latter has only the login name listed, and the user will be prompted for the password. The latter also has the `force' tag, which means that the authinfo will be sent to the NNTP server upon connection; the default (i.e., when there is not `force' tag) is to not send authinfo to the NNTP server until the NNTP server asks for it. You can also add `default' lines that will apply to all servers that don't have matching `machine' lines. default force yes This will force sending `AUTHINFO' commands to all servers not previously mentioned. Remember to not leave the `~/.authinfo' file world-readable. `nntp-server-action-alist' This is a list of regexps to match on server types and actions to be taken when matches are made. For instance, if you want Gnus to beep every time you connect to innd, you could say something like: (setq nntp-server-action-alist '(("innd" (ding)))) You probably don't want to do that, though. The default value is '(("nntpd 1\\.5\\.11t" (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader))) This ensures that Gnus doesn't send the `MODE READER' command to nntpd 1.5.11t, since that command chokes that server, I've been told. `nntp-maximum-request' If the NNTP server doesn't support NOV headers, this back end will collect headers by sending a series of `head' commands. To speed things up, the back end sends lots of these commands without waiting for reply, and then reads all the replies. This is controlled by the `nntp-maximum-request' variable, and is 400 by default. If your network is buggy, you should set this to 1. `nntp-connection-timeout' If you have lots of foreign `nntp' groups that you connect to regularly, you're sure to have problems with NNTP servers not responding properly, or being too loaded to reply within reasonable time. This is can lead to awkward problems, which can be helped somewhat by setting `nntp-connection-timeout'. This is an integer that says how many seconds the `nntp' back end should wait for a connection before giving up. If it is `nil', which is the default, no timeouts are done. `nntp-nov-is-evil' If the NNTP server does not support NOV, you could set this variable to `t', but `nntp' usually checks automatically whether NOV can be used. `nntp-xover-commands' List of strings used as commands to fetch NOV lines from a server. The default value of this variable is `("XOVER" "XOVERVIEW")'. `nntp-nov-gap' `nntp' normally sends just one big request for NOV lines to the server. The server responds with one huge list of lines. However, if you have read articles 2-5000 in the group, and only want to read article 1 and 5001, that means that `nntp' will fetch 4999 NOV lines that you will not need. This variable says how big a gap between two consecutive articles is allowed to be before the `XOVER' request is split into several request. Note that if your network is fast, setting this variable to a really small number means that fetching will probably be slower. If this variable is `nil', `nntp' will never split requests. The default is 5. `nntp-xref-number-is-evil' When Gnus refers to an article having the `Message-ID' that a user specifies or having the `Message-ID' of the parent article of the current one (*note Finding the Parent::), Gnus sends a `HEAD' command to the NNTP server to know where it is, and the server returns the data containing the pairs of a group and an article number in the `Xref' header. Gnus normally uses the article number to refer to the article if the data shows that that article is in the current group, while it uses the `Message-ID' otherwise. However, some news servers, e.g., ones running Diablo, run multiple engines having the same articles but article numbers are not kept synchronized between them. In that case, the article number that appears in the `Xref' header varies by which engine is chosen, so you cannot refer to the parent article that is in the current group, for instance. If you connect to such a server, set this variable to a non-`nil' value, and Gnus never uses article numbers. For example: (setq gnus-select-method '(nntp "newszilla" (nntp-address "newszilla.example.com") (nntp-xref-number-is-evil t) ...)) The default value of this server variable is `nil'. `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-never-echoes-commands' Non-`nil' means the nntp server never echoes commands. It is reported that some nntps server doesn't echo commands. So, you may want to set this to non-`nil' in the method for such a server setting `nntp-open-connection-function' to `nntp-open-ssl-stream' for example. The default value is `nil'. Note that the `nntp-open-connection-functions-never-echo-commands' variable overrides the `nil' value of this variable. `nntp-open-connection-functions-never-echo-commands' List of functions that never echo commands. Add or set a function which you set to `nntp-open-connection-function' to this list if it does not echo commands. Note that a non-`nil' value of the `nntp-never-echoes-commands' variable overrides this variable. The default value is `(nntp-open-network-stream)'. `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 6.2.1.1 Direct Functions ........................ These functions are called direct because they open a direct connection between your machine and the NNTP server. The behavior of these functions is also affected by commonly understood variables (*note Common Variables::). `nntp-open-network-stream' This is the default, and simply connects to some port or other on the remote system. `nntp-open-tls-stream' Opens a connection to a server over a "secure" channel. To use this you must have GNUTLS (http://www.gnu.org/software/gnutls/) installed. You then define a server as follows: ;; "nntps" is port 563 and is predefined in our `/etc/services' ;; however, `gnutls-cli -p' doesn't like named ports. ;; (nntp "snews.bar.com" (nntp-open-connection-function nntp-open-tls-stream) (nntp-port-number 563) (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-netcat-stream' Opens a connection to an NNTP server using the `netcat' program. 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-netcat-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. `nntp-open-telnet-stream' Like `nntp-open-netcat-stream', but uses `telnet' rather than `netcat'. `telnet' is a bit less robust because of things like line-end-conversion, but sometimes netcat is simply not available. The previous example would turn into: (nntp "socksified" (nntp-pre-command "runsocks") (nntp-open-connection-function nntp-open-telnet-stream) (nntp-address "the.news.server") (nntp-end-of-line "\n"))  File: gnus, Node: Indirect Functions, Next: Common Variables, Prev: Direct Functions, Up: NNTP 6.2.1.2 Indirect Functions .......................... These functions are called indirect because they connect to an intermediate host before actually connecting to the NNTP server. All of these functions and related variables are also said to belong to the "via" family of connection: they're all prefixed with "via" to make things cleaner. The behavior of these functions is also affected by commonly understood variables (*note Common Variables::). `nntp-open-via-rlogin-and-netcat' Does an `rlogin' on a remote system, and then uses `netcat' to connect 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-netcat'-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. `nntp-open-via-rlogin-and-telnet' Does essentially the same, but uses `telnet' instead of `netcat' to connect to the real NNTP server from the intermediate host. `telnet' is a bit less robust because of things like line-end-conversion, but sometimes `netcat' is simply not available. `nntp-open-via-rlogin-and-telnet'-specific variables: `nntp-telnet-command' Command used to connect to the real NNTP server from the intermediate host. The default is `telnet'. `nntp-telnet-switches' List of strings to be used as the switches to the `nntp-telnet-command' command. The default is `("-8")'. `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'. If you use `ssh', you may need to set this to `("-t" "-e" "none")' or `("-C" "-t" "-e" "none")' if the telnet command requires a pseudo-tty allocation on an intermediate host. The default is `nil'. Note that you may want to change the value for `nntp-end-of-line' to `\n' (*note Common Variables::). `nntp-open-via-telnet-and-telnet' Does essentially the same, but uses `telnet' instead of `rlogin' to connect to the intermediate host. `nntp-open-via-telnet-and-telnet'-specific variables: `nntp-via-telnet-command' Command used to `telnet' the intermediate host. The default is `telnet'. `nntp-via-telnet-switches' List of strings to be used as the switches to the `nntp-via-telnet-command' command. The default is `("-8")'. `nntp-via-user-password' Password to use when logging in on the intermediate host. `nntp-via-envuser' If non-`nil', the intermediate `telnet' session (client and server both) will support the `ENVIRON' option and not prompt for login name. This works for Solaris `telnet', for instance. `nntp-via-shell-prompt' Regexp matching the shell prompt on the intermediate host. The default is `bash\\|\$ *\r?$\\|> *\r?'. 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 6.2.1.3 Common Variables ........................ The following variables affect the behavior of all, or several of the pre-made connection functions. When not specified, all functions are affected (the values of the following variables will be used as the default if each virtual `nntp' server doesn't specify those server variables individually). `nntp-pre-command' A command wrapper to use when connecting through a non native connection function (all except `nntp-open-network-stream', `nntp-open-tls-stream', and `nntp-open-ssl-stream'). This is where you would put a `SOCKS' wrapper for instance. `nntp-address' The address of the NNTP server. `nntp-port-number' Port number to connect to the NNTP server. The default is `nntp'. If you use NNTP over TLS/SSL, you may want to use integer ports rather than named ports (i.e, use `563' instead of `snews' or `nntps'), because external TLS/SSL tools may not work with named ports. `nntp-end-of-line' String to use as end-of-line marker when talking to the NNTP server. This is `\r\n' by default, but should be `\n' when using a non native telnet connection function. `nntp-netcat-command' Command to use when connecting to the NNTP server through `netcat'. This is _not_ for an intermediate host. This is just for the real NNTP server. The default is `nc'. `nntp-netcat-switches' A list of switches to pass to `nntp-netcat-command'. The default is `()'.  File: gnus, Node: NNTP marks, Prev: Common Variables, Up: NNTP 6.2.1.4 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 6.2.2 News Spool ---------------- Subscribing to a foreign group from the local spool is extremely easy, and might be useful, for instance, to speed up reading groups that contain very big articles--`alt.binaries.pictures.furniture', for instance. Anyway, you just specify `nnspool' as the method and `""' (or anything else) as the address. If you have access to a local spool, you should probably use that as the native select method (*note Finding the News::). It is normally faster than using an `nntp' select method, but might not be. It depends. You just have to try to find out what's best at your site. `nnspool-inews-program' Program used to post an article. `nnspool-inews-switches' Parameters given to the inews program when posting an article. `nnspool-spool-directory' Where `nnspool' looks for the articles. This is normally `/usr/spool/news/'. `nnspool-nov-directory' Where `nnspool' will look for NOV files. This is normally `/usr/spool/news/over.view/'. `nnspool-lib-dir' Where the news lib dir is (`/usr/lib/news/' by default). `nnspool-active-file' The name of the active file. `nnspool-newsgroups-file' The name of the group descriptions file. `nnspool-history-file' The name of the news history file. `nnspool-active-times-file' The name of the active date file. `nnspool-nov-is-evil' If non-`nil', `nnspool' won't try to use any NOV files that it finds. `nnspool-sift-nov-with-sed' If non-`nil', which is the default, use `sed' to get the relevant portion from the overview file. If `nil', `nnspool' will load the entire file into a buffer and process it there.  File: gnus, Node: Getting Mail, Next: Browsing the Web, Prev: Getting News, Up: Select Methods 6.3 Getting Mail ================ Reading mail with a newsreader--isn't that just plain WeIrD? But of course. * Menu: * Mail in a Newsreader:: Important introductory notes. * Getting Started Reading Mail:: A simple cookbook example. * Splitting Mail:: How to create mail groups. * Mail Sources:: How to tell Gnus where to get mail from. * Mail Back End Variables:: Variables for customizing mail handling. * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. * Group Mail Splitting:: Use group customize to drive mail splitting. * Incorporating Old Mail:: What about the old mail you have? * Expiring Mail:: Getting rid of unwanted mail. * Washing Mail:: Removing cruft from the mail you get. * Duplicates:: Dealing with duplicated mail. * Not Reading Mail:: Using mail back ends for reading other files. * Choosing a Mail Back End:: Gnus can read a variety of mail formats.  File: gnus, Node: Mail in a Newsreader, Next: Getting Started Reading Mail, Up: Getting Mail 6.3.1 Mail in a Newsreader -------------------------- If you are used to traditional mail readers, but have decided to switch to reading mail with Gnus, you may find yourself experiencing something of a culture shock. Gnus does not behave like traditional mail readers. If you want to make it behave that way, you can, but it's an uphill battle. Gnus, by default, handles all its groups using the same approach. This approach is very newsreaderly--you enter a group, see the new/unread messages, and when you read the messages, they get marked as read, and you don't see them any more. (Unless you explicitly ask for them.) In particular, you do not do anything explicitly to delete messages. Does this mean that all the messages that have been marked as read are deleted? How awful! But, no, it means that old messages are "expired" according to some scheme or other. For news messages, the expire process is controlled by the news administrator; for mail, the expire process is controlled by you. The expire process for mail is covered in depth in *note Expiring Mail::. What many Gnus users find, after using it a while for both news and mail, is that the transport mechanism has very little to do with how they want to treat a message. Many people subscribe to several mailing lists. These are transported via SMTP, and are therefore mail. But we might go for weeks without answering, or even reading these messages very carefully. We may not need to save them because if we should need to read one again, they are archived somewhere else. Some people have local news groups which have only a handful of readers. These are transported via NNTP, and are therefore news. But we may need to read and answer a large fraction of the messages very carefully in order to do our work. And there may not be an archive, so we may need to save the interesting messages the same way we would personal mail. The important distinction turns out to be not the transport mechanism, but other factors such as how interested we are in the subject matter, or how easy it is to retrieve the message if we need to read it again. Gnus provides many options for sorting mail into "groups" which behave like newsgroups, and for treating each group (whether mail or news) differently. Some users never get comfortable using the Gnus (ahem) paradigm and wish that Gnus should grow up and be a male, er, mail reader. It is possible to whip Gnus into a more mailreaderly being, but, as said before, it's not easy. People who prefer proper mail readers should try VM instead, which is an excellent, and proper, mail reader. I don't mean to scare anybody off, but I want to make it clear that you may be required to learn a new way of thinking about messages. After you've been subjected to The Gnus Way, you will come to love it. I can guarantee it. (At least the guy who sold me the Emacs Subliminal Brain-Washing Functions that I've put into Gnus did guarantee it. You Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way. You Do.)  File: gnus, Node: Getting Started Reading Mail, Next: Splitting Mail, Prev: Mail in a Newsreader, Up: Getting Mail 6.3.2 Getting Started Reading Mail ---------------------------------- It's quite easy to use Gnus to read your new mail. You just plonk the mail back end of your choice into `gnus-secondary-select-methods', and things will happen automatically. For instance, if you want to use `nnml' (which is a "one file per mail" back end), you could put the following in your `~/.gnus.el' file: (setq gnus-secondary-select-methods '((nnml ""))) Now, the next time you start Gnus, this back end will be queried for new articles, and it will move all the messages in your spool file to its directory, which is `~/Mail/' by default. The new group that will be created (`mail.misc') will be subscribed, and you can read it like any other group. You will probably want to split the mail into several groups, though: (setq nnmail-split-methods '(("junk" "^From:.*Lars Ingebrigtsen") ("crazy" "^Subject:.*die\\|^Organization:.*flabby") ("other" ""))) This will result in three new `nnml' mail groups being created: `nnml:junk', `nnml:crazy', and `nnml:other'. All the mail that doesn't fit into the first two groups will be placed in the last group. This should be sufficient for reading mail with Gnus. You might want to give the other sections in this part of the manual a perusal, though. Especially *note Choosing a Mail Back End:: and *note Expiring Mail::.  File: gnus, Node: Splitting Mail, Next: Mail Sources, Prev: Getting Started Reading Mail, Up: Getting Mail 6.3.3 Splitting Mail -------------------- The `nnmail-split-methods' variable says how the incoming mail is to be split into groups. (setq nnmail-split-methods '(("mail.junk" "^From:.*Lars Ingebrigtsen") ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") ("mail.other" ""))) This variable is a list of lists, where the first element of each of these lists is the name of the mail group (they do not have to be called something beginning with `mail', by the way), and the second element is a regular expression used on the header of each mail to determine if it belongs in this mail group. The first string may contain `\\1' forms, like the ones used by `replace-match' to insert sub-expressions from the matched text. For instance: ("list.\\1" "From:.* \\(.*\\)-list@majordomo.com") In that case, `nnmail-split-lowercase-expanded' controls whether the inserted text should be made lowercase. *Note Fancy Mail Splitting::. The second element can also be a function. In that case, it will be called narrowed to the headers with the first element of the rule as the argument. It should return a non-`nil' value if it thinks that the mail belongs in that group. The last of these groups should always be a general one, and the regular expression should _always_ be `""' so that it matches any mails that haven't been matched by any of the other regexps. (These rules are processed from the beginning of the alist toward the end. The first rule to make a match will "win", unless you have crossposting enabled. In that case, all matching rules will "win".) If no rule matched, the mail will end up in the `bogus' group. When new groups are created by splitting mail, you may want to run `gnus-group-find-new-groups' to see the new groups. This also applies to the `bogus' group. If you like to tinker with this yourself, you can set this variable to a function of your choice. This function will be called without any arguments in a buffer narrowed to the headers of an incoming mail message. The function should return a list of group names that it thinks should carry this mail message. Note that the mail back ends are free to maul the poor, innocent, incoming headers all they want to. They all add `Lines' headers; some add `X-Gnus-Group' headers; most rename the Unix mbox `From' 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, splitting does not decode headers, so you can not match on non-ASCII strings. But it is useful if you want to match articles based on the raw header data. To enable it, set the `nnmail-mail-splitting-decodes' variable to a non-`nil' value. In addition, the value of the `nnmail-mail-splitting-charset' variable is used for decoding non-MIME encoded string when `nnmail-mail-splitting-decodes' is non-`nil'. The default value is `nil' which means not to decode non-MIME encoded string. A suitable value for you will be `undecided' or be the charset used normally in mails you are interested in. By default, splitting is performed on all incoming messages. If you specify a `directory' entry for the variable `mail-sources' (*note Mail Source Specifiers::), however, then splitting does _not_ happen by default. You can set the variable `nnmail-resplit-incoming' to a non-`nil' value to make splitting happen even in this case. (This variable has no effect on other kinds of entries.) Gnus gives you all the opportunity you could possibly want for shooting yourself in the foot. Let's say you create a group that will contain all the mail you get from your boss. And then you accidentally unsubscribe from the group. Gnus will still put all the mail from your boss in the unsubscribed group, and so, when your boss mails you "Have that report ready by Monday or you're fired!", you'll never see it and, come Tuesday, you'll still believe that you're gainfully employed while you really should be out collecting empty bottles to save up for next month's rent money.  File: gnus, Node: Mail Sources, Next: Mail Back End Variables, Prev: Splitting Mail, Up: Getting Mail 6.3.4 Mail Sources ------------------ Mail can be gotten from many different sources--the mail spool, from a POP mail server, from a procmail directory, or from a maildir, for instance. * Menu: * Mail Source Specifiers:: How to specify what a mail source is. * Mail Source Customization:: Some variables that influence things. * Fetching Mail:: Using the mail source specifiers.  File: gnus, Node: Mail Source Specifiers, Next: Mail Source Customization, Up: Mail Sources 6.3.4.1 Mail Source Specifiers .............................. You tell Gnus how to fetch mail by setting `mail-sources' (*note Fetching Mail::) to a "mail source specifier". Here's an example: (pop :server "pop3.mailserver.com" :user "myname") As can be observed, a mail source specifier is a list where the first element is a "mail source type", followed by an arbitrary number of "keywords". Keywords that are not explicitly specified are given default values. The `mail-sources' is global for all mail groups. You can specify an additional mail source for a particular group by including the `group' mail specifier in `mail-sources', and setting a `mail-source' group parameter (*note Group Parameters::) specifying a single mail source. When this is used, `mail-sources' is typically just `(group)'; the `mail-source' parameter for a group might look like this: (mail-source . (file :path "home/user/spools/foo.spool")) This means that the group's (and only this group's) messages will be fetched from the spool file `/user/spools/foo.spool'. 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 the `movemail' and temporary file 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 `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 you may get duplicate mails or the whole thing can fall apart and leave you with a corrupt mailbox. Here are some examples for getting mail from a POP server. 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 Make sure nothing is interfering with the output of the program, e.g., don't forget to redirect the error output to the void. 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 receives 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") `group' Get the actual mail source from the `mail-source' group parameter, *Note Group Parameters::. "Common Keywords" Common keywords can be used in any type of mail source. Keywords: `:plugged' If non-`nil', fetch the mail even when Gnus is unplugged. If you use directory source to get mail, you can specify it as in this example: (setq mail-sources '((directory :path "/home/pavel/.Spool/" :suffix "" :plugged t))) Gnus will then fetch your mail even when you are unplugged. This is useful when you use local mail and news. 6.3.4.2 Function Interface .......................... Some of the above keywords specify a Lisp function to be executed. For each keyword `:foo', the Lisp variable `foo' is bound to the value of the keyword while the function is executing. For example, consider the following mail-source setting: (setq mail-sources '((pop :user "jrl" :server "pophost" :function fetchfunc))) While the function `fetchfunc' is executing, the symbol `user' is bound to `"jrl"', and the symbol `server' is bound to `"pophost"'. The symbols `port', `password', `program', `prescript', `postscript', `function', and `authentication' are also bound (to their default values). See above for a list of keywords for each type of mail source.  File: gnus, Node: Mail Source Customization, Next: Fetching Mail, Prev: Mail Source Specifiers, Up: Mail Sources 6.3.4.3 Mail Source Customization ................................. The following is a list of variables that influence how the mail is fetched. You would normally not need to set or change any of these variables. `mail-source-crash-box' File where mail will be stored while processing it. The default is `~/.emacs-mail-crash-box'. `mail-source-delete-incoming' If non-`nil', delete incoming files after handling them. If `t', delete the files immediately, if `nil', never delete any files. If a positive number, delete files older than number of days (the deletion 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-incoming' defaults to `10' in alpha Gnusae and `2' in released Gnusae. *Note Gnus Development::. `mail-source-delete-old-incoming-confirm' If non-`nil', ask for confirmation before deleting old incoming files. This variable only applies when `mail-source-delete-incoming' is a positive number. `mail-source-ignore-errors' If non-`nil', ignore errors when reading mail from a mail source. `mail-source-directory' Directory where incoming mail source files (if any) will be stored. The default is `~/Mail/'. At present, the only thing this is used for is to say where the incoming files will be stored if the variable `mail-source-delete-incoming' is `nil' or a number. `mail-source-incoming-file-prefix' Prefix for file name for storing incoming mail. The default is `Incoming', in which case files will end up with names like `Incoming30630D_' or `Incoming298602ZD'. This is really only relevant if `mail-source-delete-incoming' is `nil' or a number. `mail-source-default-file-modes' All new mail files will get this file mode. The default is 384. `mail-source-movemail-program' If non-`nil', name of program for fetching new mail. If `nil', `movemail' in EXEC-DIRECTORY.  File: gnus, Node: Fetching Mail, Prev: Mail Source Customization, Up: Mail Sources 6.3.4.4 Fetching Mail ..................... The way to actually tell Gnus where to get new mail from is to set `mail-sources' to a list of mail source specifiers (*note Mail Source Specifiers::). If this variable is `nil', the mail back ends will never attempt to fetch mail by themselves. If you want to fetch mail both from your local spool as well as a POP mail server, you'd say something like: (setq mail-sources '((file) (pop :server "pop3.mail.server" :password "secret"))) Or, if you don't want to use any of the keyword defaults: (setq mail-sources '((file :path "/var/spool/mail/user-name") (pop :server "pop3.mail.server" :user "user-name" :port "pop3" :password "secret"))) When you use a mail back end, Gnus will slurp all your mail from your inbox and plonk it down in your home directory. Gnus doesn't move any mail if you're not using a mail back end--you have to do a lot of magic invocations first. At the time when you have finished drawing the pentagram, lightened the candles, and sacrificed the goat, you really shouldn't be too surprised when Gnus moves your mail.  File: gnus, Node: Mail Back End Variables, Next: Fancy Mail Splitting, Prev: Mail Sources, Up: Getting Mail 6.3.5 Mail Back End Variables ----------------------------- These variables are (for the most part) pertinent to all the various mail back ends. `nnmail-read-incoming-hook' The mail back ends all call this hook after reading new mail. You can use this hook to notify any mail watch programs, if you want to. `nnmail-split-hook' Hook run in the buffer where the mail headers of each message is kept just before the splitting based on these headers is done. The hook is free to modify the buffer contents in any way it sees fit--the buffer is discarded after the splitting has been done, and no changes performed in the buffer will show up in any files. `gnus-article-decode-encoded-words' is one likely function to add to this hook. `nnmail-pre-get-new-mail-hook' `nnmail-post-get-new-mail-hook' These are two useful hooks executed when treating new incoming mail--`nnmail-pre-get-new-mail-hook' (is called just before starting to handle the new mail) and `nnmail-post-get-new-mail-hook' (is called when the mail handling is done). Here's and example of using these two hooks to change the default file modes the new mail files get: (add-hook 'nnmail-pre-get-new-mail-hook (lambda () (set-default-file-modes 511))) (add-hook 'nnmail-post-get-new-mail-hook (lambda () (set-default-file-modes 551))) `nnmail-use-long-file-names' If non-`nil', the mail back ends will use long file and directory names. Groups like `mail.misc' will end up in directories (assuming use of `nnml' back end) or files (assuming use of `nnfolder' back end) like `mail.misc'. If it is `nil', the same group will end up in `mail/misc'. `nnmail-delete-file-function' Function called to delete files. It is `delete-file' by default. `nnmail-cache-accepted-message-ids' If non-`nil', put the `Message-ID's of articles imported into the back end (via `Gcc', for instance) into the mail duplication discovery cache. The default is `nil'. `nnmail-cache-ignore-groups' This can be a regular expression or a list of regular expressions. Group names that match any of the regular expressions will never be recorded in the `Message-ID' cache. This can be useful, for example, when using Fancy Splitting (*note Fancy Mail Splitting::) together with the function `nnmail-split-fancy-with-parent'.  File: gnus, Node: Fancy Mail Splitting, Next: Group Mail Splitting, Prev: Mail Back End Variables, Up: Getting Mail 6.3.6 Fancy Mail Splitting -------------------------- If the rather simple, standard method for specifying how to split mail doesn't allow you to do what you want, you can set `nnmail-split-methods' to `nnmail-split-fancy'. Then you can play with the `nnmail-split-fancy' variable. Let's look at an example value of this variable first: ;; Messages from the mailer daemon are not crossposted to any of ;; the ordinary groups. Warnings are put in a separate group ;; from real errors. (| ("from" mail (| ("subject" "warn.*" "mail.warning") "mail.misc")) ;; Non-error messages are crossposted to all relevant ;; groups, but we don't crosspost between the group for the ;; (ding) list and the group for other (ding) related mail. (& (| (any "ding@ifi\\.uio\\.no" "ding.list") ("subject" "ding" "ding.misc")) ;; Other mailing lists... (any "procmail@informatik\\.rwth-aachen\\.de" "procmail.list") (any "SmartList@informatik\\.rwth-aachen\\.de" "SmartList.list") ;; Both lists below have the same suffix, so prevent ;; cross-posting to mkpkg.list of messages posted only to ;; the bugs- list, but allow cross-posting when the ;; message was really cross-posted. (any "bugs-mypackage@somewhere" "mypkg.bugs") (any "mypackage@somewhere" - "bugs-mypackage" "mypkg.list") ;; People... (any "larsi@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) ;; Unmatched mail goes to the catch all group. "misc.misc") This variable has the format of a "split". A split is a (possibly) recursive structure where each split may contain other splits. Here are the possible split syntaxes: `group' If the split is a string, that will be taken as a group name. Normal regexp match expansion will be done. See below for examples. `(FIELD VALUE [- RESTRICT [...] ] SPLIT [INVERT-PARTIAL])' The split can be a list containing at least three elements. If the first element FIELD (a regexp matching a header) contains VALUE (also a regexp) then store the message as specified by SPLIT. If RESTRICT (yet another regexp) matches some string after FIELD and before the end of the matched VALUE, the SPLIT is ignored. If none of the RESTRICT clauses match, SPLIT is processed. The last element INVERT-PARTIAL is optional. If it is non-`nil', the match-partial-words behavior controlled by the variable `nnmail-split-fancy-match-partial-words' (see below) is be inverted. (New in Gnus 5.10.7) `(| SPLIT ...)' If the split is a list, and the first element is `|' (vertical bar), then process each SPLIT until one of them matches. A SPLIT is said to match if it will cause the mail message to be stored in one or more groups. `(& SPLIT ...)' If the split is a list, and the first element is `&', then process all SPLITs in the list. `junk' If the split is the symbol `junk', then don't save (i.e., delete) this message. Use with extreme caution. `(: FUNCTION ARG1 ARG2 ...)' If the split is a list, and the first element is `:', then the second element will be called as a function with ARGS given as arguments. The function should return a SPLIT. For instance, the following function could be used to split based on the body of the messages: (defun split-on-body () (save-excursion (save-restriction (widen) (goto-char (point-min)) (when (re-search-forward "Some.*string" nil t) "string.group")))) The buffer is narrowed to the header of the message in question when FUNCTION is run. That's why `(widen)' needs to be called after `save-excursion' and `save-restriction' in the example above. Also note that with the nnimap backend, message bodies will not be downloaded by default. You need to set `nnimap-split-download-body' to `t' to do that (*note Splitting in IMAP::). `(! FUNC SPLIT)' If the split is a list, and the first element is `!', then SPLIT will be processed, and FUNC will be called as a function with the result of SPLIT as argument. FUNC should return a split. `nil' If the split is `nil', it is ignored. In these splits, FIELD must match a complete field name. Normally, VALUE in these splits must match a complete _word_ according to the fundamental mode syntax table. In other words, all VALUE's will be implicitly surrounded by `\<...\>' markers, which are word delimiters. Therefore, if you use the following split, for example, (any "joe" "joemail") messages sent from `joedavis@foo.org' will normally not be filed in `joemail'. If you want to alter this behavior, you can use any of the following three ways: 1. You can set the `nnmail-split-fancy-match-partial-words' variable to non-`nil' in order to ignore word boundaries and instead the match becomes more like a grep. This variable controls whether partial words are matched during fancy splitting. The default value is `nil'. Note that it influences all VALUE's in your split rules. 2. VALUE beginning with `.*' ignores word boundaries in front of a word. Similarly, if VALUE ends with `.*', word boundaries in the rear of a word will be ignored. For example, the VALUE `"@example\\.com"' does not match `foo@example.com' but `".*@example\\.com"' does. 3. You can set the INVERT-PARTIAL flag in your split rules of the `(FIELD VALUE ...)' types, aforementioned in this section. If the flag is set, word boundaries on both sides of a word are ignored even if `nnmail-split-fancy-match-partial-words' is `nil'. Contrarily, if the flag is set, word boundaries are not ignored even if `nnmail-split-fancy-match-partial-words' is non-`nil'. (New in Gnus 5.10.7) FIELD and VALUE can also be Lisp symbols, in that case they are expanded as specified by the variable `nnmail-split-abbrev-alist'. This is an alist of cons cells, where the CAR of a cell contains the key, and the CDR contains the associated value. Predefined entries in `nnmail-split-abbrev-alist' include: `from' Matches the `From', `Sender' and `Resent-From' fields. `to' Matches the `To', `Cc', `Apparently-To', `Resent-To' and `Resent-Cc' fields. `any' Is the union of the `from' and `to' entries. `nnmail-split-fancy-syntax-table' is the syntax table in effect when all this splitting is performed. If you want to have Gnus create groups dynamically based on some information in the headers (i.e., do `replace-match'-like substitutions in the group names), you can say things like: (any "debian-\\b\\(\\w+\\)@lists.debian.org" "mail.debian.\\1") In this example, messages sent to `debian-foo@lists.debian.org' will be filed in `mail.debian.foo'. If the string contains the element `\&', then the previously matched string will be substituted. Similarly, the elements `\\1' up to `\\9' will be substituted with the text matched by the groupings 1 through 9. Where `nnmail-split-lowercase-expanded' controls whether the lowercase of the matched string should be used for the substitution. Setting it as non-`nil' is useful to avoid the creation of multiple groups when users send to an address using different case (i.e. mailing-list@domain vs Mailing-List@Domain). The default value is `t'. `nnmail-split-fancy-with-parent' is a function which allows you to split followups into the same groups their parents are in. Sometimes you can't make splitting rules for all your mail. For example, your boss might send you personal mail regarding different projects you are working on, and as you can't tell your boss to put a distinguishing string into the subject line, you have to resort to manually moving the messages into the right group. With this function, you only have to do it once per thread. To use this feature, you have to set `nnmail-treat-duplicates' and `nnmail-cache-accepted-message-ids' to a non-`nil' value. And then you can include `nnmail-split-fancy-with-parent' using the colon feature, like so: (setq nnmail-treat-duplicates 'warn ; or `delete' nnmail-cache-accepted-message-ids t nnmail-split-fancy '(| (: nnmail-split-fancy-with-parent) ;; other splits go here )) This feature works as follows: when `nnmail-treat-duplicates' is non-`nil', Gnus records the message id of every message it sees in the file specified by the variable `nnmail-message-id-cache-file', together with the group it is in (the group is omitted for non-mail messages). When mail splitting is invoked, the function `nnmail-split-fancy-with-parent' then looks at the References (and In-Reply-To) header of each message to split and searches the file specified by `nnmail-message-id-cache-file' for the message ids. When it has found a parent, it returns the corresponding group name unless the group name matches the regexp `nnmail-split-fancy-with-parent-ignore-groups'. It is recommended that you set `nnmail-message-id-cache-length' to a somewhat higher number than the default so that the message ids are still in the cache. (A value of 5000 appears to create a file some 300 kBytes in size.) When `nnmail-cache-accepted-message-ids' is non-`nil', Gnus also records the message ids of moved articles, so that the followup messages goes into the new group. Also see the variable `nnmail-cache-ignore-groups' if you don't want certain groups to be recorded in the cache. For example, if all outgoing messages are written to an "outgoing" group, you could set `nnmail-cache-ignore-groups' to match that group name. Otherwise, answers to all your messages would end up in the "outgoing" group.  File: gnus, Node: Group Mail Splitting, Next: Incorporating Old Mail, Prev: Fancy Mail Splitting, Up: Getting Mail 6.3.7 Group Mail Splitting -------------------------- If you subscribe to dozens of mailing lists but you don't want to maintain mail splitting rules manually, group mail splitting is for you. You just have to set `to-list' and/or `to-address' in group parameters or group customization and set `nnmail-split-methods' to `gnus-group-split'. This splitting function will scan all groups for those parameters and split mail accordingly, i.e., messages posted from or to the addresses specified in the parameters `to-list' or `to-address' of a mail group will be stored in that group. Sometimes, mailing lists have multiple addresses, and you may want mail splitting to recognize them all: just set the `extra-aliases' group parameter to the list of additional addresses and it's done. If you'd rather use a regular expression, set `split-regexp'. All these parameters in a group will be used to create an `nnmail-split-fancy' split, in which the FIELD is `any', the VALUE is a single regular expression that matches `to-list', `to-address', all of `extra-aliases' and all matches of `split-regexp', and the SPLIT is the name of the group. RESTRICTs are also supported: just set the `split-exclude' parameter to a list of regular expressions. If you can't get the right split to be generated using all these parameters, or you just need something fancier, you can set the parameter `split-spec' to an `nnmail-split-fancy' split. In this case, all other aforementioned parameters will be ignored by `gnus-group-split'. In particular, `split-spec' may be set to `nil', in which case the group will be ignored by `gnus-group-split'. `gnus-group-split' will do cross-posting on all groups that match, by defining a single `&' fancy split containing one split for each group. If a message doesn't match any split, it will be stored in the group named in `gnus-group-split-default-catch-all-group', unless some group has `split-spec' set to `catch-all', in which case that group is used as the catch-all group. Even though this variable is often used just to name a group, it may also be set to an arbitrarily complex fancy split (after all, a group name is a fancy split), and this may be useful to split mail that doesn't go to any mailing list to personal mail folders. Note that this fancy split is added as the last element of a `|' split list that also contains a `&' split with the rules extracted from group parameters. It's time for an example. Assume the following group parameters have been defined: nnml:mail.bar: ((to-address . "bar@femail.com") (split-regexp . ".*@femail\\.com")) nnml:mail.foo: ((to-list . "foo@nowhere.gov") (extra-aliases "foo@localhost" "foo-redist@home") (split-exclude "bugs-foo" "rambling-foo") (admin-address . "foo-request@nowhere.gov")) nnml:mail.others: ((split-spec . catch-all)) Setting `nnmail-split-methods' to `gnus-group-split' will behave as if `nnmail-split-fancy' had been selected and variable `nnmail-split-fancy' had been set as follows: (| (& (any "\\(bar@femail\\.com\\|.*@femail\\.com\\)" "mail.bar") (any "\\(foo@nowhere\\.gov\\|foo@localhost\\|foo-redist@home\\)" - "bugs-foo" - "rambling-foo" "mail.foo")) "mail.others") If you'd rather not use group splitting for all your mail groups, you may use it for only some of them, by using `nnmail-split-fancy' splits like this: (: gnus-group-split-fancy GROUPS NO-CROSSPOST CATCH-ALL) GROUPS may be a regular expression or a list of group names whose parameters will be scanned to generate the output split. NO-CROSSPOST can be used to disable cross-posting; in this case, a single `|' split will be output. CATCH-ALL is the fall back fancy split, used like `gnus-group-split-default-catch-all-group'. If CATCH-ALL is `nil', or if `split-regexp' matches the empty string in any selected group, no catch-all split will be issued. Otherwise, if some group has `split-spec' set to `catch-all', this group will override the value of the CATCH-ALL argument. Unfortunately, scanning all groups and their parameters can be quite slow, especially considering that it has to be done for every message. But don't despair! The function `gnus-group-split-setup' can be used to enable `gnus-group-split' in a much more efficient way. It sets `nnmail-split-methods' to `nnmail-split-fancy' and sets `nnmail-split-fancy' to the split produced by `gnus-group-split-fancy'. Thus, the group parameters are only scanned once, no matter how many messages are split. However, if you change group parameters, you'd have to update `nnmail-split-fancy' manually. You can do it by running `gnus-group-split-update'. If you'd rather have it updated automatically, just tell `gnus-group-split-setup' to do it for you. For example, add to your `~/.gnus.el': (gnus-group-split-setup AUTO-UPDATE CATCH-ALL) If AUTO-UPDATE is non-`nil', `gnus-group-split-update' will be added to `nnmail-pre-get-new-mail-hook', so you won't ever have to worry about updating `nnmail-split-fancy' again. If you don't omit CATCH-ALL (it's optional, equivalent to `nil'), `gnus-group-split-default-catch-all-group' will be set to its value. Because you may want to change `nnmail-split-fancy' after it is set by `gnus-group-split-update', this function will run `gnus-group-split-updated-hook' just before finishing.  File: gnus, Node: Incorporating Old Mail, Next: Expiring Mail, Prev: Group Mail Splitting, Up: Getting Mail 6.3.8 Incorporating Old Mail ---------------------------- Most people have lots of old mail stored in various file formats. If you have set up Gnus to read mail using one of the spiffy Gnus mail back ends, you'll probably wish to have that old mail incorporated into your mail groups. Doing so can be quite easy. To take an example: You're reading mail using `nnml' (*note Mail Spool::), and have set `nnmail-split-methods' to a satisfactory value (*note Splitting Mail::). You have an old Unix mbox file filled with important, but old, mail. You want to move it into your `nnml' groups. Here's how: 1. Go to the group buffer. 2. Type `G f' and give the file name to the mbox file when prompted to create an `nndoc' group from the mbox file (*note Foreign Groups::). 3. Type `SPACE' to enter the newly created group. 4. Type `M P b' to process-mark all articles in this group's buffer (*note Setting Process Marks::). 5. Type `B r' to respool all the process-marked articles, and answer `nnml' when prompted (*note Mail Group Commands::). All the mail messages in the mbox file will now also be spread out over all your `nnml' groups. Try entering them and check whether things have gone without a glitch. If things look ok, you may consider deleting the mbox file, but I wouldn't do that unless I was absolutely sure that all the mail has ended up where it should be. Respooling is also a handy thing to do if you're switching from one mail back end to another. Just respool all the mail in the old mail groups using the new mail back end.  File: gnus, Node: Expiring Mail, Next: Washing Mail, Prev: Incorporating Old Mail, Up: Getting Mail 6.3.9 Expiring Mail ------------------- Traditional mail readers have a tendency to remove mail articles when you mark them as read, in some way. Gnus takes a fundamentally different approach to mail reading. Gnus basically considers mail just to be news that has been received in a rather peculiar manner. It does not think that it has the power to actually change the mail, or delete any mail messages. If you enter a mail group, and mark articles as "read", or kill them in some other fashion, the mail articles will still exist on the system. I repeat: Gnus will not delete your old, read mail. Unless you ask it to, of course. To make Gnus get rid of your unwanted mail, you have to mark the articles as "expirable". (With the default key bindings, this means that you have to type `E'.) This does not mean that the articles will disappear right away, however. In general, a mail article will be deleted from your system if, 1) it is marked as expirable, AND 2) it is more than one week old. If you do not mark an article as expirable, it will remain on your system until hell freezes over. This bears repeating one more time, with some spurious capitalizations: IF you do NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. You do not have to mark articles as expirable by hand. Gnus provides two features, called "auto-expire" and "total-expire", that can help you with this. In a nutshell, "auto-expire" means that Gnus hits `E' for you when you select an article. And "total-expire" means that Gnus considers all articles as expirable that are read. So, in addition to the articles marked `E', also the articles marked `r', `R', `O', `K', `Y' and so on are considered expirable. When should either auto-expire or total-expire be used? Most people who are subscribed to mailing lists split each list into its own group and then turn on auto-expire or total-expire for those groups. (*Note Splitting Mail::, for more information on splitting each list into its own group.) Which one is better, auto-expire or total-expire? It's not easy to answer. Generally speaking, auto-expire is probably faster. Another advantage of auto-expire is that you get more marks to work with: for the articles that are supposed to stick around, you can still choose between tick and dormant and read marks. But with total-expire, you only have dormant and ticked to choose from. The advantage of total-expire is that it works well with adaptive scoring (*note Adaptive Scoring::). Auto-expire works with normal scoring but not with adaptive scoring. Groups that match the regular expression `gnus-auto-expirable-newsgroups' will have all articles that you read marked as expirable automatically. All articles marked as expirable have an `E' in the first column in the summary buffer. By default, if you have auto expiry switched on, Gnus will mark all the articles you read as expirable, no matter if they were read or unread before. To avoid having articles marked as read marked as expirable automatically, you can put something like the following in your `~/.gnus.el' file: (remove-hook 'gnus-mark-article-hook 'gnus-summary-mark-read-and-unread-as-read) (add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) Note that making a group auto-expirable doesn't mean that all read articles are expired--only the articles marked as expirable will be expired. Also note that using the `d' command won't make articles expirable--only semi-automatic marking of articles as read will mark the articles as expirable in auto-expirable groups. Let's say you subscribe to a couple of mailing lists, and you want the articles you have read to disappear after a while: (setq gnus-auto-expirable-newsgroups "mail.nonsense-list\\|mail.nice-list") Another way to have auto-expiry happen is to have the element `auto-expire' in the group parameters of the group. If you use adaptive scoring (*note Adaptive Scoring::) and auto-expiring, you'll have problems. Auto-expiring and adaptive scoring don't really mix very well. The `nnmail-expiry-wait' variable supplies the default time an expirable article has to live. Gnus starts counting days from when the message _arrived_, not from when it was sent. The default is seven days. Gnus also supplies a function that lets you fine-tune how long articles are to live, based on what group they are in. Let's say you want to have one month expiry period in the `mail.private' group, a one day expiry period in the `mail.junk' group, and a six day expiry period everywhere else: (setq nnmail-expiry-wait-function (lambda (group) (cond ((string= group "mail.private") 31) ((string= group "mail.junk") 1) ((string= group "important") 'never) (t 6)))) The group names this function is fed are "unadorned" group names--no `nnml:' prefixes and the like. The `nnmail-expiry-wait' variable and `nnmail-expiry-wait-function' function can either be a number (not necessarily an integer) or one of the symbols `immediate' or `never'. You can also use the `expiry-wait' group parameter to selectively change the expiry period (*note Group Parameters::). The normal action taken when expiring articles is to delete them. However, in some circumstances it might make more sense to move them to other groups instead of deleting them. The variable `nnmail-expiry-target' (and the `expiry-target' group parameter) controls this. The variable supplies a default value for all groups, which can be overridden for specific groups by the group parameter. default value is `delete', but this can also be a string (which should be the name of the group the message should be moved to), or a function (which will be called in a buffer narrowed to the message in question, and with the name of the group being moved from as its parameter) which should return a target--either a group name or `delete'. Here's an example for specifying a group name: (setq nnmail-expiry-target "nnml:expired") Gnus provides a function `nnmail-fancy-expiry-target' which will expire mail to groups according to the variable `nnmail-fancy-expiry-targets'. Here's an example: (setq nnmail-expiry-target 'nnmail-fancy-expiry-target nnmail-fancy-expiry-targets '((to-from "boss" "nnfolder:Work") ("subject" "IMPORTANT" "nnfolder:IMPORTANT.%Y.%b") ("from" ".*" "nnfolder:Archive-%Y"))) With this setup, any mail that has `IMPORTANT' in its Subject header and was sent in the year `YYYY' and month `MMM', will get expired to the group `nnfolder:IMPORTANT.YYYY.MMM'. If its From or To header contains the string `boss', it will get expired to `nnfolder:Work'. All other mail will get expired to `nnfolder:Archive-YYYY'. If `nnmail-keep-last-article' is non-`nil', Gnus will never expire the final article in a mail newsgroup. This is to make life easier for procmail users. By the way: That line up there, about Gnus never expiring non-expirable articles, is a lie. If you put `total-expire' in the group parameters, articles will not be marked as expirable, but all read articles will be put through the expiry process. Use with extreme caution. Even more dangerous is the `gnus-total-expirable-newsgroups' variable. All groups that match this regexp will have all read articles put through the expiry process, which means that _all_ old mail articles in the groups in question will be deleted after a while. Use with extreme caution, and don't come crying to me when you discover that the regexp you used matched the wrong group and all your important mail has disappeared. Be a _man_! Or a _woman_! Whatever you feel more comfortable with! So there! Most people make most of their mail groups total-expirable, though. If `gnus-inhibit-user-auto-expire' is non-`nil', user marking commands will not mark an article as expirable, even if the group has auto-expire turned on. The expirable marks of articles will be removed when copying or moving them to a group in which auto-expire is not turned on. This is for preventing articles from being expired unintentionally. On the other hand, to a group that has turned auto-expire on, the expirable marks of articles that are copied or moved will not be changed by default. I.e., when copying or moving to such a group, articles that were expirable will be left expirable and ones that were not expirable will not be marked as expirable. So, even though in auto-expire groups, some articles will never get expired (unless you read them again). If you don't side with that behavior that unexpirable articles may be mixed into auto-expire groups, you can set `gnus-mark-copied-or-moved-articles-as-expirable' to a non-`nil' value. In that case, articles that have been read will be marked as expirable automatically when being copied or moved to a group that has auto-expire turned on. The default value is `nil'.  File: gnus, Node: Washing Mail, Next: Duplicates, Prev: Expiring Mail, Up: Getting Mail 6.3.10 Washing Mail ------------------- Mailers and list servers are notorious for doing all sorts of really, really stupid things with mail. "Hey, RFC 822 doesn't explicitly prohibit us from adding the string `wE aRe ElItE!!!!!1!!' to the end of all lines passing through our server, so let's do that!!!!1!" Yes, but RFC 822 wasn't designed to be read by morons. Things that were considered to be self-evident were not discussed. So. Here we are. Case in point: The German version of Microsoft Exchange adds `AW: ' to the subjects of replies instead of `Re: '. I could pretend to be shocked and dismayed by this, but I haven't got the energy. It is to laugh. Gnus provides a plethora of functions for washing articles while displaying them, but it might be nicer to do the filtering before storing the mail to disk. For that purpose, we have three hooks and various functions that can be put in these hooks. `nnmail-prepare-incoming-hook' This hook is called before doing anything with the mail and is meant for grand, sweeping gestures. It is called in a buffer that contains all the new, incoming mail. Functions to be used include: `nnheader-ms-strip-cr' Remove trailing carriage returns from each line. This is default on Emacs running on MS machines. `nnmail-prepare-incoming-header-hook' This hook is called narrowed to each header. It can be used when cleaning up the headers. Functions that can be used include: `nnmail-remove-leading-whitespace' Clear leading white space that "helpful" listservs have added to the headers to make them look nice. Aaah. (Note that this function works on both the header on the body of all messages, so it is a potentially dangerous function to use (if a body of a message contains something that looks like a header line). So rather than fix the bug, it is of course the right solution to make it into a feature by documenting it.) `nnmail-remove-list-identifiers' Some list servers add an identifier--for example, `(idm)'--to the beginning of all `Subject' headers. I'm sure that's nice for people who use stone age mail readers. This function will remove strings that match the `nnmail-list-identifiers' regexp, which can also be a list of regexp. `nnmail-list-identifiers' may not contain `\\(..\\)'. For instance, if you want to remove the `(idm)' and the `nagnagnag' identifiers: (setq nnmail-list-identifiers '("(idm)" "nagnagnag")) This can also be done non-destructively with `gnus-list-identifiers', *Note Article Hiding::. `nnmail-remove-tabs' Translate all `TAB' characters into `SPACE' characters. `nnmail-ignore-broken-references' Some mail user agents (e.g. Eudora and Pegasus) produce broken `References' headers, but correct `In-Reply-To' headers. This function will get rid of the `References' header if the headers contain a line matching the regular expression `nnmail-broken-references-mailers'. `nnmail-prepare-incoming-message-hook' This hook is called narrowed to each message. Functions to be used include: `article-de-quoted-unreadable' Decode Quoted Readable encoding.  File: gnus, Node: Duplicates, Next: Not Reading Mail, Prev: Washing Mail, Up: Getting Mail 6.3.11 Duplicates ----------------- If you are a member of a couple of mailing lists, you will sometimes receive two copies of the same mail. This can be quite annoying, so `nnmail' checks for and treats any duplicates it might find. To do this, it keeps a cache of old `Message-ID's-- `nnmail-message-id-cache-file', which is `~/.nnmail-cache' by default. The approximate maximum number of `Message-ID's stored there is controlled by the `nnmail-message-id-cache-length' variable, which is 1000 by default. (So 1000 `Message-ID's will be stored.) If all this sounds scary to you, you can set `nnmail-treat-duplicates' to `warn' (which is what it is by default), and `nnmail' won't delete duplicate mails. Instead it will insert a warning into the head of the mail saying that it thinks that this is a duplicate of a different message. This variable can also be a function. If that's the case, the function will be called from a buffer narrowed to the message in question with the `Message-ID' as a parameter. The function must return either `nil', `warn', or `delete'. You can turn this feature off completely by setting the variable to `nil'. If you want all the duplicate mails to be put into a special "duplicates" group, you could do that using the normal mail split methods: (setq nnmail-split-fancy '(| ;; Messages duplicates go to a separate group. ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate") ;; Message from daemons, postmaster, and the like to another. (any mail "mail.misc") ;; Other rules. [...] )) Or something like: (setq nnmail-split-methods '(("duplicates" "^Gnus-Warning:.*duplicate") ;; Other rules. [...])) Here's a neat feature: If you know that the recipient reads her mail with Gnus, and that she has `nnmail-treat-duplicates' set to `delete', you can send her as many insults as you like, just by using a `Message-ID' of a mail that you know that she's already received. Think of all the fun! She'll never see any of it! Whee!  File: gnus, Node: Not Reading Mail, Next: Choosing a Mail Back End, Prev: Duplicates, Up: Getting Mail 6.3.12 Not Reading Mail ----------------------- If you start using any of the mail back ends, they have the annoying habit of assuming that you want to read mail with them. This might not be unreasonable, but it might not be what you want. If you set `mail-sources' and `nnmail-spool-file' to `nil', none of the back ends will ever attempt to read incoming mail, which should help. This might be too much, if, for instance, you are reading mail quite happily with `nnml' and just want to peek at some old (pre-Emacs 23) Rmail file you have stashed away with `nnbabyl'. All back ends have variables called back-end-`get-new-mail'. If you want to disable the `nnbabyl' mail reading, you edit the virtual server for the group to have a setting where `nnbabyl-get-new-mail' to `nil'. All the mail back ends will call `nn'*`-prepare-save-mail-hook' narrowed to the article to be saved before saving it when reading incoming mail.  File: gnus, Node: Choosing a Mail Back End, Prev: Not Reading Mail, Up: Getting Mail 6.3.13 Choosing a Mail Back End ------------------------------- Gnus will read the mail spool when you activate a mail group. The mail file is first copied to your home directory. What happens after that depends on what format you want to store your mail in. There are six different mail back ends in the standard Gnus, and more back ends are available separately. The mail back end most people use (because it is possibly the fastest) is `nnml' (*note Mail Spool::). * Menu: * Unix Mail Box:: Using the (quite) standard Un*x mbox. * Babyl:: Babyl was used by older versions of Rmail. * 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: Babyl, Up: Choosing a Mail Back End 6.3.13.1 Unix Mail Box ...................... The "nnmbox" back end will use the standard Un*x mbox file to store mail. `nnmbox' will add extra headers to each mail article to say which group it belongs in. Virtual server settings: `nnmbox-mbox-file' The name of the mail box in the user's home directory. Default is `~/mbox'. `nnmbox-active-file' The name of the active file for the mail box. Default is `~/.mbox-active'. `nnmbox-get-new-mail' If non-`nil', `nnmbox' will read incoming mail and split it into groups. Default is `t'.  File: gnus, Node: Babyl, Next: Mail Spool, Prev: Unix Mail Box, Up: Choosing a Mail Back End 6.3.13.2 Babyl .............. The "nnbabyl" back end will use a Babyl mail box 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 Babyl file. The default is `~/RMAIL' `nnbabyl-active-file' The name of the active file for the Babyl file. 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: Babyl, Up: Choosing a Mail Back End 6.3.13.3 Mail Spool ................... The "nnml" spool mail format isn't compatible with any other known format. It should be used with some caution. If you use this back end, Gnus will split all incoming mail into files, one file for each mail, and put the articles into the corresponding directories under the directory specified by the `nnml-directory' variable. The default value is `~/Mail/'. You do not have to create any directories beforehand; Gnus will take care of all that. If you have a strict limit as to how many files you are allowed to store in your account, you should not use this back end. As each mail gets its own file, you might very well occupy thousands of inodes within a few weeks. If this is no problem for you, and it isn't a problem for you having your friendly systems administrator walking around, madly, shouting "Who is eating all my inodes?! Who? Who!?!", then you should know that this is probably the fastest format to use. You do not have to trudge through a big mbox file just to read your new mail. `nnml' is probably the slowest back end when it comes to article splitting. It has to create lots of files, and it also generates NOV databases for the incoming mails. This makes it possibly the fastest back end when it comes to reading mail. When the marks file is used (which it is by default), `nnml' servers have the property that you may backup them using `tar' or similar, and later be able to restore them into Gnus (by adding the proper `nnml' server) and have all your marks be preserved. Marks for a group are 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 requires `auto-compression-mode' to be enabled (*note Compressed Files: (emacs)Compressed Files.). If the value of `nnml-use-compressed-files' is a string, it is used as the file extension specifying the compression program. You can set it to `.bz2' if your Emacs supports it. A value of `t' is equivalent to `.gz'. `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 6.3.13.4 MH Spool ................. `nnmh' is just like `nnml', except that is doesn't generate NOV databases and it doesn't keep an active file or marks file. This makes `nnmh' a _much_ slower back end than `nnml', but it also makes it easier to write procmail scripts for. Virtual server settings: `nnmh-directory' All `nnmh' directories will be located under this directory. The default is the value of `message-directory' (whose default is `~/Mail') `nnmh-get-new-mail' If non-`nil', `nnmh' will read incoming mail. The default is `t'. `nnmh-be-safe' If non-`nil', `nnmh' will go to ridiculous lengths to make sure that the articles in the folder are actually what Gnus thinks they are. It will check date stamps and stat everything in sight, so setting this to `t' will mean a serious slow-down. If you never use anything but Gnus to read the `nnmh' articles, you do not have to set this variable to `t'. The default is `nil'.  File: gnus, Node: Maildir, Next: Mail Folders, Prev: MH Spool, Up: Choosing a Mail Back End 6.3.13.5 Maildir ................ `nnmaildir' stores mail in the maildir format, with each maildir corresponding to a group in Gnus. This format is documented here: `http://cr.yp.to/proto/maildir.html' and here: `http://www.qmail.org/man/man5/maildir.html'. `nnmaildir' also stores extra information in the `.nnmaildir/' directory within a maildir. Maildir format was designed to allow concurrent deliveries and reading, without needing locks. With other back ends, you would have your mail delivered to a spool of some kind, and then you would configure Gnus to split mail from that spool into your groups. You can still do that with `nnmaildir', but the more common configuration is to have your mail delivered directly to the maildirs that appear as group in Gnus. `nnmaildir' is designed to be perfectly reliable: `C-g' will never corrupt its data in memory, and `SIGKILL' will never corrupt its data in the filesystem. `nnmaildir' stores article marks and NOV data in each maildir. So you can copy a whole maildir from one Gnus setup to another, and you will keep your marks. Virtual server settings: `directory' For each of your `nnmaildir' servers (it's very unlikely that you'd need more than one), you need to create a directory and populate it with maildirs or symlinks to maildirs (and nothing else; do not choose a directory already used for other purposes). Each maildir will be represented in Gnus as a newsgroup on that server; the filename of the symlink will be the name of the group. Any filenames in the directory starting with `.' are ignored. The directory is scanned when you first start Gnus, and each time you type `g' in the group buffer; if any maildirs have been removed or added, `nnmaildir' notices at these times. The value of the `directory' parameter should be a Lisp form which is processed by `eval' and `expand-file-name' to get the path of the directory for this server. The form is `eval'ed only when the server is opened; the resulting string is used until the server is closed. (If you don't know about forms and `eval', don't worry--a simple string will work.) This parameter is not optional; you must specify it. I don't recommend using `"~/Mail"' or a subdirectory of it; several other parts of Gnus use that directory by default for various things, and may get confused if `nnmaildir' uses it too. `"~/.nnmaildir"' is a typical value. `target-prefix' This should be a Lisp form which is processed by `eval' and `expand-file-name'. The form is `eval'ed only when the server is opened; the resulting string is used until the server is closed. When you create a group on an `nnmaildir' server, the maildir is created with `target-prefix' prepended to its name, and a symlink pointing to that maildir is created, named with the plain group name. So if `directory' is `"~/.nnmaildir"' and `target-prefix' is `"../maildirs/"', then when you create the group `foo', `nnmaildir' will create `~/.nnmaildir/../maildirs/foo' as a maildir, and will create `~/.nnmaildir/foo' as a symlink pointing to `../maildirs/foo'. You can set `target-prefix' to a string without any slashes to create both maildirs and symlinks in the same `directory'; in this case, any maildirs found in `directory' whose names start with `target-prefix' will not be listed as groups (but the symlinks pointing to them will be). As a special case, if `target-prefix' is `""' (the default), then when you create a group, the maildir will be created in `directory' without a corresponding symlink. Beware that you cannot use `gnus-group-delete-group' on such groups without the `force' argument. `directory-files' This should be a function with the same interface as `directory-files' (such as `directory-files' itself). It is used to scan the server's `directory' for maildirs. This parameter is optional; the default is `nnheader-directory-files-safe' if `nnheader-directory-files-is-safe' is `nil', and `directory-files' otherwise. (`nnheader-directory-files-is-safe' is checked only once when the server is opened; if you want to check it each time the directory is scanned, you'll have to provide your own function that does that.) `get-new-mail' If non-`nil', then after scanning for new mail in the group maildirs themselves as usual, this server will also incorporate mail the conventional Gnus way, from `mail-sources' according to `nnmail-split-methods' or `nnmail-split-fancy'. The default value is `nil'. Do _not_ use the same maildir both in `mail-sources' and as an `nnmaildir' group. The results might happen to be useful, but that would be by chance, not by design, and the results might be different in the future. If your split rules create new groups, remember to supply a `create-directory' server parameter. 6.3.13.6 Group parameters ......................... `nnmaildir' uses several group parameters. It's safe to ignore all this; the default behavior for `nnmaildir' is the same as the default behavior for other mail back ends: articles are deleted after one week, etc. Except for the expiry parameters, all this functionality is unique to `nnmaildir', so you can ignore it if you're just trying to duplicate the behavior you already have with another back end. If the value of any of these parameters is a vector, the first element is evaluated as a Lisp form and the result is used, rather than the original value. If the value is not a vector, the value itself is evaluated as a Lisp form. (This is why these parameters use names different from those of other, similar parameters supported by other back ends: they have different, though similar, meanings.) (For numbers, strings, `nil', and `t', you can ignore the `eval' business again; for other values, remember to use an extra quote and wrap the value in a vector when appropriate.) `expire-age' An integer specifying the minimum age, in seconds, of an article before it will be expired, or the symbol `never' to specify that articles should never be expired. If this parameter is not set, `nnmaildir' falls back to the usual `nnmail-expiry-wait'(`-function') variables (the `expiry-wait' group parameter overrides `nnmail-expiry-wait' and makes `nnmail-expiry-wait-function' ineffective). If you wanted a value of 3 days, you could use something like `[(* 3 24 60 60)]'; `nnmaildir' will evaluate the form and use the result. An article's age is measured starting from the article file's modification time. Normally, this is the same as the article's delivery time, but editing an article makes it younger. Moving an article (other than via expiry) may also make an article younger. `expire-group' If this is set to a string such as a full Gnus group name, like "backend+server.address.string:group.name" and if it is not the name of the same group that the parameter belongs to, then articles will be moved to the specified group during expiry before being deleted. _If this is set to an `nnmaildir' group, the article will be just as old in the destination group as it was in the source group._ So be careful with `expire-age' in the destination group. If this is set to the name of the same group that the parameter belongs to, then the article is not expired at all. If you use the vector form, the first element is evaluated once for each article. So that form can refer to `nnmaildir-article-file-name', etc., to decide where to put the article. _Even if this parameter is not set, `nnmaildir' does not fall back to the `expiry-target' group parameter or the `nnmail-expiry-target' variable._ `read-only' If this is set to `t', `nnmaildir' will treat the articles in this maildir as read-only. This means: articles are not renamed from `new/' into `cur/'; articles are only found in `new/', not `cur/'; articles are never deleted; articles cannot be edited. `new/' is expected to be a symlink to the `new/' directory of another maildir--e.g., a system-wide mailbox containing a mailing list of common interest. Everything in the maildir outside `new/' is _not_ treated as read-only, so for a shared mailbox, you do still need to set up your own maildir (or have write permission to the shared mailbox); your maildir just won't contain extra copies of the articles. `directory-files' A function with the same interface as `directory-files'. It is used to scan the directories in the maildir corresponding to this group to find articles. The default is the function specified by the server's `directory-files' parameter. `distrust-Lines:' If non-`nil', `nnmaildir' will always count the lines of an article, rather than use the `Lines:' header field. If `nil', the header field will be used if present. `always-marks' A list of mark symbols, such as `['(read expire)]'. Whenever Gnus asks `nnmaildir' for article marks, `nnmaildir' will say that all articles have these marks, regardless of whether the marks stored in the filesystem say so. This is a proof-of-concept feature that will probably be removed eventually; it ought to be done in Gnus proper, or abandoned if it's not worthwhile. `never-marks' A list of mark symbols, such as `['(tick expire)]'. Whenever Gnus asks `nnmaildir' for article marks, `nnmaildir' will say that no articles have these marks, regardless of whether the marks stored in the filesystem say so. `never-marks' overrides `always-marks'. This is a proof-of-concept feature that will probably be removed eventually; it ought to be done in Gnus proper, or abandoned if it's not worthwhile. `nov-cache-size' An integer specifying the size of the NOV memory cache. To speed things up, `nnmaildir' keeps NOV data in memory for a limited number of articles in each group. (This is probably not worthwhile, and will probably be removed in the future.) This parameter's value is noticed only the first time a group is seen after the server is opened--i.e., when you first start Gnus, typically. The NOV cache is never resized until the server is closed and reopened. The default is an estimate of the number of articles that would be displayed in the summary buffer: a count of articles that are either marked with `tick' or not marked with `read', plus a little extra. 6.3.13.7 Article identification ............................... Articles are stored in the `cur/' subdirectory of each maildir. Each article file is named like `uniq:info', where `uniq' contains no colons. `nnmaildir' ignores, but preserves, the `:info' part. (Other maildir readers typically use this part of the filename to store marks.) The `uniq' part uniquely identifies the article, and is used in various places in the `.nnmaildir/' subdirectory of the maildir to store information about the corresponding article. The full pathname of an article is available in the variable `nnmaildir-article-file-name' after you request the article in the summary buffer. 6.3.13.8 NOV data ................. An article identified by `uniq' has its NOV data (used to generate lines in the summary buffer) stored in `.nnmaildir/nov/uniq'. There is no `nnmaildir-generate-nov-databases' function. (There isn't much need for it--an article's NOV data is updated automatically when the article or `nnmail-extra-headers' has changed.) You can force `nnmaildir' to regenerate the NOV data for a single article simply by deleting the corresponding NOV file, but _beware_: this will also cause `nnmaildir' to assign a new article number for this article, which may cause trouble with `seen' marks, the Agent, and the cache. 6.3.13.9 Article marks ...................... An article identified by `uniq' is considered to have the mark `flag' when the file `.nnmaildir/marks/flag/uniq' exists. When Gnus asks `nnmaildir' for a group's marks, `nnmaildir' looks for such files and reports the set of marks it finds. When Gnus asks `nnmaildir' to store a new set of marks, `nnmaildir' creates and deletes the corresponding files as needed. (Actually, rather than create a new file for each mark, it just creates hard links to `.nnmaildir/markfile', to save inodes.) You can invent new marks by creating a new directory in `.nnmaildir/marks/'. You can tar up a maildir and remove it from your server, untar it later, and keep your marks. You can add and remove marks yourself by creating and deleting mark files. If you do this while Gnus is running and your `nnmaildir' server is open, it's best to exit all summary buffers for `nnmaildir' groups and type `s' in the group buffer first, and to type `g' or `M-g' in the group buffer afterwards. Otherwise, Gnus might not pick up the changes, and might undo them.  File: gnus, Node: Mail Folders, Next: Comparing Mail Back Ends, Prev: Maildir, Up: Choosing a Mail Back End 6.3.13.10 Mail Folders ...................... `nnfolder' is a back end for storing each mail group in a separate file. Each file is in the standard Un*x mbox format. `nnfolder' will add extra headers to keep track of article numbers and arrival dates. When the marks file is used (which it is by default), `nnfolder' servers have the property that you may backup them using `tar' or similar, and later be able to restore them into Gnus (by adding the proper `nnfolder' server) and have all your marks be preserved. Marks for a group are usually stored in a file named as the mbox file with `.mrk' concatenated to it (but see `nnfolder-marks-file-suffix') within the `nnfolder' directory. Individual `nnfolder' groups are also possible to backup, use `G m' to restore the group (after restoring the backup into the `nnfolder' directory). Virtual server settings: `nnfolder-directory' All the `nnfolder' mail boxes will be stored under this directory. The default is the value of `message-directory' (whose default is `~/Mail') `nnfolder-active-file' The name of the active file. The default is `~/Mail/active'. `nnfolder-newsgroups-file' The name of the group descriptions file. *Note Newsgroups File Format::. The default is `~/Mail/newsgroups' `nnfolder-get-new-mail' If non-`nil', `nnfolder' will read incoming mail. The default is `t' `nnfolder-save-buffer-hook' Hook run before saving the folders. Note that Emacs does the normal backup renaming of files even with the `nnfolder' buffers. If you wish to switch this off, you could say something like the following in your `.emacs' file: (defun turn-off-backup () (set (make-local-variable 'backup-inhibited) t)) (add-hook 'nnfolder-save-buffer-hook 'turn-off-backup) `nnfolder-delete-mail-hook' Hook run in a buffer narrowed to the message that is to be deleted. This function can be used to copy the message to somewhere else, or to extract some information from it before removing it. `nnfolder-nov-is-evil' If non-`nil', this back end will ignore any NOV files. The default is `nil'. `nnfolder-nov-file-suffix' The extension for NOV files. The default is `.nov'. `nnfolder-nov-directory' The directory where the NOV files should be stored. If `nil', `nnfolder-directory' is used. `nnfolder-marks-is-evil' If non-`nil', this back end will ignore any MARKS files. The default is `nil'. `nnfolder-marks-file-suffix' The extension for MARKS files. The default is `.mrk'. `nnfolder-marks-directory' The directory where the MARKS files should be stored. If `nil', `nnfolder-directory' is used. If you have lots of `nnfolder'-like files you'd like to read with `nnfolder', you can use the `M-x nnfolder-generate-active-file' command to make `nnfolder' aware of all likely files in `nnfolder-directory'. This only works if you use long file names, though.  File: gnus, Node: Comparing Mail Back Ends, Prev: Mail Folders, Up: Choosing a Mail Back End 6.3.13.11 Comparing Mail Back Ends .................................. First, just for terminology, the "back end" is the common word for a low-level access method--a transport, if you will, by which something is acquired. The sense is that one's mail has to come from somewhere, and so selection of a suitable back end is required in order to get that mail within spitting distance of Gnus. The same concept exists for Usenet itself: Though access to articles is typically done by NNTP these days, once upon a midnight dreary, everyone in the world got at Usenet by running a reader on the machine where the articles lay (the machine which today we call an NNTP server), and access was by the reader stepping into the articles' directory spool area directly. One can still select between either the `nntp' or `nnspool' back ends, to select between these methods, if one happens actually to live on the server (or can see its spool directly, anyway, via NFS). The goal in selecting a mail back end is to pick one which simultaneously represents a suitable way of dealing with the original format plus leaving mail in a form that is convenient to use in the future. Here are some high and low points on each: `nnmbox' UNIX systems have historically had a single, very common, and well- defined format. All messages arrive in a single "spool file", and they are delineated by a line whose regular expression matches `^From_'. (My notational use of `_' is to indicate a space, to make it clear in this instance that this is not the RFC-specified `From:' header.) Because Emacs and therefore Gnus emanate historically from the Unix environment, it is simplest if one does not mess a great deal with the original mailbox format, so if one chooses this back end, Gnus' primary activity in getting mail from the real spool area to Gnus' preferred directory is simply to copy it, with no (appreciable) format change in the process. It is the "dumbest" way to move mail into availability in the Gnus environment. This makes it fast to move into place, but slow to parse, when Gnus has to look at what's where. `nnbabyl' Once upon a time, there was the DEC-10 and DEC-20, running operating systems called TOPS and related things, and the usual (only?) mail reading environment was a thing called Babyl. I don't know what format was used for mail landing on the system, but Babyl had its own internal format to which mail was converted, primarily involving creating a spool-file-like entity with a scheme for inserting Babyl-specific headers and status bits above the top of each message in the file. Rmail was Emacs' first mail reader, it was written by Richard Stallman, and Stallman came out of that TOPS/Babyl environment, so he wrote Rmail to understand the mail files folks already had in existence. Gnus (and VM, for that matter) continue to support this format because it's perceived as having some good qualities in those mailer-specific headers/status bits stuff. Rmail itself still exists as well, of course, and is still maintained within Emacs. Since Emacs 23, it uses standard mbox format rather than Babyl. Both of the above forms leave your mail in a single file on your file system, and they must parse that entire file each time you take a look at your mail. `nnml' `nnml' is the back end which smells the most as though you were actually operating with an `nnspool'-accessed Usenet system. (In fact, I believe `nnml' actually derived from `nnspool' code, lo these years ago.) One's mail is taken from the original spool file, and is then cut up into individual message files, 1:1. It maintains a Usenet-style active file (analogous to what one finds in an INN- or CNews-based news system in (for instance) `/var/lib/news/active', or what is returned via the `NNTP LIST' verb) and also creates "overview" files for efficient group entry, as has been defined for NNTP servers for some years now. It is slower in mail-splitting, due to the creation of lots of files, updates to the `nnml' active file, and additions to overview files on a per-message basis, but it is extremely fast on access because of what amounts to the indexing support provided by the active file and overviews. `nnml' costs "inodes" in a big way; that is, it soaks up the resource which defines available places in the file system to put new files. Sysadmins take a dim view of heavy inode occupation within tight, shared file systems. But if you live on a personal machine where the file system is your own and space is not at a premium, `nnml' wins big. It is also problematic using this back end if you are living in a FAT16-based Windows world, since much space will be wasted on all these tiny files. `nnmh' The Rand MH mail-reading system has been around UNIX systems for a very long time; it operates by splitting one's spool file of messages into individual files, but with little or no indexing support--`nnmh' is considered to be semantically equivalent to "`nnml' without active file or overviews". This is arguably the worst choice, because one gets the slowness of individual file creation married to the slowness of access parsing when learning what's new in one's groups. `nnfolder' Basically the effect of `nnfolder' is `nnmbox' (the first method described above) on a per-group basis. That is, `nnmbox' itself puts _all_ one's mail in one file; `nnfolder' provides a little bit of optimization to this so that each of one's mail groups has a Unix mail box file. It's faster than `nnmbox' because each group can be parsed separately, and still provides the simple Unix mail box format requiring minimal effort in moving the mail around. In addition, it maintains an "active" file making it much faster for Gnus to figure out how many messages there are in each separate group. If you have groups that are expected to have a massive amount of messages, `nnfolder' is not the best choice, but if you receive only a moderate amount of mail, `nnfolder' is probably the most friendly mail back end all over. `nnmaildir' For configuring expiry and other things, `nnmaildir' uses incompatible group parameters, slightly different from those of other mail back ends. `nnmaildir' is largely similar to `nnml', with some notable differences. Each message is stored in a separate file, but the filename is unrelated to the article number in Gnus. `nnmaildir' also stores the equivalent of `nnml''s overview files in one file per article, so it uses about twice as many inodes as `nnml'. (Use `df -i' to see how plentiful your inode supply is.) If this slows you down or takes up very much space, consider switching to ReiserFS (http://www.namesys.com/) or another non-block-structured file system. Since maildirs don't require locking for delivery, the maildirs you use as groups can also be the maildirs your mail is directly delivered to. This means you can skip Gnus' mail splitting if your mail is already organized into different mailboxes during delivery. A `directory' entry in `mail-sources' would have a similar effect, but would require one set of mailboxes for spooling deliveries (in mbox format, thus damaging message bodies), and another set to be used as groups (in whatever format you like). A maildir has a built-in spool, in the `new/' subdirectory. Beware that currently, mail moved from `new/' to `cur/' instead of via mail splitting will not undergo treatment such as duplicate checking. `nnmaildir' stores article marks for a given group in the corresponding maildir, in a way designed so that it's easy to manipulate them from outside Gnus. You can tar up a maildir, unpack it somewhere else, and still have your marks. `nnml' also stores marks, but it's not as easy to work with them from outside Gnus as with `nnmaildir'. `nnmaildir' uses a significant amount of memory to speed things up. (It keeps in memory some of the things that `nnml' stores in files and that `nnmh' repeatedly parses out of message files.) If this is a problem for you, you can set the `nov-cache-size' group parameter to something small (0 would probably not work, but 1 probably would) to make it use less memory. This caching will probably be removed in the future. Startup is likely to be slower with `nnmaildir' than with other back ends. Everything else is likely to be faster, depending in part on your file system. `nnmaildir' does not use `nnoo', so you cannot use `nnoo' to write an `nnmaildir'-derived back end.  File: gnus, Node: Browsing the Web, Next: IMAP, Prev: Getting Mail, Up: Select Methods 6.4 Browsing the Web ==================== Web-based discussion forums are getting more and more popular. On many subjects, the web-based forums have become the most important forums, eclipsing the importance of mailing lists and news groups. The reason is easy to understand--they are friendly to new users; you just point and click, and there's the discussion. With mailing lists, you have to go through a cumbersome subscription procedure, and most people don't even know what a news group is. The problem with this scenario is that web browsers are not very good at being newsreaders. They do not keep track of what articles you've read; they do not allow you to score on subjects you're interested in; they do not allow off-line browsing; they require you to click around and drive you mad in the end. So--if web browsers suck at reading discussion forums, why not use Gnus to do it instead? Gnus has been getting a bit of a collection of back ends for providing interfaces to these sources. * Menu: * Archiving Mail:: * Web Searches:: Creating groups from articles that match a string. * Slashdot:: Reading the Slashdot comments. * Ultimate:: The Ultimate Bulletin Board systems. * Web Archive:: Reading mailing list archived on web. * RSS:: Reading RDF site summary. * Customizing W3:: Doing stuff to Emacs/W3 from Gnus. All the web sources require Emacs/W3 and the url library or those alternatives to work. The main caveat with all these web sources is that they probably won't work for a very long time. Gleaning information from the HTML data is guesswork at best, and when the layout is altered, the Gnus back end will fail. If you have reasonably new versions of these back ends, though, you should be ok. One thing all these Web methods have in common is that the Web sources are often down, unavailable or just plain too slow to be fun. In those cases, it makes a lot of sense to let the Gnus Agent (*note Gnus Unplugged::) handle downloading articles, and then you can read them at leisure from your local disk. No more World Wide Wait for you.  File: gnus, Node: Archiving Mail, Next: Web Searches, Up: Browsing the Web 6.4.1 Archiving Mail -------------------- Some of the back ends, notably `nnml', `nnfolder', and `nnmaildir', now actually store the article marks with each group. For these servers, archiving and restoring a group while preserving marks is fairly simple. (Preserving the group level and group parameters as well still requires ritual dancing and sacrifices to the `.newsrc.eld' deity though.) To archive an entire `nnml', `nnfolder', or `nnmaildir' server, take a recursive copy of the server directory. There is no need to shut down Gnus, so archiving may be invoked by `cron' or similar. You restore the data by restoring the directory tree, and adding a server definition pointing to that directory in Gnus. The *note Article Backlog::, *note Asynchronous Fetching:: and other things might interfere with overwriting data, so you may want to shut down Gnus before you restore the data. It is also possible to archive individual `nnml', `nnfolder', or `nnmaildir' groups, while preserving marks. For `nnml' or `nnmaildir', you copy all files in the group's directory. For `nnfolder' you need to copy both the base folder file itself (`FOO', say), and the marks file (`FOO.mrk' in this example). Restoring the group is done with `G m' from the Group buffer. The last step makes Gnus notice the new directory. `nnmaildir' notices the new directory automatically, so `G m' is unnecessary in that case.  File: gnus, Node: Web Searches, Next: Slashdot, Prev: Archiving Mail, Up: Browsing the Web 6.4.2 Web Searches ------------------ It's, like, too neat to search the Usenet for articles that match a string, but it, like, totally _sucks_, like, totally, to use one of those, like, Web browsers, and you, like, have to, rilly, like, look at the commercials, so, like, with Gnus you can do _rad_, rilly, searches without having to use a browser. The `nnweb' back end allows an easy interface to the mighty search engine. You create an `nnweb' group, enter a search pattern, and then enter the group and read the articles like you would any normal group. The `G w' command in the group buffer (*note Foreign Groups::) will do this in an easy-to-use fashion. `nnweb' groups don't really lend themselves to being solid groups--they have a very fleeting idea of article numbers. In fact, each time you enter an `nnweb' group (not even changing the search pattern), you are likely to get the articles ordered in a different manner. Not even using duplicate suppression (*note Duplicate Suppression::) will help, since `nnweb' doesn't even know the `Message-ID' of the articles before reading them using some search engines (Google, for instance). The only possible way to keep track of which articles you've read is by scoring on the `Date' header--mark all articles posted before the last date you read the group as read. If the search engine changes its output substantially, `nnweb' won't be able to parse it and will fail. One could hardly fault the Web providers if they were to do this--their _raison d'être_ is to make money off of advertisements, not to provide services to the community. Since `nnweb' washes the ads off all the articles, one might think that the providers might be somewhat miffed. We'll see. You must have the `url' and `W3' package or those alternatives (try `customize-group' on the `mm-url' variable group) installed to be able to use `nnweb'. Virtual server variables: `nnweb-type' What search engine type is being used. The currently supported types are `google', `dejanews', and `gmane'. Note that `dejanews' is an alias to `google'. `nnweb-search' The search string to feed to the search engine. `nnweb-max-hits' Advisory maximum number of hits per search to display. The default is 999. `nnweb-type-definition' Type-to-definition alist. This alist says what `nnweb' should do with the various search engine types. The following elements must be present: `article' Function to decode the article and provide something that Gnus understands. `map' Function to create an article number to message header and URL alist. `search' Function to send the search string to the search engine. `address' The address the aforementioned function should send the search string to. `id' Format string URL to fetch an article by `Message-ID'.  File: gnus, Node: Slashdot, Next: Ultimate, Prev: Web Searches, Up: Browsing the Web 6.4.3 Slashdot -------------- Slashdot (http://slashdot.org/) is a popular news site, with lively discussion following the news articles. `nnslashdot' will let you read this forum in a convenient manner. The easiest way to read this source is to put something like the following in your `~/.gnus.el' file: (setq gnus-secondary-select-methods '((nnslashdot ""))) This will make Gnus query the `nnslashdot' back end for new comments and groups. The `F' command will subscribe each new news article as a new Gnus group, and you can read the comments by entering these groups. (Note that the default subscription method is to subscribe new groups as zombies. Other methods are available (*note Subscription Methods::). If you want to remove an old `nnslashdot' group, the `G DEL' command is the most handy tool (*note Foreign Groups::). When following up to `nnslashdot' comments (or posting new comments), some light HTMLizations will be performed. In particular, text quoted with `> ' will be quoted with `blockquote' instead, and signatures will have `br' added to the end of each line. Other than that, you can just write HTML directly into the message buffer. Note that Slashdot filters out some HTML forms. The following variables can be altered to change its behavior: `nnslashdot-threaded' Whether `nnslashdot' should display threaded groups or not. The default is `t'. To be able to display threads, `nnslashdot' has to retrieve absolutely all comments in a group upon entry. If a threaded display is not required, `nnslashdot' will only retrieve the comments that are actually wanted by the user. Threading is nicer, but much, much slower than unthreaded. `nnslashdot-login-name' The login name to use when posting. `nnslashdot-password' The password to use when posting. `nnslashdot-directory' Where `nnslashdot' will store its files. The default is `~/News/slashdot/'. `nnslashdot-active-url' The URL format string that will be used to fetch the information on news articles and comments. The default is `http://slashdot.org/search.pl?section=&min=%d'. `nnslashdot-comments-url' The URL format string that will be used to fetch comments. `nnslashdot-article-url' The URL format string that will be used to fetch the news article. The default is `http://slashdot.org/article.pl?sid=%s&mode=nocomment'. `nnslashdot-threshold' The score threshold. The default is -1. `nnslashdot-group-number' The number of old groups, in addition to the ten latest, to keep updated. The default is 0.  File: gnus, Node: Ultimate, Next: Web Archive, Prev: Slashdot, Up: Browsing the Web 6.4.4 Ultimate -------------- The Ultimate Bulletin Board (http://www.ultimatebb.com/) is probably the most popular Web bulletin board system used. It has a quite regular and nice interface, and it's possible to get the information Gnus needs to keep groups updated. The easiest way to get started with `nnultimate' is to say something like the following in the group buffer: `B nnultimate RET http://www.tcj.com/messboard/ubbcgi/ RET'. (Substitute the URL (not including `Ultimate.cgi' or the like at the end) for a forum you're interested in; there's quite a list of them on the Ultimate web site.) Then subscribe to the groups you're interested in from the server buffer, and read them from the group buffer. The following `nnultimate' variables can be altered: `nnultimate-directory' The directory where `nnultimate' stores its files. The default is `~/News/ultimate/'.  File: gnus, Node: Web Archive, Next: RSS, Prev: Ultimate, Up: Browsing the Web 6.4.5 Web Archive ----------------- Some mailing lists only have archives on Web servers, such as `http://www.egroups.com/' and `http://www.mail-archive.com/'. It has a quite regular and nice interface, and it's possible to get the information Gnus needs to keep groups updated. The easiest way to get started with `nnwarchive' is to say something like the following in the group buffer: `M-x gnus-group-make-warchive-group RET AN_EGROUP RET egroups RET www.egroups.com RET YOUR@EMAIL.ADDRESS RET'. (Substitute the AN_EGROUP with the mailing list you subscribed, the YOUR@EMAIL.ADDRESS with your email address.), or to browse the back end by `B nnwarchive RET mail-archive RET'. The following `nnwarchive' variables can be altered: `nnwarchive-directory' The directory where `nnwarchive' stores its files. The default is `~/News/warchive/'. `nnwarchive-login' The account name on the web server. `nnwarchive-passwd' The password for your account on the web server.  File: gnus, Node: RSS, Next: Customizing W3, Prev: Web Archive, Up: Browsing the Web 6.4.6 RSS --------- Some web sites have an RDF Site Summary (RSS). RSS is a format for summarizing headlines from news related sites (such as BBC or CNN). But basically anything list-like can be presented as an RSS feed: weblogs, changelogs or recent changes to a wiki (e.g. `http://cliki.net/recent-changes.rdf'). RSS has a quite regular and nice interface, and it's possible to get the information Gnus needs to keep groups updated. Note: you had better use Emacs which supports the `utf-8' coding system because RSS uses UTF-8 for encoding non-ASCII text by default. It is also used by default for non-ASCII group names. Use `G R' from the group buffer to subscribe to a feed--you will be prompted for the location, the title and the description of the feed. The title, which allows any characters, will be used for the group name and the name of the group data file. The description can be omitted. An easy way to get started with `nnrss' is to say something like the following in the group buffer: `B nnrss RET RET y', then subscribe to groups. The `nnrss' back end saves the group data file in `nnrss-directory' (see below) for each `nnrss' group. File names containing non-ASCII characters will be encoded by the coding system specified with the `nnmail-pathname-coding-system' variable or other. Also *Note Non-ASCII Group Names::, for more information. The `nnrss' back end generates `multipart/alternative' MIME articles in which each contains a `text/plain' part and a `text/html' part. You can also use the following commands to import and export your subscriptions from a file in OPML format (Outline Processor Markup Language). -- Function: nnrss-opml-import file Prompt for an OPML file, and subscribe to each feed in the file. -- Function: nnrss-opml-export Write your current RSS subscriptions to a buffer in OPML format. The following `nnrss' variables can be altered: `nnrss-directory' The directory where `nnrss' stores its files. The default is `~/News/rss/'. `nnrss-file-coding-system' The coding system used when reading and writing the `nnrss' groups data files. The default is the value of `mm-universal-coding-system' (which defaults to `emacs-mule' in Emacs or `escape-quoted' in XEmacs). `nnrss-ignore-article-fields' Some feeds update constantly article fields during their publications, e.g. to indicate the number of comments. However, if there is a difference between the local article and the distant one, the latter is considered to be new. To avoid this and discard some fields, set this variable to the list of fields to be ignored. The default is `'(slash:comments)'. `nnrss-use-local' If you set `nnrss-use-local' to `t', `nnrss' will read the feeds from local files in `nnrss-directory'. You can use the command `nnrss-generate-download-script' to generate a download script using `wget'. `nnrss-wash-html-in-text-plain-parts' Non-`nil' means that `nnrss' renders text in `text/plain' parts as HTML. The function specified by the `mm-text-html-renderer' variable (*note Display Customization: (emacs-mime)Display Customization.) will be used to render text. If it is `nil', which is the default, text will simply be folded. Leave it `nil' if you prefer to see `text/html' parts. The following code may be helpful, if you want to show the description in the summary buffer. (add-to-list 'nnmail-extra-headers nnrss-description-field) (setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n") (defun gnus-user-format-function-X (header) (let ((descr (assq nnrss-description-field (mail-header-extra header)))) (if descr (concat "\n\t" (cdr descr)) ""))) The following code may be useful to open an nnrss url directly from the summary buffer. (require 'browse-url) (defun browse-nnrss-url (arg) (interactive "p") (let ((url (assq nnrss-url-field (mail-header-extra (gnus-data-header (assq (gnus-summary-article-number) gnus-newsgroup-data)))))) (if url (progn (browse-url (cdr url)) (gnus-summary-mark-as-read-forward 1)) (gnus-summary-scroll-up arg)))) (eval-after-load "gnus" #'(define-key gnus-summary-mode-map (kbd "") 'browse-nnrss-url)) (add-to-list 'nnmail-extra-headers nnrss-url-field) Even if you have added `text/html' to the `mm-discouraged-alternatives' variable (*note Display Customization: (emacs-mime)Display Customization.) since you don't want to see HTML parts, it might be more useful especially in `nnrss' groups to display `text/html' parts. Here's an example of setting `mm-discouraged-alternatives' as a group parameter (*note Group Parameters::) in order to display `text/html' parts only in `nnrss' groups: ;; Set the default value of `mm-discouraged-alternatives'. (eval-after-load "gnus-sum" '(add-to-list 'gnus-newsgroup-variables '(mm-discouraged-alternatives . '("text/html" "image/.*")))) ;; Display `text/html' parts in `nnrss' groups. (add-to-list 'gnus-parameters '("\\`nnrss:" (mm-discouraged-alternatives nil)))  File: gnus, Node: Customizing W3, Prev: RSS, Up: Browsing the Web 6.4.7 Customizing W3 -------------------- Gnus uses the url library to fetch web pages and Emacs/W3 (or those alternatives) to display web pages. Emacs/W3 is documented in its own manual, but there are some things that may be more relevant for Gnus users. For instance, a common question is how to make Emacs/W3 follow links using the `browse-url' functions (which will call some external web browser like Netscape). Here's one way: (eval-after-load "w3" '(progn (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) (defun w3-fetch (&optional url target) (interactive (list (w3-read-url-with-default))) (if (eq major-mode 'gnus-article-mode) (browse-url url) (w3-fetch-orig url target))))) Put that in your `.emacs' file, and hitting links in W3-rendered HTML in the Gnus article buffers will use `browse-url' to follow the link.  File: gnus, Node: IMAP, Next: Other Sources, Prev: Browsing the Web, Up: Select Methods 6.5 IMAP ======== IMAP is a network protocol for reading mail (or news, or ...), think of it as a modernized NNTP. Connecting to a IMAP server is much similar to connecting to a news server, you just specify the network address of the server. IMAP has two properties. First, IMAP can do everything that POP can, it can hence be viewed as a POP++. Secondly, IMAP is a mail storage protocol, similar to NNTP being a news storage protocol--however, IMAP offers more features than NNTP because news is more or less read-only whereas mail is read-write. If you want to use IMAP as a POP++, use an imap entry in `mail-sources'. With this, Gnus will fetch mails from the IMAP server and store them on the local disk. This is not the usage described in this section--*Note Mail Sources::. If you want to use IMAP as a mail storage protocol, use an nnimap entry in `gnus-secondary-select-methods'. With this, Gnus will manipulate mails stored on the IMAP server. This is the kind of usage explained in this section. A server configuration in `~/.gnus.el' with a few IMAP servers might look something like the following. (Note that for TLS/SSL, you need external programs and libraries, see below.) (setq gnus-secondary-select-methods '((nnimap "simpleserver") ; no special configuration ; perhaps a ssh port forwarded server: (nnimap "dolk" (nnimap-address "localhost") (nnimap-server-port 1430)) ; a UW server running on localhost (nnimap "barbar" (nnimap-server-port 143) (nnimap-address "localhost") (nnimap-list-pattern ("INBOX" "mail/*"))) ; anonymous public cyrus server: (nnimap "cyrus.andrew.cmu.edu" (nnimap-authenticator anonymous) (nnimap-list-pattern "archive.*") (nnimap-stream network)) ; a ssl server on a non-standard port: (nnimap "vic20" (nnimap-address "vic20.somewhere.com") (nnimap-server-port 9930) (nnimap-stream ssl)))) After defining the new server, you can subscribe to groups on the server using normal Gnus commands such as `U' in the Group Buffer (*note Subscription Commands::) or via the Server Buffer (*note Server Buffer::). The following variables can be used to create a virtual `nnimap' server: `nnimap-address' The address of the remote IMAP server. Defaults to the virtual server name if not specified. `nnimap-server-port' Port on server to contact. Defaults to port 143, or 993 for TLS/SSL. Note that this should be an integer, example server specification: (nnimap "mail.server.com" (nnimap-server-port 4711)) `nnimap-list-pattern' String or list of strings of mailboxes to limit available groups to. This is used when the server has very many mailboxes and you're only interested in a few--some servers export your home directory via IMAP, you'll probably want to limit the mailboxes to those in `~/Mail/*' then. The string can also be a cons of REFERENCE and the string as above, what REFERENCE is used for is server specific, but on the University of Washington server it's a directory that will be concatenated with the mailbox. Example server specification: (nnimap "mail.server.com" (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" ("~friend/Mail/" . "list/*")))) `nnimap-stream' The type of stream used to connect to your server. By default, nnimap will detect and automatically use all of the below, with the exception of TLS/SSL. (IMAP over TLS/SSL is being replaced by STARTTLS, which can be automatically detected, but it's not widely deployed yet.) Example server specification: (nnimap "mail.server.com" (nnimap-stream ssl)) Please note that the value of `nnimap-stream' is a symbol! * "gssapi:" Connect with GSSAPI (usually Kerberos 5). Requires the `gsasl' or `imtest' program. * "kerberos4:" Connect with Kerberos 4. Requires the `imtest' program. * "starttls:" Connect via the STARTTLS extension (similar to TLS/SSL). Requires the external library `starttls.el' and program `starttls'. * "tls:" Connect through TLS. Requires GNUTLS (the program `gnutls-cli'). * "ssl:" Connect through SSL. Requires OpenSSL (the program `openssl') or SSLeay (`s_client'). * "shell:" Use a shell command to start IMAP connection. * "network:" Plain, TCP/IP network connection. The `imtest' program is shipped with Cyrus IMAPD. If you're using `imtest' from Cyrus IMAPD < 2.0.14 (which includes version 1.5.x and 1.6.x) you need to frob `imap-process-connection-type' to make `imap.el' use a pty instead of a pipe when communicating with `imtest'. You will then suffer from a line length restrictions on IMAP commands, which might make Gnus seem to hang indefinitely if you have many articles in a mailbox. The variable `imap-kerberos4-program' contain parameters to pass to the imtest program. For TLS connection, the `gnutls-cli' program from GNUTLS is needed. It is available from `http://www.gnu.org/software/gnutls/'. This parameter specifies a list of command lines that invoke a GSSAPI authenticated IMAP stream in a subshell. They are tried sequentially until a connection is made, or the list has been exhausted. By default, `gsasl' from GNU SASL, available from `http://www.gnu.org/software/gsasl/', and the `imtest' program from Cyrus IMAPD (see `imap-kerberos4-program'), are tried. For SSL connections, the OpenSSL program is available from `http://www.openssl.org/'. OpenSSL was formerly known as SSLeay, and nnimap support it too--although the most recent versions of SSLeay, 0.9.x, are known to have serious bugs making it useless. Earlier versions, especially 0.8.x, of SSLeay are known to work. The variable `imap-ssl-program' contain parameters to pass to OpenSSL/SSLeay. For IMAP connections using the `shell' stream, the variable `imap-shell-program' specify what program to call. Make sure nothing is interfering with the output of the program, e.g., don't forget to redirect the error output to the void. `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 frobbing 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. However, if `nnimap-search-uids-not-since-is-evil' is true, this variable has no effect since the search logic is reversed, as described below. `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. `nnimap-nov-is-evil' Never generate or use a local NOV database. Defaults to the value of `gnus-agent'. Using a NOV database usually makes header fetching much faster, but it uses the `UID SEARCH UID' command, which is very slow on some servers (notably some versions of Courier). Since the Gnus Agent caches the information in the NOV database without using the slow command, this variable defaults to true if the Agent is in use, and false otherwise. `nnimap-search-uids-not-since-is-evil' Avoid the `UID SEARCH UID MESSAGE NUMBERS NOT SINCE DATE' command, which is slow on some IMAP servers (notably, some versions of Courier). Instead, use `UID SEARCH SINCE DATE' and prune the list of expirable articles within Gnus. When Gnus expires your mail (*note Expiring Mail::), it starts with a list of expirable articles and asks the IMAP server questions like "Of these articles, which ones are older than a week?" While this seems like a perfectly reasonable question, some IMAP servers take a long time to answer it, since they seemingly go looking into every old article to see if it is one of the expirable ones. Curiously, the question "Of _all_ articles, which ones are newer than a week?" seems to be much faster to answer, so setting this variable causes Gnus to ask this question and figure out the answer to the real question itself. This problem can really sneak up on you: when you first configure Gnus, everything works fine, but once you accumulate a couple thousand messages, you start cursing Gnus for being so slow. On the other hand, if you get a lot of email within a week, setting this variable will cause a lot of network traffic between Gnus and the IMAP server. `nnimap-logout-timeout' There is a case where a connection to a IMAP server is unable to close, when connecting to the server via a certain kind of network, e.g. VPN. In that case, it will be observed that a connection between Emacs and the local network looks alive even if the server has closed a connection for some reason (typically, a timeout). Consequently, Emacs continues waiting for a response from the server for the `LOGOUT' command that Emacs sent, or hangs in other words. If you are in such a network, setting this variable to a number of seconds will be helpful. If it is set, a hung connection will be closed forcibly, after this number of seconds from the time Emacs sends the `LOGOUT' command. It should not be too small value but too large value will be inconvenient too. Perhaps the value 1.0 will be a good candidate but it might be worth trying some other values. Example server specification: (nnimap "mail.server.com" (nnimap-logout-timeout 1.0)) * Menu: * Splitting in IMAP:: Splitting mail with nnimap. * Expiring in IMAP:: Expiring mail with nnimap. * Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. * Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. * A note on namespaces:: How to (not) use IMAP namespace in Gnus. * Debugging IMAP:: What to do when things don't work.  File: gnus, Node: Splitting in IMAP, Next: Expiring in IMAP, Up: IMAP 6.5.1 Splitting in IMAP ----------------------- Splitting is something Gnus users have loved and used for years, and now the rest of the world is catching up. Yeah, dream on, not many IMAP servers have server side splitting and those that have splitting seem to use some non-standard protocol. This means that IMAP support for Gnus has to do its own splitting. And it does. (Incidentally, people seem to have been dreaming on, and Sieve has gaining a market share and is supported by several IMAP servers. Fortunately, Gnus support it too, *Note Sieve Commands::.) Here are the variables of interest: `nnimap-split-crosspost' If non-`nil', do crossposting if several split methods match the mail. If `nil', the first match in `nnimap-split-rule' found will be used. Nnmail equivalent: `nnmail-crosspost'. `nnimap-split-inbox' A string or a list of strings that gives the name(s) of IMAP mailboxes to split from. Defaults to `nil', which means that splitting is disabled! (setq nnimap-split-inbox '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap")) No nnmail equivalent. `nnimap-split-rule' New mail found in `nnimap-split-inbox' will be split according to this variable. This variable contains a list of lists, where the first element in the sublist gives the name of the IMAP mailbox to move articles matching the regexp in the second element in the sublist. Got that? Neither did I, we need examples. (setq nnimap-split-rule '(("INBOX.nnimap" "^Sender: owner-nnimap@vic20.globalcom.se") ("INBOX.junk" "^Subject:.*MAKE MONEY") ("INBOX.private" ""))) This will put all articles from the nnimap mailing list into mailbox INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line into INBOX.junk and everything else in INBOX.private. The first string may contain `\\1' forms, like the ones used by replace-match to insert sub-expressions from the matched text. For instance: ("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@") The first element can also be the symbol `junk' to indicate that matching messages should simply be deleted. Use with care. The second element can also be a function. In that case, it will be called with the first element of the rule as the argument, in a buffer containing the headers of the article. It should return a non-`nil' value if it thinks that the mail belongs in that group. Nnmail users might recollect that the last regexp had to be empty to match all articles (like in the example above). This is not required in nnimap. Articles not matching any of the regexps will not be moved out of your inbox. (This might affect performance if you keep lots of unread articles in your inbox, since the splitting code would go over them every time you fetch new mail.) These rules are processed from the beginning of the alist toward the end. The first rule to make a match will "win", unless you have crossposting enabled. In that case, all matching rules will "win". This variable can also have a function as its value, the function will be called with the headers narrowed and should return a group where it thinks the article should be split to. See `nnimap-split-fancy'. The splitting code tries to create mailboxes if it needs to. To allow for different split rules on different virtual servers, and even different split rules in different inboxes on the same server, the syntax of this variable have been extended along the lines of: (setq nnimap-split-rule '(("my1server" (".*" (("ding" "ding@gnus.org") ("junk" "From:.*Simon")))) ("my2server" ("INBOX" nnimap-split-fancy)) ("my[34]server" (".*" (("private" "To:.*Simon") ("junk" my-junk-func)))))) The virtual server name is in fact a regexp, so that the same rules may apply to several servers. In the example, the servers `my3server' and `my4server' both use the same rules. Similarly, the inbox string is also a regexp. The actual splitting rules are as before, either a function, or a list with group/regexp or group/function elements. Nnmail equivalent: `nnmail-split-methods'. `nnimap-split-predicate' Mail matching this predicate in `nnimap-split-inbox' will be split, it is a string and the default is `UNSEEN UNDELETED'. This might be useful if you use another IMAP client to read mail in your inbox but would like Gnus to split all articles in the inbox regardless of readedness. Then you might change this to `UNDELETED'. `nnimap-split-fancy' It's possible to set `nnimap-split-rule' to `nnmail-split-fancy' if you want to use fancy splitting. *Note Fancy Mail Splitting::. However, to be able to have different fancy split rules for nnmail and nnimap back ends you can set `nnimap-split-rule' to `nnimap-split-fancy' and define the nnimap specific fancy split rule in `nnimap-split-fancy'. Example: (setq nnimap-split-rule 'nnimap-split-fancy nnimap-split-fancy ...) Nnmail equivalent: `nnmail-split-fancy'. `nnimap-split-download-body' Set to non-`nil' to download entire articles during splitting. This is generally not required, and will slow things down considerably. You may need it if you want to use an advanced splitting function that analyzes the body to split the article.  File: gnus, Node: Expiring in IMAP, Next: Editing IMAP ACLs, Prev: Splitting in IMAP, Up: IMAP 6.5.2 Expiring in IMAP ---------------------- Even though `nnimap' is not a proper `nnmail' derived back end, it supports most features in regular expiring (*note Expiring Mail::). Unlike splitting in IMAP (*note Splitting in IMAP::) it does not clone the `nnmail' variables (i.e., creating NNIMAP-EXPIRY-WAIT) but reuse the `nnmail' variables. What follows below are the variables used by the `nnimap' expiry process. A note on how the expire mark is stored on the IMAP server is appropriate here as well. The expire mark is translated into a `imap' client specific mark, `gnus-expire', and stored on the message. This means that likely only Gnus will understand and treat the `gnus-expire' mark properly, although other clients may allow you to view client specific flags on the message. It also means that your server must support permanent storage of client specific flags on messages. Most do, fortunately. If expiring IMAP mail seems very slow, try setting the server variable `nnimap-search-uids-not-since-is-evil'. `nnmail-expiry-wait' `nnmail-expiry-wait-function' These variables are fully supported. The expire value can be a number, the symbol `immediate' or `never'. `nnmail-expiry-target' This variable is supported, and internally implemented by calling the `nnmail' functions that handle this. It contains an optimization that if the destination is a IMAP group on the same server, the article is copied instead of appended (that is, uploaded again).  File: gnus, Node: Editing IMAP ACLs, Next: Expunging mailboxes, Prev: Expiring in IMAP, Up: IMAP 6.5.3 Editing IMAP ACLs ----------------------- ACL stands for Access Control List. ACLs are used in IMAP for limiting (or enabling) other users access to your mail boxes. Not all IMAP servers support this, this function will give an error if it doesn't. To edit an ACL for a mailbox, type `G l' (`gnus-group-edit-nnimap-acl') and you'll be presented with an ACL editing window with detailed instructions. Some possible uses: * Giving "anyone" the "lrs" rights (lookup, read, keep seen/unseen flags) on your mailing list mailboxes enables other users on the same server to follow the list without subscribing to it. * At least with the Cyrus server, you are required to give the user "anyone" posting ("p") capabilities to have "plussing" work (that is, mail sent to user+mailbox@domain ending up in the IMAP mailbox INBOX.mailbox).  File: gnus, Node: Expunging mailboxes, Next: A note on namespaces, Prev: Editing IMAP ACLs, Up: IMAP 6.5.4 Expunging mailboxes ------------------------- If you're using the `never' setting of `nnimap-expunge-on-close', you may want the option of expunging all deleted articles in a mailbox manually. This is exactly what `G x' does. Currently there is no way of showing deleted articles, you can just delete them.  File: gnus, Node: A note on namespaces, Next: Debugging IMAP, Prev: Expunging mailboxes, Up: IMAP 6.5.5 A note on namespaces -------------------------- The IMAP protocol has a concept called namespaces, described by the following text in the RFC2060: 5.1.2. Mailbox Namespace Naming Convention By convention, the first hierarchical element of any mailbox name which begins with "#" identifies the "namespace" of the remainder of the name. This makes it possible to disambiguate between different types of mailbox stores, each of which have their own namespaces. For example, implementations which offer access to USENET newsgroups MAY use the "#news" namespace to partition the USENET newsgroup namespace from that of other mailboxes. Thus, the comp.mail.misc newsgroup would have an mailbox name of "#news.comp.mail.misc", and the name "comp.mail.misc" could refer to a different object (e.g. a user's private mailbox). While there is nothing in this text that warrants concern for the IMAP implementation in Gnus, some servers use namespace prefixes in a way that does not work with how Gnus uses mailbox names. Specifically, University of Washington's IMAP server uses mailbox names like `#driver.mbx/read-mail' which are valid only in the CREATE and APPEND commands. After the mailbox is created (or a messages is appended to a mailbox), it must be accessed without the namespace prefix, i.e. `read-mail'. Since Gnus do not make it possible for the user to guarantee that user entered mailbox names will only be used with the CREATE and APPEND commands, you should simply not use the namespace prefixed mailbox names in Gnus. See the UoW IMAPD documentation for the `#driver.*/' prefix for more information on how to use the prefixes. They are a power tool and should be used only if you are sure what the effects are.  File: gnus, Node: Debugging IMAP, Prev: A note on namespaces, Up: IMAP 6.5.6 Debugging IMAP -------------------- IMAP is a complex protocol, more so than NNTP or POP3. Implementation bugs are not unlikely, and we do our best to fix them right away. If you encounter odd behavior, chances are that either the server or Gnus is buggy. If you are familiar with network protocols in general, you will probably be able to extract some clues from the protocol dump of the exchanges between Gnus and the server. Even if you are not familiar with network protocols, when you include the protocol dump in IMAP-related bug reports you are helping us with data critical to solving the problem. Therefore, we strongly encourage you to include the protocol dump when reporting IMAP bugs in Gnus. Because the protocol dump, when enabled, generates lots of data, it is disabled by default. You can enable it by setting `imap-log' as follows: (setq imap-log t) This instructs the `imap.el' package to log any exchanges with the server. The log is stored in the buffer `*imap-log*'. Look for error messages, which sometimes are tagged with the keyword `BAD'--but when submitting a bug, make sure to include all the data.  File: gnus, Node: Other Sources, Next: Combined Groups, Prev: IMAP, Up: Select Methods 6.6 Other Sources ================= Gnus can do more than just read news or mail. The methods described below allow Gnus to view directories and files as if they were newsgroups. * Menu: * Directory Groups:: You can read a directory as if it was a newsgroup. * Anything Groups:: Dired? Who needs dired? * Document Groups:: Single files can be the basis of a group. * SOUP:: Reading SOUP packets ``offline''. * Mail-To-News Gateways:: Posting articles via mail-to-news gateways.  Local Variables: coding: iso-8859-1 End: