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
|
|
9 Copyright @copyright{} 2008 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.2 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
|
|
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
|