From: David Bremner <david@tethera.net>
Date: Sat, 16 Jul 2022 21:22:24 +0000 (-0400)
Subject: doc/emacs: add docstring and example for n-search-result-format
X-Git-Tag: 0.37_rc0~26
X-Git-Url: https://git.cworth.org/git?p=notmuch;a=commitdiff_plain;h=2b10a56c78af816b902aee7fdfecb357605539f5

doc/emacs: add docstring and example for n-search-result-format

When the ability to use functions was added, this example was confined
to a commit message, which is not user discoverable.
---

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 189a51ad..49111d28 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -220,8 +220,38 @@ variables.
 
 .. emacsvar:: notmuch-search-result-format
 
-    Control how each thread of messages is presented in the
-    ``notmuch-show-mode`` buffer
+   |docstring::notmuch-search-result-format|
+
+   If the car of an element in notmuch-search-result-format is a
+   function, insert the result of calling the function into the buffer.
+
+   This allows a user to generate custom fields in the output of a
+   search result. For example, with the following settings, the first
+   few characters on each line of the search result are used to show
+   information about some significant tags associated with the thread.
+
+   .. code:: lisp
+
+      (defun -notmuch-result-flags (format-string result)
+        (let ((tags-to-letters '(("flagged" . "!")
+                                 ("unread" . "u")
+                                 ("mine" . "m")
+                                 ("sent" . "s")
+                                 ("replied" . "r")))
+              (tags (plist-get result :tags)))
+          (format format-string
+                  (mapconcat (lambda (t2l)
+                               (if (member (car t2l) tags)
+                                   (cdr t2l)
+                                 " "))
+                             tags-to-letters ""))))
+
+      (setq notmuch-search-result-format '((-notmuch-result-flags . "%s ")
+                                           ("date" . "%12s ")
+                                           ("count" . "%9s ")
+                                           ("authors" . "%-30s ")
+                                           ("subject" . "%s ")
+                                           ("tags" . "(%s)")))
 
 .. emacsvar:: notmuch-search-oldest-first