annotate doc/misc/mairix-el.texi @ 110931:2316b868d5be

Merge changes from emacs-23 branch.

\input texinfo.tex

@setfilename ../../info/mairix-el
@settitle Emacs Interface for Mairix

@documentencoding ISO-8859-1

@copying
Copyright @copyright{} 2008, 2009, 2010 Free Software Foundation, Inc.

@quotation
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.''
@end quotation
@end copying

@dircategory Emacs
@direntry
* Mairix: (mairix-el).          Emacs interface to the Mairix mail indexer.
@end direntry

@titlepage
@title mairix.el - Mairix interface for Emacs

@author David Engster
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@node Top
@top 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.

@code{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
@file{.emacs} for future use and lets you call mairix for updating the
database.

@ifnottex
@insertcopying
@end ifnottex

@menu
* About mairix and mairix.el::  About the mairix search engine and mairix.el
* Configuring mairix::          How to configure mairix
* Setting up mairix.el::        Set up mairix.el
* Using mairix.el::             List of interactive functions
* Extending mairix.el::         Support your favorite mail reader!
@end menu

@node About mairix and mairix.el
@chapter 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
@uref{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 @emph{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.

@code{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
@file{.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, @code{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 @code{mairix.el}
(@pxref{Extending mairix.el}).

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

@node Configuring mairix
@chapter Configuring mairix

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

@example
# Your mail base folder
base=~/Mail
@end example

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

@example
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 ...
@end example

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 @code{mairixrc} for details.

@example
mformat = mbox
database = ... location of database file ...
@end example

This chooses @code{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

@example
omit = mairix*
@end example

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

@example
database = /home/user/.mairixdatabase
@end example

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

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

Now simply call @code{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.

@node Setting up mairix.el
@chapter Setting up mairix.el

First, put @code{mairix.el} in your Emacs search path and put
@code{(require 'mairix)} into your @file{.emacs} file.  Then, use
@kbd{M-x customize-group mairix RET} to set your preferences for
mairix.el.  The most important items are @emph{Mairix File Path},
@emph{Mairix Search File} and @emph{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.  @xref{Extending
mairix.el}, on how to integrate it into mairix.el.

Now you should be ready to go. @xref{Using mairix.el}, for the available
commands.

@node Using mairix.el
@chapter 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 @code{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 @file{.emacs} and adapt to your needs:

@lisp
(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)
@end lisp

Here's a description of the available interactive functions:

@table @code

@item mairix-search
@kindex M-x mairix-search
@findex mairix-search
@vindex mairix-search-file
@vindex mairix-file-path
@vindex mairix-command
@vindex mairix-search-options
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.

@item mairix-widget-search
@kindex M-x mairix-widget-search
@findex mairix-widget-search
@vindex mairix-widget-fields-list
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'.

@item mairix-widget-search-based-on-article
@kindex M-x mairix-widget-search-based-on-article
@findex 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.

@item mairix-search-from-this-article
@kindex M-x mairix-search-from-this-article
@findex mairix-search-from-this-article
Search messages from sender of the current article.  This is effectively
a shortcut for calling @code{mairix-search} with @code{f:current_from}.
If used with a prefix, include whole threads of the found messages.

@item mairix-search-thread-this-article
@kindex M-x mairix-search-thread-this-article
@findex mairix-search-thread-this-article
Search thread for the current article.  This is effectively a shortcut
for calling @code{mairix-search} with @code{m:msgid} of the current article and
enabled threads.

@item mairix-save-search
@kindex M-x mairix-save-search
@findex 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 @file{.emacs}.  If you answer with yes, the variable
@code{mairix-saved-searches} will be saved in the customize section of
your @file{.emacs}.  You can also do this later by using
`mairix-edit-saved-searches'.

@item mairix-use-saved-search
@kindex M-x mairix-use-saved-search
@findex mairix-use-saved-search
Call mairix with a previously saved search.  You will be asked for the
name of the saved search (use @kbd{TAB} for completion).

@item mairix-edit-saved-searches
@kindex M-x mairix-edit-saved-searches
@findex mairix-edit-saved-searches
Edit your current mairix searches.  This is a simple major mode for
editing the contents of the variable @code{mairix-saved-searches}.  You
can edit and delete searches and save them in your @file{.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.

@item mairix-edit-saved-searches-customize
@kindex M-x mairix-edit-saved-searches-customize
@findex mairix-edit-saved-searches-customize
Edit the variable @code{mairix-saved-searches} in a normal customization
buffer.  This function exists more or less for historic reasons, but
maybe you like it.

@item mairix-update-database
@kindex M-x mairix-update-database
@findex mairix-update-database
@vindex mairix-update-options
@vindex mairix-synchronous-update
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.

@end table


@node Extending mairix.el
@chapter 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:

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

@item 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 @code{mairix-rmail-fetch-field} and
@code{mairix-gnus-fetch-field} for RMail and Gnus, respectively.

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

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

And that's it!



@bye

@ignore
   arch-tag: cb81470f-e080-489d-bb67-0d11516b63b9
@end ignore