doc: document the new contacts handling

mu4e.texi and NEWS.org

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

mu4e/mu4e.texi

@@ -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
+It can sometimes be useful to discard or rewrite the contact
-@t{mu4e} provides, for example to convert them to some standardized
+information that @t{mu4e} provides, for example to fix spelling
-format, or to fix spelling errors. And sometimes, you may want to remove
+errors, or omit unwanted contacts.
-certain contacts altogether.
 
-For this, @t{mu4e} provides @code{mu4e-contact-rewrite-function}, which
+To handle this, @t{mu4e} provides
-passes each contact to a user-provided function, which is expected to
+@code{mu4e-contact-process-function}, which, if defined, is applied to
-return either the possibly rewritten contact or @code{nil} to remove the
+each contact. If the result is @t{nil}, the contact is discarded,
-contact from the list --- note that the latter can also be achieved using
+otherwise the (modified or not) contact information is used.
-@code{mu4e-compose-complete-ignore-address-regexp}.
 
-Each of the contacts are property-lists (`plists'), with properties
+Each contact is a full e-mail address as you would see in a
-@code{:name} (which may be @code{nil}), and @code{:mail}, and a number
+contact-field of an e-mail message, e.g.,
-of other properties which you should return unchanged.
+@verbatim
+"Foo Bar" <foo.bar@example.com>
+@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)
+(defun my-contact-processor (contact)
-  (let ((name (or (plist-get contact :name) ""))
+  (cond
-	 (mail (plist-get contact :mail)))
+    ;; remove unwanted
-    (cond
+    ((string-match-p "evilspammer@@example.com" contact) nil)
-      ;; jonh smiht --> John Smith
+    ((string-match-p "noreply" contact) nil)
-      ((string= "jonh smiht" name) 
+    ;;
-	(plist-put contact :name "John C. Smith")
+    ;; jonh smiht --> John Smith
-	contact) 
+    ((string-match "jonh smiht" contact)
-      ;; remove evilspammer from the contacts list
+       (replace-regexp-in-string "jonh smiht" "John Smith" contact))
-      ((string= "evilspammer@@example.com" mail) nil)
+    (t contact)))
-      ;; others stay as the are
-      (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