doc/misc/mairix-el.texi

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