| 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, 2009 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. 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 | @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 mairix and mairix.el:: About the mairix search engine and mairix.el |
| 60 | * Configuring mairix:: How to configure mairix |
| 61 | * Setting up mairix.el:: Set up mairix.el |
| 62 | * Using mairix.el:: List of interactive functions |
| 63 | * Extending mairix.el:: Support your favorite mail reader! |
| 64 | @end menu |
| 65 | |
| 66 | @node About mairix and mairix.el |
| 67 | @chapter About mairix and mairix.el |
| 68 | |
| 69 | Mairix is a tool for indexing and searching words in locally stored |
| 70 | mail. It was written by Richard Curnow and is licensed under the |
| 71 | GPL. Mairix comes with most popular GNU/Linux distributions, but it also |
| 72 | runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can |
| 73 | be found at |
| 74 | @uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} |
| 75 | |
| 76 | Though mairix might not be as flexible as other search tools like |
| 77 | swish++ or namazu, it has the prime advantage of being incredibly fast. |
| 78 | On current systems, it can easily search through headers and message |
| 79 | bodies of thousands and thousands of mails in well under a second. |
| 80 | Building the database necessary for searching might take a minute or |
| 81 | two, but only has to be done once fully. Afterwards, the updates are |
| 82 | done incrementally and therefore are really fast, too. Additionally, |
| 83 | mairix is very easy to set up. |
| 84 | |
| 85 | Mairix presents the search results by either populating a @emph{virtual} |
| 86 | maildir/MH folder with symlinks which point to the ``real'' message |
| 87 | files, or if mbox is used, it creates a new mbox file which contains |
| 88 | copies of the found messages. |
| 89 | |
| 90 | @code{mairix.el} is an interface to the mairix search engine. It allows |
| 91 | you to call mairix with a search term, easily create searches based on |
| 92 | the currently displayed mail, save regularly used searches in your |
| 93 | @file{.emacs} for future use and lets you call mairix for updating the |
| 94 | database. It also lets you easily create search queries using graphical |
| 95 | widgets, similar to a customization buffer. |
| 96 | |
| 97 | Currently, @code{mairix.el} is only tested with mbox output together |
| 98 | with RMail, Gnus, or VM as the Emacs mail program. However, it should |
| 99 | also work with Maildir or MH, and it should be very easy to integrate |
| 100 | other Emacs mail programs into @code{mairix.el} |
| 101 | (@pxref{Extending mairix.el}). |
| 102 | |
| 103 | If you use Gnus with maildir or MH, you should really use the native |
| 104 | Gnus back end @code{nnmairix} instead, since it is more tightly |
| 105 | integrated into Gnus and has more features. |
| 106 | |
| 107 | @node Configuring mairix |
| 108 | @chapter Configuring mairix |
| 109 | |
| 110 | Setting up mairix is easy: simply create a @file{.mairixrc} file with |
| 111 | (at least) the following entries: |
| 112 | |
| 113 | @example |
| 114 | # Your mail base folder |
| 115 | base=~/Mail |
| 116 | @end example |
| 117 | |
| 118 | This is the base folder for your mails. All the following directories, |
| 119 | except the one for the database, are relative to this base folder. |
| 120 | |
| 121 | @example |
| 122 | mbox = ... your mbox files which should be indexed ... |
| 123 | maildir= ... your maildir folders which should be indexed ... |
| 124 | mh= ... your nnml/mh folders which should be indexed ... |
| 125 | @end example |
| 126 | |
| 127 | Specify all your maildir/nnml folders and mbox files (relative to the |
| 128 | base directory!) you want to index with mairix. Use colons to separate |
| 129 | different files. See the man-page for @code{mairixrc} for details. |
| 130 | |
| 131 | @example |
| 132 | mformat = mbox |
| 133 | database = ... location of database file ... |
| 134 | @end example |
| 135 | |
| 136 | This chooses @code{mbox} as the output format for the mairix search |
| 137 | results. Currently, this is the supported format by mairix.el, but |
| 138 | technically it should be possible to also use maildir or mh; it's just |
| 139 | not tested (yet). |
| 140 | |
| 141 | You should make sure that you don't accidentally index the search |
| 142 | results produced by mairix. This can be done by pointing |
| 143 | `mairix-file-path' to a directory which is surely not indexed by mairix. |
| 144 | Another possibility is to use something like |
| 145 | |
| 146 | @example |
| 147 | omit = mairix* |
| 148 | @end example |
| 149 | |
| 150 | in the @file{.mairixrc} file, and prefix every search file you use with |
| 151 | ``mairix''. |
| 152 | |
| 153 | @example |
| 154 | database = /home/user/.mairixdatabase |
| 155 | @end example |
| 156 | |
| 157 | This specifies the name of the database file. Note that this is not |
| 158 | relative to the @code{base} folder. |
| 159 | |
| 160 | See the man page for @code{mairixrc} for details and further options, |
| 161 | especially regarding wildcard usage, which may be a little different |
| 162 | than you are used to. |
| 163 | |
| 164 | Now simply call @code{mairix} to create the index for the first time. |
| 165 | Note that this may take a few minutes, but every following index will do |
| 166 | the updates incrementally and hence is very fast. |
| 167 | |
| 168 | @node Setting up mairix.el |
| 169 | @chapter Setting up mairix.el |
| 170 | |
| 171 | First, put @code{mairix.el} in your Emacs search path and put |
| 172 | @code{(require 'mairix)} into your @file{.emacs} file. Then, use |
| 173 | @kbd{M-x customize-group mairix RET} to set your preferences for |
| 174 | mairix.el. The most important items are @emph{Mairix File Path}, |
| 175 | @emph{Mairix Search File} and @emph{Mairix Mail Program}. The latter |
| 176 | specifies which mail program should be used to display the mairix search |
| 177 | results. Currently, RMail, Gnus with mbox files, and VM are supported. |
| 178 | If you use Gnus with maildir or mh, use the native Gnus back end |
| 179 | nnmairix instead. |
| 180 | |
| 181 | If you use another Emacs mail program which is not yet supported by |
| 182 | mairix.el, it is pretty easy to integrate it. @xref{Extending |
| 183 | mairix.el}, on how to integrate it into mairix.el. |
| 184 | |
| 185 | Now you should be ready to go. @xref{Using mairix.el}, for the available |
| 186 | commands. |
| 187 | |
| 188 | @node Using mairix.el |
| 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 mairix.el |
| 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 | |
| 350 | |
| 351 | @bye |
| 352 | |
| 353 | @ignore |
| 354 | arch-tag: cb81470f-e080-489d-bb67-0d11516b63b9 |
| 355 | @end ignore |