unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* emacs: Customize how each tag is displayed
@ 2013-01-18 16:03 Damien Cassou
  2013-01-18 16:03 ` [PATCH 1/4] emacs: Add notmuch-intersperse to notmuch-lib/ Damien Cassou
                   ` (4 more replies)
  0 siblings, 5 replies; 8+ messages in thread
From: Damien Cassou @ 2013-01-18 16:03 UTC (permalink / raw)
  To: notmuch mailing list

[PATCH 1/4] emacs: Add notmuch-intersperse to notmuch-lib/
[PATCH 2/4] emacs: pictures that might be used as icons for tags
[PATCH 3/4] emacs: possibility to customize the rendering of tags
[PATCH 4/4] emacs: provide convenience functions for notmuch-tagger


These patches are the first of an upcoming series whose goal is to
integrate notmuch-labeler into notmuch. See the following for more
details: https://github.com/DamienCassou/notmuch-labeler

Points of discussion:

- This series does not have any unit-test to make it smaller and more
  amenable to comments. I will send a patch when requested.

- Patch 3/4 formats tags as mode-line templates so that we can show
  tags in the header-line in a later series.

- Patch 3/4 introduces `notmuch-tagger-formats', a list of pairs (KEY
  FORMAT) to format a tag matching KEY using a special format.
  Currently, an example of such a list is:

    (("unread"
         (:propertize "unread" face
                      (:foreground "red")))
     ("flagged"
         (:propertize "flagged" display
                      (image :type svg
                             :file ,(notmuch-tagger-image-path "star.svg")
                             :ascent center :mask heuristic))))

  to set the unread tag to be red and the flagged tag to have a star
  picture attached. Because this variable is hard to edit without
  making mistakes, patch 4/4 introduces customization functions that
  the user can call on their init.el file like this:

  (notmuch-tagger-propertize "unread" :foreground "red")
  (notmuch-tagger-image-star "flagged")

  Nevertheless, implementing a customize interface for this variable
  is difficult as Emacs does not provide customization widgets for
  text-property lists. A possible solution could be to change the list
  value so that it looks like:

    (("unread" (propertize :foreground "red"))
     ("flagged" (image-star)))

  where the FORMAT part of each pair would be the suffix of a
  notmuch-tagger customization function name (as introduced by patch
  4/4) and the rest would be parameters to pass to this function
  (except the KEY parameter that is already in each pair of the
  `notmuch-tagger-formats' list). This solution would be more amenable
  to the customization interface, but maybe less powerful.

^ permalink raw reply	[flat|nested] 8+ messages in thread
* [PATCH 1/4] emacs: Add notmuch-intersperse to notmuch-lib/
  2013-01-18 16:03 emacs: Customize how each tag is displayed Damien Cassou
@ 2013-01-18 16:03 ` Damien Cassou
  2013-01-18 16:03 ` [PATCH 2/4] emacs: pictures that might be used as icons for tags Damien Cassou
                   ` (3 subsequent siblings)
  4 siblings, 0 replies; 8+ messages in thread
From: Damien Cassou @ 2013-01-18 16:03 UTC (permalink / raw)
  To: notmuch mailing list

(notmuch-intersperse LIST SEP)

Return a list with all elements of LIST separated by SEP.

Signed-off-by: Damien Cassou <damien.cassou@gmail.com>
---
 emacs/notmuch-lib.el |   11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/emacs/notmuch-lib.el b/emacs/notmuch-lib.el
index d78bcf8..3566126 100644
--- a/emacs/notmuch-lib.el
+++ b/emacs/notmuch-lib.el
@@ -716,8 +716,15 @@ left it."
     ;; Clear out what we've parsed
     (delete-region (point-min) (point))))
 
-
-
+(defun notmuch-intersperse (list sep)
+  "Return a list with all elements of LIST separated by SEP."
+  (let ((first t)
+        (res nil))
+    (dolist (elt list (nreverse res))
+      (unless first
+        (push sep res))
+      (setq first nil)
+      (push elt res))))
 
 (provide 'notmuch-lib)
 
-- 
1.7.10.4

^ permalink raw reply related	[flat|nested] 8+ messages in thread
* [PATCH 2/4] emacs: pictures that might be used as icons for tags
  2013-01-18 16:03 emacs: Customize how each tag is displayed Damien Cassou
  2013-01-18 16:03 ` [PATCH 1/4] emacs: Add notmuch-intersperse to notmuch-lib/ Damien Cassou
@ 2013-01-18 16:03 ` Damien Cassou
  2013-01-18 16:03 ` [PATCH 3/4] emacs: possibility to customize the rendering of tags Damien Cassou
                   ` (2 subsequent siblings)
  4 siblings, 0 replies; 8+ messages in thread
From: Damien Cassou @ 2013-01-18 16:03 UTC (permalink / raw)
  To: notmuch mailing list

I made these icons myself so there is no copyright infringement. I am
by no means a designer so feel free to improve them if you can.

Signed-off-by: Damien Cassou <damien.cassou@gmail.com>
---
 emacs/resources/star-empty.svg |   85 ++++++++++++++++++++++++++++++++++++++++
 emacs/resources/star.svg       |   85 ++++++++++++++++++++++++++++++++++++++++
 emacs/resources/tag.svg        |   62 +++++++++++++++++++++++++++++
 3 files changed, 232 insertions(+)
 create mode 100644 emacs/resources/star-empty.svg
 create mode 100644 emacs/resources/star.svg
 create mode 100644 emacs/resources/tag.svg

diff --git a/emacs/resources/star-empty.svg b/emacs/resources/star-empty.svg
new file mode 100644
index 0000000..d2a1466
--- /dev/null
+++ b/emacs/resources/star-empty.svg
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="16"
+   height="16"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.3.1 r9886"
+   sodipodi:docname="star.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="22.4"
+     inkscape:cx="2.9628491"
+     inkscape:cy="7.3057226"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     inkscape:window-width="1280"
+     inkscape:window-height="776"
+     inkscape:window-x="0"
+     inkscape:window-y="24"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0">
+    <sodipodi:guide
+       orientation="0,1"
+       position="119.36003,-45.040775"
+       id="guide2987" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-242.81601,-315.59635)">
+    <path
+       sodipodi:type="star"
+       style="fill:#d6d6d1;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;fill-opacity:1"
+       id="path2985"
+       sodipodi:sides="5"
+       sodipodi:cx="274.28571"
+       sodipodi:cy="306.64789"
+       sodipodi:r1="31.943829"
+       sodipodi:r2="15.971914"
+       sodipodi:arg1="1.0471976"
+       sodipodi:arg2="1.6755161"
+       inkscape:flatsided="false"
+       inkscape:rounded="0"
+       inkscape:randomized="0"
+       d="m 290.25762,334.31206 -17.64143,-11.77975 -19.70508,7.85447 5.75171,-20.41814 -13.55925,-16.31348 21.19618,-0.83936 11.325,-17.93675 7.34825,19.89939 20.55849,5.22795 -16.65471,13.13786 z"
+       inkscape:transform-center-x="0.0012242519"
+       inkscape:transform-center-y="-0.76081"
+       transform="matrix(0.2484147,-0.02623394,0.02623394,0.2484147,174.63605,255.37691)" />
+  </g>
+</svg>
diff --git a/emacs/resources/star.svg b/emacs/resources/star.svg
new file mode 100644
index 0000000..3178510
--- /dev/null
+++ b/emacs/resources/star.svg
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="16"
+   height="16"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.3.1 r9886"
+   sodipodi:docname="star.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="22.4"
+     inkscape:cx="10.819992"
+     inkscape:cy="7.3057226"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     inkscape:window-width="1280"
+     inkscape:window-height="776"
+     inkscape:window-x="0"
+     inkscape:window-y="24"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0">
+    <sodipodi:guide
+       orientation="0,1"
+       position="119.36003,-45.040775"
+       id="guide2987" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-242.81601,-315.59635)">
+    <path
+       sodipodi:type="star"
+       style="fill:#ffff00;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       id="path2985"
+       sodipodi:sides="5"
+       sodipodi:cx="274.28571"
+       sodipodi:cy="306.64789"
+       sodipodi:r1="31.943829"
+       sodipodi:r2="15.971914"
+       sodipodi:arg1="1.0471976"
+       sodipodi:arg2="1.6755161"
+       inkscape:flatsided="false"
+       inkscape:rounded="0"
+       inkscape:randomized="0"
+       d="m 290.25762,334.31206 -17.64143,-11.77975 -19.70508,7.85447 5.75171,-20.41814 -13.55925,-16.31348 21.19618,-0.83936 11.325,-17.93675 7.34825,19.89939 20.55849,5.22795 -16.65471,13.13786 z"
+       inkscape:transform-center-x="0.0012242519"
+       inkscape:transform-center-y="-0.76081"
+       transform="matrix(0.2484147,-0.02623394,0.02623394,0.2484147,174.63605,255.37691)" />
+  </g>
+</svg>
diff --git a/emacs/resources/tag.svg b/emacs/resources/tag.svg
new file mode 100644
index 0000000..58dd1cb
--- /dev/null
+++ b/emacs/resources/tag.svg
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="16"
+   height="16"
+   id="svg3805"
+   version="1.1"
+   inkscape:version="0.48.3.1 r9886"
+   sodipodi:docname="New document 5">
+  <defs
+     id="defs3807" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="22.4"
+     inkscape:cx="9.169538"
+     inkscape:cy="8.6002515"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1280"
+     inkscape:window-height="776"
+     inkscape:window-x="0"
+     inkscape:window-y="24"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata3810">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-1036.3622)">
+    <path
+       style="fill:#ffff00;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.25;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1"
+       d="m 0.44642857,1040.9336 12.50000043,0 2.700893,3.6161 -2.700893,3.616 -12.50000043,0 z"
+       id="rect4321"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cccccc" />
+  </g>
+</svg>
-- 
1.7.10.4

^ permalink raw reply related	[flat|nested] 8+ messages in thread
* [PATCH 3/4] emacs: possibility to customize the rendering of tags
  2013-01-18 16:03 emacs: Customize how each tag is displayed Damien Cassou
  2013-01-18 16:03 ` [PATCH 1/4] emacs: Add notmuch-intersperse to notmuch-lib/ Damien Cassou
  2013-01-18 16:03 ` [PATCH 2/4] emacs: pictures that might be used as icons for tags Damien Cassou
@ 2013-01-18 16:03 ` Damien Cassou
  2013-01-23  0:17   ` Austin Clements
  2013-01-18 16:03 ` [PATCH 4/4] emacs: provide convenience functions for notmuch-tagger configuration Damien Cassou
  2013-01-23  0:24 ` emacs: Customize how each tag is displayed Austin Clements
  4 siblings, 1 reply; 8+ messages in thread
From: Damien Cassou @ 2013-01-18 16:03 UTC (permalink / raw)
  To: notmuch mailing list

This patch extracts the rendering of tags in notmuch-show to a
dedicated notmuch-tagger file.

This new file introduces a `notmuch-tagger-formats' variable that
associates each tag to a particular format. For example,

(("unread"
  (:propertize "unread" face
               (:foreground "red")))
 ("flagged"
  (:propertize "flagged" display
               (image :type svg :file "~/notmuch/emacs/resources/star.svg" :ascent center :mask heuristic))))

associates a red font to the "unread" tag and a star picture to
the "flagged" tag.

In the future, I would like to use the Customization interface of
Emacs to edit this variable and also to provide high-lever
functions to manipulate it such
that (notmuch-tagger-propertize "unread" :foreground "red")
and (notmuch-tagger-picture "flagged" "star.svg").

`mode-line-format' templates are used to represent the format for
each tag. This is a concize format that can also be used in
`header-line-format' if later desired.

Signed-off-by: Damien Cassou <damien.cassou@gmail.com>
---
 emacs/notmuch-show.el   |    7 ++---
 emacs/notmuch-tagger.el |   75 +++++++++++++++++++++++++++++++++++++++++++++++
 emacs/notmuch.el        |    5 ++--
 3 files changed, 80 insertions(+), 7 deletions(-)
 create mode 100644 emacs/notmuch-tagger.el

diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el
index 1864dd1..7bf9f3c 100644
--- a/emacs/notmuch-show.el
+++ b/emacs/notmuch-show.el
@@ -36,6 +36,7 @@
 (require 'notmuch-mua)
 (require 'notmuch-crypto)
 (require 'notmuch-print)
+(require 'notmuch-tagger)
 
 (declare-function notmuch-call-notmuch-process "notmuch" (&rest args))
 (declare-function notmuch-fontify-headers "notmuch" nil)
@@ -362,8 +363,7 @@ operation on the contents of the current buffer."
     (if (re-search-forward "(\\([^()]*\\))$" (line-end-position) t)
 	(let ((inhibit-read-only t))
 	  (replace-match (concat "("
-				 (propertize (mapconcat 'identity tags " ")
-					     'face 'notmuch-tag-face)
+				 (notmuch-tagger-present-tags tags)
 				 ")"))))))
 
 (defun notmuch-clean-address (address)
@@ -441,8 +441,7 @@ message at DEPTH in the current thread."
 	    " ("
 	    date
 	    ") ("
-	    (propertize (mapconcat 'identity tags " ")
-			'face 'notmuch-tag-face)
+	    (notmuch-tagger-present-tags tags)
 	    ")\n")
     (overlay-put (make-overlay start (point)) 'face 'notmuch-message-summary-face)))
 
diff --git a/emacs/notmuch-tagger.el b/emacs/notmuch-tagger.el
new file mode 100644
index 0000000..90730f6
--- /dev/null
+++ b/emacs/notmuch-tagger.el
@@ -0,0 +1,75 @@
+;; notmuch-tagger.el --- Library to improve the way tags are displayed
+;;
+;; Copyright © Damien Cassou
+;;
+;; This file is part of Notmuch.
+;;
+;; Notmuch is free software: you can redistribute it and/or modify it
+;; under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+;;
+;; Notmuch is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;; General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with Notmuch.  If not, see <http://www.gnu.org/licenses/>.
+;;
+;; Authors: Damien Cassou <damien.cassou@gmail.com>
+;;; Commentary:
+;;
+;;; Comments
+;;
+;;; Code:
+;;
+
+(require 'cl)
+
+(defvar notmuch-tagger-formats
+  `(("unread"
+     (:propertize "unread" face
+                  (:foreground "red")))
+    ("flagged"
+     (:propertize "flagged" display
+                  (image :type svg :file
+                         ,(expand-file-name
+                           "resources/star.svg"
+                           (file-name-directory
+                            (or
+                             (locate-library "notmuch-tagger")
+                             (buffer-file-name))))
+                         :ascent center :mask heuristic))))
+  "Contains pairs of (KEY FORMAT) to format a tag matching KEY.
+
+KEY must be a string with a tag name. In the future, KEY could
+also be a regexp or list of keys to be matched against tags.
+
+The default value set the unread tag to be red and the flagged
+tag to have a star picture attached. Those are just examples so
+you get an idea of what you can do.")
+
+(defun notmuch-tagger-tag-format (tag)
+  "Format TAG as a `mode-line-format' template.
+
+The format to apply to TAG is searched in
+`notmuch-tagger-formats'. If not found, the default
+`notmuch-tag-face' is used."
+  (let ((match (assoc tag notmuch-tagger-formats)))
+    (if match
+        (cadr match)
+      `(:propertize ,tag face notmuch-tag-face))))
+
+(defun notmuch-tagger-tags-format (tags)
+  "Format TAGS as a `mode-line-format' template."
+  (notmuch-intersperse
+   (remove nil (mapcar #'notmuch-tagger-tag-format tags))
+   " "))
+
+(defun notmuch-tagger-present-tags (tags)
+  "Return a string that represent TAGS with their format."
+  (format-mode-line (notmuch-tagger-tags-format tags)))
+
+(provide 'notmuch-tagger)
+;;; notmuch-tagger.el ends here
diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index c98a4fe..c607905 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -797,9 +797,8 @@ non-authors is found, assume that all of the authors match."
     (notmuch-search-insert-authors format-string (plist-get result :authors)))
 
    ((string-equal field "tags")
-    (let ((tags-str (mapconcat 'identity (plist-get result :tags) " ")))
-      (insert (propertize (format format-string tags-str)
-			  'face 'notmuch-tag-face))))))
+    (let ((tags (plist-get result :tags)))
+      (insert (format format-string (notmuch-tagger-present-tags tags)))))))
 
 (defun notmuch-search-show-result (result &optional pos)
   "Insert RESULT at POS or the end of the buffer if POS is null."
-- 
1.7.10.4

^ permalink raw reply related	[flat|nested] 8+ messages in thread
* [PATCH 4/4] emacs: provide convenience functions for notmuch-tagger configuration
  2013-01-18 16:03 emacs: Customize how each tag is displayed Damien Cassou
                   ` (2 preceding siblings ...)
  2013-01-18 16:03 ` [PATCH 3/4] emacs: possibility to customize the rendering of tags Damien Cassou
@ 2013-01-18 16:03 ` Damien Cassou
  2013-01-23  0:24 ` emacs: Customize how each tag is displayed Austin Clements
  4 siblings, 0 replies; 8+ messages in thread
From: Damien Cassou @ 2013-01-18 16:03 UTC (permalink / raw)
  To: notmuch mailing list

This patch adds functions like `notmuch-tagger-rename',
`notmuch-tagger-hide', and `notmuch-tagger-image-star' to facilitate
the manipulation of `notmuch-tagger-formats'. For example, a typical
.init.el file would contain:

    ;; Capitalize the tag 'important' and set its color
    (notmuch-tagger-rename "important" "Important" :foreground "red")

    ;; Use a star icon for the 'starred' tag
    (notmuch-tagger-image-star "starred")

Signed-off-by: Damien Cassou <damien.cassou@gmail.com>
---
 emacs/notmuch-tagger.el |  101 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 94 insertions(+), 7 deletions(-)

diff --git a/emacs/notmuch-tagger.el b/emacs/notmuch-tagger.el
index 90730f6..f798757 100644
--- a/emacs/notmuch-tagger.el
+++ b/emacs/notmuch-tagger.el
@@ -22,24 +22,37 @@
 ;;
 ;;; Comments
 ;;
+;; Example use:
+;;
+;; Capitalize the tag 'important' and set its color
+;; (notmuch-tagger-rename "important" "Important" :foreground "red")
+;;
+;; Use a star icon for the 'starred' tag
+;; (notmuch-tagger-image-star "starred")
+;;
 ;;; Code:
 ;;
 
 (require 'cl)
 
+(defun notmuch-tagger-image-path (image)
+  "Get full path for IMAGE name in the resources/ sub-directory."
+  (expand-file-name
+   image
+   (expand-file-name "resources"
+                     (file-name-directory
+                      (or
+                       (locate-library "notmuch-tagger")
+                       (buffer-file-name))))))
+
 (defvar notmuch-tagger-formats
   `(("unread"
      (:propertize "unread" face
                   (:foreground "red")))
     ("flagged"
      (:propertize "flagged" display
-                  (image :type svg :file
-                         ,(expand-file-name
-                           "resources/star.svg"
-                           (file-name-directory
-                            (or
-                             (locate-library "notmuch-tagger")
-                             (buffer-file-name))))
+                  (image :type svg
+                         :file ,(notmuch-tagger-image-path "star.svg")
                          :ascent center :mask heuristic))))
   "Contains pairs of (KEY FORMAT) to format a tag matching KEY.
 
@@ -50,6 +63,80 @@ The default value set the unread tag to be red and the flagged
 tag to have a star picture attached. Those are just examples so
 you get an idea of what you can do.")
 
+(defun notmuch-tagger-set-format (key format)
+  "Set that tags matched by KEY must be displayed using FORMAT.
+
+This function updates `notmuch-tagger-formats' according to its
+parameters.
+
+Instead of calling this function, use one of the higher-level
+ones like `notmuch-tagger-rename', `notmuch-tagger-propertize',
+`notmuch-tagger-hide', and `notmuch-tagger-image'."
+  (let ((pair (assoc key notmuch-tagger-formats)))
+    (if pair
+        (setf (cdr pair) (list format))
+      (add-to-list 'notmuch-tagger-formats (list key format)))))
+
+
+(defun notmuch-tagger-rename (key new-name &rest face)
+  "Display tags matching KEY as NEW-NAME with a particular FACE.
+Use this function like this:
+
+\(notmuch-tagger-rename \"draft\" \"Draft\" :foreground \"red\")
+
+This will present the draft tag with a capital and in red."
+  (notmuch-tagger-set-format key
+       `(:propertize ,new-name face ,(or face 'notmuch-tag-face))))
+
+(defun notmuch-tagger-propertize (key &rest face)
+  "Render tags matching KEY with a particular face.
+Use this function like this:
+
+\(notmuch-tagger-propertize \"draft\" :foreground \"red\")
+
+This will present the draft tag in red."
+  (apply 'notmuch-tagger-rename key key face))
+
+(defun notmuch-tagger-hide (key)
+  "Hide tags matching KEY."
+  (notmuch-tagger-set-format key nil))
+
+(defun notmuch-tagger-image (key file type)
+  "Show tags matching KEY as images taken from FILE with type TYPE.
+
+See Info node `(elisp)Image Formats' for possible values for
+TYPE (e.g., 'svg and 'png).
+
+There is a set of predefined pictures that you can use by calling
+ functions like `notmuch-tagger-image-star' and
+ `notmuch-tagger-image-tag'."
+  (notmuch-tagger-set-format
+   key
+   `(:propertize ,key display
+                 (image :type ,type
+                        :file ,file
+                        :ascent center
+                        :mask heuristic))))
+
+(defun notmuch-tagger-provided-image (key image)
+  "Show tags matching KEY as IMAGE provided by notmuch-tagger."
+  (notmuch-tagger-image
+   key
+   (notmuch-tagger-image-path image)
+   (intern (file-name-extension image))))
+
+(defun notmuch-tagger-image-star (key)
+  "Show tags matching KEY as resources/star.svg."
+  (notmuch-tagger-provided-image key "star.svg"))
+
+(defun notmuch-tagger-image-star-empty (key)
+  "Show tags matching KEY as resources/star-empty.svg."
+  (notmuch-tagger-provided-image key "star-empty.svg"))
+
+(defun notmuch-tagger-image-tag (tag)
+  "Show tags matching KEY as resources/tag.svg."
+  (notmuch-tagger-provided-image tag "tag.svg"))
+
 (defun notmuch-tagger-tag-format (tag)
   "Format TAG as a `mode-line-format' template.
 
-- 
1.7.10.4

^ permalink raw reply related	[flat|nested] 8+ messages in thread
* Re: [PATCH 3/4] emacs: possibility to customize the rendering of tags
  2013-01-18 16:03 ` [PATCH 3/4] emacs: possibility to customize the rendering of tags Damien Cassou
@ 2013-01-23  0:17   ` Austin Clements
  2013-01-23  2:15     ` Tomi Ollila
  0 siblings, 1 reply; 8+ messages in thread
From: Austin Clements @ 2013-01-23  0:17 UTC (permalink / raw)
  To: Damien Cassou, notmuch mailing list

On Fri, 18 Jan 2013, Damien Cassou <damien.cassou@gmail.com> wrote:
> This patch extracts the rendering of tags in notmuch-show to a
> dedicated notmuch-tagger file.
>
> This new file introduces a `notmuch-tagger-formats' variable that
> associates each tag to a particular format. For example,
>
> (("unread"
>   (:propertize "unread" face
>                (:foreground "red")))
>  ("flagged"
>   (:propertize "flagged" display
>                (image :type svg :file "~/notmuch/emacs/resources/star.svg" :ascent center :mask heuristic))))
>
> associates a red font to the "unread" tag and a star picture to
> the "flagged" tag.
>
> In the future, I would like to use the Customization interface of
> Emacs to edit this variable and also to provide high-lever

s/lever/level/

> functions to manipulate it such
> that (notmuch-tagger-propertize "unread" :foreground "red")
> and (notmuch-tagger-picture "flagged" "star.svg").
>
> `mode-line-format' templates are used to represent the format for
> each tag. This is a concize format that can also be used in

"concise"?

> `header-line-format' if later desired.
>
> Signed-off-by: Damien Cassou <damien.cassou@gmail.com>
> ---
>  emacs/notmuch-show.el   |    7 ++---
>  emacs/notmuch-tagger.el |   75 +++++++++++++++++++++++++++++++++++++++++++++++
>  emacs/notmuch.el        |    5 ++--
>  3 files changed, 80 insertions(+), 7 deletions(-)
>  create mode 100644 emacs/notmuch-tagger.el
>
> diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el
> index 1864dd1..7bf9f3c 100644
> --- a/emacs/notmuch-show.el
> +++ b/emacs/notmuch-show.el
> @@ -36,6 +36,7 @@
>  (require 'notmuch-mua)
>  (require 'notmuch-crypto)
>  (require 'notmuch-print)
> +(require 'notmuch-tagger)
>  
>  (declare-function notmuch-call-notmuch-process "notmuch" (&rest args))
>  (declare-function notmuch-fontify-headers "notmuch" nil)
> @@ -362,8 +363,7 @@ operation on the contents of the current buffer."
>      (if (re-search-forward "(\\([^()]*\\))$" (line-end-position) t)
>  	(let ((inhibit-read-only t))
>  	  (replace-match (concat "("
> -				 (propertize (mapconcat 'identity tags " ")
> -					     'face 'notmuch-tag-face)
> +				 (notmuch-tagger-present-tags tags)
>  				 ")"))))))
>  
>  (defun notmuch-clean-address (address)
> @@ -441,8 +441,7 @@ message at DEPTH in the current thread."
>  	    " ("
>  	    date
>  	    ") ("
> -	    (propertize (mapconcat 'identity tags " ")
> -			'face 'notmuch-tag-face)
> +	    (notmuch-tagger-present-tags tags)
>  	    ")\n")
>      (overlay-put (make-overlay start (point)) 'face 'notmuch-message-summary-face)))
>  
> diff --git a/emacs/notmuch-tagger.el b/emacs/notmuch-tagger.el
> new file mode 100644
> index 0000000..90730f6
> --- /dev/null
> +++ b/emacs/notmuch-tagger.el
> @@ -0,0 +1,75 @@
> +;; notmuch-tagger.el --- Library to improve the way tags are displayed

The verb-er naming scheme made sense when this wasn't part of notmuch,
but it seems to needlessly (and confusingly) set it apart from standard
notmuch functionality.  Any thoughts on including this straight in
notmuch-tag.el (and adding your author and copyright to that file, of
course)?

> +;;
> +;; Copyright © Damien Cassou
> +;;
> +;; This file is part of Notmuch.
> +;;
> +;; Notmuch is free software: you can redistribute it and/or modify it
> +;; under the terms of the GNU General Public License as published by
> +;; the Free Software Foundation, either version 3 of the License, or
> +;; (at your option) any later version.
> +;;
> +;; Notmuch is distributed in the hope that it will be useful, but
> +;; WITHOUT ANY WARRANTY; without even the implied warranty of
> +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> +;; General Public License for more details.
> +;;
> +;; You should have received a copy of the GNU General Public License
> +;; along with Notmuch.  If not, see <http://www.gnu.org/licenses/>.
> +;;
> +;; Authors: Damien Cassou <damien.cassou@gmail.com>
> +;;; Commentary:

Since there is no commentary, you should leave out this header section.

> +;;
> +;;; Comments

I'm not sure what this is, but it should probably also be omitted.

> +;;
> +;;; Code:
> +;;
> +
> +(require 'cl)
> +
> +(defvar notmuch-tagger-formats

notmuch-tag-formats?

> +  `(("unread"
> +     (:propertize "unread" face
> +                  (:Foreground "red")))
> +    ("flagged"
> +     (:propertize "flagged" display
> +                  (image :type svg :file
> +                         ,(expand-file-name
> +                           "resources/star.svg"
> +                           (file-name-directory
> +                            (or
> +                             (locate-library "notmuch-tagger")
> +                             (buffer-file-name))))

Interesting.  Is this a standard way to locate resources?  (I've never
had need to.)

Since there are other icons here as well, perhaps the resources
directory should be bound to a global variable so it's easy to construct
other standard notmuch icon names?  You capture this in a function in
patch 4, but that function doesn't obviously accomplish anything a
simple variable wouldn't.

Another possibility is that these icons could be included directly in
the Elisp source, probably as simplified SVGs (your SVGs look like they
could be cut down to 3 or 4 lines of XML easily) or as XPMs.  Besides
skirting issues with resource location, this would make it trivial to
alter their colors based on user preferences.

> +                         :ascent center :mask heuristic))))
> +  "Contains pairs of (KEY FORMAT) to format a tag matching KEY.
> +
> +KEY must be a string with a tag name. In the future, KEY could
> +also be a regexp or list of keys to be matched against tags.

This "in the future" comment doesn't really belong in a doc string,
though it would make sense as a source comment in
`notmuch-tagger-tag-format'.

> +
> +The default value set the unread tag to be red and the flagged
> +tag to have a star picture attached. Those are just examples so
> +you get an idea of what you can do.")
> +
> +(defun notmuch-tagger-tag-format (tag)
> +  "Format TAG as a `mode-line-format' template.

This makes it sounds like this function actually formats the template,
which it doesn't.  Perhaps

  Return a `mode-line-format' template for tag TAG.

and call it notmuch-tag-get-format?

> +
> +The format to apply to TAG is searched in
> +`notmuch-tagger-formats'. If not found, the default
> +`notmuch-tag-face' is used."
> +  (let ((match (assoc tag notmuch-tagger-formats)))
> +    (if match
> +        (cadr match)
> +      `(:propertize ,tag face notmuch-tag-face))))

This changes how we use notmuch-tag-face.  For example, currently, if
notmuch-tag-face has a background color, it will apply to the whole tag
list, including the spaces between tags.  With this, it will only apply
to the individual tags.  Also, if a tag does have a format, it will
completely override notmuch-tag-face, rather than combining with it,
which I think is undesirable.  Fixing this is a little tricky because
Emacs makes it a pain to combine faces, but
notmuch-combine-face-text-property already mostly implements this.  I'd
suggest simply returning tag in the alternate case above (in which case
you can simplify the above function down to just
 (assoc-default tag notmuch-tag-formats nil tag)
) and replacing the propertize calls that used to apply notmuch-tag-face
with calls to this updated notmuch-combine-face-text-property:

(defun notmuch-combine-face-text-property (start end face &optional below object)
  "Combine FACE into the 'face text property between START and END.

This function combines FACE with any existing faces between START
and END in OBJECT (which defaults to the current buffer).
Attributes specified by FACE take precedence over existing
attributes unless BELOW is non-nil.  FACE must be a face name (a
symbol or string), a property list of face attributes, or a list
of these.  For convenience when applied to strings, this returns
OBJECT."

  (let ((pos start))
    (while (< pos end)
      (let* ((cur (get-text-property pos 'face object))
	     (next (next-single-property-change pos 'face object end))
	     (new (if below
		      (append cur (list face))
		    (cons face cur))))
	(put-text-property pos next 'face new object)
	(setq pos next))))
  object)

The new BELOW argument will let faces applied by tag formats override
notmuch-tag-face even though notmuch-tag-face is applied afterward, and
the new OBJECT argument will let this operate on strings.

> +
> +(defun notmuch-tagger-tags-format (tags)
> +  "Format TAGS as a `mode-line-format' template."

Same comment here.  Perhaps notmuch-tag-list-get-format and

  Return a `mode-line-format' template for tag list TAGS.

> +  (notmuch-intersperse
> +   (remove nil (mapcar #'notmuch-tagger-tag-format tags))

The remove nil would be worth a comment.  It took me a long time to
figure out that this was because tags can be hidden by formatting them
as nil (which makes sense in retrospect).

> +   " "))
> +
> +(defun notmuch-tagger-present-tags (tags)

This doesn't actually present the tags.  If you like the renaming I
suggested above, it would make sense to call this
notmuch-tag-format-tag-list, since it actually does the formatting.

> +  "Return a string that represent TAGS with their format."
> +  (format-mode-line (notmuch-tagger-tags-format tags)))
> +
> +(provide 'notmuch-tagger)
> +;;; notmuch-tagger.el ends here
> diff --git a/emacs/notmuch.el b/emacs/notmuch.el
> index c98a4fe..c607905 100644
> --- a/emacs/notmuch.el
> +++ b/emacs/notmuch.el
> @@ -797,9 +797,8 @@ non-authors is found, assume that all of the authors match."
>      (notmuch-search-insert-authors format-string (plist-get result :authors)))
>  
>     ((string-equal field "tags")
> -    (let ((tags-str (mapconcat 'identity (plist-get result :tags) " ")))
> -      (insert (propertize (format format-string tags-str)
> -			  'face 'notmuch-tag-face))))))
> +    (let ((tags (plist-get result :tags)))
> +      (insert (format format-string (notmuch-tagger-present-tags tags)))))))
>  
>  (defun notmuch-search-show-result (result &optional pos)
>    "Insert RESULT at POS or the end of the buffer if POS is null."
> -- 
> 1.7.10.4
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch

^ permalink raw reply	[flat|nested] 8+ messages in thread
* Re: emacs: Customize how each tag is displayed
  2013-01-18 16:03 emacs: Customize how each tag is displayed Damien Cassou
                   ` (3 preceding siblings ...)
  2013-01-18 16:03 ` [PATCH 4/4] emacs: provide convenience functions for notmuch-tagger configuration Damien Cassou
@ 2013-01-23  0:24 ` Austin Clements
  4 siblings, 0 replies; 8+ messages in thread
From: Austin Clements @ 2013-01-23  0:24 UTC (permalink / raw)
  To: Damien Cassou, notmuch mailing list

On Fri, 18 Jan 2013, Damien Cassou <damien.cassou@gmail.com> wrote:
> [PATCH 1/4] emacs: Add notmuch-intersperse to notmuch-lib/
> [PATCH 2/4] emacs: pictures that might be used as icons for tags
> [PATCH 3/4] emacs: possibility to customize the rendering of tags
> [PATCH 4/4] emacs: provide convenience functions for notmuch-tagger
>
>
> These patches are the first of an upcoming series whose goal is to
> integrate notmuch-labeler into notmuch. See the following for more
> details: https://github.com/DamienCassou/notmuch-labeler
>
> Points of discussion:
>
> - This series does not have any unit-test to make it smaller and more
>   amenable to comments. I will send a patch when requested.
>
> - Patch 3/4 formats tags as mode-line templates so that we can show
>   tags in the header-line in a later series.
>
> - Patch 3/4 introduces `notmuch-tagger-formats', a list of pairs (KEY
>   FORMAT) to format a tag matching KEY using a special format.
>   Currently, an example of such a list is:
>
>     (("unread"
>          (:propertize "unread" face
>                       (:foreground "red")))
>      ("flagged"
>          (:propertize "flagged" display
>                       (image :type svg
>                              :file ,(notmuch-tagger-image-path "star.svg")
>                              :ascent center :mask heuristic))))
>
>   to set the unread tag to be red and the flagged tag to have a star
>   picture attached. Because this variable is hard to edit without
>   making mistakes, patch 4/4 introduces customization functions that
>   the user can call on their init.el file like this:
>
>   (notmuch-tagger-propertize "unread" :foreground "red")
>   (notmuch-tagger-image-star "flagged")
>
>   Nevertheless, implementing a customize interface for this variable
>   is difficult as Emacs does not provide customization widgets for
>   text-property lists. A possible solution could be to change the list
>   value so that it looks like:
>
>     (("unread" (propertize :foreground "red"))
>      ("flagged" (image-star)))
>
>   where the FORMAT part of each pair would be the suffix of a
>   notmuch-tagger customization function name (as introduced by patch
>   4/4) and the rest would be parameters to pass to this function
>   (except the KEY parameter that is already in each pair of the
>   `notmuch-tagger-formats' list). This solution would be more amenable
>   to the customization interface, but maybe less powerful.

I'm not sold on your mode-line-format approach.  On the one hand, it's
rather quaint that you can reuse all of the mode-line formatting
mechanism.  But, on the other hand, 90% of the mode-line formatting
mechanism makes no sense in this context, and all of the utility
functions you add to make this variable accessible as well as the
difficulty in creating a customize interface for it suggest that this is
a false economy: that mode-line formatting is, in fact, the wrong
abstraction for this.

I'm not sure what the best representation is, but here's one idea.
Instead of inventing (or reusing) some specialized formatting language,
use the language already at your disposal: make the tag format a list of
Elisp expressions that transform the tag string into an arbitrary
propertized string to use in place of the tag.  You can't get much more
powerful than that, and, plus, it would be really easy to implement.

Here's what I'm imagining, complete with working (slightly hairy)
customize interface:

(defcustom notmuch-tag-formats
  '(("unread" (propertize tag 'face '(:foreground "red")))
    ("flagged" (notmuch-tag-format-image tag "star.svg")))

  "Custom formats for individual tags.

This gives a list that maps from tag names to lists of formatting
expressions.  The car of each element gives a tag name and the
cdr gives a list of Elisp expressions that modify the tag.  If
the list is empty, the tag will simply be hidden.  Otherwise,
each expression will be evaluated in order: for the first
expression, the variable `tag' will be bound to the tag name; for
each later expression, the variable `tag' will be bound to the
result of the previous expression.  In this way, each expression
can build on the formatting performed by the previous expression.
The result of the last expression will displayed in place of the
tag.

For example, to replace a tag with another string, simply use
that string as a formatting expression.  To change the foreground
of a tag to red, use the expression
  (propertize tag 'face '(:foreground \"red\"))

See also `notmuch-tag-format-image', which can help replace tags
with images."

  :group 'notmuch-search
  :group 'notmuch-show
  :type '(alist :key-type (string :tag "Tag")
		:extra-offset -3
		:value-type
		(radio :format "%v"
		       (const :tag "Hidden" nil)
		       (set :tag "Modified"
			    (string :tag "Display as")
			    (list :tag "Face" :extra-offset -4
				  (const :format "" :inline t
					 (propertize tag 'face))
				  (list :format "%v"
					(const :format "" quote)
					custom-face-edit))
			    (list :format "%v" :extra-offset -4
				  (const :format "" :inline t
					 (notmuch-tag-format-image tag))
				  (choice :tag "Image"
					  (const :tag "Star" "star.svg")
					  (const :tag "Empty star"
						 "star-empty.svg")
					  (const :tag "Tag" "tag.svg")
					  (string :tag "Custom")))
			    (sexp :tag "Custom")))))

where I'm imagining notmuch-tag-format-image would be very similar to
your existing image utilities, with an interface something like

(defun notmuch-tag-format-image (tag image)
  "Replace TAG with IMAGE, if available.

Returns a propertized string that will display IMAGE in place of
TAG.  If IMAGE is a relative path, it will be looked for in the
standard notmuch image directory.  This is designed for use in
`notmuch-tag-formats'."
  ...)

Thoughts?

^ permalink raw reply	[flat|nested] 8+ messages in thread
* Re: [PATCH 3/4] emacs: possibility to customize the rendering of tags
  2013-01-23  0:17   ` Austin Clements
@ 2013-01-23  2:15     ` Tomi Ollila
  0 siblings, 0 replies; 8+ messages in thread
From: Tomi Ollila @ 2013-01-23  2:15 UTC (permalink / raw)
  To: Austin Clements, Damien Cassou, notmuch mailing list

On Wed, Jan 23 2013, Austin Clements <amdragon@MIT.EDU> wrote:

> On Fri, 18 Jan 2013, Damien Cassou <damien.cassou@gmail.com> wrote:
>
>> +  `(("unread"
>> +     (:propertize "unread" face
>> +                  (:Foreground "red")))
>> +    ("flagged"
>> +     (:propertize "flagged" display
>> +                  (image :type svg :file
>> +                         ,(expand-file-name
>> +                           "resources/star.svg"
>> +                           (file-name-directory
>> +                            (or
>> +                             (locate-library "notmuch-tagger")
>> +                             (buffer-file-name))))
>
> Interesting.  Is this a standard way to locate resources?  (I've never
> had need to.)
>
> Since there are other icons here as well, perhaps the resources
> directory should be bound to a global variable so it's easy to construct
> other standard notmuch icon names?  You capture this in a function in
> patch 4, but that function doesn't obviously accomplish anything a
> simple variable wouldn't.

I was thinking this too. M-x apropos RET -path RET (apropos "-path")
outputs (at least) 2 symbols that are relevant here:

image-load-path
  Variable: List of locations in which to search for image files.
  Properties: standard-value custom-type custom-requests
              variable-documentation
and

image-load-path-for-library
  Function: Return a suitable search path for images used by LIBRARY.

(if the second were used I'd suggest to use 'notmuch' instead of
'notmuch-tagger' -- just to support me who just installs notmuch.elc
which is done by concatenating all notmuch .el files together to one
notmuch.el file which is then byte-compiled :D)

> Another possibility is that these icons could be included directly in
> the Elisp source, probably as simplified SVGs (your SVGs look like they
> could be cut down to 3 or 4 lines of XML easily) or as XPMs.  Besides
> skirting issues with resource location, this would make it trivial to
> alter their colors based on user preferences.

I also had the same 2 things in mind, simplify SVGs and possibly include
that directly in the source...


Tomi

^ permalink raw reply	[flat|nested] 8+ messages in thread
end of thread, other threads:[~2013-01-23  2:15 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-01-18 16:03 emacs: Customize how each tag is displayed Damien Cassou
2013-01-18 16:03 ` [PATCH 1/4] emacs: Add notmuch-intersperse to notmuch-lib/ Damien Cassou
2013-01-18 16:03 ` [PATCH 2/4] emacs: pictures that might be used as icons for tags Damien Cassou
2013-01-18 16:03 ` [PATCH 3/4] emacs: possibility to customize the rendering of tags Damien Cassou
2013-01-23  0:17   ` Austin Clements
2013-01-23  2:15     ` Tomi Ollila
2013-01-18 16:03 ` [PATCH 4/4] emacs: provide convenience functions for notmuch-tagger configuration Damien Cassou
2013-01-23  0:24 ` emacs: Customize how each tag is displayed Austin Clements

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

	https://yhetil.org/notmuch.git/

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).