doc/emacs: add docstring for notmuch-unthreaded-result-format.

[notmuch] / doc / notmuch-emacs.rst

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 189a51ad96f47552ffed0a27ec99677a9da84d98..e69bd23da5cf69b343ff69ad4506fc408ab5e0a2 100644 (file)
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -220,8 +220,41 @@ 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)")))
+
+   See also :emacsvar:`notmuch-tree-result-format` and
+   :emacsvar:`notmuch-unthreaded-result-format`.
 
 .. emacsvar:: notmuch-search-oldest-first
 
@@ -445,6 +478,41 @@ tags.
 As is the case with :ref:`notmuch-search`, the presentation of results
 can be controlled by the variable ``notmuch-search-oldest-first``.
 
+.. emacsvar:: notmuch-tree-result-format
+
+   |docstring::notmuch-tree-result-format|
+
+   The following example shows how to optionally display recipients instead
+   of authors for sent mail (assuming the user is named Mustermann).
+
+   .. code:: lisp
+
+      (defun -notmuch-authors-or-to (format-string result)
+        (let* ((headers (plist-get result :headers))
+               (to (plist-get headers :To))
+               (author (plist-get headers :From))
+               (face (if (plist-get result :match)
+                         'notmuch-tree-match-author-face
+                       'notmuch-tree-no-match-author-face)))
+          (propertize
+           (format format-string
+                   (if (string-match "Mustermann" author)
+                       (concat "To:" (notmuch-tree-clean-address to))
+                     author))
+           'face face)))
+
+      (setq notmuch-tree-result-format
+            '(("date" . "%12s  ")
+              (-notmuch-authors-or-to . "%-20.20s")
+              ((("tree" . "%s")
+                ("subject" . "%s"))
+               . " %-54s ")
+              ("tags" . "(%s)")))
+
+   See also :emacsvar:`notmuch-search-result-format` and
+   :emacsvar:`notmuch-unthreaded-result-format`.
+
+
 .. _notmuch-unthreaded:
 
 notmuch-unthreaded
@@ -456,6 +524,13 @@ is presented.
 
 Keybindings are the same as :any:`notmuch-tree`.
 
+.. emacsvar:: notmuch-unthreaded-result-format
+
+   |docstring::notmuch-unthreaded-result-format|
+
+   See also :emacsvar:`notmuch-search-result-format` and
+   :emacsvar:`notmuch-tree-result-format`.
+
 Global key bindings
 ===================