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: Virtual Groups, Next: Kibozed Groups, Up: Combined Groups Virtual Groups -------------- An "nnvirtual group" is really nothing more than a collection of other groups. For instance, if you are tired of reading many small groups, you can put them all in one big group, and then grow tired of reading one big, unwieldy group. The joys of computing! You specify `nnvirtual' as the method. The address should be a regexp to match component groups. All marks in the virtual group will stick to the articles in the component groups. So if you tick an article in a virtual group, the article will also be ticked in the component group from whence it came. (And vice versa--marks from the component groups will also be shown in the virtual group.). To create an empty virtual group, run `G V' (`gnus-group-make-empty-virtual') in the group buffer and edit the method regexp with `M-e' (`gnus-group-edit-group-method') Here's an example `nnvirtual' method that collects all Andrea Dworkin newsgroups into one, big, happy newsgroup: (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") The component groups can be native or foreign; everything should work smoothly, but if your computer explodes, it was probably my fault. Collecting the same group from several servers might actually be a good idea if users have set the Distribution header to limit distribution. If you would like to read `soc.motss' both from a server in Japan and a server in Norway, you could use the following as the group regexp: "^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" (Remember, though, that if you're creating the group with `G m', you shouldn't double the backslashes, and you should leave off the quote characters at the beginning and the end of the string.) This should work kinda smoothly--all articles from both groups should end up in this one, and there should be no duplicates. Threading (and the rest) will still work as usual, but there might be problems with the sequence of articles. Sorting on date might be an option here (*note Selecting a Group::). One limitation, however--all groups included in a virtual group have to be alive (i.e., subscribed or unsubscribed). Killed or zombie groups can't be component groups for `nnvirtual' groups. If the `nnvirtual-always-rescan' is non-`nil', `nnvirtual' will always scan groups for unread articles when entering a virtual group. If this variable is `nil' (which is the default) and you read articles in a component group after the virtual group has been activated, the read articles from the component group will show up when you enter the virtual group. You'll also see this effect if you have two virtual groups that have a component group in common. If that's the case, you should set this variable to `t'. Or you can just tap `M-g' on the virtual group every time before you enter it--it'll have much the same effect. `nnvirtual' can have both mail and news groups as component groups. When responding to articles in `nnvirtual' groups, `nnvirtual' has to ask the back end of the component group the article comes from whether it is a news or mail back end. However, when you do a `^', there is typically no sure way for the component back end to know this, and in that case `nnvirtual' tells Gnus that the article came from a not-news back end. (Just to be on the safe side.) `C-c C-n' in the message buffer will insert the `Newsgroups' line from the article you respond to in these cases. `nnvirtual' groups do not inherit anything but articles and marks from component groups--group parameters, for instance, are not inherited.  File: gnus, Node: Kibozed Groups, Prev: Virtual Groups, Up: Combined Groups Kibozed Groups -------------- "Kibozing" is defined by the OED as "grepping through (parts of) the news feed". `nnkiboze' is a back end that will do this for you. Oh joy! Now you can grind any NNTP server down to a halt with useless requests! Oh happiness! To create a kibozed group, use the `G k' command in the group buffer. The address field of the `nnkiboze' method is, as with `nnvirtual', a regexp to match groups to be "included" in the `nnkiboze' group. That's where most similarities between `nnkiboze' and `nnvirtual' end. In addition to this regexp detailing component groups, an `nnkiboze' group must have a score file to say what articles are to be included in the group (*note Scoring::). You must run `M-x nnkiboze-generate-groups' after creating the `nnkiboze' groups you want to have. This command will take time. Lots of time. Oodles and oodles of time. Gnus has to fetch the headers from all the articles in all the component groups and run them through the scoring process to determine if there are any articles in the groups that are to be part of the `nnkiboze' groups. Please limit the number of component groups by using restrictive regexps. Otherwise your sysadmin may become annoyed with you, and the NNTP site may throw you off and never let you back in again. Stranger things have happened. `nnkiboze' component groups do not have to be alive--they can be dead, and they can be foreign. No restrictions. The generation of an `nnkiboze' group means writing two files in `nnkiboze-directory', which is `~/News/kiboze/' by default. One contains the NOV header lines for all the articles in the group, and the other is an additional `.newsrc' file to store information on what groups have been searched through to find component articles. Articles marked as read in the `nnkiboze' group will have their NOV lines removed from the NOV file.  File: gnus, Node: Gnus Unplugged, Prev: Combined Groups, Up: Select Methods Gnus Unplugged ============== In olden times (ca. February '88), people used to run their newsreaders on big machines with permanent connections to the net. News transport was dealt with by news servers, and all the newsreaders had to do was to read news. Believe it or not. Nowadays most people read news and mail at home, and use some sort of modem to connect to the net. To avoid running up huge phone bills, it would be nice to have a way to slurp down all the news and mail, hang up the phone, read for several hours, and then upload any responses you have to make. And then you repeat the procedure. Of course, you can use news servers for doing this as well. I've used `inn' together with `slurp', `pop' and `sendmail' for some years, but doing that's a bore. Moving the news server functionality up to the newsreader makes sense if you're the only person reading news on a machine. Setting up Gnus as an "offline" newsreader is quite simple. In fact, you don't even have to configure anything. Of course, to use it as such, you have to learn a few new commands. * Menu: * Agent Basics:: How it all is supposed to work. * Agent Categories:: How to tell the Gnus Agent what to download. * Agent Commands:: New commands for all the buffers. * Agent Visuals:: Ways that the agent may effect your summary buffer. * Agent as Cache:: The Agent is a big cache too. * Agent Expiry:: How to make old articles go away. * Agent Regeneration:: How to recover from lost connections and other accidents. * Agent and IMAP:: How to use the Agent with IMAP. * Outgoing Messages:: What happens when you post/mail something? * Agent Variables:: Customizing is fun. * Example Setup:: An example `~/.gnus.el' file for offline people. * Batching Agents:: How to fetch news from a `cron' job. * Agent Caveats:: What you think it'll do and what it does.  File: gnus, Node: Agent Basics, Next: Agent Categories, Up: Gnus Unplugged Agent Basics ------------ First, let's get some terminology out of the way. The Gnus Agent is said to be "unplugged" when you have severed the connection to the net (and notified the Agent that this is the case). When the connection to the net is up again (and Gnus knows this), the Agent is "plugged". The "local" machine is the one you're running on, and which isn't connected to the net continuously. "Downloading" means fetching things from the net to your local machine. "Uploading" is doing the opposite. You know that Gnus gives you all the opportunity you'd ever want for shooting yourself in the foot. Some people call it flexibility. Gnus is also customizable to a great extent, which means that the user has a say on how Gnus behaves. Other newsreaders might unconditionally shoot you in your foot, but with Gnus, you have a choice! Gnus is never really in plugged or unplugged state. Rather, it applies that state to each server individually. This means that some servers can be plugged while others can be unplugged. Additionally, some servers can be ignored by the Agent altogether (which means that they're kinda like plugged always). So when you unplug the Agent and then wonder why is Gnus opening a connection to the Net, the next step to do is to look whether all servers are agentized. If there is an unagentized server, you found the culprit. Another thing is the "offline" state. Sometimes, servers aren't reachable. When Gnus notices this, it asks you whether you want the server to be switched to offline state. If you say yes, then the server will behave somewhat as if it was unplugged, except that Gnus will ask you whether you want to switch it back online again. Let's take a typical Gnus session using the Agent. * You start Gnus with `gnus-unplugged'. This brings up the Gnus Agent in a disconnected state. You can read all the news that you have already fetched while in this mode. * You then decide to see whether any new news has arrived. You connect your machine to the net (using PPP or whatever), and then hit `J j' to make Gnus become "plugged" and use `g' to check for new mail as usual. To check for new mail in unplugged mode (*note Mail Source Specifiers::). * You can then read the new news immediately, or you can download the news onto your local machine. If you want to do the latter, you press `g' to check if there are any new news and then `J s' to fetch all the eligible articles in all the groups. (To let Gnus know which articles you want to download, *note Agent Categories::). * After fetching the articles, you press `J j' to make Gnus become unplugged again, and you shut down the PPP thing (or whatever). And then you read the news offline. * And then you go to step 2. Here are some things you should do the first time (or so) that you use the Agent. * Decide which servers should be covered by the Agent. If you have a mail back end, it would probably be nonsensical to have it covered by the Agent. Go to the server buffer (`^' in the group buffer) and press `J a' on the server (or servers) that you wish to have covered by the Agent (*note Server Agent Commands::), or `J r' on automatically added servers you do not wish to have covered by the Agent. By default, all `nntp' and `nnimap' servers in `gnus-select-method' and `gnus-secondary-select-methods' are agentized. * Decide on download policy. It's fairly simple once you decide whether you are going to use agent categories, topic parameters, and/or group parameters to implement your policy. If you're new to gnus, it is probably best to start with a category, *Note Agent Categories::. Both topic parameters (*note Topic Parameters::) and agent categories (*note Agent Categories::) provide for setting a policy that applies to multiple groups. Which you use is entirely up to you. Topic parameters do override categories so, if you mix the two, you'll have to take that into account. If you have a few groups that deviate from your policy, you can use group parameters (*note Group Parameters::) to configure them. * Uhm... that's it.  File: gnus, Node: Agent Categories, Next: Agent Commands, Prev: Agent Basics, Up: Gnus Unplugged Agent Categories ---------------- One of the main reasons to integrate the news transport layer into the newsreader is to allow greater control over what articles to download. There's not much point in downloading huge amounts of articles, just to find out that you're not interested in reading any of them. It's better to be somewhat more conservative in choosing what to download, and then mark the articles for downloading manually if it should turn out that you're interested in the articles anyway. One of the more effective methods for controlling what is to be downloaded is to create a "category" and then assign some (or all) groups to this category. Groups that do not belong in any other category belong to the `default' category. Gnus has its own buffer for creating and managing categories. If you prefer, you can also use group parameters (*note Group Parameters::) and topic parameters (*note Topic Parameters::) for an alternative approach to controlling the agent. The only real difference is that categories are specific to the agent (so there is less to learn) while group and topic parameters include the kitchen sink. Since you can set agent parameters in several different places we have a rule to decide which source to believe. This rule specifies that the parameter sources are checked in the following order: group parameters, topic parameters, agent category, and finally customizable variables. So you can mix all of these sources to produce a wide range of behavior, just don't blame me if you don't remember where you put your settings. * Menu: * Category Syntax:: What a category looks like. * Category Buffer:: A buffer for maintaining categories. * Category Variables:: Customize'r'Us.  File: gnus, Node: Category Syntax, Next: Category Buffer, Up: Agent Categories Category Syntax ............... A category consists of a name, the list of groups belonging to the category, and a number of optional parameters that override the customizable variables. The complete list of agent parameters are listed below. `gnus-agent-cat-name' The name of the category. `gnus-agent-cat-groups' The list of groups that are in this category. `gnus-agent-cat-predicate' A predicate which (generally) gives a rough outline of which articles are eligible for downloading; and `gnus-agent-cat-score-file' a score rule which (generally) gives you a finer granularity when deciding what articles to download. (Note that this "download score" is not necessarily related to normal scores.) `gnus-agent-cat-enable-expiration' a boolean indicating whether the agent should expire old articles in this group. Most groups should be expired to conserve disk space. In fact, its probably safe to say that the gnus.* hierarchy contains the only groups that should not be expired. `gnus-agent-cat-days-until-old' an integer indicating the number of days that the agent should wait before deciding that a read article is safe to expire. `gnus-agent-cat-low-score' an integer that overrides the value of `gnus-agent-low-score'. `gnus-agent-cat-high-score' an integer that overrides the value of `gnus-agent-high-score'. `gnus-agent-cat-length-when-short' an integer that overrides the value of `gnus-agent-short-article'. `gnus-agent-cat-length-when-long' an integer that overrides the value of `gnus-agent-long-article'. The name of a category can not be changed once the category has been created. Each category maintains a list of groups that are exclusive members of that category. The exclusivity rule is automatically enforced, add a group to a new category and it is automatically removed from its old category. A predicate in its simplest form can be a single predicate such as `true' or `false'. These two will download every available article or nothing respectively. In the case of these two special predicates an additional score rule is superfluous. Predicates of `high' or `low' download articles in respect of their scores in relationship to `gnus-agent-high-score' and `gnus-agent-low-score' as described below. To gain even finer control of what is to be regarded eligible for download a predicate can consist of a number of predicates with logical operators sprinkled in between. Perhaps some examples are in order. Here's a simple predicate. (It's the default predicate, in fact, used for all groups that don't belong to any other category.) short Quite simple, eh? This predicate is true if and only if the article is short (for some value of "short"). Here's a more complex predicate: (or high (and (not low) (not long))) This means that an article should be downloaded if it has a high score, or if the score is not low and the article is not long. You get the drift. The available logical operators are `or', `and' and `not'. (If you prefer, you can use the more "C"-ish operators `|', `&' and `!' instead.) The following predicates are pre-defined, but if none of these fit what you want to do, you can write your own. When evaluating each of these predicates, the named constant will be bound to the value determined by calling `gnus-agent-find-parameter' on the appropriate parameter. For example, gnus-agent-short-article will be bound to `(gnus-agent-find-parameter group 'agent-short-article)'. This means that you can specify a predicate in your category then tune that predicate to individual groups. `short' True iff the article is shorter than `gnus-agent-short-article' lines; default 100. `long' True iff the article is longer than `gnus-agent-long-article' lines; default 200. `low' True iff the article has a download score less than `gnus-agent-low-score'; default 0. `high' True iff the article has a download score greater than `gnus-agent-high-score'; default 0. `spam' True iff the Gnus Agent guesses that the article is spam. The heuristics may change over time, but at present it just computes a checksum and sees whether articles match. `true' Always true. `false' Always false. If you want to create your own predicate function, here's what you have to know: The functions are called with no parameters, but the `gnus-headers' and `gnus-score' dynamic variables are bound to useful values. For example, you could decide that you don't want to download articles that were posted more than a certain number of days ago (e.g. posted more than `gnus-agent-expire-days' ago) you might write a function something along the lines of the following: (defun my-article-old-p () "Say whether an article is old." (< (time-to-days (date-to-time (mail-header-date gnus-headers))) (- (time-to-days (current-time)) gnus-agent-expire-days))) with the predicate then defined as: (not my-article-old-p) or you could append your predicate to the predefined `gnus-category-predicate-alist' in your `~/.gnus.el' or wherever. (require 'gnus-agent) (setq gnus-category-predicate-alist (append gnus-category-predicate-alist '((old . my-article-old-p)))) and simply specify your predicate as: (not old) If/when using something like the above, be aware that there are many misconfigured systems/mailers out there and so an article's date is not always a reliable indication of when it was posted. Hell, some people just don't give a damn. The above predicates apply to _all_ the groups which belong to the category. However, if you wish to have a specific predicate for an individual group within a category, or you're just too lazy to set up a new category, you can enter a group's individual predicate in its group parameters like so: (agent-predicate . short) This is the group/topic parameter equivalent of the agent category default. Note that when specifying a single word predicate like this, the `agent-predicate' specification must be in dotted pair notation. The equivalent of the longer example from above would be: (agent-predicate or high (and (not low) (not long))) The outer parenthesis required in the category specification are not entered here as, not being in dotted pair notation, the value of the predicate is assumed to be a list. Now, the syntax of the download score is the same as the syntax of normal score files, except that all elements that require actually seeing the article itself are verboten. This means that only the following headers can be scored on: `Subject', `From', `Date', `Message-ID', `References', `Chars', `Lines', and `Xref'. As with predicates, the specification of the `download score rule' to use in respect of a group can be in either the category definition if it's to be applicable to all groups in therein, or a group's parameters if it's to be specific to that group. In both of these places the `download score rule' can take one of three forms: 1. Score rule This has the same syntax as a normal gnus score file except only a subset of scoring keywords are available as mentioned above. example: * Category specification (("from" ("Lars Ingebrigtsen" 1000000 nil s)) ("lines" (500 -100 nil <))) * Group/Topic Parameter specification (agent-score ("from" ("Lars Ingebrigtsen" 1000000 nil s)) ("lines" (500 -100 nil <))) Again, note the omission of the outermost parenthesis here. 2. Agent score file These score files must _only_ contain the permitted scoring keywords stated above. example: * Category specification ("~/News/agent.SCORE") or perhaps ("~/News/agent.SCORE" "~/News/agent.group.SCORE") * Group Parameter specification (agent-score "~/News/agent.SCORE") Additional score files can be specified as above. Need I say anything about parenthesis? 3. Use `normal' score files If you don't want to maintain two sets of scoring rules for a group, and your desired `downloading' criteria for a group are the same as your `reading' criteria then you can tell the agent to refer to your `normal' score files when deciding what to download. These directives in either the category definition or a group's parameters will cause the agent to read in all the applicable score files for a group, _filtering out_ those sections that do not relate to one of the permitted subset of scoring keywords. * Category Specification file * Group Parameter specification (agent-score . file)  File: gnus, Node: Category Buffer, Next: Category Variables, Prev: Category Syntax, Up: Agent Categories Category Buffer ............... You'd normally do all category maintenance from the category buffer. When you enter it for the first time (with the `J c' command from the group buffer), you'll only see the `default' category. The following commands are available in this buffer: `q' Return to the group buffer (`gnus-category-exit'). `e' Use a customization buffer to set all of the selected category's parameters at one time (`gnus-category-customize-category'). `k' Kill the current category (`gnus-category-kill'). `c' Copy the current category (`gnus-category-copy'). `a' Add a new category (`gnus-category-add'). `p' Edit the predicate of the current category (`gnus-category-edit-predicate'). `g' Edit the list of groups belonging to the current category (`gnus-category-edit-groups'). `s' Edit the download score rule of the current category (`gnus-category-edit-score'). `l' List all the categories (`gnus-category-list').  File: gnus, Node: Category Variables, Prev: Category Buffer, Up: Agent Categories Category Variables .................. `gnus-category-mode-hook' Hook run in category buffers. `gnus-category-line-format' Format of the lines in the category buffer (*note Formatting Variables::). Valid elements are: `c' The name of the category. `g' The number of groups in the category. `gnus-category-mode-line-format' Format of the category mode line (*note Mode Line Formatting::). `gnus-agent-short-article' Articles that have fewer lines than this are short. Default 100. `gnus-agent-long-article' Articles that have more lines than this are long. Default 200. `gnus-agent-low-score' Articles that have a score lower than this have a low score. Default 0. `gnus-agent-high-score' Articles that have a score higher than this have a high score. Default 0. `gnus-agent-expire-days' The number of days that a `read' article must stay in the agent's local disk before becoming eligible for expiration (While the name is the same, this doesn't mean expiring the article on the server. It just means deleting the local copy of the article). What is also important to understand is that the counter starts with the time the article was written to the local disk and not the time the article was read. Default 7. `gnus-agent-enable-expiration' Determines whether articles in a group are, by default, expired or retained indefinitely. The default is `ENABLE' which means that you'll have to disable expiration when desired. On the other hand, you could set this to `DISABLE'. In that case, you would then have to enable expiration in selected groups.  File: gnus, Node: Agent Commands, Next: Agent Visuals, Prev: Agent Categories, Up: Gnus Unplugged Agent Commands -------------- All the Gnus Agent commands are on the `J' submap. The `J j' (`gnus-agent-toggle-plugged') command works in all modes, and toggles the plugged/unplugged state of the Gnus Agent. * Menu: * Group Agent Commands:: Configure groups and fetch their contents. * Summary Agent Commands:: Manually select then fetch specific articles. * Server Agent Commands:: Select the servers that are supported by the agent.  File: gnus, Node: Group Agent Commands, Next: Summary Agent Commands, Up: Agent Commands Group Agent Commands .................... `J u' Fetch all eligible articles in the current group (`gnus-agent-fetch-groups'). `J c' Enter the Agent category buffer (`gnus-enter-category-buffer'). `J s' Fetch all eligible articles in all groups (`gnus-agent-fetch-session'). `J S' Send all sendable messages in the queue group (`gnus-group-send-queue'). *Note Drafts::. `J a' Add the current group to an Agent category (`gnus-agent-add-group'). This command understands the process/prefix convention (*note Process/Prefix::). `J r' Remove the current group from its category, if any (`gnus-agent-remove-group'). This command understands the process/prefix convention (*note Process/Prefix::). `J Y' Synchronize flags changed while unplugged with remote server, if any.  File: gnus, Node: Summary Agent Commands, Next: Server Agent Commands, Prev: Group Agent Commands, Up: Agent Commands Summary Agent Commands ...................... `J #' Mark the article for downloading (`gnus-agent-mark-article'). `J M-#' Remove the downloading mark from the article (`gnus-agent-unmark-article'). `@' Toggle whether to download the article (`gnus-agent-toggle-mark'). The download mark is `%' by default. `J c' Mark all articles as read (`gnus-agent-catchup') that are neither cached, downloaded, nor downloadable. `J S' Download all eligible (*note Agent Categories::) articles in this group. (`gnus-agent-fetch-group'). `J s' Download all processable articles in this group. (`gnus-agent-fetch-series'). `J u' Download all downloadable articles in the current group (`gnus-agent-summary-fetch-group').  File: gnus, Node: Server Agent Commands, Prev: Summary Agent Commands, Up: Agent Commands Server Agent Commands ..................... `J a' Add the current server to the list of servers covered by the Gnus Agent (`gnus-agent-add-server'). `J r' Remove the current server from the list of servers covered by the Gnus Agent (`gnus-agent-remove-server').  File: gnus, Node: Agent Visuals, Next: Agent as Cache, Prev: Agent Commands, Up: Gnus Unplugged Agent Visuals ------------- If you open a summary while unplugged and, Gnus knows from the group's active range that there are more articles than the headers currently stored in the Agent, you may see some articles whose subject looks something like `[Undownloaded article #####]'. These are placeholders for the missing headers. Aside from setting a mark, there is not much that can be done with one of these placeholders. When Gnus finally gets a chance to fetch the group's headers, the placeholders will automatically be replaced by the actual headers. You can configure the summary buffer's maneuvering to skip over the placeholders if you care (See `gnus-auto-goto-ignores'). While it may be obvious to all, the only headers and articles available while unplugged are those headers and articles that were fetched into the Agent while previously plugged. To put it another way, "If you forget to fetch something while plugged, you might have a less than satisfying unplugged session". For this reason, the Agent adds two visual effects to your summary buffer. These effects display the download status of each article so that you always know which articles will be available when unplugged. The first visual effect is the `%O' spec. If you customize `gnus-summary-line-format' to include this specifier, you will add a single character field that indicates an article's download status. Articles that have been fetched into either the Agent or the Cache, will display `gnus-downloaded-mark' (defaults to `+'). All other articles will display `gnus-undownloaded-mark' (defaults to `-'). If you open a group that has not been agentized, a space (` ') will be displayed. The second visual effect are the undownloaded faces. The faces, there are three indicating the article's score (low, normal, high), seem to result in a love/hate response from many Gnus users. The problem is that the face selection is controlled by a list of condition tests and face names (See `gnus-summary-highlight'). Each condition is tested in the order in which it appears in the list so early conditions have precedence over later conditions. All of this means that, if you tick an undownloaded article, the article will continue to be displayed in the undownloaded face rather than the ticked face. If you use the Agent as a cache (to avoid downloading the same article each time you visit it or to minimize your connection time), the undownloaded face will probably seem like a good idea. The reason being that you do all of our work (marking, reading, deleting) with downloaded articles so the normal faces always appear. For occasional Agent users, the undownloaded faces may appear to be an absolutely horrible idea. The issue being that, since most of their articles have not been fetched into the Agent, most of the normal faces will be obscured by the undownloaded faces. If this is your situation, you have two choices available. First, you can completely disable the undownload faces by customizing `gnus-summary-highlight' to delete the three cons-cells that refer to the `gnus-summary-*-undownloaded-face' faces. Second, if you prefer to take a more fine-grained approach, you may set the `agent-disable-undownloaded-faces' group parameter to t. This parameter, like all other agent parameters, may be set on an Agent Category (*note Agent Categories::), a Group Topic (*note Topic Parameters::), or an individual group (*note Group Parameters::).  File: gnus, Node: Agent as Cache, Next: Agent Expiry, Prev: Agent Visuals, Up: Gnus Unplugged Agent as Cache -------------- When Gnus is plugged, it is not efficient to download headers or articles from the server again, if they are already stored in the Agent. So, Gnus normally only downloads headers once, and stores them in the Agent. These headers are later used when generating the summary buffer, regardless of whether you are plugged or unplugged. Articles are not cached in the Agent by default though (that would potentially consume lots of disk space), but if you have already downloaded an article into the Agent, Gnus will not download the article from the server again but use the locally stored copy instead. If you so desire, you can configure the agent (see `gnus-agent-cache' *note Agent Variables::) to always download headers and articles while plugged. Gnus will almost certainly be slower, but it will be kept synchronized with the server. That last point probably won't make any sense if you are using a nntp or nnimap back end.  File: gnus, Node: Agent Expiry, Next: Agent Regeneration, Prev: Agent as Cache, Up: Gnus Unplugged Agent Expiry ------------ The Agent back end, `nnagent', doesn't handle expiry. Well, at least it doesn't handle it like other back ends. Instead, there are special `gnus-agent-expire' and `gnus-agent-expire-group' commands that will expire all read articles that are older than `gnus-agent-expire-days' days. They can be run whenever you feel that you're running out of space. Neither are particularly fast or efficient, and it's not a particularly good idea to interrupt them (with `C-g' or anything else) once you've started one of them. Note that other functions, e.g. `gnus-request-expire-articles', might run `gnus-agent-expire' for you to keep the agent synchronized with the group. The agent parameter `agent-enable-expiration' may be used to prevent expiration in selected groups. If `gnus-agent-expire-all' is non-`nil', the agent expiration commands will expire all articles--unread, read, ticked and dormant. If `nil' (which is the default), only read articles are eligible for expiry, and unread, ticked and dormant articles will be kept indefinitely. If you find that some articles eligible for expiry are never expired, perhaps some Gnus Agent files are corrupted. There's are special commands, `gnus-agent-regenerate' and `gnus-agent-regenerate-group', to fix possible problems.  File: gnus, Node: Agent Regeneration, Next: Agent and IMAP, Prev: Agent Expiry, Up: Gnus Unplugged Agent Regeneration ------------------ The local data structures used by `nnagent' may become corrupted due to certain exceptional conditions. When this happens, `nnagent' functionality may degrade or even fail. The solution to this problem is to repair the local data structures by removing all internal inconsistencies. For example, if your connection to your server is lost while downloaded articles into the agent, the local data structures will not know about articles successfully downloaded prior to the connection failure. Running `gnus-agent-regenerate' or `gnus-agent-regenerate-group' will update the data structures such that you don't need to download these articles a second time. The command `gnus-agent-regenerate' will perform `gnus-agent-regenerate-group' on every agentized group. While you can run `gnus-agent-regenerate' in any buffer, it is strongly recommended that you first close all summary buffers. The command `gnus-agent-regenerate-group' uses the local copies of individual articles to repair the local NOV(header) database. It then updates the internal data structures that document which articles are stored locally. An optional argument will mark articles in the agent as unread.  File: gnus, Node: Agent and IMAP, Next: Outgoing Messages, Prev: Agent Regeneration, Up: Gnus Unplugged Agent and IMAP -------------- The Agent works with any Gnus back end, including nnimap. However, since there are some conceptual differences between NNTP and IMAP, this section (should) provide you with some information to make Gnus Agent work smoother as a IMAP Disconnected Mode client. The first thing to keep in mind is that all flags (read, ticked, etc) are kept on the IMAP server, rather than in `.newsrc' as is the case for nntp. Thus Gnus need to remember flag changes when disconnected, and synchronize these flags when you plug back in. Gnus keeps track of flag changes when reading nnimap groups under the Agent. When you plug back in, Gnus will check if you have any changed any flags and ask if you wish to synchronize these with the server. The behavior is customizable by `gnus-agent-synchronize-flags'. If `gnus-agent-synchronize-flags' is `nil', the Agent will never automatically synchronize flags. If it is `ask', which is the default, the Agent will check if you made any changes and if so ask if you wish to synchronize these when you re-connect. If it has any other value, all flags will be synchronized automatically. If you do not wish to synchronize flags automatically when you re-connect, you can do it manually with the `gnus-agent-synchronize-flags' command that is bound to `J Y' in the group buffer. Some things are currently not implemented in the Agent that you'd might expect from a disconnected IMAP client, including: * Copying/moving articles into nnimap groups when unplugged. * Creating/deleting nnimap groups when unplugged. Technical note: the synchronization algorithm does not work by "pushing" all local flags to the server, but rather incrementally update the server view of flags by changing only those flags that were changed by the user. Thus, if you set one flag on an article, quit the group and re-select the group and remove the flag; the flag will be set and removed from the server when you "synchronize". The queued flag operations can be found in the per-server `flags' file in the Agent directory. It's emptied when you synchronize flags.  File: gnus, Node: Outgoing Messages, Next: Agent Variables, Prev: Agent and IMAP, Up: Gnus Unplugged Outgoing Messages ----------------- When Gnus is unplugged, all outgoing messages (both mail and news) are stored in the draft group "queue" (*note Drafts::). You can view them there after posting, and edit them at will. When Gnus is plugged again, you can send the messages either from the draft group with the special commands available there, or you can use the `J S' command in the group buffer to send all the sendable messages in the draft group.  File: gnus, Node: Agent Variables, Next: Example Setup, Prev: Outgoing Messages, Up: Gnus Unplugged Agent Variables --------------- `gnus-agent-directory' Where the Gnus Agent will store its files. The default is `~/News/agent/'. `gnus-agent-handle-level' Groups on levels (*note Group Levels::) higher than this variable will be ignored by the Agent. The default is `gnus-level-subscribed', which means that only subscribed group will be considered by the Agent by default. `gnus-agent-plugged-hook' Hook run when connecting to the network. `gnus-agent-unplugged-hook' Hook run when disconnecting from the network. `gnus-agent-fetched-hook' Hook run when finished fetching articles. `gnus-agent-cache' Variable to control whether use the locally stored NOV and articles when plugged, e.g. essentially using the Agent as a cache. The default is non-`nil', which means to use the Agent as a cache. `gnus-agent-go-online' If `gnus-agent-go-online' is `nil', the Agent will never automatically switch offline servers into online status. If it is `ask', the default, the Agent will ask if you wish to switch offline servers into online status when you re-connect. If it has any other value, all offline servers will be automatically switched into online status. `gnus-agent-mark-unread-after-downloaded' If `gnus-agent-mark-unread-after-downloaded' is non-`nil', mark articles as unread after downloading. This is usually a safe thing to do as the newly downloaded article has obviously not been read. The default is t. `gnus-agent-consider-all-articles' If `gnus-agent-consider-all-articles' is non-`nil', the agent will fetch all missing headers. When `nil', the agent will fetch only new headers. The default is `nil'. `gnus-agent-max-fetch-size' The agent fetches articles into a temporary buffer prior to parsing them into individual files. To avoid exceeding the max. buffer size, the agent alternates between fetching and parsing until all articles have been fetched. `gnus-agent-max-fetch-size' provides a size limit to control how often the cycling occurs. A large value improves performance. A small value minimizes the time lost should the connection be lost while fetching (You may need to run `gnus-agent-regenerate-group' to update the group's state. However, all articles parsed prior to loosing the connection will be available while unplugged). The default is 10M so it is unusual to see any cycling. `gnus-server-unopen-status' Perhaps not an Agent variable, but closely related to the Agent, this variable says what will happen if Gnus cannot open a server. If the Agent is enabled, the default, `nil', makes Gnus ask the user whether to deny the server or whether to unplug the agent. If the Agent is disabled, Gnus always simply deny the server. Other choices for this variable include `denied' and `offline' the latter is only valid if the Agent is used. `gnus-auto-goto-ignores' Another variable that isn't an Agent variable, yet so closely related that most will look for it here, this variable tells the summary buffer how to maneuver around undownloaded (only headers stored in the agent) and unfetched (neither article nor headers stored) articles. The legal values are `nil' (maneuver to any article), `undownloaded' (maneuvering while unplugged ignores articles that have not been fetched), `always-undownloaded' (maneuvering always ignores articles that have not been fetched), `unfetched' (maneuvering ignores articles whose headers have not been fetched).  File: gnus, Node: Example Setup, Next: Batching Agents, Prev: Agent Variables, Up: Gnus Unplugged Example Setup ------------- If you don't want to read this manual, and you have a fairly standard setup, you may be able to use something like the following as your `~/.gnus.el' file to get started. ;;; Define how Gnus is to fetch news. We do this over NNTP ;;; from your ISP's server. (setq gnus-select-method '(nntp "news.your-isp.com")) ;;; Define how Gnus is to read your mail. We read mail from ;;; your ISP's POP server. (setq mail-sources '((pop :server "pop.your-isp.com"))) ;;; Say how Gnus is to store the mail. We use nnml groups. (setq gnus-secondary-select-methods '((nnml ""))) ;;; Make Gnus into an offline newsreader. ;;; (gnus-agentize) ; The obsolete setting. ;;; (setq gnus-agent t) ; Now the default. That should be it, basically. Put that in your `~/.gnus.el' file, edit to suit your needs, start up PPP (or whatever), and type `M-x gnus'. If this is the first time you've run Gnus, you will be subscribed automatically to a few default newsgroups. You'll probably want to subscribe to more groups, and to do that, you have to query the NNTP server for a complete list of groups with the `A A' command. This usually takes quite a while, but you only have to do it once. After reading and parsing a while, you'll be presented with a list of groups. Subscribe to the ones you want to read with the `u' command. `l' to make all the killed groups disappear after you've subscribe to all the groups you want to read. (`A k' will bring back all the killed groups.) You can now read the groups at once, or you can download the articles with the `J s' command. And then read the rest of this manual to find out which of the other gazillion things you want to customize.  File: gnus, Node: Batching Agents, Next: Agent Caveats, Prev: Example Setup, Up: Gnus Unplugged Batching Agents --------------- Having the Gnus Agent fetch articles (and post whatever messages you've written) is quite easy once you've gotten things set up properly. The following shell script will do everything that is necessary: You can run a complete batch command from the command line with the following incantation: #!/bin/sh emacs -batch -l ~/.emacs -f -l ~/.gnus.el gnus-agent-batch >/dev/null 2>&1  File: gnus, Node: Agent Caveats, Prev: Batching Agents, Up: Gnus Unplugged Agent Caveats ------------- The Gnus Agent doesn't seem to work like most other offline newsreaders. Here are some common questions that some imaginary people may ask: "If I read an article while plugged, do they get entered into the Agent?" *No*. If you want this behaviour, add `gnus-agent-fetch-selected-article' to `gnus-select-article-hook'. "If I read an article while plugged, and the article already exists in" the Agent, will it get downloaded once more? *No*, unless `gnus-agent-cache' is `nil'. In short, when Gnus is unplugged, it only looks into the locally stored articles; when it's plugged, it talks to your ISP and may also use the locally stored articles.  File: gnus, Node: Scoring, Next: Various, Prev: Select Methods, Up: Top Scoring ******* Other people use "kill files", but we here at Gnus Towers like scoring better than killing, so we'd rather switch than fight. They do something completely different as well, so sit up straight and pay attention! All articles have a default score (`gnus-summary-default-score'), which is 0 by default. This score may be raised or lowered either interactively or by score files. Articles that have a score lower than `gnus-summary-mark-below' are marked as read. Gnus will read any "score files" that apply to the current group before generating the summary buffer. There are several commands in the summary buffer that insert score entries based on the current article. You can, for instance, ask Gnus to lower or increase the score of all articles with a certain subject. There are two sorts of scoring entries: Permanent and temporary. Temporary score entries are self-expiring entries. Any entries that are temporary and have not been used for, say, a week, will be removed silently to help keep the sizes of the score files down. * Menu: * Summary Score Commands:: Adding score entries for the current group. * Group Score Commands:: General score commands. * Score Variables:: Customize your scoring. (My, what terminology). * Score File Format:: What a score file may contain. * Score File Editing:: You can edit score files by hand as well. * Adaptive Scoring:: Big Sister Gnus knows what you read. * Home Score File:: How to say where new score entries are to go. * Followups To Yourself:: Having Gnus notice when people answer you. * Scoring On Other Headers:: Scoring on non-standard headers. * Scoring Tips:: How to score effectively. * Reverse Scoring:: That problem child of old is not problem. * Global Score Files:: Earth-spanning, ear-splitting score files. * Kill Files:: They are still here, but they can be ignored. * Converting Kill Files:: Translating kill files to score files. * GroupLens:: Getting predictions on what you like to read. * Advanced Scoring:: Using logical expressions to build score rules. * Score Decays:: It can be useful to let scores wither away.