unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* update documentation for notmuch-*-result-format
@ 2022-07-16 21:22 David Bremner
  2022-07-16 21:22 ` [PATCH 1/6] emacs: update defcustom for notmuch-search-result-format David Bremner
                   ` (5 more replies)
  0 siblings, 6 replies; 8+ messages in thread
From: David Bremner @ 2022-07-16 21:22 UTC (permalink / raw)
  To: notmuch

Jon Hurst asked a question [1], and the the answer turned out to be
the existing, but previously undocumented feature of using functions
in format specifiers. This series tries to improve both the
customization and documentation for 3 related variables.

[1]: id:87a699e6wn.fsf@hursts.org.uk


^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH 1/6] emacs: update defcustom for notmuch-search-result-format.
  2022-07-16 21:22 update documentation for notmuch-*-result-format David Bremner
@ 2022-07-16 21:22 ` David Bremner
  2022-07-16 21:22 ` [PATCH 2/6] doc/emacs: add docstring and example for n-search-result-format David Bremner
                   ` (4 subsequent siblings)
  5 siblings, 0 replies; 8+ messages in thread
From: David Bremner @ 2022-07-16 21:22 UTC (permalink / raw)
  To: notmuch

It seems redundant to have the previous example, since the default
value is always show by describe variable.

Enforce more restrictions on the keys in the alist, since arbitrary
strings don't work as field names.

Document that functions can be used in lieu of field names.
---
 emacs/notmuch.el | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index 01a92997..5cb7acd2 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -90,11 +90,11 @@
     ("tags" . "(%s)"))
   "Search result formatting.
 
-Supported fields are: date, count, authors, subject, tags.
-For example:
-    (setq notmuch-search-result-format
-          \\='((\"authors\" . \"%-40s\")
-            (\"subject\" . \"%s\")))
+List of pairs of (field . format-string).  Supported field
+strings are: \"date\", \"count\", \"authors\", \"subject\",
+\"tags\".  It is also supported to pass a function in place of a
+field name. In this case the function is passed the thread
+object (plist) and format string.
 
 Line breaks are permitted in format strings (though this is
 currently experimental).  Note that a line break at the end of an
@@ -102,7 +102,16 @@ currently experimental).  Note that a line break at the end of an
 place it instead at the beginning of the following field.  To
 enter a line break when setting this variable with setq, use \\n.
 To enter a line break in customize, press \\[quoted-insert] C-j."
-  :type '(alist :key-type string :value-type string)
+  :type '(alist
+	  :key-type
+	  (choice
+	   (const :tag "Date" "date")
+	   (const :tag "Count" "count")
+	   (const :tag "Authors" "authors")
+	   (const :tag "Subject" "subject")
+	   (const :tag "Tags" "tags")
+	   function)
+	  :value-type (string :tag "Format"))
   :group 'notmuch-search)
 
 ;; The name of this variable `notmuch-init-file' is consistent with the
-- 
2.35.1

^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH 2/6] doc/emacs: add docstring and example for n-search-result-format
  2022-07-16 21:22 update documentation for notmuch-*-result-format David Bremner
  2022-07-16 21:22 ` [PATCH 1/6] emacs: update defcustom for notmuch-search-result-format David Bremner
@ 2022-07-16 21:22 ` David Bremner
  2022-07-16 21:22 ` [PATCH 3/6] emacs: update defcustom for notmuch-search-result-format David Bremner
                   ` (3 subsequent siblings)
  5 siblings, 0 replies; 8+ messages in thread
From: David Bremner @ 2022-07-16 21:22 UTC (permalink / raw)
  To: notmuch

When the ability to use functions was added, this example was confined
to a commit message, which is not user discoverable.
---
 doc/notmuch-emacs.rst | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

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
 
-- 
2.35.1

^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH 3/6] emacs: update defcustom for notmuch-search-result-format.
  2022-07-16 21:22 update documentation for notmuch-*-result-format David Bremner
  2022-07-16 21:22 ` [PATCH 1/6] emacs: update defcustom for notmuch-search-result-format David Bremner
  2022-07-16 21:22 ` [PATCH 2/6] doc/emacs: add docstring and example for n-search-result-format David Bremner
@ 2022-07-16 21:22 ` David Bremner
  2022-07-16 21:22 ` [PATCH 4/6] doc/emacs: add docstring and example for n-tree-result-format David Bremner
                   ` (2 subsequent siblings)
  5 siblings, 0 replies; 8+ messages in thread
From: David Bremner @ 2022-07-16 21:22 UTC (permalink / raw)
  To: notmuch

It seems redundant to have the previous example, since the default
value is always show by describe variable.

Enforce more restrictions on the keys in the alist, since arbitrary
strings don't work as field names.

Document that functions can be used in lieu of field names.
---
 emacs/notmuch-tree.el | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/emacs/notmuch-tree.el b/emacs/notmuch-tree.el
index 8b246a2e..68614623 100644
--- a/emacs/notmuch-tree.el
+++ b/emacs/notmuch-tree.el
@@ -97,6 +97,15 @@ different kind of arrow point."
   :type '(alist :key-type symbol :value-type string)
   :group 'notmuch-tree)
 
+(defconst notmuch-tree--field-names
+  '(choice :tag "Field"
+	   (const :tag "Date" "date")
+	   (const :tag "Authors" "authors")
+	   (const :tag "Subject" "subject")
+	   (const :tag "Tree" "tree")
+	   (const :tag "Tags" "tags")
+	   (function)))
+
 (defcustom notmuch-tree-result-format
   `(("date" . "%12s  ")
     ("authors" . "%-20s")
@@ -106,7 +115,11 @@ different kind of arrow point."
     ("tags" . "(%s)"))
   "Result formatting for tree view.
 
-Supported fields are: date, authors, subject, tree, tags.
+List of pairs of (field . format-string).  Supported field
+strings are: \"date\", \"authors\", \"subject\", \"tree\",
+\"tags\".  It is also supported to pass a function in place of a
+field-name. In this case the function is passed the thread
+object (plist) and format string.
 
 Tree means the thread tree box graphics. The field may
 also be a list in which case the formatting rules are
@@ -114,14 +127,12 @@ applied recursively and then the output of all the fields
 in the list is inserted according to format-string.
 
 Note that the author string should not contain whitespace
-\(put it in the neighbouring fields instead). For example:
-    (setq notmuch-tree-result-format
-          '((\"authors\" . \"%-40s\")
-            (\"subject\" . \"%s\")))"
-  :type '(alist :key-type (choice string
-				  (alist :key-type string
-					 :value-type string))
-		:value-type string)
+\(put it in the neighbouring fields instead)."
+
+  :type `(alist :key-type (choice ,notmuch-tree--field-names
+				  (alist :key-type ,notmuch-tree--field-names
+					 :value-type (string :tag "Format")))
+		:value-type (string :tag "Format"))
   :group 'notmuch-tree)
 
 (defcustom notmuch-unthreaded-result-format
-- 
2.35.1

^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH 4/6] doc/emacs: add docstring and example for n-tree-result-format
  2022-07-16 21:22 update documentation for notmuch-*-result-format David Bremner
                   ` (2 preceding siblings ...)
  2022-07-16 21:22 ` [PATCH 3/6] emacs: update defcustom for notmuch-search-result-format David Bremner
@ 2022-07-16 21:22 ` David Bremner
  2022-07-16 21:22 ` [PATCH 5/6] emacs: update defcustom for notmuch-unthreaded-result-format David Bremner
  2022-07-16 21:22 ` [PATCH 6/6] doc/emacs: add docstring " David Bremner
  5 siblings, 0 replies; 8+ messages in thread
From: David Bremner @ 2022-07-16 21:22 UTC (permalink / raw)
  To: notmuch

This example is based on one originally by Jon Hurst.
---
 doc/notmuch-emacs.rst | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 49111d28..44dca384 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -253,6 +253,8 @@ variables.
                                            ("subject" . "%s ")
                                            ("tags" . "(%s)")))
 
+   See also :emacsvar:`notmuch-tree-result-format`.
+
 .. emacsvar:: notmuch-search-oldest-first
 
     Display the oldest threads at the top of the buffer
@@ -475,6 +477,39 @@ 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`.
+
 .. _notmuch-unthreaded:
 
 notmuch-unthreaded
-- 
2.35.1

^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH 5/6] emacs: update defcustom for notmuch-unthreaded-result-format
  2022-07-16 21:22 update documentation for notmuch-*-result-format David Bremner
                   ` (3 preceding siblings ...)
  2022-07-16 21:22 ` [PATCH 4/6] doc/emacs: add docstring and example for n-tree-result-format David Bremner
@ 2022-07-16 21:22 ` David Bremner
  2022-07-16 21:22 ` [PATCH 6/6] doc/emacs: add docstring " David Bremner
  5 siblings, 0 replies; 8+ messages in thread
From: David Bremner @ 2022-07-16 21:22 UTC (permalink / raw)
  To: notmuch

This is essentially a copy of that for notmuch-tree-result-format,
aside from the default value.
---
 emacs/notmuch-tree.el | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/emacs/notmuch-tree.el b/emacs/notmuch-tree.el
index 68614623..f63ac9a5 100644
--- a/emacs/notmuch-tree.el
+++ b/emacs/notmuch-tree.el
@@ -142,7 +142,11 @@ Note that the author string should not contain whitespace
     ("tags" . "(%s)"))
   "Result formatting for unthreaded tree view.
 
-Supported fields are: date, authors, subject, tree, tags.
+List of pairs of (field . format-string).  Supported field
+strings are: \"date\", \"authors\", \"subject\", \"tree\",
+\"tags\".  It is also supported to pass a function in place of a
+field-name. In this case the function is passed the thread
+object (plist) and format string.
 
 Tree means the thread tree box graphics. The field may
 also be a list in which case the formatting rules are
@@ -150,14 +154,12 @@ applied recursively and then the output of all the fields
 in the list is inserted according to format-string.
 
 Note that the author string should not contain whitespace
-\(put it in the neighbouring fields instead). For example:
-    (setq notmuch-unthreaded-result-format
-          '((\"authors\" . \"%-40s\")
-            (\"subject\" . \"%s\")))"
-  :type '(alist :key-type (choice string
-				  (alist :key-type string
-					 :value-type string))
-		:value-type string)
+\(put it in the neighbouring fields instead)."
+
+  :type `(alist :key-type (choice ,notmuch-tree--field-names
+				  (alist :key-type ,notmuch-tree--field-names
+					 :value-type (string :tag "Format")))
+		:value-type (string :tag "Format"))
   :group 'notmuch-tree)
 
 (defun notmuch-tree-result-format ()
-- 
2.35.1

^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH 6/6] doc/emacs: add docstring for notmuch-unthreaded-result-format.
  2022-07-16 21:22 update documentation for notmuch-*-result-format David Bremner
                   ` (4 preceding siblings ...)
  2022-07-16 21:22 ` [PATCH 5/6] emacs: update defcustom for notmuch-unthreaded-result-format David Bremner
@ 2022-07-16 21:22 ` David Bremner
  2022-07-30 12:15   ` David Bremner
  5 siblings, 1 reply; 8+ messages in thread
From: David Bremner @ 2022-07-16 21:22 UTC (permalink / raw)
  To: notmuch

The main change is actually updating cross references.
---
 doc/notmuch-emacs.rst | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 44dca384..e69bd23d 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -253,7 +253,8 @@ variables.
                                            ("subject" . "%s ")
                                            ("tags" . "(%s)")))
 
-   See also :emacsvar:`notmuch-tree-result-format`.
+   See also :emacsvar:`notmuch-tree-result-format` and
+   :emacsvar:`notmuch-unthreaded-result-format`.
 
 .. emacsvar:: notmuch-search-oldest-first
 
@@ -508,7 +509,9 @@ can be controlled by the variable ``notmuch-search-oldest-first``.
                . " %-54s ")
               ("tags" . "(%s)")))
 
-   See also :emacsvar:`notmuch-search-result-format`.
+   See also :emacsvar:`notmuch-search-result-format` and
+   :emacsvar:`notmuch-unthreaded-result-format`.
+
 
 .. _notmuch-unthreaded:
 
@@ -521,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
 ===================
 
-- 
2.35.1

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH 6/6] doc/emacs: add docstring for notmuch-unthreaded-result-format.
  2022-07-16 21:22 ` [PATCH 6/6] doc/emacs: add docstring " David Bremner
@ 2022-07-30 12:15   ` David Bremner
  0 siblings, 0 replies; 8+ messages in thread
From: David Bremner @ 2022-07-30 12:15 UTC (permalink / raw)
  To: notmuch

David Bremner <david@tethera.net> writes:

> The main change is actually updating cross references.

series applied to master.

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2022-07-30 12:16 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-07-16 21:22 update documentation for notmuch-*-result-format David Bremner
2022-07-16 21:22 ` [PATCH 1/6] emacs: update defcustom for notmuch-search-result-format David Bremner
2022-07-16 21:22 ` [PATCH 2/6] doc/emacs: add docstring and example for n-search-result-format David Bremner
2022-07-16 21:22 ` [PATCH 3/6] emacs: update defcustom for notmuch-search-result-format David Bremner
2022-07-16 21:22 ` [PATCH 4/6] doc/emacs: add docstring and example for n-tree-result-format David Bremner
2022-07-16 21:22 ` [PATCH 5/6] emacs: update defcustom for notmuch-unthreaded-result-format David Bremner
2022-07-16 21:22 ` [PATCH 6/6] doc/emacs: add docstring " David Bremner
2022-07-30 12:15   ` David Bremner

Code repositories for project(s) associated with this inbox:

	notmuch.git.git (no URL configured)

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).