Mercurial > emacs
annotate doc/misc/mairix-el.texi @ 111173:c7d5564f0621
Move ns-win.el's rather wacky menu adjustments to menu-bar.el.
* lisp/term/ns-win.el: Do not require easymenu.
(menu-bar-edit-menu) <copy, paste, paste-from-menu, separator-undo>:
<spell>: Move adjustments to menu-bar.el.
* lisp/menu-bar.el (menu-bar-edit-menu) <copy, paste, paste-from-menu>:
<separator-undo, spell>: Move ns-win's adjustments here.
* lisp/loadup.el [ns]: Do not load easymenu.
* src/Makefile.in (SOME_MACHINE_LISP): Remove easymenu.elc.
* lib-src/makefile.w32-in (OTHER_PLATFORM_SUPPORT): Remove easymenu.elc.
author | Glenn Morris <rgm@gnu.org> |
---|---|
date | Sun, 24 Oct 2010 17:48:26 -0700 |
parents | a91e94388547 |
children | 376148b31b5e |
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 | |
106815 | 9 Copyright @copyright{} 2008, 2009, 2010 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 | |
109274
a91e94388547
Minor doc/misc/*.texi direntry fixes.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
27 * Mairix: (mairix-el). Emacs interface to the Mairix mail indexer. |
97101 | 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 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
39 @contents |
97101 | 40 |
41 @node Top | |
42 @top mairix.el - Mairix interface for Emacs | |
43 | |
44 Mairix is a tool for indexing and searching words in locally stored | |
45 mail. It was written by Richard Curnow and is licensed under the | |
46 GPL. | |
47 | |
48 @code{mairix.el} is an interface to the mairix search engine. It allows you to | |
49 call mairix with a search term, easily create searches based on the | |
50 currently displayed mail, save regularly used searches in your | |
51 @file{.emacs} for future use and lets you call mairix for updating the | |
52 database. | |
53 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
54 @ifnottex |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
55 @insertcopying |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
56 @end ifnottex |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
57 |
97101 | 58 @menu |
59 * About mairix and mairix.el:: About the mairix search engine and mairix.el | |
60 * Configuring mairix:: How to configure mairix | |
61 * Setting up mairix.el:: Set up mairix.el | |
62 * Using mairix.el:: List of interactive functions | |
63 * Extending mairix.el:: Support your favorite mail reader! | |
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 | |
71 GPL. Mairix comes with most popular GNU/Linux distributions, but it also | |
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 | |
249 currently displayed article, i.e. the available fields will be filled | |
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 | |
349 | |
350 | |
351 @bye | |
97106 | 352 |
353 @ignore | |
354 arch-tag: cb81470f-e080-489d-bb67-0d11516b63b9 | |
355 @end ignore |