Commit | Line | Data |
---|---|---|
351ecdb2 CY |
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 | |
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 | |
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 | |
f1902fc0 MB |
347 | |
348 | @ignore | |
349 | arch-tag: cb81470f-e080-489d-bb67-0d11516b63b9 | |
350 | @end ignore |