mu4e: Contact completion - better sorting / display

Improve the contact-sorting algorithm, and make it better cooperate with
completion-at-point functions.

Also deal better with broken rewritten contacts, and document how
rewriting should done (docstrings and reference doc).

mu4e/mu4e.texi

@@ -12,7 +12,7 @@
 @c %**end of header
 
 @copying
-Copyright @copyright{} 2012-2015 Dirk-Jan C. Binnema
+Copyright @copyright{} 2012-2016 Dirk-Jan C. Binnema
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -2885,7 +2885,11 @@ 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}.
 
-Let's look at an example.
+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.
+
+Let's look at an example:
 
 @lisp
 (defun my-rewrite-function (contact)
@@ -2893,7 +2897,9 @@ Let's look at an example.
 	 (mail (plist-get contact :mail)))
     (cond
       ;; jonh smiht --> John Smith
-      ((string= "jonh smiht" name) (list :name "John Smith" :mail mail)) 
+      ((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