From c858651d0c70bb7afcd8023140cdf46c650f7645 Mon Sep 17 00:00:00 2001 From: djcb Date: Sat, 11 May 2019 13:27:39 +0300 Subject: [PATCH] doc: document the new contacts handling mu4e.texi and NEWS.org --- NEWS.org | 20 +++++++++++ mu4e/mu4e.texi | 91 +++++++++++++++++++++++++------------------------- 2 files changed, 66 insertions(+), 45 deletions(-) diff --git a/NEWS.org b/NEWS.org index 9327203e..8c72e483 100644 --- a/NEWS.org +++ b/NEWS.org @@ -1,6 +1,26 @@ #+STARTUP:showall * NEWS (user visible changes) +* 1.4 (unreleased) + +*** mu + + - The contacts cache (as uses in ~mu cfind~ and mu4e contact-completion is now + stored as part of the Xapian database rather than as a separate file. + +*** mu4e + + - In many cases, ~mu4e~ used to get /all/ contacts after each indexing + operation; this was slow for some users, so we have updated this to only + get the contacts that have changed since the last time ~mu4e~ received that + information. + + We also moved sorting the contacts to the mu-side, which speeds things up + further. However, as a side-effect of this, ~mu4e-contacts-rewrite-function~ + and ~mu4e-compose-complete-ignore-address-regexp~ have been obsoleted; users + of those should migrate to ~mu4e-contact-process-function~; see its + docstring for details. + ** 1.2 After a bit over a year since version 1.0, here is version 1.2. This is diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi index f70fd1a9..d9a9f6e0 100644 --- a/mu4e/mu4e.texi +++ b/mu4e/mu4e.texi @@ -1120,16 +1120,16 @@ An example message view: Date: Mon 19 Jan 2004 09:39:42 AM EET Maildir: /inbox Attachments(2): [1]DSCN4961.JPG(1.3M), [2]DSCN4962.JPG(1.4M) - + Hi Julia, - + Some pics from our trip to Cerin Amroth. Enjoy! - + All the best, Randy. - + On Sun 21 Dec 2003 09:06:34 PM EET, Julia wrote: - + [....] @end verbatim @end cartouche @@ -1571,9 +1571,9 @@ functionality is available, as well some @t{mu4e}-specifics. Its major mode is To: Wally the Walrus Subject: Re: Eau-qui d'eau qui? --text follows this line-- - + On Mon 16 Jan 2012 10:18:47 AM EET, Wally the Walrus wrote: - + > Hi Rupert, > > Dude - how are things? @@ -2574,8 +2574,8 @@ when starting; see the discussion in the previous section. :leave-func (lambda () (mu4e-message "Leaving Private context")) ;; we match based on the contact-fields of the message :match-func (lambda (msg) - (when msg - (mu4e-message-contact-field-matches msg + (when msg + (mu4e-message-contact-field-matches msg :to "aliced@@home.example.com"))) :vars '( ( user-mail-address . "aliced@@home.example.com" ) ( user-full-name . "Alice Derleth" ) @@ -2615,12 +2615,12 @@ when starting; see the discussion in the previous section. ;; set `mu4e-context-policy` and `mu4e-compose-policy` to tweak when mu4e should ;; guess or ask the correct context, e.g. - ;; start with the first (default) context; + ;; start with the first (default) context; ;; default is to ask-if-none (ask when there's no context yet, and none match) ;; (setq mu4e-context-policy 'pick-first) ;; compose with the current context is no context matches; - ;; default is to ask + ;; default is to ask ;; (setq mu4e-compose-context-policy nil) @end lisp @@ -2629,25 +2629,25 @@ A couple of notes about this example: @item You can manually switch the context use @code{M-x mu4e-context-switch}, by default bound to @kbd{;} in headers, view and main mode. The current context appears in the mode-line. -@item Normally, @code{M-x mu4e-context-switch} does not call the enter or +@item Normally, @code{M-x mu4e-context-switch} does not call the enter or leave functions if the 'new' context is the same as the old one. However, with a prefix-argument (@kbd{C-u}), you can force @t{mu4e} to invoke those function even in that case. -@item The function @code{mu4e-context-current} returns the current-context; +@item The function @code{mu4e-context-current} returns the current-context; the current context is also visible in the mode-line when in headers, view or main mode. -@item You can set any kind of variable; including settings for mail servers etc. +@item You can set any kind of variable; including settings for mail servers etc. However, settings such as @code{mu4e-maildir} and @code{mu4e-mu-home} are not changeable after they have been set without quitting @t{mu4e} first. -@item @code{leave-func} (if defined) for the context we are leaving, is invoked +@item @code{leave-func} (if defined) for the context we are leaving, is invoked before the @code{enter-func} (if defined) of the context we are entering. @item @code{enter-func} (if defined) is invoked before setting the variables. @item @code{match-func} (if defined) is invoked just before @code{mu4e-compose-pre-hook}. @item See the variables @code{mu4e-context-policy} and -@code{mu4e-compose-context-policy} to tweak what @t{mu4e} should do when +@code{mu4e-compose-context-policy} to tweak what @t{mu4e} should do when no context matches (or if you always want to be asked). -@item Finally, be careful to get the quotations right --- backticks, single quotes +@item Finally, be careful to get the quotations right --- backticks, single quotes and commas and note the '.' between variable name and its value. @end itemize @@ -3128,41 +3128,42 @@ As a fairly useless example, suppose we insist on reading @t{mu4e} as @node Contact functions @section Contact functions -It can sometimes be useful to rewrite the contact information that -@t{mu4e} provides, for example to convert them to some standardized -format, or to fix spelling errors. And sometimes, you may want to remove -certain contacts altogether. +It can sometimes be useful to discard or rewrite the contact +information that @t{mu4e} provides, for example to fix spelling +errors, or omit unwanted contacts. -For this, @t{mu4e} provides @code{mu4e-contact-rewrite-function}, which -passes each contact to a user-provided function, which is expected to -return either the possibly rewritten contact or @code{nil} to remove the -contact from the list --- note that the latter can also be achieved using -@code{mu4e-compose-complete-ignore-address-regexp}. +To handle this, @t{mu4e} provides +@code{mu4e-contact-process-function}, which, if defined, is applied to +each contact. If the result is @t{nil}, the contact is discarded, +otherwise the (modified or not) contact information is used. -Each of the contacts are property-lists (`plists'), with properties -@code{:name} (which may be @code{nil}), and @code{:mail}, and a number -of other properties which you should return unchanged. +Each contact is a full e-mail address as you would see in a +contact-field of an e-mail message, e.g., +@verbatim +"Foo Bar" +@end verbatim +or +@verbatim +cuux@example.com +@end verbatim -Let's look at an example: +An example @code{mu4e-contact-process-function} might look like: @lisp -(defun my-rewrite-function (contact) - (let ((name (or (plist-get contact :name) "")) - (mail (plist-get contact :mail))) - (cond - ;; jonh smiht --> John Smith - ((string= "jonh smiht" name) - (plist-put contact :name "John C. Smith") - contact) - ;; remove evilspammer from the contacts list - ((string= "evilspammer@@example.com" mail) nil) - ;; others stay as the are - (t contact)))) +(defun my-contact-processor (contact) + (cond + ;; remove unwanted + ((string-match-p "evilspammer@@example.com" contact) nil) + ((string-match-p "noreply" contact) nil) + ;; + ;; jonh smiht --> John Smith + ((string-match "jonh smiht" contact) + (replace-regexp-in-string "jonh smiht" "John Smith" contact)) + (t contact))) -(setq mu4e-contact-rewrite-function 'my-rewrite-function) +(setq mu4e-contact-process-function 'my-contact-processor) @end lisp -This function is called for each of your contacts. @node Utility functions @section Utility functions @@ -3329,7 +3330,7 @@ such as @file{~/.emacs.d/init.el}) the following @emph{after} the (setq mu4e-compose-complete-addresses nil) (setq bbdb-mua-pop-up t) (setq bbdb-mua-pop-up-window-size 5) - (setq mu4e-view-show-addresses t) + (setq mu4e-view-show-addresses t) @end lisp @noindent