emacs: help: split out notmuch-describe-key as a function

[notmuch] / emacs / notmuch-lib.el

diff --git a/emacs/notmuch-lib.el b/emacs/notmuch-lib.el
index 17040ed86bd352343c6ce87296ff8ba2bb4c8752..065645c88234d7091e3b256153e6a01110583be9 100644 (file)
--- a/emacs/notmuch-lib.el
+++ b/emacs/notmuch-lib.el
@@ -80,9 +80,8 @@ search."
   "An external script to incorporate new mail into the notmuch database.
 
 This variable controls the action invoked by
   "An external script to incorporate new mail into the notmuch database.
 
 This variable controls the action invoked by

-`notmuch-search-poll-and-refresh-view' and
-`notmuch-hello-poll-and-update' (each have a default keybinding
-of 'G') to incorporate new mail into the notmuch database.
+`notmuch-poll-and-refresh-this-buffer' (bound by default to 'G')
+to incorporate new mail into the notmuch database.

 
 If set to nil (the default), new mail is processed by invoking
 \"notmuch new\". Otherwise, this should be set to a string that
 
 If set to nil (the default), new mail is processed by invoking
 \"notmuch new\". Otherwise, this should be set to a string that


@@ -237,12 +236,37 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."
        "M-"
       (concat desc " "))))
 
        "M-"
       (concat desc " "))))
 

+
+(defun notmuch-describe-key (actual-key binding prefix ua-keys tail)
+  "Prepend cons cells describing prefix-arg ACTUAL-KEY and ACTUAL-KEY to TAIL
+
+It does not prepend if ACTUAL-KEY is already listed in TAIL."
+  (let ((key-string (concat prefix (format-kbd-macro actual-key))))
+    ;; We don't include documentation if the key-binding is
+    ;; over-ridden. Note, over-riding a binding automatically hides the
+    ;; prefixed version too.
+    (unless (assoc key-string tail)
+      (when (and ua-keys (symbolp binding)
+                (get binding 'notmuch-prefix-doc))
+       ;; Documentation for prefixed command
+       (let ((ua-desc (key-description ua-keys)))
+         (push (cons (concat ua-desc " " prefix (format-kbd-macro actual-key))
+                     (get binding 'notmuch-prefix-doc))
+               tail)))
+      ;; Documentation for command
+      (push (cons key-string
+                 (or (and (symbolp binding) (get binding 'notmuch-doc))
+                     (notmuch-documentation-first-line binding)))
+           tail)))
+    tail)
+

 (defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)
 (defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)

-  "Return a list of strings, each describing one binding in KEYMAP.
+  "Return a list of cons cells, each describing one binding in KEYMAP.

 
 

-Each string gives a human-readable description of the key and a
-one-line description of the bound function.  See `notmuch-help'
-for an overview of how this documentation is extracted.
+Each cons cell consists of a string giving a human-readable
+description of the key, and a one-line description of the bound
+function.  See `notmuch-help' for an overview of how this
+documentation is extracted.

 
 UA-KEYS should be a key sequence bound to `universal-argument'.
 It will be used to describe bindings of commands that support a
 
 UA-KEYS should be a key sequence bound to `universal-argument'.
 It will be used to describe bindings of commands that support a


@@ -254,19 +278,8 @@ prefix argument.  PREFIX and TAIL are used internally."
            (setq tail
                  (notmuch-describe-keymap
                   binding ua-keys (notmuch-prefix-key-description key) tail)))
            (setq tail
                  (notmuch-describe-keymap
                   binding ua-keys (notmuch-prefix-key-description key) tail)))

-          (t
-           (when (and ua-keys (symbolp binding)
-                      (get binding 'notmuch-prefix-doc))
-             ;; Documentation for prefixed command
-             (let ((ua-desc (key-description ua-keys)))
-               (push (concat ua-desc " " prefix (format-kbd-macro (vector key))
-                             "\t" (get binding 'notmuch-prefix-doc))
-                     tail)))
-           ;; Documentation for command
-           (push (concat prefix (format-kbd-macro (vector key)) "\t"
-                         (or (and (symbolp binding) (get binding 'notmuch-doc))
-                             (notmuch-documentation-first-line binding)))
-                 tail))))
+          (binding
+           (setq tail (notmuch-describe-key (vector key) binding prefix ua-keys tail)))))

    keymap)
   tail)
 
    keymap)
   tail)
 


@@ -274,11 +287,14 @@ prefix argument.  PREFIX and TAIL are used internally."
   "Like `substitute-command-keys' but with documentation, not function names."
   (let ((beg 0))
     (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)
   "Like `substitute-command-keys' but with documentation, not function names."
   (let ((beg 0))
     (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)

-      (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))
-            (keymap (symbol-value (intern keymap-name)))
-            (ua-keys (where-is-internal 'universal-argument keymap t))
-            (desc-list (notmuch-describe-keymap keymap ua-keys))
-            (desc (mapconcat #'identity desc-list "\n")))
+      (let ((desc
+            (save-match-data
+              (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))
+                     (keymap (symbol-value (intern keymap-name)))
+                     (ua-keys (where-is-internal 'universal-argument keymap t))
+                     (desc-alist (notmuch-describe-keymap keymap ua-keys))
+                     (desc-list (mapcar (lambda (arg) (concat (car arg) "\t" (cdr arg))) desc-alist)))
+                (mapconcat #'identity desc-list "\n")))))

        (setq doc (replace-match desc 1 1 doc)))
       (setq beg (match-end 0)))
     doc))
        (setq doc (replace-match desc 1 1 doc)))
       (setq beg (match-end 0)))
     doc))


@@ -355,6 +371,14 @@ user-friendly queries."
   "Return a query that matches the message with id ID."
   (concat "id:" (notmuch-escape-boolean-term id)))
 
   "Return a query that matches the message with id ID."
   (concat "id:" (notmuch-escape-boolean-term id)))
 

+(defun notmuch-hex-encode (str)
+  "Hex-encode STR (e.g., as used by batch tagging).
+
+This replaces spaces, percents, and double quotes in STR with
+%NN where NN is the hexadecimal value of the character."
+  (replace-regexp-in-string
+   "[ %\"]" (lambda (match) (format "%%%02x" (aref match 0))) str))
+

 ;;
 
 (defun notmuch-common-do-stash (text)
 ;;
 
 (defun notmuch-common-do-stash (text)