6.9 Gnus Unplugged

In olden times (ca. February ’88), people used to run their newsreaders on big machines with permanent connections to the net. News transport was dealt with by news servers, and all the newsreaders had to do was to read news. Believe it or not.

Nowadays most people read news and mail at home, and use some sort of modem to connect to the net. To avoid running up huge phone bills, it would be nice to have a way to slurp down all the news and mail, hang up the phone, read for several hours, and then upload any responses you have to make. And then you repeat the procedure.

Of course, you can use news servers for doing this as well. I’ve used inn together with slurp, pop and sendmail for some years, but doing that’s a bore. Moving the news server functionality up to the newsreader makes sense if you’re the only person reading news on a machine.

Setting up Gnus as an “offline” newsreader is quite simple. In fact, you don’t have to configure anything as the agent is now enabled by default (see section gnus-agent).

Of course, to use it as such, you have to learn a few new commands.

6.9.1 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 (see section 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, see section 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 (see section Server Agent Commands), or J r on automatically added servers you do not wish to have covered by the Agent. By default, no servers 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, See section Agent Categories.

  Both topic parameters (see section Topic Parameters) and agent categories (see section 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 (see section Group Parameters) to configure them.

• Uhm… that’s it.

6.9.2 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 (see section Group Parameters) and topic parameters (see section 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.

6.9.2.1 Category Syntax

A category consists of a name, the list of groups belonging to the category, and a number of optional parameters that override the customizable variables. The complete list of agent parameters are listed below.

agent-groups

The list of groups that are in this category.

agent-predicate

A predicate which (generally) gives a rough outline of which articles are eligible for downloading; and

agent-score

a score rule which (generally) gives you a finer granularity when deciding what articles to download. (Note that this download score is not necessarily related to normal scores.)

agent-enable-expiration

a boolean indicating whether the agent should expire old articles in this group. Most groups should be expired to conserve disk space. In fact, its probably safe to say that the gnus.* hierarchy contains the only groups that should not be expired.

agent-days-until-old

an integer indicating the number of days that the agent should wait before deciding that a read article is safe to expire.

agent-low-score

an integer that overrides the value of gnus-agent-low-score.

agent-high-score

an integer that overrides the value of gnus-agent-high-score.

agent-short-article

an integer that overrides the value of gnus-agent-short-article.

agent-long-article

an integer that overrides the value of gnus-agent-long-article.

agent-enable-undownloaded-faces

a symbol indicating whether the summary buffer should display undownloaded articles using the gnus-summary-*-undownloaded-face faces. Any symbol other than nil will enable the use of undownloaded faces.

The name of a category can not be changed once the category has been created.

Each category maintains a list of groups that are exclusive members of that category. The exclusivity rule is automatically enforced, add a group to a new category and it is automatically removed from its old category.

A predicate in its simplest form can be a single predicate such as true or false. These two will download every available article or nothing respectively. In the case of these two special predicates an additional score rule is superfluous.

Predicates of high or low download articles in respect of their scores in relationship to gnus-agent-high-score and gnus-agent-low-score as described below.

To gain even finer control of what is to be regarded eligible for download a predicate can consist of a number of predicates with logical operators sprinkled in between.

Perhaps some examples are in order.

Here’s a simple predicate. (It’s the default predicate, in fact, used for all groups that don’t belong to any other category.)

short

Quite simple, eh? This predicate is true if and only if the article is short (for some value of “short”).

Here’s a more complex predicate:

(or high
    (and
     (not low)
     (not long)))

This means that an article should be downloaded if it has a high score, or if the score is not low and the article is not long. You get the drift.

The available logical operators are or, and and not. (If you prefer, you can use the more “C”-ish operators ‘|’, & and ! instead.)

The following predicates are pre-defined, but if none of these fit what you want to do, you can write your own.

When evaluating each of these predicates, the named constant will be bound to the value determined by calling gnus-agent-find-parameter on the appropriate parameter. For example, gnus-agent-short-article will be bound to (gnus-agent-find-parameter group 'agent-short-article). This means that you can specify a predicate in your category then tune that predicate to individual groups.

short

True if the article is shorter than gnus-agent-short-article lines; default 100.

long

True if the article is longer than gnus-agent-long-article lines; default 200.

low

True if the article has a download score less than gnus-agent-low-score; default 0.

high

True if the article has a download score greater than gnus-agent-high-score; default 0.

spam

True if 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)

6.9.2.2 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).

6.9.2.3 Category Variables

gnus-category-mode-hook

Hook run in category buffers.

gnus-category-line-format

Format of the lines in the category buffer (see section 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 (see section 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.

6.9.3 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.

6.9.3.1 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). See section Drafts.

J a

Add the current group to an Agent category (gnus-agent-add-group). This command understands the process/prefix convention (see section Process/Prefix).

J r

Remove the current group from its category, if any (gnus-agent-remove-group). This command understands the process/prefix convention (see section Process/Prefix).

J Y

Synchronize flags changed while unplugged with remote server, if any.

6.9.3.2 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 (see section Agent Categories) articles in this group. (gnus-agent-fetch-group).

J s

Download all processable articles in this group. (gnus-agent-summary-fetch-series).

J u

Download all downloadable articles in the current group (gnus-agent-summary-fetch-group).

6.9.3.3 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).

6.9.4 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 those users using the agent to improve online performance by caching the NOV database (most users since 5.10.2), the undownloaded faces may appear to be an absolutely horrible idea. The issue being that, since none of their articles have been fetched into the Agent, all of the normal faces will be obscured by the undownloaded faces.

If you would like to use the undownloaded faces, you must enable the undownloaded faces by setting the agent-enable-undownloaded-faces group parameter to t. This parameter, like all other agent parameters, may be set on an Agent Category (see section Agent Categories), a Group Topic (see section Topic Parameters), or an individual group (see section Group Parameters).

The one problem common to all users using the agent is how quickly it can consume disk space. If you using the agent on many groups, it is even more difficult to effectively recover disk space. One solution is the ‘%F’ format available in gnus-group-line-format. This format will display the actual disk space used by articles fetched into both the agent and cache. By knowing which groups use the most space, users know where to focus their efforts when “agent expiring” articles.

6.9.5 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 see section 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.

6.9.6 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 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.

6.9.7 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.

6.9.8 Agent and flags

The Agent works with any Gnus back end including those, such as nnimap, that store flags (read, ticked, etc.) on the server. Sadly, the Agent does not actually know which backends keep their flags in the backend server rather than in ‘.newsrc’. This means that the Agent, while unplugged or disconnected, will always record all changes to the flags in its own files.

When you plug back in, Gnus will then check to see if you have any changed any flags and ask if you wish to synchronize these with the server. This 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.

Technical note: the synchronization algorithm does not work by “pushing” all local flags to the server, but rather by incrementally updated 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 then 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.

6.9.9 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.

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.

6.9.10 Outgoing Messages

By default, when Gnus is unplugged, all outgoing messages (both mail and news) are stored in the draft group “queue” (see section Drafts). You can view them there after posting, and edit them at will.

You can control the circumstances under which outgoing mail is queued (see gnus-agent-queue-mail, see section Agent Variables). Outgoing news is always queued when Gnus is unplugged, and never otherwise.

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. Posting news will only work when Gnus is plugged, but you can send mail at any time.

If sending mail while unplugged does not work for you and you worry about hitting J S by accident when unplugged, you can have Gnus ask you to confirm your action (see gnus-agent-prompt-send-queue, see section Agent Variables).

6.9.11 Agent Variables

gnus-agent

Is the agent enabled? The default is t. When first enabled, the agent will use gnus-agent-auto-agentize-methods to automatically mark some back ends as agentized. You may change which back ends are agentized using the agent commands in the server buffer.

To enter the server buffer, use the ^ (gnus-group-enter-server-mode) command in the group buffer.

gnus-agent-directory

Where the Gnus Agent will store its files. The default is ‘~/News/agent/’.

gnus-agent-handle-level

Groups on levels (see section 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-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.

gnus-agent-consider-all-articles

If gnus-agent-consider-all-articles is non-nil, the agent will let the agent predicate decide whether articles need to be downloaded or not, for all articles. When nil, the default, the agent will only let the predicate decide whether unread articles are downloaded or not. If you enable this, you may also want to look into the agent expiry settings (see section Category Variables), so that the agent doesn’t download articles which the agent will later expire, over and over again.

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 losing 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 valid 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).

gnus-agent-queue-mail

When gnus-agent-queue-mail is always, Gnus will always queue mail rather than sending it straight away. When t, Gnus will queue mail when unplugged only. When nil, never queue mail. The default is t.

gnus-agent-prompt-send-queue

When gnus-agent-prompt-send-queue is non-nil Gnus will prompt you to confirm that you really wish to proceed if you hit J S while unplugged. The default is nil.

gnus-agent-auto-agentize-methods

If you have never used the Agent before (or more technically, if ‘~/News/agent/lib/servers’ does not exist), Gnus will automatically agentize a few servers for you. This variable control which back ends should be auto-agentized. It is typically only useful to agentize remote back ends. The auto-agentizing has the same effect as running J a on the servers (see section Server Agent Commands). If the file exist, you must manage the servers manually by adding or removing them, this variable is only applicable the first time you start Gnus. The default is ‘nil’.

6.9.12 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.

6.9.13 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 -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1

6.9.14 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 behavior, 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.

This document was generated on January 25, 2015 using texi2html 1.82.