Commit | Line | Data |
---|---|---|
351ecdb2 CY |
1 | \input texinfo.tex |
2 | ||
3 | @setfilename ../../info/mairix-el | |
4 | @settitle Emacs Interface for Mairix | |
5 | ||
681ebc33 | 6 | @documentencoding UTF-8 |
351ecdb2 CY |
7 | |
8 | @copying | |
ab422c4d | 9 | Copyright @copyright{} 2008--2013 Free Software Foundation, Inc. |
351ecdb2 CY |
10 | |
11 | @quotation | |
12 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 13 | under the terms of the GNU Free Documentation License, Version 1.3 or |
351ecdb2 CY |
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 | |
6bf430d1 | 20 | modify this GNU manual.'' |
351ecdb2 CY |
21 | @end quotation |
22 | @end copying | |
23 | ||
0c973505 | 24 | @dircategory Emacs network features |
351ecdb2 | 25 | @direntry |
62e034c2 | 26 | * Mairix: (mairix-el). Emacs interface to the Mairix mail indexer. |
351ecdb2 CY |
27 | @end direntry |
28 | ||
29 | @titlepage | |
f99f1641 | 30 | @title mairix.el---Mairix interface for Emacs |
351ecdb2 CY |
31 | |
32 | @author David Engster | |
33 | @page | |
34 | @vskip 0pt plus 1filll | |
35 | @insertcopying | |
36 | @end titlepage | |
37 | ||
5dc584b5 | 38 | @contents |
351ecdb2 CY |
39 | |
40 | @node Top | |
f99f1641 | 41 | @top mairix.el---Mairix interface for Emacs |
351ecdb2 CY |
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 | ||
5dc584b5 KB |
53 | @ifnottex |
54 | @insertcopying | |
55 | @end ifnottex | |
56 | ||
351ecdb2 CY |
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! | |
8ee70028 | 63 | * GNU Free Documentation License:: The license for this documentation. |
351ecdb2 CY |
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 | |
1df7defd | 71 | GPL@. Mairix comes with most popular GNU/Linux distributions, but it also |
351ecdb2 CY |
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 | |
1df7defd | 249 | currently displayed article, i.e., the available fields will be filled |
351ecdb2 CY |
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 | ||
8ee70028 GM |
349 | @node GNU Free Documentation License |
350 | @appendix GNU Free Documentation License | |
351 | @include doclicense.texi | |
351ecdb2 CY |
352 | |
353 | @bye |