branch: externals/notmuch-indicator
commit c7e62b16a01cf85be872f4f2488b5ef15833bce3
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Update docs in light of commit bfb48f7
---
README.md | 33 ++++++++++++++++++++-------------
notmuch-indicator.el | 45 ++++++++++++++++++++++++++-------------------
2 files changed, 46 insertions(+), 32 deletions(-)
diff --git a/README.md b/README.md
index 840ba08555..e12640f200 100644
--- a/README.md
+++ b/README.md
@@ -12,19 +12,26 @@ 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.
+lists). Each plist consists of one mandarory property and two optional
+ones:
+
+1. The `:terms`, which is required, is a string that holds the
+ command-line arguments passed to `notmuch-count(1)` (read the Notmuch
+ documentation for the technicalities).
+
+2. The `:label`, which is optional, is an arbitrary string that is
+ prepended to the return value of the above. If nil or omitted, no
+ label is displayed.
+
+3. The `face`, which is optional, is the symbol of a face that is
+ applied to the `:label`. It should not be quoted, so like `:face
+ bold`. Good candidates are `bold`, `italic`, `success`, `warning`,
+ `error`, though anything will do. If nil or omitted, no face is
+ used.
+
+Multiple plist lists 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 searches:
diff --git a/notmuch-indicator.el b/notmuch-indicator.el
index ef798ec795..2b3363b07b 100644
--- a/notmuch-indicator.el
+++ b/notmuch-indicator.el
@@ -27,31 +27,38 @@
;;; Commentary:
;;
-;; 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.
+;; 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.
+;; 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:
+;; lists). Each plist consists of one mandarory property and two
+;; optional ones:
;;
-;; 1. The `:terms' holds the command-line arguments passed to
-;; `notmuch-count(1)' (read the Notmuch documentation for the
-;; technicalities).
+;; 1. The `:terms', which is required, is a string that 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.
+;; 2. The `:label', which is optional, is an arbitrary string that is
+;; prepended to the return value of the above. If nil or omitted, no
+;; label is displayed.
;;
-;; Multiple plists represent separate `notmuch-count(1)' queries. These
-;; are run sequentially. Their return values are joined into a single
-;; string.
+;; 3. The `face', which is optional, is the symbol of a face that is
+;; applied to the `:label'. It should not be quoted, so like :face
+;; bold. Good candidates are `bold', `italic', `success', `warning',
+;; `error', though anything will do. If nil or omitted, no face is
+;; used.
+;;
+;; Multiple plist lists 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 searches:
;;
@@ -62,9 +69,9 @@
;;
;; 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-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
