8.1 nnir

This section describes how to use nnir to search for articles within gnus.

8.1.1 What is nnir?

nnir is a Gnus interface to a number of tools for searching through mail and news repositories. Different backends (like nnimap and nntp) work with different tools (called engines in nnir lingo), but all use the same basic search interface.

The nnimap and gmane search engines should work with no configuration. Other engines require a local index that needs to be created and maintained outside of Gnus.

8.1.2 Basic Usage

In the group buffer typing G G will search the group on the current line by calling gnus-group-make-nnir-group. This prompts for a query string, creates an ephemeral nnir group containing the articles that match this query, and takes you to a summary buffer showing these articles. Articles may then be read, moved and deleted using the usual commands.

The nnir group made in this way is an ephemeral group, and some changes are not permanent: aside from reading, moving, and deleting, you can’t act on the original article. But there is an alternative: you can warp (i.e., jump) to the original group for the article on the current line with A W, aka gnus-warp-to-article. Even better, the function gnus-summary-refer-thread, bound by default in summary buffers to A T, will first warp to the original group before it works its magic and includes all the articles in the thread. From here you can read, move and delete articles, but also copy them, alter article marks, whatever. Go nuts.

You say you want to search more than just the group on the current line? No problem: just process-mark the groups you want to search. You want even more? Calling for an nnir search with the cursor on a topic heading will search all the groups under that heading.

Still not enough? OK, in the server buffer gnus-group-make-nnir-group (now bound to G) will search all groups from the server on the current line. Too much? Want to ignore certain groups when searching, like spam groups? Just customize nnir-ignored-newsgroups.

One more thing: individual search engines may have special search features. You can access these special features by giving a prefix-arg to gnus-group-make-nnir-group. If you are searching multiple groups with different search engines you will be prompted for the special search features for each engine separately.

8.1.3 Setting up nnir

To set up nnir you may need to do some prep work. Firstly, you may need to configure the search engines you plan to use. Some of them, like imap and gmane, need no special configuration. Others, like namazu and swish, require configuration as described below. Secondly, you need to associate a search engine with a server or a backend.

If you just want to use the imap engine to search nnimap servers, and the gmane engine to search gmane then you don’t have to do anything. But you might want to read the details of the query language anyway.

8.1.3.1 Associating Engines

When searching a group, nnir needs to know which search engine to use. You can configure a given server to use a particular engine by setting the server variable nnir-search-engine to the engine name. For example to use the namazu engine to search the server named home you can use

(setq gnus-secondary-select-methods
      '((nnml "home"
         (nnimap-address "localhost")
         (nnir-search-engine namazu))))

Alternatively you might want to use a particular engine for all servers with a given backend. For example, you might want to use the imap engine for all servers using the nnimap backend. In this case you can customize the variable nnir-method-default-engines. This is an alist of pairs of the form (backend . engine). By default this variable is set to use the imap engine for all servers using the nnimap backend, and the gmane backend for nntp servers. (Don’t worry, the gmane search engine won’t actually try to search non-gmane nntp servers.) But if you wanted to use namazu for all your servers with an nnimap backend you could change this to

'((nnimap . namazu)
  (nntp . gmane))

8.1.3.2 The imap Engine

The imap engine requires no configuration.

Queries using the imap engine follow a simple query language. The search is always case-insensitive and supports the following features (inspired by the Google search input language):

‘Boolean query operators’

AND, OR, and NOT are supported, and parentheses can be used to control operator precedence, e.g., (emacs OR xemacs) AND linux. Note that operators must be written with all capital letters to be recognized. Also preceding a term with a - sign is equivalent to NOT term.

‘Automatic AND queries’

If you specify multiple words then they will be treated as an AND expression intended to match all components.

‘Phrase searches’

If you wrap your query in double-quotes then it will be treated as a literal string.

By default the whole message will be searched. The query can be limited to a specific part of a message by using a prefix-arg. After inputting the query this will prompt (with completion) for a message part. Choices include “Whole message”, “Subject”, “From”, and “To”. Any unrecognized input is interpreted as a header name. For example, typing Message-ID in response to this prompt will limit the query to the Message-ID header.

Finally selecting “Imap” will interpret the query as a raw IMAP search query. The format of such queries can be found in RFC3501.

If you don’t like the default of searching whole messages you can customize nnir-imap-default-search-key. For example to use IMAP queries by default

(setq nnir-imap-default-search-key "Imap")

8.1.3.3 The gmane Engine

The gmane engine requires no configuration.

Gmane queries follow a simple query language:

‘Boolean query operators’

AND, OR, NOT (or AND NOT), and XOR are supported, and brackets can be used to control operator precedence, e.g., (emacs OR xemacs) AND linux. Note that operators must be written with all capital letters to be recognized.

‘Required and excluded terms’

+ and - can be used to require or exclude terms, e.g., football -american

‘Unicode handling’

The search engine converts all text to utf-8, so searching should work in any language.

‘Stopwords’

Common English words (like ’the’ and ’a’) are ignored by default. You can override this by prefixing such words with a + (e.g., +the) or enclosing the word in quotes (e.g., "the").

The query can be limited to articles by a specific author using a prefix-arg. After inputting the query this will prompt for an author name (or part of a name) to match.

8.1.3.4 The swish++ Engine

FIXME: Say something more here.

Documentation for swish++ may be found at the swish++ sourceforge page: http://swishplusplus.sourceforge.net

nnir-swish++-program

The name of the swish++ executable. Defaults to search

nnir-swish++-additional-switches

A list of strings to be given as additional arguments to swish++. nil by default.

nnir-swish++-remove-prefix

The prefix to remove from each file name returned by swish++ in order to get a group name. By default this is $HOME/Mail.

8.1.3.5 The swish-e Engine

FIXME: Say something more here.

Documentation for swish-e may be found at the swish-e homepage http://swish-e.org

nnir-swish-e-program

The name of the swish-e search program. Defaults to swish-e.

nnir-swish-e-additional-switches

A list of strings to be given as additional arguments to swish-e. nil by default.

nnir-swish-e-remove-prefix

The prefix to remove from each file name returned by swish-e in order to get a group name. By default this is $HOME/Mail.

8.1.3.6 The namazu Engine

Using the namazu engine requires creating and maintaining index files. One directory should contain all the index files, and nnir must be told where to find them by setting the nnir-namazu-index-directory variable.

To work correctly the nnir-namazu-remove-prefix variable must also be correct. This is the prefix to remove from each file name returned by Namazu in order to get a proper group name (albeit with ‘/’ instead of ‘.’).

For example, suppose that Namazu returns file names such as ‘/home/john/Mail/mail/misc/42’. For this example, use the following setting: (setq nnir-namazu-remove-prefix "/home/john/Mail/") Note the trailing slash. Removing this prefix from the directory gives ‘mail/misc/42’. nnir knows to remove the ‘/42’ and to replace ‘/’ with ‘.’ to arrive at the correct group name ‘mail.misc’.

Extra switches may be passed to the namazu search command by setting the variable nnir-namazu-additional-switches. It is particularly important not to pass any any switches to namazu that will change the output format. Good switches to use include ‘–sort’, ‘–ascending’, ‘–early’ and ‘–late’. Refer to the Namazu documentation for further information on valid switches.

Mail must first be indexed with the ‘mknmz’ program. Read the documentation for namazu to create a configuration file. Here is an example:

 package conf;  # Don't remove this line!

 # Paths which will not be indexed. Don't use `^' or `$' anchors.
 $EXCLUDE_PATH = "spam|sent";

 # Header fields which should be searchable. case-insensitive
 $REMAIN_HEADER = "from|date|message-id|subject";

 # Searchable fields. case-insensitive
 $SEARCH_FIELD = "from|date|message-id|subject";

 # The max length of a word.
 $WORD_LENG_MAX = 128;

 # The max length of a field.
 $MAX_FIELD_LENGTH = 256;

For this example, mail is stored in the directories ‘~/Mail/mail/’, ‘~/Mail/lists/’ and ‘~/Mail/archive/’, so to index them go to the index directory set in nnir-namazu-index-directory and issue the following command:

mknmz --mailnews ~/Mail/archive/ ~/Mail/mail/ ~/Mail/lists/

For maximum searching efficiency you might want to have a cron job run this command periodically, say every four hours.

8.1.3.7 The notmuch Engine

nnir-notmuch-program

The name of the notmuch search executable. Defaults to ‘notmuch’.

nnir-notmuch-additional-switches

A list of strings, to be given as additional arguments to notmuch.

nnir-notmuch-remove-prefix

The prefix to remove from each file name returned by notmuch in order to get a group name (albeit with ‘/’ instead of ‘.’). This is a regular expression.

8.1.3.8 The hyrex Engine

This engine is obsolete.

8.1.3.9 Customizations

nnir-method-default-engines

Alist of pairs of server backends and search engines. The default associations are

(nnimap . imap) (nntp . gmane)

nnir-ignored-newsgroups

A regexp to match newsgroups in the active file that should be skipped when searching all groups on a server.

nnir-summary-line-format

The format specification to be used for lines in an nnir summary buffer. All the items from ‘gnus-summary-line-format’ are available, along with three items unique to nnir summary buffers:

%Z Search retrieval score value (integer) %G Article original full group name (string) %g Article original short group name (string)

If nil (the default) this will use gnus-summary-line-format.

nnir-retrieve-headers-override-function

If non-nil, a function that retrieves article headers rather than using the gnus built-in function. This function takes an article list and group as arguments and populates the ‘nntp-server-buffer’ with the retrieved headers. It should then return either ’nov or ’headers indicating the retrieved header format. Failure to retrieve headers should return nil.

If this variable is nil, or if the provided function returns nil for a search result, gnus-retrieve-headers will be called instead."

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