mairix.el - Mairix interface for Emacs
**************************************

Mairix is a tool for indexing and searching words in locally stored mail.  It was written by Richard Curnow and is licensed under the GPL.

mairix.el is an interface to the mairix search engine.  It allows you to call mairix with a search term, easily create searches based on the currently displayed mail, save regularly used searches in your .emacs for future use and lets you call mairix for updating the database.

Copyright © 2008, 2009, 2010 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.3 or any later version published by the Free Software Foundation; with no Invariant Sections, 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''.

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.  Buying copies from the FSF supports it in developing GNU and promoting software freedom.''

About mairix and mairix.el
**************************

Mairix is a tool for indexing and searching words in locally stored mail.  It was written by Richard Curnow and is licensed under the GPL.  Mairix comes with most popular GNU/Linux distributions, but it also runs under Windows (with cygwin), Mac OS X and Solaris.  The homepage can be found at http://www.rpcurnow.force9.co.uk/mairix/index.html

Though mairix might not be as flexible as other search tools like swish++ or namazu, it has the prime advantage of being incredibly fast. On current systems, it can easily search through headers and message bodies of thousands and thousands of mails in well under a second. Building the database necessary for searching might take a minute or two, but only has to be done once fully.  Afterwards, the updates are done incrementally and therefore are really fast, too.  Additionally, mairix is very easy to set up.

Mairix presents the search results by either populating a virtual maildir/MH folder with symlinks which point to the ``real'' message files, or if mbox is used, it creates a new mbox file which contains copies of the found messages.

mairix.el is an interface to the mairix search engine.  It allows you to call mairix with a search term, easily create searches based on the currently displayed mail, save regularly used searches in your .emacs for future use and lets you call mairix for updating the database.  It also lets you easily create search queries using graphical widgets, similar to a customization buffer.

Currently, mairix.el is only tested with mbox output together with RMail, Gnus, or VM as the Emacs mail program.  However, it should also work with Maildir or MH, and it should be very easy to integrate other Emacs mail programs into mairix.el (see Extending mairix.el).

If you use Gnus with maildir or MH, you should really use the native Gnus back end nnmairix instead, since it is more tightly integrated into Gnus and has more features.

Configuring mairix
******************

Setting up mairix is easy: simply create a .mairixrc file with (at least) the following entries:

     # Your mail base folder
     base=~/Mail

This is the base folder for your mails.  All the following directories, except the one for the database, are relative to this base folder.

     mbox = ... your mbox files which should be indexed ...
     maildir= ... your maildir folders which should be indexed ...
     mh= ... your nnml/mh folders which should be indexed ...

Specify all your maildir/nnml folders and mbox files (relative to the base directory!) you want to index with mairix.  Use colons to separate different files.  See the man-page for mairixrc for details.

     mformat = mbox
     database = ... location of database file ...

This chooses mbox as the output format for the mairix search results.  Currently, this is the supported format by mairix.el, but technically it should be possible to also use maildir or mh; it's just not tested (yet).

You should make sure that you don't accidentally index the search results produced by mairix.  This can be done by pointing `mairix-file-path' to a directory which is surely not indexed by mairix. Another possibility is to use something like

     omit = mairix*

in the .mairixrc file, and prefix every search file you use with ``mairix''.

     database = /home/user/.mairixdatabase

This specifies the name of the database file.  Note that this is not relative to the base folder.

See the man page for mairixrc for details and further options, especially regarding wildcard usage, which may be a little different than you are used to.

Now simply call mairix to create the index for the first time. Note that this may take a few minutes, but every following index will do the updates incrementally and hence is very fast.

Setting up mairix.el
********************

First, put mairix.el in your Emacs search path and put (require 'mairix) into your .emacs file.  Then, use M-x customize-group mairix RET to set your preferences for mairix.el.  The most important items are Mairix File Path, Mairix Search File and Mairix Mail Program.  The latter specifies which mail program should be used to display the mairix search results.  Currently, RMail, Gnus with mbox files, and VM are supported. If you use Gnus with maildir or mh, use the native Gnus back end nnmairix instead.

If you use another Emacs mail program which is not yet supported by mairix.el, it is pretty easy to integrate it.  See Extending mairix.el, on how to integrate it into mairix.el.

Now you should be ready to go. See Using mairix.el, for the available commands.

Using mairix.el
***************

There are currently no default key bindings for mairix.el, since those should depend on the used mail program and I personally do not use RMail, so I wouldn't know which key bindings are reasonable.  I hope some day this will change and mairix.el will come with some good key bindings for the different mail programs.  Feel free to send me your suggestions.  Until then, define some bindings yourself.  Here's a quick and dirty solution with global key definitions I currently use, which might or might not collide with some other modes.  Simply include them in your .emacs and adapt to your needs:

     (global-set-key (kbd "C-c C-o m") 'mairix-search)
     (global-set-key (kbd "C-c C-o w") 'mairix-widget-search)
     (global-set-key (kbd "C-c C-o u") 'mairix-update-database)
     (global-set-key (kbd "C-c C-o f") 'mairix-search-from-this-article)
     (global-set-key (kbd "C-c C-o t") 'mairix-search-thread-this-article)
     (global-set-key (kbd "C-c C-o b") 'mairix-widget-search-based-on-article)
     (global-set-key (kbd "C-c C-o s") 'mairix-save-search)
     (global-set-key (kbd "C-c C-o i") 'mairix-use-saved-search)
     (global-set-key (kbd "C-c C-o e") 'mairix-edit-saved-searches)

Here's a description of the available interactive functions:

mairix-search
     Call mairix with a search query.  You will also be asked if you want to include whole threads.  The results are saved by mairix in the default mail file, which is set through the variable `mairix-search-file', which again is prefixed by `mairix-file-path'.  The results will then be displayed with the chosen mail program.  The command used to call mairix is specified by the variable `mairix-command', together with the options `mairix-search-options'.  The latter has the default ``-F'' for making searching faster.

mairix-widget-search
     Creates a mairix query using graphical widgets.  Very handy if you're not (yet) familiar with the mairix search syntax.  Just call it to see how it works.  You can then directly call mairix with the search term or save it for future use.  Since mairix allows almost arbitrary combinations of search commands (like ``tc'' for ``to or cc''), you might want to include some other fields.  This can be easily done by modifying `mairix-widget-fields-list'.

mairix-widget-search-based-on-article
     Create a mairix query using graphical widgets, but based on the currently displayed article, i.e. the available fields will be filled with the current header values.

mairix-search-from-this-article
     Search messages from sender of the current article.  This is effectively a shortcut for calling mairix-search with f:current_from. If used with a prefix, include whole threads of the found messages.

mairix-search-thread-this-article
     Search thread for the current article.  This is effectively a shortcut for calling mairix-search with m:msgid of the current article and enabled threads.

mairix-save-search
     Save the last search for future use.  You will have to specify a name for the search and will then be asked if you want to save your saved searches in your .emacs.  If you answer with yes, the variable mairix-saved-searches will be saved in the customize section of your .emacs.  You can also do this later by using `mairix-edit-saved-searches'.

mairix-use-saved-search
     Call mairix with a previously saved search.  You will be asked for the name of the saved search (use TAB for completion).

mairix-edit-saved-searches
     Edit your current mairix searches.  This is a simple major mode for editing the contents of the variable mairix-saved-searches.  You can edit and delete searches and save them in your .emacs.  You can also use this mode to call mairix with one of the saved searches. Additionally, you can specify a file name for mairix to use for a certain search instead of the default one.  This is useful if you want to open different searches at the same time, or if you want to regularly access certain searches without the need to call mairix.

mairix-edit-saved-searches-customize
     Edit the variable mairix-saved-searches in a normal customization buffer.  This function exists more or less for historic reasons, but maybe you like it.

mairix-update-database
     Call mairix to update the database.  Mairix will be called with the options `mairix-update-options'; the default is ``-F'' and ``-Q'' to make updates as fast as possible.  Note that by using these options, absolutely no integrity checking is done.  If your database somehow gets corrupted, simply delete it and update.  If `mairix-synchronous-update' is nil (the default), mairix will be called in a subprocess so Emacs will still be usable while the update is done.

Extending mairix.el
*******************

Your favorite Emacs mail program is not supported?  Shame on me.  But it is really easy to integrate other mail programs into mairix.el.  Just do the following:

Write a display function
     Write a function that displays the mairix search results.  This function will be called from mairix.el with the mail file/folder as the single argument.  For example, the function mairix-rmail-display is currently used for RMail and mairix-gnus-ephemeral-nndoc is used for Gnus.

Write a get-header function
     Write a function that retrieves a header from the currently active mail. The single argument for this function is a string with the header name. For examples, see mairix-rmail-fetch-field and mairix-gnus-fetch-field for RMail and Gnus, respectively.

Integrate the functions into mairix.el
     Add your mail program to the defcustom of mairix-mail-program. Then add the functions to mairix-display-functions and mairix-get-mail-header-functions.

Let me know...
     ...so that I can eventually integrate it into future versions of mairix.el.

And that's it!