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