From 3806a7a3c963a18429c0c7239489b8126190a0c5 Mon Sep 17 00:00:00 2001
From: slotThe <soliditsallgood@mailbox.org>
Date: Sat, 28 Nov 2020 09:24:51 +0100
Subject: Update readme and changelog

---
 changelog.md                      |  1 +
 readme.md                         | 81 ++++++++++++++++++++++++++++++++++++++-
 src/Xmobar/Plugins/NotmuchMail.hs |  4 +-
 3 files changed, 83 insertions(+), 3 deletions(-)

diff --git a/changelog.md b/changelog.md
index cfa9ada..deaa219 100644
--- a/changelog.md
+++ b/changelog.md
@@ -5,6 +5,7 @@ _New features_
   - New command line option `--add-font` (Ivan Brennan)
   - New monitor `MPDX` that extends `MPD` with the ability of having a
     custom alias.  Useful for connecting with multiple servers.
+  - New plugin `NotmuchMail` to monitor mail indexed by `notmuch`.
 
 _Bug fixes_
 
diff --git a/readme.md b/readme.md
index 8f820be..8a7f322 100644
--- a/readme.md
+++ b/readme.md
@@ -45,12 +45,13 @@
     - [`Volume Mixer Element Args RefreshRate`](#volume-mixer-element-args-refreshrate)
     - [`Alsa Mixer Element Args`](#alsa-mixer-element-args)
     - [`MPD Args RefreshRate`](#mpd-args-refreshrate)
-    - [`MPDX Alias Args RefreshRate`](#mpdx-alias-args-refreshrate)
+    - [`MPDX Args RefreshRate Alias`](#mpdx-args-refreshrate-alias)
     - [`Mpris1 PlayerName Args RefreshRate`](#mpris1-playername-args-refreshrate)
     - [`Mpris2 PlayerName Args RefreshRate`](#mpris2-playername-args-refreshrate)
     - [`Mail Args Alias`](#mail-args-alias)
     - [`MailX Args Opts Alias`](#mailx-args-opts-alias)
     - [`MBox Mboxes Opts Alias`](#mbox-mboxes-opts-alias)
+    - [`NotmuchMail Alias Args Rate`](#notmuchmail-alias-args-rate)
     - [`XPropertyLog PropName`](#xpropertylog-propname)
     - [`UnsafeXPropertyLog PropName`](#unsafexpropertylog-propname)
     - [`NamedXPropertyLog PropName Alias`](#namedxpropertylog-propname-alias)
@@ -1432,6 +1433,84 @@ Like `MPD` but uses as alias its last argument instead of "mpd".
                  ["-d", "/var/mail/", "-p", " "] "mbox"
     ```
 
+## `NotmuchMail Alias Args Rate`
+
+This plugin checks for new mail, provided that this mail is indexed by
+`notmuch`.  In the `notmuch` spirit, this plugin checks for new
+**threads** and not new individual messages.
+
+- Alias: What name the plugin should have in your template string.
+- Args: A list of `MailItem`s of the form
+
+    ``` haskell
+        [ MailItem "name" "address" "query"
+        ...
+        ]
+    ```
+
+  or, using explicit record syntax:
+
+    ``` haskell
+        [ MailItem
+            { name    = "name"
+            , address = "address"
+            , query   = "query"
+            }
+          ...
+        ]
+    ```
+
+  where
+
+    - `name` is what gets printed in the status bar before the number
+      of new threads.
+    - `address` is the e-mail address of the recipient, i.e. we only
+      query mail that was send to this particular address (in more
+      concrete terms, we pass the address to the `to:` constructor when
+      performing the search).  If `address` is empty, we search through
+      all unread mail, regardless of whom it was sent to.
+    - `query` is funneled to `notmuch search` verbatim.  For the general
+      query syntax, consult `notmuch search --help`, as well as
+      `notmuch-search-terms(7)`.  Note that the `unread` tag is
+      **always** added in front of the query and composed with it via an
+      **and**.
+
+- Rate: Rate with which to update the plugin (in deciseconds).
+- Example:
+
+  - A single `MailItem` that displays all unread threads from the given
+    address:
+
+      ``` haskell
+          MailItem "mbs:" "soliditsallgood@mailbox.org" ""
+      ```
+
+  - A single `MailItem` that displays all unread threads with
+    "[My-Subject]" somewhere in the title:
+
+      ``` haskell
+        MailItem "S:" "" "subject:[My-Subject]"
+      ```
+
+  - A full example of a `NotmuchMail` configuration:
+
+      ``` haskell
+          Run NotmuchMail "mail"  -- name for the template string
+            [ -- All unread mail to the below address, but nothing that's tagged
+              -- with @lists@ or @haskell@.
+              MailItem "mbs:"
+                       "soliditsallgood@mailbox.org"
+                       "not tag:lists and not tag:haskell"
+
+              -- All unread mail that has @[Haskell-Cafe]@ in the subject line.
+            , MailItem "C:" "" "subject:[Haskell-Cafe]"
+
+              -- All unread mail that's tagged as @lists@, but not @haskell@.
+            , MailItem "H:" "" "tag:lists and not tag:haskell"
+            ]
+            600                   -- update every 60 seconds
+      ```
+
 ## `XPropertyLog PropName`
 
 - Aliases to `PropName`
diff --git a/src/Xmobar/Plugins/NotmuchMail.hs b/src/Xmobar/Plugins/NotmuchMail.hs
index 4544a81..3da170c 100644
--- a/src/Xmobar/Plugins/NotmuchMail.hs
+++ b/src/Xmobar/Plugins/NotmuchMail.hs
@@ -18,8 +18,8 @@
 --
 -- As mail that was tagged is moved from the @new@ directory to @cur@,
 -- the @inotify@ solution that he mail 'Mail' plugin (and its variants)
--- uses won't work for such mail.  Hence we have to resort to refreshing
--- every N time intervals.
+-- uses won't work for such mail.  Hence, we have to resort to a
+-- refresh-based monitor.
 --
 -- Note that, in the `notmuch` spirit, this plugin checks for new
 -- threads and not new individual messages.  For convenience, the
-- 
cgit v1.2.3