mu4e: make it easy to use shr for viewing rich text message

new emacs versions have the shr html renderer; we can use it to render
rich text messages. And some snippet to do so, and document it.

mu4e/mu4e-contrib.el

@@ -39,6 +39,19 @@
   (mu4e-headers-mark-all-unread-read)
   (mu4e-mark-execute-all t))
 
+;;;
+
+(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))))
+    (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

@@ -37,12 +37,11 @@
 (defcustom mu4e-html2text-command 'html2text
   "Either a shell command or a function that converts from html to plain text.
 
-If it is a shell-command, the command has to read html from stdin
+If it is a shell-command, the command reads html from standard
-and output plain text on stdout. If this is not defined, the emacs
+input and outputs plain text on standard output. If you use the
-`html2text' tool will be used when faced with html-only
+htmltext program, it's recommended you use \"html2text -utf8 -width
-messages. If you use htmltext, it's recommended you use \"html2text
+72\". Alternatives are the python-based html2markdown, w3m and on
--utf8 -width 72\". Alternatives are the python-based html2markdown,
+MacOS you may want to use textutil.
-w3m 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'

mu4e/mu4e.texi

@@ -1196,16 +1196,24 @@ is used for images.
 both a plain-text and html (rich-text) versions of the body-text. You can
 change this by setting @code{mu4e-view-prefer-html} to @t{t}.
 
-If there is only an html-version, or if the plain-text version is too short in
+If there is only an html-version, or if the plain-text version is too
-comparison with the html part@footnote{this is for the case where the
+short in comparison with the html part@footnote{this is for the case
-text-part only warns that you should use the html-version}, @t{mu4e} tries to
+where the text-part only warns that you should use the html-version},
-convert the html into plain-text for display. The default way to do that is to
+@t{mu4e} tries to convert the html into plain-text for display.
-use the @command{emacs} built-in @code{html2text} function. However, you can
-set the variable @code{mu4e-html2text-command} to some external program
-instead. This program is expected to take html from standard input and write
-plain text in @t{UTF-8} encoding on standard output.
 
-An example of such a program is the program that is actually @emph{called}
+The default way to do that is to use the @command{emacs} built-in
+@code{html2text} function. However, you can set the variable
+@code{mu4e-html2text-command} to a either a shell command or a function
+instead.
+
+@subsection Html2text commands
+
+If @code{mu4e-html2text-command} is a shell command, it is expected to
+take html from standard input and write plain text in @t{UTF-8} encoding
+on standard output.
+
+An example of such a program is the program that is actually
+@emph{called}
 @t{html2text}@footnote{@url{http://www.mbayer.de/html2text/}}. After
 installation, you can set it up with something like the following:
 
@@ -1228,6 +1236,24 @@ On MacOS, there is a program called @t{textutil} as yet another alternative:
   "textutil -stdin -format html -convert txt -stdout")
 @end lisp
 
+@subsection Html2text functions
+@anchor{Html2text functions}
+
+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 html (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
+
+
 @node MSGV Crypto
 @section Crypto
 
@@ -3106,11 +3132,12 @@ messages}.
 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}.
 @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
+an external web browser?} Indeed, airlines often send messages that
-depend on html and are hard to digest inside emacs. Fortunately, there's an
+heavily depend on html and are hard to digest inside emacs. Fortunately,
-@emph{action} (@ref{Adding an action in the message view}) defined for
+there's an @emph{action} (@ref{Adding an action in the message view})
-this. Simply add to your configuration:
+defined for this. Simply add to your configuration:
 @lisp
 (add-to-list 'mu4e-view-actions
   '("ViewInBrowser" . mu4e-action-view-in-browser) t)