doc/misc/mairix-el.texi

   1 \input texinfo.tex
   2
   3 @setfilename ../../info/mairix-el
   4 @settitle Emacs Interface for Mairix
   5
   6 @documentencoding ISO-8859-1
   7
   8 @copying
   9 Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.
  10
  11 @quotation
  12 Permission is granted to copy, distribute and/or modify this document
  13 under the terms of the GNU Free Documentation License, Version 1.3 or
  14 any later version published by the Free Software Foundation; with no
  15 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
  16 and with the Back-Cover Texts as in (a) below.  A copy of the license
  17 is included in the section entitled ``GNU Free Documentation License''.
  18
  19 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  20 modify this GNU manual.''
  21 @end quotation
  22 @end copying
  23
  24 @dircategory Emacs network features
  25 @direntry
  26 * Mairix: (mairix-el).          Emacs interface to the Mairix mail indexer.
  27 @end direntry
  28
  29 @titlepage
  30 @title mairix.el - Mairix interface for Emacs
  31
  32 @author David Engster
  33 @page
  34 @vskip 0pt plus 1filll
  35 @insertcopying
  36 @end titlepage
  37
  38 @contents
  39
  40 @node Top
  41 @top mairix.el - Mairix interface for Emacs
  42
  43 Mairix is a tool for indexing and searching words in locally stored
  44 mail.  It was written by Richard Curnow and is licensed under the
  45 GPL.
  46
  47 @code{mairix.el} is an interface to the mairix search engine.  It allows you to
  48 call mairix with a search term, easily create searches based on the
  49 currently displayed mail, save regularly used searches in your
  50 @file{.emacs} for future use and lets you call mairix for updating the
  51 database.
  52
  53 @ifnottex
  54 @insertcopying
  55 @end ifnottex
  56
  57 @menu
  58 * About mairix and mairix.el::  About the mairix search engine and mairix.el
  59 * Configuring mairix::          How to configure mairix
  60 * Setting up mairix.el::        Set up mairix.el
  61 * Using mairix.el::             List of interactive functions
  62 * Extending mairix.el::         Support your favorite mail reader!
  63 @end menu
  64
  65 @node About mairix and mairix.el
  66 @chapter About mairix and mairix.el
  67
  68 Mairix is a tool for indexing and searching words in locally stored
  69 mail.  It was written by Richard Curnow and is licensed under the
  70 GPL@.  Mairix comes with most popular GNU/Linux distributions, but it also
  71 runs under Windows (with cygwin), Mac OS X and Solaris.  The homepage can
  72 be found at
  73 @uref{http://www.rpcurnow.force9.co.uk/mairix/index.html}
  74
  75 Though mairix might not be as flexible as other search tools like
  76 swish++ or namazu, it has the prime advantage of being incredibly fast.
  77 On current systems, it can easily search through headers and message
  78 bodies of thousands and thousands of mails in well under a second.
  79 Building the database necessary for searching might take a minute or
  80 two, but only has to be done once fully.  Afterwards, the updates are
  81 done incrementally and therefore are really fast, too.  Additionally,
  82 mairix is very easy to set up.
  83
  84 Mairix presents the search results by either populating a @emph{virtual}
  85 maildir/MH folder with symlinks which point to the ``real'' message
  86 files, or if mbox is used, it creates a new mbox file which contains
  87 copies of the found messages.
  88
  89 @code{mairix.el} is an interface to the mairix search engine.  It allows
  90 you to call mairix with a search term, easily create searches based on
  91 the currently displayed mail, save regularly used searches in your
  92 @file{.emacs} for future use and lets you call mairix for updating the
  93 database.  It also lets you easily create search queries using graphical
  94 widgets, similar to a customization buffer.
  95
  96 Currently, @code{mairix.el} is only tested with mbox output together
  97 with RMail, Gnus, or VM as the Emacs mail program.  However, it should
  98 also work with Maildir or MH, and it should be very easy to integrate
  99 other Emacs mail programs into @code{mairix.el}
 100 (@pxref{Extending mairix.el}).
 101
 102 If you use Gnus with maildir or MH, you should really use the native
 103 Gnus back end @code{nnmairix} instead, since it is more tightly
 104 integrated into Gnus and has more features.
 105
 106 @node Configuring mairix
 107 @chapter Configuring mairix
 108
 109 Setting up mairix is easy: simply create a @file{.mairixrc} file with
 110 (at least) the following entries:
 111
 112 @example
 113 # Your mail base folder
 114 base=~/Mail
 115 @end example
 116
 117 This is the base folder for your mails.  All the following directories,
 118 except the one for the database, are relative to this base folder.
 119
 120 @example
 121 mbox = ... your mbox files which should be indexed ...
 122 maildir= ... your maildir folders which should be indexed ...
 123 mh= ... your nnml/mh folders which should be indexed ...
 124 @end example
 125
 126 Specify all your maildir/nnml folders and mbox files (relative to the
 127 base directory!) you want to index with mairix.  Use colons to separate
 128 different files.  See the man-page for @code{mairixrc} for details.
 129
 130 @example
 131 mformat = mbox
 132 database = ... location of database file ...
 133 @end example
 134
 135 This chooses @code{mbox} as the output format for the mairix search
 136 results.  Currently, this is the supported format by mairix.el, but
 137 technically it should be possible to also use maildir or mh; it's just
 138 not tested (yet).
 139
 140 You should make sure that you don't accidentally index the search
 141 results produced by mairix.  This can be done by pointing
 142 `mairix-file-path' to a directory which is surely not indexed by mairix.
 143 Another possibility is to use something like
 144
 145 @example
 146 omit = mairix*
 147 @end example
 148
 149 in the @file{.mairixrc} file, and prefix every search file you use with
 150 ``mairix''.
 151
 152 @example
 153 database = /home/user/.mairixdatabase
 154 @end example
 155
 156 This specifies the name of the database file.  Note that this is not
 157 relative to the @code{base} folder.
 158
 159 See the man page for @code{mairixrc} for details and further options,
 160 especially regarding wildcard usage, which may be a little different
 161 than you are used to.
 162
 163 Now simply call @code{mairix} to create the index for the first time.
 164 Note that this may take a few minutes, but every following index will do
 165 the updates incrementally and hence is very fast.
 166
 167 @node Setting up mairix.el
 168 @chapter Setting up mairix.el
 169
 170 First, put @code{mairix.el} in your Emacs search path and put
 171 @code{(require 'mairix)} into your @file{.emacs} file.  Then, use
 172 @kbd{M-x customize-group mairix RET} to set your preferences for
 173 mairix.el.  The most important items are @emph{Mairix File Path},
 174 @emph{Mairix Search File} and @emph{Mairix Mail Program}.  The latter
 175 specifies which mail program should be used to display the mairix search
 176 results.  Currently, RMail, Gnus with mbox files, and VM are supported.
 177 If you use Gnus with maildir or mh, use the native Gnus back end
 178 nnmairix instead.
 179
 180 If you use another Emacs mail program which is not yet supported by
 181 mairix.el, it is pretty easy to integrate it.  @xref{Extending
 182 mairix.el}, on how to integrate it into mairix.el.
 183
 184 Now you should be ready to go. @xref{Using mairix.el}, for the available
 185 commands.
 186
 187 @node Using mairix.el
 188 @chapter Using mairix.el
 189
 190 There are currently no default key bindings for mairix.el, since those
 191 should depend on the used mail program and I personally do not use
 192 RMail, so I wouldn't know which key bindings are reasonable.  I hope some
 193 day this will change and @code{mairix.el} will come with some good
 194 key bindings for the different mail programs.  Feel free to send me your
 195 suggestions.  Until then, define some bindings yourself.  Here's a quick
 196 and dirty solution with global key definitions I currently use, which
 197 might or might not collide with some other modes.  Simply include them
 198 in your @file{.emacs} and adapt to your needs:
 199
 200 @lisp
 201 (global-set-key (kbd "C-c C-o m") 'mairix-search)
 202 (global-set-key (kbd "C-c C-o w") 'mairix-widget-search)
 203 (global-set-key (kbd "C-c C-o u") 'mairix-update-database)
 204 (global-set-key (kbd "C-c C-o f") 'mairix-search-from-this-article)
 205 (global-set-key (kbd "C-c C-o t") 'mairix-search-thread-this-article)
 206 (global-set-key (kbd "C-c C-o b") 'mairix-widget-search-based-on-article)
 207 (global-set-key (kbd "C-c C-o s") 'mairix-save-search)
 208 (global-set-key (kbd "C-c C-o i") 'mairix-use-saved-search)
 209 (global-set-key (kbd "C-c C-o e") 'mairix-edit-saved-searches)
 210 @end lisp
 211
 212 Here's a description of the available interactive functions:
 213
 214 @table @code
 215
 216 @item mairix-search
 217 @kindex M-x mairix-search
 218 @findex mairix-search
 219 @vindex mairix-search-file
 220 @vindex mairix-file-path
 221 @vindex mairix-command
 222 @vindex mairix-search-options
 223 Call mairix with a search query.  You will also be asked if you want to
 224 include whole threads.  The results are saved by mairix in the default
 225 mail file, which is set through the variable `mairix-search-file', which
 226 again is prefixed by `mairix-file-path'.  The results will then be
 227 displayed with the chosen mail program.  The command used to call mairix
 228 is specified by the variable `mairix-command', together with the options
 229 `mairix-search-options'.  The latter has the default ``-F'' for making
 230 searching faster.
 231
 232 @item mairix-widget-search
 233 @kindex M-x mairix-widget-search
 234 @findex mairix-widget-search
 235 @vindex mairix-widget-fields-list
 236 Creates a mairix query using graphical widgets.  Very handy if you're
 237 not (yet) familiar with the mairix search syntax.  Just call it to see
 238 how it works.  You can then directly call mairix with the search term or
 239 save it for future use.  Since mairix allows almost arbitrary
 240 combinations of search commands (like ``tc'' for ``to or cc''), you
 241 might want to include some other fields.  This can be easily done by
 242 modifying `mairix-widget-fields-list'.
 243
 244 @item mairix-widget-search-based-on-article
 245 @kindex M-x mairix-widget-search-based-on-article
 246 @findex mairix-widget-search-based-on-article
 247 Create a mairix query using graphical widgets, but based on the
 248 currently displayed article, i.e., the available fields will be filled
 249 with the current header values.
 250
 251 @item mairix-search-from-this-article
 252 @kindex M-x mairix-search-from-this-article
 253 @findex mairix-search-from-this-article
 254 Search messages from sender of the current article.  This is effectively
 255 a shortcut for calling @code{mairix-search} with @code{f:current_from}.
 256 If used with a prefix, include whole threads of the found messages.
 257
 258 @item mairix-search-thread-this-article
 259 @kindex M-x mairix-search-thread-this-article
 260 @findex mairix-search-thread-this-article
 261 Search thread for the current article.  This is effectively a shortcut
 262 for calling @code{mairix-search} with @code{m:msgid} of the current article and
 263 enabled threads.
 264
 265 @item mairix-save-search
 266 @kindex M-x mairix-save-search
 267 @findex mairix-save-search
 268 Save the last search for future use.  You will have to specify a name
 269 for the search and will then be asked if you want to save your saved
 270 searches in your @file{.emacs}.  If you answer with yes, the variable
 271 @code{mairix-saved-searches} will be saved in the customize section of
 272 your @file{.emacs}.  You can also do this later by using
 273 `mairix-edit-saved-searches'.
 274
 275 @item mairix-use-saved-search
 276 @kindex M-x mairix-use-saved-search
 277 @findex mairix-use-saved-search
 278 Call mairix with a previously saved search.  You will be asked for the
 279 name of the saved search (use @kbd{TAB} for completion).
 280
 281 @item mairix-edit-saved-searches
 282 @kindex M-x mairix-edit-saved-searches
 283 @findex mairix-edit-saved-searches
 284 Edit your current mairix searches.  This is a simple major mode for
 285 editing the contents of the variable @code{mairix-saved-searches}.  You
 286 can edit and delete searches and save them in your @file{.emacs}.  You
 287 can also use this mode to call mairix with one of the saved searches.
 288 Additionally, you can specify a file name for mairix to use for a
 289 certain search instead of the default one.  This is useful if you want
 290 to open different searches at the same time, or if you want to regularly
 291 access certain searches without the need to call mairix.
 292
 293 @item mairix-edit-saved-searches-customize
 294 @kindex M-x mairix-edit-saved-searches-customize
 295 @findex mairix-edit-saved-searches-customize
 296 Edit the variable @code{mairix-saved-searches} in a normal customization
 297 buffer.  This function exists more or less for historic reasons, but
 298 maybe you like it.
 299
 300 @item mairix-update-database
 301 @kindex M-x mairix-update-database
 302 @findex mairix-update-database
 303 @vindex mairix-update-options
 304 @vindex mairix-synchronous-update
 305 Call mairix to update the database.  Mairix will be called with the
 306 options `mairix-update-options'; the default is ``-F'' and ``-Q'' to
 307 make updates as fast as possible.  Note that by using these options,
 308 absolutely no integrity checking is done.  If your database somehow gets
 309 corrupted, simply delete it and update.  If `mairix-synchronous-update'
 310 is nil (the default), mairix will be called in a subprocess so Emacs
 311 will still be usable while the update is done.
 312
 313 @end table
 314
 315
 316 @node Extending mairix.el
 317 @chapter Extending mairix.el
 318
 319 Your favorite Emacs mail program is not supported?  Shame on me.  But
 320 it is really easy to integrate other mail programs into mairix.el.  Just
 321 do the following:
 322
 323 @table @strong
 324 @item Write a display function
 325 Write a function that displays the mairix search results.  This function
 326 will be called from @code{mairix.el} with the mail file/folder as the
 327 single argument.  For example, the function @code{mairix-rmail-display}
 328 is currently used for RMail and @code{mairix-gnus-ephemeral-nndoc} is
 329 used for Gnus.
 330
 331 @item Write a get-header function
 332 Write a function that retrieves a header from the currently active mail.
 333 The single argument for this function is a string with the header name.
 334 For examples, see @code{mairix-rmail-fetch-field} and
 335 @code{mairix-gnus-fetch-field} for RMail and Gnus, respectively.
 336
 337 @item Integrate the functions into mairix.el
 338 Add your mail program to the defcustom of @code{mairix-mail-program}.
 339 Then add the functions to @code{mairix-display-functions} and
 340 @code{mairix-get-mail-header-functions}.
 341
 342 @item Let me know...
 343 ...so that I can eventually integrate it into future versions of mairix.el.
 344 @end table
 345
 346 And that's it!
 347
 348
 349
 350 @bye