This is gnus, produced by makeinfo version 4.5 from gnus.texi. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Gnus: (gnus). The newsreader Gnus. END-INFO-DIR-ENTRY This file documents Gnus, the GNU Emacs newsreader. Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being none, with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License" in the Emacs manual. (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.  File: gnus, Node: Oort Gnus, Prev: Pterodactyl Gnus, Up: New Features Oort Gnus ......... New features in Gnus 5.10: * `gnus-group-read-ephemeral-group' can be called interactively, using `G M'. * In draft groups, `e' is now bound to `gnus-draft-edit-message'. Use `B w' for `gnus-summary-edit-article' instead. * The revised Gnus FAQ is included in the manual, *Note Frequently Asked Questions::. * Upgrading from previous (stable) version if you have used Oort. If you have tried Oort (the unstable Gnus branch leading to this release) but went back to a stable version, be careful when upgrading to this version. In particular, you will probably want to remove all `.marks' (nnml) and `.mrk' (nnfolder) files, so that flags are read from your `.newsrc.eld' instead of from the `.marks'/`.mrk' file where this release store flags. See a later entry for more information about marks. Note that downgrading isn't save in general. * Article Buttons More buttons for URLs, mail addresses, Message-IDs, Info links, man pages and Emacs or Gnus related references. *Note Article Buttons::. The variables `gnus-button-*-level' can be used to control the appearance of all article buttons. *Note Article Button Levels::. * Dired integration `gnus-dired-minor-mode' (see *Note Other modes::) installs key bindings in dired buffers to send a file as an attachment, open a file using the appropriate mailcap entry, and print a file using the mailcap entry. * Gnus can display RSS newsfeeds as a newsgroup. *Note RSS::. * Single-part yenc encoded attachments can be decoded. * Picons The picons code has been reimplemented to work in GNU Emacs--some of the previous options have been removed or renamed. Picons are small "personal icons" representing users, domain and newsgroups, which can be displayed in the Article buffer. *Note Picons::. * If the new option `gnus-treat-body-boundary' is non-`nil', a boundary line is drawn at the end of the headers. * Retrieval of charters and control messages There are new commands for fetching newsgroup charters (`H c') and control messages (`H C'). * Delayed articles You can delay the sending of a message with `C-c C-j' in the Message buffer. The messages are delivered at specified time. This is useful for sending yourself reminders. *Note Delayed Articles::. * If `auto-compression-mode' is enabled, attachments are automatically decompressed when activated. * If the new option `nnml-use-compressed-files' is non-`nil', the nnml back end allows compressed message files. * Signed article headers (X-PGP-Sig) can be verified with `W p'. * The Summary Buffer uses an arrow in the fringe to indicate the current article. Use `(setq gnus-summary-display-arrow nil)' to disable it. * Warn about email replies to news Do you often find yourself replying to news by email by mistake? Then the new option `gnus-confirm-mail-reply-to-news' is just the thing for you. * If the new option `gnus-summary-display-while-building' is non-`nil', the summary buffer is shown and updated as it's being built. * The new `recent' mark `.' indicates newly arrived messages (as opposed to old but unread messages). * The new option `gnus-gcc-mark-as-read' automatically marks Gcc articles as read. * The nndoc back end now supports mailman digests and exim bounces. * Gnus supports RFC 2369 mailing list headers, and adds a number of related commands in mailing list groups. *Note Mailing List::. * The Date header can be displayed in a format that can be read aloud in English. *Note Article Date::. * The envelope sender address can be customized when using Sendmail. *Note Mail Variables: (message)Mail Variables. * diffs are automatically highlighted in groups matching `mm-uu-diff-groups-regexp' * TLS wrapper shipped with Gnus TLS/SSL is now supported in IMAP and NNTP via `tls.el' and GNUTLS. The old TLS/SSL support via (external third party) `ssl.el' and OpenSSL still works. * New `make.bat' for compiling and installing Gnus under MS Windows Use `make.bat' if you want to install Gnus under MS Windows, the first argument to the batch-program should be the directory where `xemacs.exe' respectively `emacs.exe' is located, iff you want to install Gnus after compiling it, give `make.bat' `/copy' as the second parameter. `make.bat' has been rewritten from scratch, it now features automatic recognition of XEmacs and GNU Emacs, generates `gnus-load.el', checks if errors occur while compilation and generation of info files and reports them at the end of the build process. It now uses `makeinfo' if it is available and falls back to `infohack.el' otherwise. `make.bat' should now install all files which are necessary to run Gnus and be generally a complete replacement for the `configure; make; make install' cycle used under Unix systems. The new `make.bat' makes `make-x.bat' superfluous, so it has been removed. * Support for non-ASCII domain names Message supports non-ASCII domain names in From:, To: and Cc: and will query you whether to perform encoding when you try to send a message. The variable `message-use-idna' controls this. Gnus will also decode non-ASCII domain names in From:, To: and Cc: when you view a message. The variable `gnus-use-idna' controls this. * Better handling of Microsoft citation styles Gnus now tries to recognize the mangled header block that some Microsoft mailers use to indicate that the rest of the message is a citation, even though it is not quoted in any way. The variable `gnus-cite-unsightly-citation-regexp' matches the start of these citations. * `gnus-article-skip-boring' If you set `gnus-article-skip-boring' to `t', then Gnus will not scroll down to show you a page that contains only boring text, which by default means cited text and signature. You can customize what is skippable using `gnus-article-boring-faces'. This feature is especially useful if you read many articles that consist of a little new content at the top with a long, untrimmed message cited below. * The format spec `%C' for positioning point has changed to `%*'. * The new variable `gnus-parameters' can be used to set group parameters. Earlier this was done only via `G p' (or `G c'), which stored the parameters in `~/.newsrc.eld', but via this variable you can enjoy the powers of customize, and simplified backups since you set the variable in `~/.emacs' instead of `~/.newsrc.eld'. The variable maps regular expressions matching group names to group parameters, a'la: (setq gnus-parameters '(("mail\\..*" (gnus-show-threads nil) (gnus-use-scoring nil)) ("^nnimap:\\(foo.bar\\)$" (to-group . "\\1")))) * Smileys (`:-)', `;-)' etc) are now iconized for Emacs too. Put `(setq gnus-treat-display-smileys nil)' in `~/.emacs' to disable it. * Gnus no longer generate the Sender: header automatically. Earlier it was generated iff the user configurable email address was different from the Gnus guessed default user address. As the guessing algorithm is rarely correct these days, and (more controversially) the only use of the Sender: header was to check if you are entitled to cancel/supersede news (which is now solved by Cancel Locks instead, see another entry), generation of the header has been disabled by default. See the variables `message-required-headers', `message-required-news-headers', and `message-required-mail-headers'. * Features from third party `message-utils.el' added to `message.el'. Message now asks if you wish to remove `(was: )' from subject lines (see `message-subject-trailing-was-query'). `C-c M-m' and `C-c M-f' inserts markers indicating included text. `C-c C-f a' adds a X-No-Archive: header. `C-c C-f x' inserts appropriate headers and a note in the body for cross-postings and followups (see the variables `message-cross-post-*'). * References and X-Draft-Headers are no longer generated when you start composing messages and `message-generate-headers-first' is `nil'. * Improved anti-spam features. Gnus is now able to take out spam from your mail and news streams using a wide variety of programs and filter rules. Among the supported methods are RBL blocklists, bogofilter and white/blacklists. Hooks for easy use of external packages such as SpamAssassin and Hashcash are also new. *Note Thwarting Email Spam::. * Easy inclusion of X-Faces headers. * Face headers handling. * In the summary buffer, the new command `/ N' inserts new messages and `/ o' inserts old messages. * Gnus decodes morse encoded messages if you press `W m'. * Unread count correct in nnimap groups. The estimated number of unread articles in the group buffer should now be correct for nnimap groups. This is achieved by calling `nnimap-fixup-unread-after-getting-new-news' from the `gnus-setup-news-hook' (called on startup) and `gnus-after-getting-new-news-hook'. (called after getting new mail). If you have modified those variables from the default, you may want to add `nnimap-fixup-unread-after-getting-new-news' again. If you were happy with the estimate and want to save some (minimal) time when getting new mail, remove the function. * Group Carbon Copy (GCC) quoting To support groups that contains SPC and other weird characters, groups are quoted before they are placed in the Gcc: header. This means variables such as `gnus-message-archive-group' should no longer contain quote characters to make groups containing SPC work. Also, if you are using the string `nnml:foo, nnml:bar' (indicating Gcc into two groups) you must change it to return the list `("nnml:foo" "nnml:bar")', otherwise the Gcc: line will be quoted incorrectly. Note that returning the string `nnml:foo, nnml:bar' was incorrect earlier, it just didn't generate any problems since it was inserted directly. * `~/News/overview/' not used. As a result of the following change, the `~/News/overview/' directory is not used any more. You can safely delete the entire hierarchy. * `gnus-agent' The Gnus Agent has seen a major updated and is now enabled by default, and all nntp and nnimap servers from `gnus-select-method' and `gnus-secondary-select-method' are agentized by default. Earlier only the server in `gnus-select-method' was agentized by the default, and the agent was disabled by default. When the agent is enabled, headers are now also retrieved from the Agent cache instead of the back ends when possible. Earlier this only happened in the unplugged state. You can enroll or remove servers with `J a' and `J r' in the server buffer. Gnus will not download articles into the Agent cache, unless you instruct it to do so, though, by using `J u' or `J s' from the Group buffer. You revert to the old behaviour of having the Agent disabled with `(setq gnus-agent nil)'. Note that putting `(gnus-agentize)' in `~/.gnus.el' is not needed any more. * `gnus-summary-line-format' The default value changed to `%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n'. Moreover `gnus-extra-headers', `nnmail-extra-headers' and `gnus-ignored-from-addresses' changed their default so that the users name will be replaced by the recipient's name or the group name posting to for NNTP groups. * `deuglify.el' (`gnus-article-outlook-deuglify-article') A new file from Raymond Scholz for deuglifying broken Outlook (Express) articles. * `(require 'gnus-load)' If you use a stand-alone Gnus distribution, you'd better add `(require 'gnus-load)' into your `~/.emacs' after adding the Gnus lisp directory into load-path. File `gnus-load.el' contains autoload commands, functions and variables, some of which may not be included in distributions of Emacsen. * `gnus-slave-unplugged' A new command which starts Gnus offline in slave mode. * `message-insinuate-rmail' Adding `(message-insinuate-rmail)' and `(setq mail-user-agent 'gnus-user-agent)' in `.emacs' convinces Rmail to compose, reply and forward messages in message-mode, where you can enjoy the power of MML. * `message-minibuffer-local-map' The line below enables BBDB in resending a message: (define-key message-minibuffer-local-map [(tab)] 'bbdb-complete-name) * Externalizing and deleting of attachments. If `gnus-gcc-externalize-attachments' or `message-fcc-externalize-attachments' is non-`nil', attach local files as external parts. The command `gnus-mime-save-part-and-strip' (bound to `C-o' on MIME buttons) saves a part and replaces the part with an external one. `gnus-mime-delete-part' (bound to `d' on MIME buttons) removes a part. It works only on back ends that support editing. * `gnus-default-charset' The default value is determined from the `current-language-environment' variable, instead of `iso-8859-1'. Also the `.*' item in `gnus-group-charset-alist' is removed. * `gnus-posting-styles' Add a new format of match like ((header "to" "larsi.*org") (Organization "Somewhere, Inc.")) The old format like the lines below is obsolete, but still accepted. (header "to" "larsi.*org" (Organization "Somewhere, Inc.")) * `message-ignored-news-headers' and `message-ignored-mail-headers' `X-Draft-From' and `X-Gnus-Agent-Meta-Information' have been added into these two variables. If you customized those, perhaps you need add those two headers too. * Gnus reads the NOV and articles in the Agent if plugged. If one reads an article while plugged, and the article already exists in the Agent, it won't get downloaded once more. `(setq gnus-agent-cache nil)' reverts to the old behavior. * Gnus supports the "format=flowed" (RFC 2646) parameter. On composing messages, it is enabled by `use-hard-newlines'. Decoding format=flowed was present but not documented in earlier versions. * Gnus supports the generation of RFC 2298 Disposition Notification requests. This is invoked with the `C-c M-n' key binding from message mode. * Gnus supports Maildir groups. Gnus includes a new back end `nnmaildir.el'. *Note Maildir::. * Printing capabilities are enhanced. Gnus supports Muttprint natively with `O P' from the Summary and Article buffers. Also, each individual MIME part can be printed using `p' on the MIME button. * Message supports the Importance: (RFC 2156) header. In the message buffer, `C-c C-f C-i' or `C-c C-u' cycles through the valid values. * Gnus supports Cancel Locks in News. This means a header `Cancel-Lock' is inserted in news posting. It is used to determine if you wrote an article or not (for canceling and superseding). Gnus generates a random password string the first time you post a message, and saves it in your `~/.emacs' using the Custom system. While the variable is called `canlock-password', it is not security sensitive data. Publishing your canlock string on the web will not allow anyone to be able to anything she could not already do. The behaviour can be changed by customizing `message-insert-canlock'. * Gnus supports server-side mail filtering using Sieve. Sieve rules can be added as Group Parameters for groups, and the complete Sieve script is generated using `D g' from the Group buffer, and then uploaded to the server using `C-c C-l' in the generated Sieve buffer. *Note Sieve Commands::, and the new Sieve manual *Note Top: (sieve)Top. * Extended format specs. Format spec `%&user-date;' is added into `gnus-summary-line-format-alist'. Also, user defined extended format specs are supported. The extended format specs look like `%u&foo;', which invokes function `gnus-user-format-function-FOO'. Because `&' is used as the escape character, old user defined format `%u&' is no longer supported. * `/ *' (`gnus-summary-limit-include-cached') is rewritten. It was aliased to `Y c' (`gnus-summary-insert-cached-articles'). The new function filters out other articles. * Some limiting commands accept a `C-u' prefix to negate the match. If `C-u' is used on subject, author or extra headers, i.e., `/ s', `/ a', and `/ x' (`gnus-summary-limit-to-{subject,author,extra}') respectively, the result will be to display all articles that do not match the expression. * Group names are treated as UTF-8 by default. This is supposedly what USEFOR wanted to migrate to. See `gnus-group-name-charset-group-alist' and `gnus-group-name-charset-method-alist' for customization. * The nnml and nnfolder back ends store marks for each groups. This makes it possible to take backup of nnml/nnfolder servers/groups separately of `~/.newsrc.eld', while preserving marks. It also makes it possible to share articles and marks between users (without sharing the `~/.newsrc.eld' file) within e.g. a department. It works by storing the marks stored in `~/.newsrc.eld' in a per-group file `.marks' (for nnml) and `GROUPNAME.mrk' (for nnfolder, named GROUPNAME). If the nnml/nnfolder is moved to another machine, Gnus will automatically use the `.marks' or `.mrk' file instead of the information in `~/.newsrc.eld'. The new server variables `nnml-marks-is-evil' and `nnfolder-marks-is-evil' can be used to disable this feature. * The menu bar item (in Group and Summary buffer) named "Misc" has been renamed to "Gnus". * The menu bar item (in Message mode) named "MML" has been renamed to "Attachments". Note that this menu also contains security related stuff, like signing and encryption (*note Security: (message)Security.). * `gnus-group-charset-alist' and `gnus-group-ignored-charsets-alist'. The regexps in these variables are compared with full group names instead of real group names in 5.8. Users who customize these variables should change those regexps accordingly. For example: ("^han\\>" euc-kr) -> ("\\(^\\|:\\)han\\>" euc-kr) * Gnus supports PGP (RFC 1991/2440), PGP/MIME (RFC 2015/3156) and S/MIME (RFC 2630-2633). It needs an external S/MIME and OpenPGP implementation, but no additional Lisp libraries. This add several menu items to the Attachments menu, and `C-c RET' key bindings, when composing messages. This also obsoletes `gnus-article-hide-pgp-hook'. * Gnus inlines external parts (message/external). * MML (Mime compose) prefix changed from `M-m' to `C-c C-m'. This change was made to avoid conflict with the standard binding of `back-to-indentation', which is also useful in message mode. * The default for `message-forward-show-mml' changed to symbol `best'. The behaviour for the `best' value is to show MML (i.e., convert to MIME) when appropriate. MML will not be used when forwarding signed or encrypted messages, as the conversion invalidate the digital signature.  File: gnus, Node: On Writing Manuals, Next: Terminology, Prev: History, Up: Appendices On Writing Manuals ================== I guess most manuals are written after-the-fact; documenting a program that's already there. This is not how this manual is written. When implementing something, I write the manual entry for that something straight away. I then see that it's difficult to explain the functionality, so I write how it's supposed to be, and then I change the implementation. Writing the documentation and writing the code goes hand in hand. This, of course, means that this manual has no, or little, flow. It documents absolutely everything in Gnus, but often not where you're looking for it. It is a reference manual, and not a guide to how to get started with Gnus. That would be a totally different book, that should be written using the reference manual as source material. It would look quite differently.  File: gnus, Node: Terminology, Next: Customization, Prev: On Writing Manuals, Up: Appendices Terminology =========== "news" This is what you are supposed to use this thing for--reading news. News is generally fetched from a nearby NNTP server, and is generally publicly available to everybody. If you post news, the entire world is likely to read just what you have written, and they'll all snigger mischievously. Behind your back. "mail" Everything that's delivered to you personally is mail. Some news/mail readers (like Gnus) blur the distinction between mail and news, but there is a difference. Mail is private. News is public. Mailing is not posting, and replying is not following up. "reply" Send a mail to the person who has written what you are reading. "follow up" Post an article to the current newsgroup responding to the article you are reading. "back end" Gnus considers mail and news to be mostly the same, really. The only difference is how to access the actual articles. News articles are commonly fetched via the protocol NNTP, whereas mail messages could be read from a file on the local disk. The internal architecture of Gnus thus comprises a "front end" and a number of "back ends". Internally, when you enter a group (by hitting , say), you thereby invoke a function in the front end in Gnus. The front end then "talks" to a back end and says things like "Give me the list of articles in the foo group" or "Show me article number 4711". So a back end mainly defines either a protocol (the `nntp' back end accesses news via NNTP, the `nnimap' back end accesses mail via IMAP) or a file format and directory layout (the `nnspool' back end accesses news via the common "spool directory" format, the `nnml' back end access mail via a file format and directory layout that's quite similar). Gnus does not handle the underlying media, so to speak--this is all done by the back ends. A back end is a collection of functions to access the articles. However, sometimes the term "back end" is also used where "server" would have been more appropriate. And then there is the term "select method" which can mean either. The Gnus terminology can be quite confusing. "native" Gnus will always use one method (and back end) as the "native", or default, way of getting news. "foreign" You can also have any number of foreign groups active at the same time. These are groups that use non-native non-secondary back ends for getting news. "secondary" Secondary back ends are somewhere half-way between being native and being foreign, but they mostly act like they are native. "article" A message that has been posted as news. "mail message" A message that has been mailed. "message" A mail message or news article "head" The top part of a message, where administrative information (etc.) is put. "body" The rest of an article. Everything not in the head is in the body. "header" A line from the head of an article. "headers" A collection of such lines, or a collection of heads. Or even a collection of NOV lines. "NOV" When Gnus enters a group, it asks the back end for the headers of all unread articles in the group. Most servers support the News OverView format, which is more compact and much faster to read and parse than the normal HEAD format. "level" Each group is subscribed at some "level" or other (1-9). The ones that have a lower level are "more" subscribed than the groups with a higher level. In fact, groups on levels 1-5 are considered "subscribed"; 6-7 are "unsubscribed"; 8 are "zombies"; and 9 are "killed". Commands for listing groups and scanning for new articles will all use the numeric prefix as "working level". "killed groups" No information on killed groups is stored or updated, which makes killed groups much easier to handle than subscribed groups. "zombie groups" Just like killed groups, only slightly less dead. "active file" The news server has to keep track of what articles it carries, and what groups exist. All this information in stored in the active file, which is rather large, as you might surmise. "bogus groups" A group that exists in the `.newsrc' file, but isn't known to the server (i.e., it isn't in the active file), is a _bogus group_. This means that the group probably doesn't exist (any more). "activating" The act of asking the server for info on a group and computing the number of unread articles is called "activating the group". Un-activated groups are listed with `*' in the group buffer. "server" A machine one can connect to and get news (or mail) from. "select method" A structure that specifies the back end, the server and the virtual server settings. "virtual server" A named select method. Since a select method defines all there is to know about connecting to a (physical) server, taking the thing as a whole is a virtual server. "washing" Taking a buffer and running it through a filter of some sort. The result will (more often than not) be cleaner and more pleasing than the original. "ephemeral groups" Most groups store data on what articles you have read. "Ephemeral" groups are groups that will have no data stored--when you exit the group, it'll disappear into the aether. "solid groups" This is the opposite of ephemeral groups. All groups listed in the group buffer are solid groups. "sparse articles" These are article placeholders shown in the summary buffer when `gnus-build-sparse-threads' has been switched on. "threading" To put responses to articles directly after the articles they respond to--in a hierarchical fashion. "root" The first article in a thread is the root. It is the ancestor of all articles in the thread. "parent" An article that has responses. "child" An article that responds to a different article--its parent. "digest" A collection of messages in one file. The most common digest format is specified by RFC 1153. "splitting" The action of sorting your emails according to certain rules. Sometimes incorrectly called mail filtering.  File: gnus, Node: Customization, Next: Troubleshooting, Prev: Terminology, Up: Appendices Customization ============= All variables are properly documented elsewhere in this manual. This section is designed to give general pointers on how to customize Gnus for some quite common situations. * Menu: * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. * Slow Terminal Connection:: You run a remote Emacs. * Little Disk Space:: You feel that having large setup files is icky. * Slow Machine:: You feel like buying a faster machine.  File: gnus, Node: Slow/Expensive Connection, Next: Slow Terminal Connection, Up: Customization Slow/Expensive NNTP Connection ------------------------------ If you run Emacs on a machine locally, and get your news from a machine over some very thin strings, you want to cut down on the amount of data Gnus has to get from the NNTP server. `gnus-read-active-file' Set this to `nil', which will inhibit Gnus from requesting the entire active file from the server. This file is often v. large. You also have to set `gnus-check-new-newsgroups' and `gnus-check-bogus-newsgroups' to `nil' to make sure that Gnus doesn't suddenly decide to fetch the active file anyway. `gnus-nov-is-evil' This one has to be `nil'. If not, grabbing article headers from the NNTP server will not be very fast. Not all NNTP servers support XOVER; Gnus will detect this by itself.  File: gnus, Node: Slow Terminal Connection, Next: Little Disk Space, Prev: Slow/Expensive Connection, Up: Customization Slow Terminal Connection ------------------------ Let's say you use your home computer for dialing up the system that runs Emacs and Gnus. If your modem is slow, you want to reduce (as much as possible) the amount of data sent over the wires. `gnus-auto-center-summary' Set this to `nil' to inhibit Gnus from re-centering the summary buffer all the time. If it is `vertical', do only vertical re-centering. If it is neither `nil' nor `vertical', do both horizontal and vertical recentering. `gnus-visible-headers' Cut down on the headers included in the articles to the minimum. You can, in fact, make do without them altogether--most of the useful data is in the summary buffer, anyway. Set this variable to `^NEVVVVER' or `From:', or whatever you feel you need. Set this hook to all the available hiding commands: (setq gnus-treat-hide-headers 'head gnus-treat-hide-signature t gnus-treat-hide-citation t) `gnus-use-full-window' By setting this to `nil', you can make all the windows smaller. While this doesn't really cut down much generally, it means that you have to see smaller portions of articles before deciding that you didn't want to read them anyway. `gnus-thread-hide-subtree' If this is non-`nil', all threads in the summary buffer will be hidden initially. `gnus-updated-mode-lines' If this is `nil', Gnus will not put information in the buffer mode lines, which might save some time.  File: gnus, Node: Little Disk Space, Next: Slow Machine, Prev: Slow Terminal Connection, Up: Customization Little Disk Space ----------------- The startup files can get rather large, so you may want to cut their sizes a bit if you are running out of space. `gnus-save-newsrc-file' If this is `nil', Gnus will never save `.newsrc'--it will only save `.newsrc.eld'. This means that you will not be able to use any other newsreaders than Gnus. This variable is `t' by default. `gnus-read-newsrc-file' If this is `nil', Gnus will never read `.newsrc'--it will only read `.newsrc.eld'. This means that you will not be able to use any other newsreaders than Gnus. This variable is `t' by default. `gnus-save-killed-list' If this is `nil', Gnus will not save the list of dead groups. You should also set `gnus-check-new-newsgroups' to `ask-server' and `gnus-check-bogus-newsgroups' to `nil' if you set this variable to `nil'. This variable is `t' by default.  File: gnus, Node: Slow Machine, Prev: Little Disk Space, Up: Customization Slow Machine ------------ If you have a slow machine, or are just really impatient, there are a few things you can do to make Gnus run faster. Set `gnus-check-new-newsgroups' and `gnus-check-bogus-newsgroups' to `nil' to make startup faster. Set `gnus-show-threads', `gnus-use-cross-reference' and `gnus-nov-is-evil' to `nil' to make entering and exiting the summary buffer faster.  File: gnus, Node: Troubleshooting, Next: Gnus Reference Guide, Prev: Customization, Up: Appendices Troubleshooting =============== Gnus works _so_ well straight out of the box--I can't imagine any problems, really. Ahem. 1. Make sure your computer is switched on. 2. Make sure that you really load the current Gnus version. If you have been running GNUS, you need to exit Emacs and start it up again before Gnus will work. 3. Try doing an `M-x gnus-version'. If you get something that looks like `Gnus v5.10.6' you have the right files loaded. Otherwise you have some old `.el' files lying around. Delete these. 4. Read the help group (`G h' in the group buffer) for a FAQ and a how-to. 5. Gnus works on many recursive structures, and in some extreme (and very rare) cases Gnus may recurse down "too deeply" and Emacs will beep at you. If this happens to you, set `max-lisp-eval-depth' to 500 or something like that. If all else fails, report the problem as a bug. If you find a bug in Gnus, you can report it with the `M-x gnus-bug' command. `M-x set-variable RET debug-on-error RET t RET', and send me the backtrace. I will fix bugs, but I can only fix them if you send me a precise description as to how to reproduce the bug. You really can never be too detailed in a bug report. Always use the `M-x gnus-bug' command when you make bug reports, even if it creates a 10Kb mail each time you use it, and even if you have sent me your environment 500 times before. I don't care. I want the full info each time. It is also important to remember that I have no memory whatsoever. If you send a bug report, and I send you a reply, and then you just send back "No, it's not! Moron!", I will have no idea what you are insulting me about. Always over-explain everything. It's much easier for all of us--if I don't have all the information I need, I will just mail you and ask for more info, and everything takes more time. If the problem you're seeing is very visual, and you can't quite explain it, copy the Emacs window to a file (with `xwd', for instance), put it somewhere it can be reached, and include the URL of the picture in the bug report. If you would like to contribute a patch to fix bugs or make improvements, please produce the patch using `diff -u'. If you want to debug your problem further before reporting, possibly in order to solve the problem yourself and send a patch, you can use edebug. Debugging Lisp code is documented in the Elisp manual (*note Debugging Lisp Programs: (elisp)Debugging.). To get you started with edebug, consider if you discover some weird behaviour when pressing `c', the first step is to do `C-h k c' and click on the hyperlink (Emacs only) in the documentation buffer that leads you to the function definition, then press `M-x edebug-defun RET' with point inside that function, return to Gnus and press `c' to invoke the code. You will be placed in the lisp buffer and can single step using `SPC' and evaluate expressions using `M-:' or inspect variables using `C-h v', abort execution with `q', and resume execution with `c' or `g'. Sometimes, a problem do not directly generate an elisp error but manifests itself by causing Gnus to be very slow. In these cases, you can use `M-x toggle-debug-on-quit' and press `C-g' when things are slow, and then try to analyze the backtrace (repeating the procedure helps isolating the real problem areas). A fancier approach is to use the elisp profiler, ELP. The profiler is (or should be) fully documented elsewhere, but to get you started there are a few steps that need to be followed. First, instrument the part of Gnus you are interested in for profiling, e.g. `M-x elp-instrument-package RET gnus' or `M-x elp-instrument-package RET message'. Then perform the operation that is slow and press `M-x elp-results'. You will then see which operations that takes time, and can debug them further. If the entire operation takes much longer than the time spent in the slowest function in the profiler output, you probably profiled the wrong part of Gnus. To reset profiling statistics, use `M-x elp-reset-all'. `M-x elp-restore-all' is supposed to remove profiling, but given the complexities and dynamic code generation in Gnus, it might not always work perfectly. If you just need help, you are better off asking on `gnu.emacs.gnus'. I'm not very helpful. You can also ask on the ding mailing list . Write to to subscribe.  File: gnus, Node: Gnus Reference Guide, Next: Emacs for Heathens, Prev: Troubleshooting, Up: Appendices Gnus Reference Guide ==================== It is my hope that other people will figure out smart stuff that Gnus can do, and that other people will write those smart things as well. To facilitate that I thought it would be a good idea to describe the inner workings of Gnus. And some of the not-so-inner workings, while I'm at it. You can never expect the internals of a program not to change, but I will be defining (in some details) the interface between Gnus and its back ends (this is written in stone), the format of the score files (ditto), data structures (some are less likely to change than others) and general methods of operation. * Menu: * Gnus Utility Functions:: Common functions and variable to use. * Back End Interface:: How Gnus communicates with the servers. * Score File Syntax:: A BNF definition of the score file standard. * Headers:: How Gnus stores headers internally. * Ranges:: A handy format for storing mucho numbers. * Group Info:: The group info format. * Extended Interactive:: Symbolic prefixes and stuff. * Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. * Various File Formats:: Formats of files that Gnus use.  File: gnus, Node: Gnus Utility Functions, Next: Back End Interface, Up: Gnus Reference Guide Gnus Utility Functions ---------------------- When writing small functions to be run from hooks (and stuff), it's vital to have access to the Gnus internal functions and variables. Below is a list of the most common ones. `gnus-newsgroup-name' This variable holds the name of the current newsgroup. `gnus-find-method-for-group' A function that returns the select method for GROUP. `gnus-group-real-name' Takes a full (prefixed) Gnus group name, and returns the unprefixed name. `gnus-group-prefixed-name' Takes an unprefixed group name and a select method, and returns the full (prefixed) Gnus group name. `gnus-get-info' Returns the group info list for GROUP. `gnus-group-unread' The number of unread articles in GROUP, or `t' if that is unknown. `gnus-active' The active entry for GROUP. `gnus-set-active' Set the active entry for GROUP. `gnus-add-current-to-buffer-list' Adds the current buffer to the list of buffers to be killed on Gnus exit. `gnus-continuum-version' Takes a Gnus version string as a parameter and returns a floating point number. Earlier versions will always get a lower number than later versions. `gnus-group-read-only-p' Says whether GROUP is read-only or not. `gnus-news-group-p' Says whether GROUP came from a news back end. `gnus-ephemeral-group-p' Says whether GROUP is ephemeral or not. `gnus-server-to-method' Returns the select method corresponding to SERVER. `gnus-server-equal' Says whether two virtual servers are equal. `gnus-group-native-p' Says whether GROUP is native or not. `gnus-group-secondary-p' Says whether GROUP is secondary or not. `gnus-group-foreign-p' Says whether GROUP is foreign or not. `gnus-group-find-parameter' Returns the parameter list of GROUP. If given a second parameter, returns the value of that parameter for GROUP. `gnus-group-set-parameter' Takes three parameters; GROUP, PARAMETER and VALUE. `gnus-narrow-to-body' Narrows the current buffer to the body of the article. `gnus-check-backend-function' Takes two parameters, FUNCTION and GROUP. If the back end GROUP comes from supports FUNCTION, return non-`nil'. (gnus-check-backend-function "request-scan" "nnml:misc") => t `gnus-read-method' Prompts the user for a select method.  File: gnus, Node: Back End Interface, Next: Score File Syntax, Prev: Gnus Utility Functions, Up: Gnus Reference Guide Back End Interface ------------------ Gnus doesn't know anything about NNTP, spools, mail or virtual groups. It only knows how to talk to "virtual servers". A virtual server is a "back end" and some "back end variables". As examples of the first, we have `nntp', `nnspool' and `nnmbox'. As examples of the latter we have `nntp-port-number' and `nnmbox-directory'. When Gnus asks for information from a back end--say `nntp'--on something, it will normally include a virtual server name in the function parameters. (If not, the back end should use the "current" virtual server.) For instance, `nntp-request-list' takes a virtual server as its only (optional) parameter. If this virtual server hasn't been opened, the function should fail. Note that a virtual server name has no relation to some physical server name. Take this example: (nntp "odd-one" (nntp-address "ifi.uio.no") (nntp-port-number 4324)) Here the virtual server name is `odd-one' while the name of the physical server is `ifi.uio.no'. The back ends should be able to switch between several virtual servers. The standard back ends implement this by keeping an alist of virtual server environments that they pull down/push up when needed. There are two groups of interface functions: "required functions", which must be present, and "optional functions", which Gnus will always check for presence before attempting to call 'em. All these functions are expected to return data in the buffer `nntp-server-buffer' (` *nntpd*'), which is somewhat unfortunately named, but we'll have to live with it. When I talk about "resulting data", I always refer to the data in that buffer. When I talk about "return value", I talk about the function value returned by the function call. Functions that fail should return `nil' as the return value. Some back ends could be said to be "server-forming" back ends, and some might be said not to be. The latter are back ends that generally only operate on one group at a time, and have no concept of "server" --they have a group, and they deliver info on that group and nothing more. Gnus identifies each message by way of group name and article number. A few remarks about these article numbers might be useful. First of all, the numbers are positive integers. Secondly, it is normally not possible for later articles to "re-use" older article numbers without confusing Gnus. That is, if a group has ever contained a message numbered 42, then no other message may get that number, or Gnus will get mightily confused.(1) Third, article numbers must be assigned in order of arrival in the group; this is not necessarily the same as the date of the message. The previous paragraph already mentions all the "hard" restrictions that article numbers must fulfill. But it seems that it might be useful to assign _consecutive_ article numbers, for Gnus gets quite confused if there are holes in the article numbering sequence. However, due to the "no-reuse" restriction, holes cannot be avoided altogether. It's also useful for the article numbers to start at 1 to avoid running out of numbers as long as possible. Note that by convention, back ends are named `nnsomething', but Gnus also comes with some `nnnotbackends', such as `nnheader.el', `nnmail.el' and `nnoo.el'. In the examples and definitions I will refer to the imaginary back end `nnchoke'. * Menu: * Required Back End Functions:: Functions that must be implemented. * Optional Back End Functions:: Functions that need not be implemented. * Error Messaging:: How to get messages and report errors. * Writing New Back Ends:: Extending old back ends. * Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. * Mail-like Back Ends:: Some tips on mail back ends. ---------- Footnotes ---------- (1) See the function `nnchoke-request-update-info', *Note Optional Back End Functions::.