Mercurial > emacs
annotate doc/misc/mairix-el.texi @ 101327:b0eef2ac5a59
(completion--insert-strings): Fix up computation of
column position which manifested e.g. in proced's signal completion.
author | Stefan Monnier <monnier@iro.umontreal.ca> |
---|---|
date | Wed, 21 Jan 2009 21:20:55 +0000 |
parents | cb5d2387102c |
children | 9bcea07061a8 |
rev | line source |
---|---|
97101 | 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 | |
100974 | 9 Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc. |
97101 | 10 |
11 @quotation | |
12 Permission is granted to copy, distribute and/or modify this document | |
99709
6de181810d0f
Relicense all texi files under FDL 1.3 or later.
Glenn Morris <rgm@gnu.org>
parents:
97106
diff
changeset
|
13 under the terms of the GNU Free Documentation License, Version 1.3 or |
97101 | 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 | |
97106 | 347 |
348 @ignore | |
349 arch-tag: cb81470f-e080-489d-bb67-0d11516b63b9 | |
350 @end ignore |