Mercurial > emacs

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/misc/mairix-el.texi	Tue Jul 29 18:00:35 2008 +0000
@@ -0,0 +1,346 @@
+\input texinfo.tex
+
+@setfilename ../../info/mairix-el
+@settitle Emacs Interface for Mairix
+
+@documentencoding ISO-8859-1
+
+@copying
+Copyright @copyright{} 2008 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.2 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.el: (mairix-el).	Mairix interface for Emacs.
+@end direntry
+
+@titlepage
+@title mairix.el - Mairix interface for Emacs
+
+@author David Engster
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@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.
+
+@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