Mercurial > emacs
view doc/misc/mairix-el.texi @ 107908:44e86aa9f6f9
Merge from mainline.
author | Katsumi Yamaoka <yamaoka@jpl.org> |
---|---|
date | Wed, 31 Mar 2010 06:31:33 +0000 |
parents | 1d1d5d9bd884 |
children | a91e94388547 |
line wrap: on
line source
\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