9.18 The Gnus Registry

The Gnus registry is a package that tracks messages by their Message-ID across all backends. This allows Gnus users to do several cool things, be the envy of the locals, get free haircuts, and be experts on world issues. Well, maybe not all of those, but the features are pretty cool.

Although they will be explained in detail shortly, here’s a quick list of said features in case your attention span is... never mind.

1. Split messages to their parent

   This keeps discussions in the same group. You can use the subject and the sender in addition to the Message-ID. Several strategies are available.

2. Refer to messages by ID

   Commands like gnus-summary-refer-parent-article can take advantage of the registry to jump to the referred article, regardless of the group the message is in.

3. Store custom flags and keywords

   The registry can store custom flags and keywords for a message. For instance, you can mark a message “To-Do” this way and the flag will persist whether the message is in the nnimap, nnml, nnmaildir, etc. backends.

4. Store arbitrary data

   Through a simple ELisp API, the registry can remember any data for a message. A built-in inverse map, when activated, allows quick lookups of all messages matching a particular set of criteria.

9.18.1 Gnus Registry Setup

Fortunately, setting up the Gnus registry is pretty easy:

(setq gnus-registry-max-entries 2500)

(gnus-registry-initialize)

This adds registry saves to Gnus newsrc saves (which happen on exit and when you press s from the ‘*Group*’ buffer. It also adds registry calls to article actions in Gnus (copy, move, etc.) so it’s not easy to undo the initialization. See gnus-registry-initialize for the gory details.

Here are other settings used by the author of the registry (understand what they do before you copy them blindly).

(setq
 gnus-registry-split-strategy 'majority
 gnus-registry-ignored-groups '(("nntp" t)
                                ("nnrss" t)
                                ("spam" t)
                                ("train" t))
 gnus-registry-max-entries 500000
 ;; this is the default
 gnus-registry-track-extra '(sender subject))

They say: keep a lot of messages around, track messages by sender and subject (not just parent Message-ID), and when the registry splits incoming mail, use a majority rule to decide where messages should go if there’s more than one possibility. In addition, the registry should ignore messages in groups that match “nntp”, “nnrss”, “spam”, or “train.”

You are doubtless impressed by all this, but you ask: “I am a Gnus user, I customize to live. Give me more.” Here you go, these are the general settings.

Variable: gnus-registry-unfollowed-groups

The groups that will not be followed by gnus-registry-split-fancy-with-parent. They will still be remembered by the registry. This is a list of regular expressions. By default any group name that ends with “delayed”, “drafts”, “queue”, or “INBOX”, belongs to the nnmairix backend, or contains the word “archive” is not followed.

Variable: gnus-registry-max-entries

The number (an integer or nil for unlimited) of entries the registry will keep. If the registry has reached or exceeded this size, it will reject insertion of new entries.

Variable: gnus-registry-prune-factor

This option (a float between 0 and 1) controls how much the registry is cut back during pruning. In order to prevent constant pruning, the registry will be pruned back to less than gnus-registry-max-entries. This option controls exactly how much less: the target is calculated as the maximum number of entries minus the maximum number times this factor. The default is 0.1: i.e. if your registry is limited to 50000 entries, pruning will try to cut back to 45000 entries. Entries with keys marked as precious will not be pruned.

Variable: gnus-registry-default-sort-function

This option specifies how registry entries are sorted during pruning. If a function is given, it should sort least valuable entries first, as pruning starts from the beginning of the list. The default value is gnus-registry-sort-by-creation-time, which proposes the oldest entries for pruning. Set to nil to perform no sorting, which will speed up the pruning process.

Variable: gnus-registry-cache-file

The file where the registry will be stored between Gnus sessions. By default the file name is .gnus.registry.eieio in the same directory as your .newsrc.eld.

9.18.2 Fetching by Message-ID Using the Registry

The registry knows how to map each Message-ID to the group it’s in. This can be leveraged to enhance the “article refer method”, the thing that tells Gnus how to look up an article given its Message-ID (see section Finding the Parent).

The nnregistry refer method does exactly that. It has the advantage that an article may be found regardless of the group it’s in—provided its Message-ID is known to the registry. It can be enabled by augmenting the start-up file with something along these lines:

;; Keep enough entries to have a good hit rate when referring to an
;; article using the registry.  Use long group names so that Gnus
;; knows where the article is.
(setq gnus-registry-max-entries 2500)

(gnus-registry-initialize)

(setq gnus-refer-article-method
      '(current
        (nnregistry)
        (nnweb "gmane" (nnweb-type gmane))))

The example above instructs Gnus to first look up the article in the current group, or, alternatively, using the registry, and finally, if all else fails, using Gmane.

9.18.3 Fancy splitting to parent

Simply put, this lets you put followup e-mail where it belongs.

Every message has a Message-ID, which is unique, and the registry remembers it. When the message is moved or copied, the registry will notice this and offer the new group as a choice to the splitting strategy.

When a followup is made, usually it mentions the original message’s Message-ID in the headers. The registry knows this and uses that mention to find the group where the original message lives. You only have to put a rule like this:

(setq nnimap-my-split-fancy '(|

      ;; split to parent: you need this
      (: gnus-registry-split-fancy-with-parent)

      ;; other rules, as an example
      (: spam-split)
      ;; default mailbox
      "mail")

in your fancy split setup. In addition, you may want to customize the following variables.

Variable: gnus-registry-track-extra

This is a list of symbols, so it’s best to change it from the Customize interface. By default it’s (subject sender recipient), which may work for you. It can be annoying if your mail flow is large and people don’t stick to the same groups.

When you decide to stop tracking any of those extra data, you can use the command gnus-registry-remove-extra-data to purge it from the existing registry entries.

Variable: gnus-registry-split-strategy

This is a symbol, so it’s best to change it from the Customize interface. By default it’s nil, but you may want to set it to majority or first to split by sender or subject based on the majority of matches or on the first found. I find majority works best.

9.18.4 Store custom flags and keywords

The registry lets you set custom flags and keywords per message. You can use the Gnus->Registry Marks menu or the M M x keyboard shortcuts, where x is the first letter of the mark’s name.

Variable: gnus-registry-marks

The custom marks that the registry can use. You can modify the default list, if you like. If you do, you’ll have to exit Emacs before they take effect (you can also unload the registry and reload it or evaluate the specific macros you’ll need, but you probably don’t want to bother). Use the Customize interface to modify the list.

By default this list has the Important, Work, Personal, To-Do, and Later marks. They all have keyboard shortcuts like M M i for Important, using the first letter.

Function: gnus-registry-mark-article

Call this function to mark an article with a custom registry mark. It will offer the available marks for completion.

You can use defalias to install a summary line formatting function that will show the registry marks. There are two flavors of this function, either showing the marks as single characters, using their :char property, or showing the marks as full strings.

;; show the marks as single characters (see the :char property in
;; `gnus-registry-marks'):
;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-chars)

;; show the marks by name (see `gnus-registry-marks'):
;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-names)

9.18.5 Store arbitrary data

The registry has a simple API that uses a Message-ID as the key to store arbitrary data (as long as it can be converted to a list for storage).

Function: gnus-registry-set-id-key (id key value)

Store value under key for message id.

Function: gnus-registry-get-id-key (id key)

Get the data under key for message id.

Variable: gnus-registry-extra-entries-precious

If any extra entries are precious, their presence will make the registry keep the whole entry forever, even if there are no groups for the Message-ID and if the size limit of the registry is reached. By default this is just (marks) so the custom registry marks are precious.

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