mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-17 10:06:13 +00:00
9743f48de7
* doc/emacs/killing.texi: * doc/lispintro/emacs-lisp-intro.texi: * doc/misc/calc.texi: * doc/misc/cc-mode.texi: * doc/misc/dired-x.texi: * doc/misc/ede.texi: * doc/misc/edt.texi: * doc/misc/efaq.texi: * doc/misc/erc.texi: * doc/misc/eshell.texi: * doc/misc/gnus-faq.texi: * doc/misc/gnus-news.texi: * doc/misc/idlwave.texi: * doc/misc/ido.texi: * doc/misc/mairix-el.texi: * doc/misc/message.texi: * doc/misc/mh-e.texi: * doc/misc/newsticker.texi: * doc/misc/org.texi: * doc/misc/pcl-cvs.texi: * doc/misc/ses.texi: * doc/misc/sieve.texi: * doc/misc/smtpmail.texi: * doc/misc/speedbar.texi: * doc/misc/srecode.texi: * doc/misc/vhdl-mode.texi: * doc/misc/vip.texi: * doc/misc/viper.texi: Mark keys consistently.
343 lines
13 KiB
Plaintext
343 lines
13 KiB
Plaintext
\input texinfo.tex
|
|
|
|
@setfilename ../../info/mairix-el.info
|
|
@settitle Emacs Interface for Mairix
|
|
@include docstyle.texi
|
|
|
|
@copying
|
|
Copyright @copyright{} 2008--2018 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.''
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Emacs network features
|
|
@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:: About the mairix search engine and mairix.el.
|
|
* Configuring mairix:: How to configure mairix.
|
|
* Setting up the mairix interface:: Set up mairix.el.
|
|
* Using:: List of interactive functions
|
|
* Extending:: Support your favorite mail reader!
|
|
* GNU Free Documentation License:: The license for this documentation.
|
|
@end menu
|
|
|
|
@node About
|
|
@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), macOS 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}).
|
|
|
|
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
|
|
@code{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 the mairix interface
|
|
@chapter Setting up the mairix interface
|
|
|
|
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 @key{RET} mairix @key{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},
|
|
on how to integrate it into mairix.el.
|
|
|
|
Now you should be ready to go. @xref{Using}, for the available commands.
|
|
|
|
@node Using
|
|
@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
|
|
@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 @code{mairix-search-file}, which
|
|
again is prefixed by @code{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 @code{mairix-command}, together with the options
|
|
@code{mairix-search-options}. The latter has the default @option{-F}
|
|
for making searching faster.
|
|
|
|
@item 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 @code{mairix-widget-fields-list}.
|
|
|
|
@item 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
|
|
@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
|
|
@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
|
|
@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
|
|
@code{mairix-edit-saved-searches}.
|
|
|
|
@item 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
|
|
@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
|
|
@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
|
|
@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 @code{mairix-update-options}; the default is @option{-F} and
|
|
@option{-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 @code{mairix-synchronous-update}
|
|
is @code{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
|
|
@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!
|
|
|
|
@node GNU Free Documentation License
|
|
@appendix GNU Free Documentation License
|
|
@include doclicense.texi
|
|
|
|
@bye
|