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 | |
6bc383b1 | 9 | Copyright @copyright{} 2008--2014 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 | 14 | any later version published by the Free Software Foundation; with no |
551a89e1 | 15 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
351ecdb2 CY |
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 | 57 | @menu |
55f612f0 GM |
58 | * About:: About the mairix search engine and mairix.el. |
59 | * Configuring mairix:: How to configure mairix. | |
60 | * Setting up the mairix interface:: Set up mairix.el. | |
61 | * Using:: List of interactive functions | |
62 | * Extending:: Support your favorite mail reader! | |
8ee70028 | 63 | * GNU Free Documentation License:: The license for this documentation. |
351ecdb2 CY |
64 | @end menu |
65 | ||
55f612f0 | 66 | @node About |
351ecdb2 CY |
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} | |
55f612f0 | 101 | (@pxref{Extending}). |
351ecdb2 CY |
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 | ||
55f612f0 GM |
168 | @node Setting up the mairix interface |
169 | @chapter Setting up the mairix interface | |
351ecdb2 CY |
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 | |
55f612f0 GM |
182 | mairix.el, it is pretty easy to integrate it. @xref{Extending}, |
183 | on how to integrate it into mairix.el. | |
351ecdb2 | 184 | |
55f612f0 | 185 | Now you should be ready to go. @xref{Using}, for the available commands. |
351ecdb2 | 186 | |
55f612f0 | 187 | @node Using |
351ecdb2 CY |
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 | |
1df7defd | 248 | currently displayed article, i.e., the available fields will be filled |
351ecdb2 CY |
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' | |
4181427f | 310 | is @code{nil} (the default), mairix will be called in a subprocess so Emacs |
351ecdb2 CY |
311 | will still be usable while the update is done. |
312 | ||
313 | @end table | |
314 | ||
315 | ||
55f612f0 | 316 | @node Extending |
351ecdb2 CY |
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 | ||
8ee70028 GM |
348 | @node GNU Free Documentation License |
349 | @appendix GNU Free Documentation License | |
350 | @include doclicense.texi | |
351ecdb2 CY |
351 | |
352 | @bye |