93/3529132b5d68fd09ef746e64f21722a32c80da

   1 Return-Path: <amdragon@mit.edu>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id 6F1CD431FAF\r
   6         for <notmuch@notmuchmail.org>; Sat,  5 Oct 2013 20:23:03 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -0.7\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
  12         tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id qmOxs4DTKSO6 for <notmuch@notmuchmail.org>;\r
  16         Sat,  5 Oct 2013 20:22:57 -0700 (PDT)\r
  17 Received: from dmz-mailsec-scanner-6.mit.edu (dmz-mailsec-scanner-6.mit.edu\r
  18         [18.7.68.35])\r
  19         by olra.theworths.org (Postfix) with ESMTP id 0F962431FBC\r
  20         for <notmuch@notmuchmail.org>; Sat,  5 Oct 2013 20:22:56 -0700 (PDT)\r
  21 X-AuditID: 12074423-b7fc98e0000009a2-82-5250d78fe7e2\r
  22 Received: from mailhub-auth-2.mit.edu ( [18.7.62.36])\r
  23         by dmz-mailsec-scanner-6.mit.edu (Symantec Messaging Gateway) with SMTP\r
  24         id 4E.46.02466.F87D0525; Sat,  5 Oct 2013 23:22:55 -0400 (EDT)\r
  25 Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
  26         by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id r963MrQe012799; \r
  27         Sat, 5 Oct 2013 23:22:54 -0400\r
  28 Received: from drake.dyndns.org\r
  29         (216-15-114-40.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com\r
  30         [216.15.114.40]) (authenticated bits=0)\r
  31         (User authenticated as amdragon@ATHENA.MIT.EDU)\r
  32         by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r963MpQI024420\r
  33         (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
  34         Sat, 5 Oct 2013 23:22:53 -0400\r
  35 Received: from amthrax by drake.dyndns.org with local (Exim 4.77)\r
  36         (envelope-from <amdragon@mit.edu>)\r
  37         id 1VSevj-00037t-QP; Sat, 05 Oct 2013 23:22:51 -0400\r
  38 From: Austin Clements <amdragon@MIT.EDU>\r
  39 To: notmuch@notmuchmail.org\r
  40 Subject: [PATCH 4/6] emacs: Support overriding help and describing prefix\r
  41         action\r
  42 Date: Sat,  5 Oct 2013 23:22:46 -0400\r
  43 Message-Id: <1381029768-11883-5-git-send-email-amdragon@mit.edu>\r
  44 X-Mailer: git-send-email 1.8.4.rc3\r
  45 In-Reply-To: <1381029768-11883-1-git-send-email-amdragon@mit.edu>\r
  46 References: <1381029768-11883-1-git-send-email-amdragon@mit.edu>\r
  47 X-Brightmail-Tracker:\r
  48  H4sIAAAAAAAAA+NgFtrEIsWRmVeSWpSXmKPExsUixG6nott/PSDIoP2ppsX1mzOZHRg9nq26\r
  49         xRzAGMVlk5Kak1mWWqRvl8CVMe3KM8aC//IVi868YmlgfC7ZxcjJISFgItH87QEzhC0mceHe\r
  50         ejYQW0hgH6PEi82WXYxcQPYGRokJ19tZIZzbTBIX55xih3DmMkrMPfYXrJ1NQENi2/7ljCC2\r
  51         iIC0xM67s4E6ODiYBdQk/nSpgISFBQIkbrTOZwexWQRUJXq3H2YBsXkFHCT2XWhjgbhCSWLh\r
  52         qW2sIDangKPE5lNvGCEucpC4vvw54wRG/gWMDKsYZVNyq3RzEzNzilOTdYuTE/PyUot0zfRy\r
  53         M0v0UlNKNzGCg8ZFeQfjn4NKhxgFOBiVeHgdvAKChFgTy4orcw8xSnIwKYnyTr8KFOJLyk+p\r
  54         zEgszogvKs1JLT7EKMHBrCTCy1IAlONNSaysSi3Kh0lJc7AoifPe4rAPEhJITyxJzU5NLUgt\r
  55         gsnKcHAoSfD2XANqFCxKTU+tSMvMKUFIM3FwggznARo+GaSGt7ggMbc4Mx0if4pRUUqcdzZI\r
  56         QgAkkVGaB9cLi+pXjOJArwjzbgep4gEmBLjuV0CDmYAGR0n4ggwuSURISTUwsp0qypv+fdMG\r
  57         gcCu8tXbndU5+N8378huWeD16mnRflvhdRUSsW3/eUSWMK9zW7nTgTHkAe/23FkzzVy4Rebz\r
  58         nw97s+Wqh0rq2qcWjnvOr1t9Z57vkr7ZGfF3hGX5edxYZ8zatijynf16B6/impWRqVGVW9Yy\r
  59         sRqs/XuK44ybkXDA8YZPf2/2KbEUZyQaajEXFScCAIcdGEHFAgAA\r
  60 X-BeenThere: notmuch@notmuchmail.org\r
  61 X-Mailman-Version: 2.1.13\r
  62 Precedence: list\r
  63 List-Id: "Use and development of the notmuch mail system."\r
  64         <notmuch.notmuchmail.org>\r
  65 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  66         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  67 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  68 List-Post: <mailto:notmuch@notmuchmail.org>\r
  69 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  70 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  71         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  72 X-List-Received-Date: Sun, 06 Oct 2013 03:23:03 -0000\r
  73 \r
  74 Traditionally, function documentation strings are intended primarily\r
  75 for programmers, rather than users.  They're written from the\r
  76 perspective of calling the function, not interactively invoking it.\r
  77 They're only ever displayed along with the function prototype (and\r
  78 often refer to argument names).  And built-in help commands like\r
  79 `describe-bindings' show the name of the command, not its\r
  80 documentation.\r
  81 \r
  82 The notmuch help system is like `describe-bindings', but tries to be\r
  83 more user-friendly by displaying documentation strings, rather than\r
  84 Elisp command names.  For most commands, this is fine, but for some\r
  85 the "programmer description" is inappropriate for interactive use.\r
  86 This is particularly noticeable for commands that take an optional\r
  87 prefix argument.\r
  88 \r
  89 This patch adds support for two symbol properties: notmuch-doc and\r
  90 notmuch-prefix-doc, which let a command override its interactive\r
  91 documentation and provide separate documentation for its prefixed\r
  92 invocation.  If notmuch-prefix-doc is present, we add an extra line to\r
  93 the help giving the prefixed key sequence along with the documentation\r
  94 for the prefixed command.\r
  95 ---\r
  96  emacs/notmuch.el | 29 ++++++++++++++++++++++++-----\r
  97  1 file changed, 24 insertions(+), 5 deletions(-)\r
  98 \r
  99 diff --git a/emacs/notmuch.el b/emacs/notmuch.el\r
 100 index a36849f..278bd35 100644\r
 101 --- a/emacs/notmuch.el\r
 102 +++ b/emacs/notmuch.el\r
 103 @@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."\r
 104         "M-"\r
 105        (concat desc " "))))\r
 106  \r
 107 -(defun notmuch-describe-keymap (keymap &optional prefix tail)\r
 108 +(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)\r
 109    "Return a list of strings, each describing one key in KEYMAP.\r
 110  \r
 111  Each string gives a human-readable description of the key and the\r
 112 @@ -151,10 +151,19 @@ first line of documentation for the bound function."\r
 113            ((keymapp binding)\r
 114             (setq tail\r
 115                   (notmuch-describe-keymap\r
 116 -                  binding (notmuch-prefix-key-description key) tail)))\r
 117 +                  binding ua-keys (notmuch-prefix-key-description key) tail)))\r
 118            (t\r
 119 +           (when (and ua-keys (symbolp binding)\r
 120 +                      (get binding 'notmuch-prefix-doc))\r
 121 +             ;; Documentation for prefixed command\r
 122 +             (let ((ua-desc (key-description ua-keys)))\r
 123 +               (push (concat ua-desc " " prefix (format-kbd-macro (vector key))\r
 124 +                             "\t" (get binding 'notmuch-prefix-doc))\r
 125 +                     tail)))\r
 126 +           ;; Documentation for command\r
 127             (push (concat prefix (format-kbd-macro (vector key)) "\t"\r
 128 -                         (notmuch-documentation-first-line binding))\r
 129 +                         (or (and (symbolp binding) (get binding 'notmuch-doc))\r
 130 +                             (notmuch-documentation-first-line binding)))\r
 131                   tail))))\r
 132     keymap)\r
 133    tail)\r
 134 @@ -165,14 +174,24 @@ first line of documentation for the bound function."\r
 135      (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)\r
 136        (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))\r
 137              (keymap (symbol-value (intern keymap-name)))\r
 138 -            (desc-list (notmuch-describe-keymap keymap))\r
 139 +            (ua-keys (where-is-internal 'universal-argument keymap t))\r
 140 +            (desc-list (notmuch-describe-keymap keymap ua-keys))\r
 141              (desc (mapconcat #'identity desc-list "\n")))\r
 142         (setq doc (replace-match desc 1 1 doc)))\r
 143        (setq beg (match-end 0)))\r
 144      doc))\r
 145  \r
 146  (defun notmuch-help ()\r
 147 -  "Display help for the current notmuch mode."\r
 148 +  "Display help for the current notmuch mode.\r
 149 +\r
 150 +This is similar to `describe-function' for the current major\r
 151 +mode, but bindings tables are shown with documentation strings\r
 152 +rather than command names.  By default, this uses the first line\r
 153 +of each command's documentation string.  A command can override\r
 154 +this by setting the 'notmuch-doc property of its command symbol.\r
 155 +A command that supports a prefix argument can explicitly document\r
 156 +its prefixed behavior by setting the 'notmuch-prefix-doc property\r
 157 +of its command symbol."\r
 158    (interactive)\r
 159    (let* ((mode major-mode)\r
 160          (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))\r
 161 -- \r
 162 1.8.4.rc3\r
 163 \r