mu4e: default to mu4e-shr2text when available

Make shr the default renderer for rich-text emails, if shr is
available. Update the documentation.

mu4e/mu4e-contrib.el

@@ -51,25 +51,6 @@
 
 ;;;
 
-(defun mu4e-shr2text ()
-  "Html to text using the shr engine; this can be used in
-`mu4e-html2text-command' in a new enough emacs. Based on code by
-Titus von der Malsburg."
-  (interactive)
-  (let ((dom (libxml-parse-html-region (point-min) (point-max)))
-	 ;; When HTML emails contain references to remote images,
-	 ;; retrieving these images leaks information. For example,
-	 ;; the sender can see when I openend the email and from which
-	 ;; computer (IP address). For this reason, it is preferrable
-	 ;; to not retrieve images.
-	 ;; See this discussion on mu-discuss:
-	 ;; https://groups.google.com/forum/#!topic/mu-discuss/gr1cwNNZnXo
-	(shr-inhibit-images t))
-    (erase-buffer)
-    (shr-insert-document dom)
-    (goto-char (point-min))))
-
-
 ;;; Bookmark handlers
 ;;
 ;;  Allow bookmarking a mu4e buffer in regular emacs bookmarks.

mu4e/mu4e-message.el

@@ -34,22 +34,26 @@
 (require 'html2text)
 
 
-(defcustom mu4e-html2text-command 'html2text
+(defcustom mu4e-html2text-command
+  (if (fboundp 'shr-insert-document) 'mu4e-shr2text 'html2text)
+  
   "Either a shell command or a function that converts from html to plain text.
 
 If it is a shell-command, the command reads html from standard
 input and outputs plain text on standard output. If you use the
-htmltext program, it's recommended you use \"html2text -utf8 -width
+htmltext program, it's recommended you use \"html2text -utf8
-72\". Alternatives are the python-based html2markdown, w3m and on
+-width 72\". Alternatives are the python-based html2markdown, w3m
-MacOS you may want to use textutil.
+and on MacOS you may want to use textutil.
 
 It can also be a function, which takes the current buffer in html
 as input, and transforms it into html (like the `html2text'
 function).
 
-In both cases, the output is expected to be in utf-8 encoding.
+In both cases, the output is expected to be in UTF-8 encoding.
 
-The default is emacs' built-in `html2text' function."
+Newer emacs has the shr renderer, and when its available,
+conversion defaults `mu4e-shr2text'; otherwise, the default is
+emacs' built-in `html2text' function."
   :type '(choice string function)
   :group 'mu4e-view)
 
@@ -259,4 +263,22 @@ point in eiter the headers buffer or the view buffer."
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 
+(defun mu4e-shr2text ()
+  "Html to text using the shr engine; this can be used in
+`mu4e-html2text-command' in a new enough emacs. Based on code by
+Titus von der Malsburg."
+  (interactive)
+  (let ((dom (libxml-parse-html-region (point-min) (point-max)))
+	 ;; When HTML emails contain references to remote images,
+	 ;; retrieving these images leaks information. For example,
+	 ;; the sender can see when I openend the email and from which
+	 ;; computer (IP address). For this reason, it is preferrable
+	 ;; to not retrieve images.
+	 ;; See this discussion on mu-discuss:
+	 ;; https://groups.google.com/forum/#!topic/mu-discuss/gr1cwNNZnXo
+	 (shr-inhibit-images t))
+    (erase-buffer)
+    (shr-insert-document dom)
+    (goto-char (point-min))))
+
 (provide 'mu4e-message)

mu4e/mu4e.texi

@@ -1278,10 +1278,32 @@ case where the text-part is only a short blurb telling you to use the
 html-version; see @code{mu4e-view-html-plaintext-ratio-heuristic}},
 @t{mu4e} tries to convert the html into plain-text for display.
 
-The default way to do that is to use the @command{emacs} built-in
+With emacs 24.4 or newer, this defaults to @code{mu4e-shr2text}, which
-@code{html2text} function. However, you can set the variable
+uses the built-in @t{shr} renderer. For older emacs versions, this
-@code{mu4e-html2text-command} to a either a shell command or a function
+defaults to the built-in @code{html2text} function. In practice, the
+latter gives much better results.
+
+If you use @code{mu4e-shr2text}, it might be useful to emulate some of
+the @t{shr} key bindings, with something like:
+@lisp
+(add-hook 'mu4e-view-mode-hook
+  (lambda()
+    ;; try to emulate some of the eww key-bindings
+    (local-set-key (kbd "<tab>") 'shr-next-link)
+    (local-set-key (kbd "<backtab>") 'shr-previous-link)))
+@end lisp
+
+If you're using a dark theme, and the messages are hard to read, it can help to change
+the luminosity, e.g.:
+@lisp
+(setq shr-color-visible-luminance-min 80)
+@end lisp
+
+If your emacs does not have @t{shr} yet, it can be useful to use a
+custom method. For that, you can set the variable
+@code{mu4e-html2text-command} to either a shell command or a function
 instead.
+ 
 
 @subsection Html2text commands
 
@@ -1321,32 +1343,6 @@ If @code{mu4e-html2text-command} refers to an elisp function, it is
 expected to take the current buffer in html as input, and transform it
 into text (just like the @code{html2text} function).
 
-For example, emacs 24.4 and later versions include the @code{eww}
-browser which uses the @code{shr} html renderer; @t{mu4e} includes a
-little snippet to uses this with @code{mu4e-html2text-command}; for
-this, add the following to your configuration:
-
-@lisp
-(require 'mu4e-contrib)
-(setq mu4e-html2text-command 'mu4e-shr2text)
-@end lisp
-
-If you use the @code{mu4e-shr2text}, it might be useful to emulate some
-of the @t{shr} key bindings, with something like:
-@lisp
-(add-hook 'mu4e-view-mode-hook
-  (lambda()
-    ;; try to emulate some of the eww key-bindings
-    (local-set-key (kbd "<tab>") 'shr-next-link)
-    (local-set-key (kbd "<backtab>") 'shr-previous-link)))
-@end lisp
-
-If you're using a dark theme, and the messages are hard to read, it can help to change
-the luminosity, e.g.:
-@lisp
-(setq shr-color-visible-luminance-min 80)
-@end lisp
-
 @node MSGV Crypto
 @section Crypto
 
@@ -3294,9 +3290,6 @@ customize.
 ;; a  list of user's e-mail addresses
 (setq mu4e-user-mail-address-list '("foo@@bar.example.com" "cuux@@example.com")
 
-;; when you want to use some external command for text->html
-;; conversion, e.g. the 'html2text' program
-;; (setq mu4e-html2text-command "html2text")
 
 ;; the headers to show in the headers list -- a pair of a field
 ;; and its width, with `nil' meaning 'unlimited'
@@ -3671,7 +3664,8 @@ like Gmail does?} Yes -- see @ref{Including related messages}.
 @item @emph{There seem to be a lot of duplicate messages -- how can I get rid
 of them?} See @ref{Skipping duplicates}.
 @item @emph{How can I use the @t{eww} browser to view rich-text messages?}
-See @ref{Html2text functions}.
+With a new enough emacs, this happens automatically. See @ref{Html2text
+functions} for some details.
 @item @emph{Some messages are almost unreadable in emacs - can I view them in
 an external web browser?} Indeed, airlines often send messages that
 heavily depend on html and are hard to digest inside emacs. Fortunately,