ab/8a5d87924d7004043204f96c7e6499cbe6bfc7

   1 Return-Path: <m.walters@qmul.ac.uk>\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 4D132431FBC\r
   6         for <notmuch@notmuchmail.org>; Sun,  6 Oct 2013 13:14:29 -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: -1.098\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-1.098 tagged_above=-999 required=5\r
  12         tests=[DKIM_ADSP_CUSTOM_MED=0.001, FREEMAIL_FROM=0.001,\r
  13         NML_ADSP_CUSTOM_MED=1.2, RCVD_IN_DNSWL_MED=-2.3] autolearn=disabled\r
  14 Received: from olra.theworths.org ([127.0.0.1])\r
  15         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  16         with ESMTP id 84BzyTUCfjsZ for <notmuch@notmuchmail.org>;\r
  17         Sun,  6 Oct 2013 13:14:23 -0700 (PDT)\r
  18 Received: from mail2.qmul.ac.uk (mail2.qmul.ac.uk [138.37.6.6])\r
  19         (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))\r
  20         (No client certificate requested)\r
  21         by olra.theworths.org (Postfix) with ESMTPS id 0A5EA431FAF\r
  22         for <notmuch@notmuchmail.org>; Sun,  6 Oct 2013 13:14:23 -0700 (PDT)\r
  23 Received: from smtp.qmul.ac.uk ([138.37.6.40])\r
  24         by mail2.qmul.ac.uk with esmtp (Exim 4.71)\r
  25         (envelope-from <m.walters@qmul.ac.uk>)\r
  26         id 1VSuiM-0000fE-Ln; Sun, 06 Oct 2013 21:14:09 +0100\r
  27 Received: from 93-97-24-31.zone5.bethere.co.uk ([93.97.24.31] helo=localhost)\r
  28         by smtp.qmul.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.71)\r
  29         (envelope-from <m.walters@qmul.ac.uk>)\r
  30         id 1VSuiM-0007C9-AE; Sun, 06 Oct 2013 21:14:06 +0100\r
  31 From: Mark Walters <markwalters1009@gmail.com>\r
  32 To: Austin Clements <amdragon@MIT.EDU>, notmuch@notmuchmail.org\r
  33 Subject: Re: [PATCH 4/6] emacs: Support overriding help and describing prefix\r
  34         action\r
  35 In-Reply-To: <1381029768-11883-5-git-send-email-amdragon@mit.edu>\r
  36 References: <1381029768-11883-1-git-send-email-amdragon@mit.edu>\r
  37         <1381029768-11883-5-git-send-email-amdragon@mit.edu>\r
  38 User-Agent: Notmuch/0.16 (http://notmuchmail.org) Emacs/24.3.1\r
  39         (x86_64-pc-linux-gnu)\r
  40 Date: Sun, 06 Oct 2013 21:14:04 +0100\r
  41 Message-ID: <87wqlqqhrn.fsf@qmul.ac.uk>\r
  42 MIME-Version: 1.0\r
  43 Content-Type: text/plain\r
  44 X-Sender-Host-Address: 93.97.24.31\r
  45 X-QM-SPAM-Info: Sender has good ham record.  :)\r
  46 X-QM-Body-MD5: 4b1b0e1d5fb09106fd36f4b71bfaeb7a (of first 20000 bytes)\r
  47 X-SpamAssassin-Score: 0.0\r
  48 X-SpamAssassin-SpamBar: /\r
  49 X-SpamAssassin-Report: The QM spam filters have analysed this message to\r
  50         determine if it is\r
  51         spam. We require at least 5.0 points to mark a message as spam.\r
  52         This message scored 0.0 points. Summary of the scoring: \r
  53         * 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail\r
  54         provider *      (markwalters1009[at]gmail.com)\r
  55         *  0.0 AWL AWL: From: address is in the auto white-list\r
  56 X-QM-Scan-Virus: ClamAV says the message is clean\r
  57 X-BeenThere: notmuch@notmuchmail.org\r
  58 X-Mailman-Version: 2.1.13\r
  59 Precedence: list\r
  60 List-Id: "Use and development of the notmuch mail system."\r
  61         <notmuch.notmuchmail.org>\r
  62 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  63         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  64 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  65 List-Post: <mailto:notmuch@notmuchmail.org>\r
  66 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  67 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  68         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  69 X-List-Received-Date: Sun, 06 Oct 2013 20:14:29 -0000\r
  70 \r
  71 \r
  72 This whole series looks good to me. If you are rolling another version\r
  73 for any reason I have one trivial comment\r
  74 \r
  75 On Sun, 06 Oct 2013, Austin Clements <amdragon@MIT.EDU> wrote:\r
  76 > Traditionally, function documentation strings are intended primarily\r
  77 > for programmers, rather than users.  They're written from the\r
  78 > perspective of calling the function, not interactively invoking it.\r
  79 > They're only ever displayed along with the function prototype (and\r
  80 > often refer to argument names).  And built-in help commands like\r
  81 > `describe-bindings' show the name of the command, not its\r
  82 > documentation.\r
  83 >\r
  84 > The notmuch help system is like `describe-bindings', but tries to be\r
  85 > more user-friendly by displaying documentation strings, rather than\r
  86 > Elisp command names.  For most commands, this is fine, but for some\r
  87 > the "programmer description" is inappropriate for interactive use.\r
  88 > This is particularly noticeable for commands that take an optional\r
  89 > prefix argument.\r
  90 >\r
  91 > This patch adds support for two symbol properties: notmuch-doc and\r
  92 > notmuch-prefix-doc, which let a command override its interactive\r
  93 > documentation and provide separate documentation for its prefixed\r
  94 > invocation.  If notmuch-prefix-doc is present, we add an extra line to\r
  95 > the help giving the prefixed key sequence along with the documentation\r
  96 > for the prefixed command.\r
  97 > ---\r
  98 >  emacs/notmuch.el | 29 ++++++++++++++++++++++++-----\r
  99 >  1 file changed, 24 insertions(+), 5 deletions(-)\r
 100 >\r
 101 > diff --git a/emacs/notmuch.el b/emacs/notmuch.el\r
 102 > index a36849f..278bd35 100644\r
 103 > --- a/emacs/notmuch.el\r
 104 > +++ b/emacs/notmuch.el\r
 105 > @@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."\r
 106 >       "M-"\r
 107 >        (concat desc " "))))\r
 108 >  \r
 109 > -(defun notmuch-describe-keymap (keymap &optional prefix tail)\r
 110 > +(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)\r
 111 >    "Return a list of strings, each describing one key in KEYMAP.\r
 112 >  \r
 113 >  Each string gives a human-readable description of the key and the\r
 114 \r
 115 It would be nice to document the ua-keys variable here. It took me some\r
 116 time to work out what was going in (and I worked out based on the\r
 117 caller).\r
 118 \r
 119 Best wishes\r
 120 \r
 121 Mark\r
 122 \r
 123 > @@ -151,10 +151,19 @@ first line of documentation for the bound function."\r
 124 >          ((keymapp binding)\r
 125 >           (setq tail\r
 126 >                 (notmuch-describe-keymap\r
 127 > -                binding (notmuch-prefix-key-description key) tail)))\r
 128 > +                binding ua-keys (notmuch-prefix-key-description key) tail)))\r
 129 >          (t\r
 130 > +         (when (and ua-keys (symbolp binding)\r
 131 > +                    (get binding 'notmuch-prefix-doc))\r
 132 > +           ;; Documentation for prefixed command\r
 133 > +           (let ((ua-desc (key-description ua-keys)))\r
 134 > +             (push (concat ua-desc " " prefix (format-kbd-macro (vector key))\r
 135 > +                           "\t" (get binding 'notmuch-prefix-doc))\r
 136 > +                   tail)))\r
 137 > +         ;; Documentation for command\r
 138 >           (push (concat prefix (format-kbd-macro (vector key)) "\t"\r
 139 > -                       (notmuch-documentation-first-line binding))\r
 140 > +                       (or (and (symbolp binding) (get binding 'notmuch-doc))\r
 141 > +                           (notmuch-documentation-first-line binding)))\r
 142 >                 tail))))\r
 143 >     keymap)\r
 144 >    tail)\r
 145 > @@ -165,14 +174,24 @@ first line of documentation for the bound function."\r
 146 >      (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)\r
 147 >        (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))\r
 148 >            (keymap (symbol-value (intern keymap-name)))\r
 149 > -          (desc-list (notmuch-describe-keymap keymap))\r
 150 > +          (ua-keys (where-is-internal 'universal-argument keymap t))\r
 151 > +          (desc-list (notmuch-describe-keymap keymap ua-keys))\r
 152 >            (desc (mapconcat #'identity desc-list "\n")))\r
 153 >       (setq doc (replace-match desc 1 1 doc)))\r
 154 >        (setq beg (match-end 0)))\r
 155 >      doc))\r
 156 >  \r
 157 >  (defun notmuch-help ()\r
 158 > -  "Display help for the current notmuch mode."\r
 159 > +  "Display help for the current notmuch mode.\r
 160 > +\r
 161 > +This is similar to `describe-function' for the current major\r
 162 > +mode, but bindings tables are shown with documentation strings\r
 163 > +rather than command names.  By default, this uses the first line\r
 164 > +of each command's documentation string.  A command can override\r
 165 > +this by setting the 'notmuch-doc property of its command symbol.\r
 166 > +A command that supports a prefix argument can explicitly document\r
 167 > +its prefixed behavior by setting the 'notmuch-prefix-doc property\r
 168 > +of its command symbol."\r
 169 >    (interactive)\r
 170 >    (let* ((mode major-mode)\r
 171 >        (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))\r
 172 > -- \r
 173 > 1.8.4.rc3\r
 174 >\r
 175 > _______________________________________________\r
 176 > notmuch mailing list\r
 177 > notmuch@notmuchmail.org\r
 178 > http://notmuchmail.org/mailman/listinfo/notmuch\r