From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id 6F1CD431FAF for ; Sat, 5 Oct 2013 20:23:03 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -0.7 X-Spam-Level: X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id qmOxs4DTKSO6 for ; Sat, 5 Oct 2013 20:22:57 -0700 (PDT) Received: from dmz-mailsec-scanner-6.mit.edu (dmz-mailsec-scanner-6.mit.edu [18.7.68.35]) by olra.theworths.org (Postfix) with ESMTP id 0F962431FBC for ; Sat, 5 Oct 2013 20:22:56 -0700 (PDT) X-AuditID: 12074423-b7fc98e0000009a2-82-5250d78fe7e2 Received: from mailhub-auth-2.mit.edu ( [18.7.62.36]) by dmz-mailsec-scanner-6.mit.edu (Symantec Messaging Gateway) with SMTP id 4E.46.02466.F87D0525; Sat, 5 Oct 2013 23:22:55 -0400 (EDT) Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11]) by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id r963MrQe012799; Sat, 5 Oct 2013 23:22:54 -0400 Received: from drake.dyndns.org (216-15-114-40.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com [216.15.114.40]) (authenticated bits=0) (User authenticated as amdragon@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r963MpQI024420 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT); Sat, 5 Oct 2013 23:22:53 -0400 Received: from amthrax by drake.dyndns.org with local (Exim 4.77) (envelope-from ) id 1VSevj-00037t-QP; Sat, 05 Oct 2013 23:22:51 -0400 From: Austin Clements To: notmuch@notmuchmail.org Subject: [PATCH 4/6] emacs: Support overriding help and describing prefix action Date: Sat, 5 Oct 2013 23:22:46 -0400 Message-Id: <1381029768-11883-5-git-send-email-amdragon@mit.edu> X-Mailer: git-send-email 1.8.4.rc3 In-Reply-To: <1381029768-11883-1-git-send-email-amdragon@mit.edu> References: <1381029768-11883-1-git-send-email-amdragon@mit.edu> X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFtrEIsWRmVeSWpSXmKPExsUixG6nott/PSDIoP2ppsX1mzOZHRg9nq26 xRzAGMVlk5Kak1mWWqRvl8CVMe3KM8aC//IVi868YmlgfC7ZxcjJISFgItH87QEzhC0mceHe ejYQW0hgH6PEi82WXYxcQPYGRokJ19tZIZzbTBIX55xih3DmMkrMPfYXrJ1NQENi2/7ljCC2 iIC0xM67s4E6ODiYBdQk/nSpgISFBQIkbrTOZwexWQRUJXq3H2YBsXkFHCT2XWhjgbhCSWLh qW2sIDangKPE5lNvGCEucpC4vvw54wRG/gWMDKsYZVNyq3RzEzNzilOTdYuTE/PyUot0zfRy M0v0UlNKNzGCg8ZFeQfjn4NKhxgFOBiVeHgdvAKChFgTy4orcw8xSnIwKYnyTr8KFOJLyk+p zEgszogvKs1JLT7EKMHBrCTCy1IAlONNSaysSi3Kh0lJc7AoifPe4rAPEhJITyxJzU5NLUgt gsnKcHAoSfD2XANqFCxKTU+tSMvMKUFIM3FwggznARo+GaSGt7ggMbc4Mx0if4pRUUqcdzZI QgAkkVGaB9cLi+pXjOJArwjzbgep4gEmBLjuV0CDmYAGR0n4ggwuSURISTUwsp0qypv+fdMG gcCu8tXbndU5+N8378huWeD16mnRflvhdRUSsW3/eUSWMK9zW7nTgTHkAe/23FkzzVy4Rebz nw97s+Wqh0rq2qcWjnvOr1t9Z57vkr7ZGfF3hGX5edxYZ8zatijynf16B6/impWRqVGVW9Yy sRqs/XuK44ybkXDA8YZPf2/2KbEUZyQaajEXFScCAIcdGEHFAgAA X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 06 Oct 2013 03:23:03 -0000 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. --- emacs/notmuch.el | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/emacs/notmuch.el b/emacs/notmuch.el index a36849f..278bd35 100644 --- a/emacs/notmuch.el +++ b/emacs/notmuch.el @@ -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))))) -- 1.8.4.rc3