branch: externals/notmuch-indicator
commit 598dedf9928d9055f71562b7e79c8a2d500ec0c8
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Add docs to the Commentary
---
notmuch-indicator.el | 43 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 43 insertions(+)
diff --git a/notmuch-indicator.el b/notmuch-indicator.el
index d010586c0a..ab346c404d 100644
--- a/notmuch-indicator.el
+++ b/notmuch-indicator.el
@@ -28,6 +28,49 @@
;;; Commentary:
;;
;; Work-in-progress.
+;;
+;; 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:
+;;
+;; (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.
;;; Code:
