branch: externals/notmuch-indicator
commit 700772763b9bc7e5c70886c6ab474d868c755e14
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Add documentation to the README
---
README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 47 insertions(+)
diff --git a/README.md b/README.md
index 8a88a0357b..74516e0178 100644
--- a/README.md
+++ b/README.md
@@ -2,3 +2,50 @@
WORK-IN-PROGRESS. Read the announcement:
<https://protesilaos.com/codelog/2022-09-19-emacs-notmuch-indicator-prototype/>.
+
+* * *
+
+This is a simple package that renders an indicator with an email count
+of the `notmuch` index on the Emacs mode line. The underlying mechanism
+is that of `notmuch-count(1)`, which is used to find the number of items
+that match the given search terms.
+
+The indicator is enabled when `notmuch-indicator-mode` is on.
+
+The user option `notmuch-indicator-args` provides the means to define
+search terms and associate them with a given label. The label is purely
+cosmetic, though it helps characterise the resulting counter.
+
+The value of `notmuch-indicator-args` is a list of plists (property
+lists). Each plist consists of two properties, both of which accept a
+string value:
+
+1. The `:terms` holds the command-line arguments passed to
+ `notmuch-count(1)` (read the Notmuch documentation for the
+ technicalities).
+
+2. The `:label` is an arbitrary string that is prepended to the return
+ value of the above.
+
+Multiple plists represent separate `notmuch-count(1)` queries. These
+are run sequentially. Their return values are joined into a single
+string.
+
+For instance, a value like the following defines three commands:
+
+```elisp
+(setq notmuch-indicator-args
+ '((:terms "tag:unread and tag:inbox" :label "@")
+ (:terms "from:authorities and tag:unread" :label "👺")
+ (:terms "--output threads tag:loveletter" :label "💕")))
+```
+
+These form a string like: `@50 👺1000 💕0`.
+
+The user option `notmuch-indicator-refresh-count` determines how often
+the indicator will be refreshed. It accepts a numeric argument which
+represents seconds.
+
+The user option `notmuch-indicator-force-refresh-commands` accepts as
+its value a list of symbols. Those are commands that will forcefully
+update the indicator after they are invoked.
