emacs: document/defcustom notmuch-multipart/alternative-discouraged

This variable is important for people who want to change the default
behaviour when displaying multipart/alternative messages.  Previously
it was undocumented.  Add a defcustom to help users and copy some
documentation from the wiki. The usual machinery of re-using
docstrings is a bit tricky to use here because it mangles the example
lisp code, and the link to the info node should not be in e.g. the
html page.

Add a simple test to make sure the switch from defvar to defcustom did
not break something obvious.

1 files changed, 21 insertions, 0 deletions

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 67dbfc2b..ec7dee78 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -238,6 +238,27 @@ Display of messages can be controlled by the following variables
 :index:`notmuch-show-header-line`
        |docstring::notmuch-show-header-line|
 
+:index:`notmuch-multipart/alternative-discouraged`
+
+   Which mime types to hide by default for multipart messages.
+
+   Can either be a list of mime types (as strings) or a function
+   mapping a plist representing the current message to such a list.
+   The following example function would discourage `text/html` and
+   `multipart/related` generally, but discourage `text/plain` should
+   the message be sent from `whatever@example.com`.
+
+   .. code:: lisp
+
+      (defun my--determine-discouraged (msg)
+        (let* ((headers (plist-get msg :headers))
+               (from (or (plist-get headers :From) "")))
+          (cond
+           ((string-match "whatever@example.com" from)
+            (list "text/plain"))
+           (t
+            (list "text/html" "multipart/related")))))
+
 .. _show-copy:
 
 Copy to kill-ring