debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-12-22 17:34:54 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

emacs: Support overriding help and describing prefix action

Browse source 
Traditionally, function documentation strings are intended primarily
for programmers, rather than users.  They're written from the
perspective of calling the function, not interactively invoking it.
They're only ever displayed along with the function prototype (and
often refer to argument names).  And built-in help commands like
`describe-bindings' show the name of the command, not its
documentation.

The notmuch help system is like `describe-bindings', but tries to be
more user-friendly by displaying documentation strings, rather than
Elisp command names.  For most commands, this is fine, but for some
the "programmer description" is inappropriate for interactive use.
This is particularly noticeable for commands that take an optional
prefix argument.

This patch adds support for two symbol properties: notmuch-doc and
notmuch-prefix-doc, which let a command override its interactive
documentation and provide separate documentation for its prefixed
invocation.  If notmuch-prefix-doc is present, we add an extra line to
the help giving the prefixed key sequence along with the documentation
for the prefixed command.
This commit is contained in:
Austin Clements 2013-10-05 23:22:46 -04:00 committed by David Bremner
parent adfff87a71
commit fad4f21cb7
1 changed files with 24 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
emacs/notmuch.el
View file

@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."
"M-"
(concat desc " "))))
(defun notmuch-describe-keymap (keymap &optional prefix tail)
(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)
"Return a list of strings, each describing one key in KEYMAP.
Each string gives a human-readable description of the key and the
@ -151,10 +151,19 @@ first line of documentation for the bound function."
((keymapp binding)
(setq tail
(notmuch-describe-keymap
binding (notmuch-prefix-key-description key) tail)))
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"
(notmuch-documentation-first-line binding))
(or (and (symbolp binding) (get binding 'notmuch-doc))
(notmuch-documentation-first-line binding)))
tail))))
keymap)
tail)
@ -165,14 +174,24 @@ first line of documentation for the bound function."
(while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)
(let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))
(keymap (symbol-value (intern keymap-name)))
(desc-list (notmuch-describe-keymap keymap))
(ua-keys (where-is-internal 'universal-argument keymap t))
(desc-list (notmuch-describe-keymap keymap ua-keys))
(desc (mapconcat #'identity desc-list "\n")))
(setq doc (replace-match desc 1 1 doc)))
(setq beg (match-end 0)))
doc))
(defun notmuch-help ()
"Display help for the current notmuch mode."
"Display help for the current notmuch mode.
This is similar to `describe-function' for the current major
mode, but bindings tables are shown with documentation strings
rather than command names. By default, this uses the first line
of each command's documentation string. A command can override
this by setting the 'notmuch-doc property of its command symbol.
A command that supports a prefix argument can explicitly document
its prefixed behavior by setting the 'notmuch-prefix-doc property
of its command symbol."
(interactive)
(let* ((mode major-mode)
(doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))