38/b7708c97454bf526cc0a2b16348d49771268ea

   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 1CD73431FAF\r
   6         for <notmuch@notmuchmail.org>; Mon,  7 Oct 2013 15:50:07 -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 qIC7nNgD3teE for <notmuch@notmuchmail.org>;\r
  16         Mon,  7 Oct 2013 15:50:01 -0700 (PDT)\r
  17 Received: from dmz-mailsec-scanner-1.mit.edu (dmz-mailsec-scanner-1.mit.edu\r
  18         [18.9.25.12])\r
  19         by olra.theworths.org (Postfix) with ESMTP id 6D907431FAE\r
  20         for <notmuch@notmuchmail.org>; Mon,  7 Oct 2013 15:50:01 -0700 (PDT)\r
  21 X-AuditID: 1209190c-b7fd38e0000009aa-28-52533a98a3c6\r
  22 Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])\r
  23         by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP\r
  24         id D2.E1.02474.89A33525; Mon,  7 Oct 2013 18:50:00 -0400 (EDT)\r
  25 Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
  26         by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id r97Mo0RH009653; \r
  27         Mon, 7 Oct 2013 18:50:00 -0400\r
  28 Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
  29         (authenticated bits=0)\r
  30         (User authenticated as amdragon@ATHENA.MIT.EDU)\r
  31         by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r97MnwWS001555\r
  32         (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT);\r
  33         Mon, 7 Oct 2013 18:49:59 -0400\r
  34 Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80)\r
  35         (envelope-from <amdragon@MIT.EDU>)\r
  36         id 1VTJck-0001Ni-7x; Mon, 07 Oct 2013 18:49:58 -0400\r
  37 Date: Mon, 7 Oct 2013 18:49:57 -0400\r
  38 From: Austin Clements <amdragon@MIT.EDU>\r
  39 To: Mark Walters <markwalters1009@gmail.com>\r
  40 Subject: Re: [PATCH 4/6] emacs: Support overriding help and describing prefix\r
  41         action\r
  42 Message-ID: <20131007224957.GL21611@mit.edu>\r
  43 References: <1381029768-11883-1-git-send-email-amdragon@mit.edu>\r
  44         <1381029768-11883-5-git-send-email-amdragon@mit.edu>\r
  45         <87wqlqqhrn.fsf@qmul.ac.uk>\r
  46 MIME-Version: 1.0\r
  47 Content-Type: text/plain; charset=us-ascii\r
  48 Content-Disposition: inline\r
  49 In-Reply-To: <87wqlqqhrn.fsf@qmul.ac.uk>\r
  50 User-Agent: Mutt/1.5.21 (2010-09-15)\r
  51 X-Brightmail-Tracker:\r
  52  H4sIAAAAAAAAA+NgFmpmleLIzCtJLcpLzFFi42IR4hRV1p1hFRxksL3FxmL1XB6L6zdnMjsw\r
  53         eeycdZfd49mqW8wBTFFcNimpOZllqUX6dglcGWdmdLAX7FWrOHO0soGxU66LkZNDQsBE4sje\r
  54         AywQtpjEhXvr2boYuTiEBPYxSix+9Z8ZwtnAKHG1+QuUc4pJ4sfSdewQzhJGidv3bjKD9LMI\r
  55         qEjsnzqVEcRmE9CQ2LZ/OZgtIqAjcfvQAnYQm1lAWuLb72YmEFtYIEzi5+WLYL28QDUXjn+A\r
  56         2jCVUWLTvANsEAlBiZMzn7BANGtJ3Pj3EqiZA2zQ8n8cIGFOoF2dm3vA5ogC3TDl5Da2CYxC\r
  57         s5B0z0LSPQuhewEj8ypG2ZTcKt3cxMyc4tRk3eLkxLy81CJdQ73czBK91JTSTYzgsJbk2cH4\r
  58         5qDSIUYBDkYlHl6Bw0FBQqyJZcWVuYcYJTmYlER5eyyDg4T4kvJTKjMSizPii0pzUosPMUpw\r
  59         MCuJ8AoYAeV4UxIrq1KL8mFS0hwsSuK8Nznsg4QE0hNLUrNTUwtSi2CyMhwcShK8kSBDBYtS\r
  60         01Mr0jJzShDSTBycIMN5gIbPA6nhLS5IzC3OTIfIn2JUlBLnnQ2SEABJZJTmwfXC0s4rRnGg\r
  61         V4R5d4BU8QBTFlz3K6DBTECDddkDQQaXJCKkpBoYSyY72vSem9J0QdNhmu3pZe95ePc8cbJv\r
  62         +r1Q+K6Fz99v2iLPT596eHmfTLS1qdADud9lLj/m6b8+xpYnPuPIO56aS8+PfL/snho0Qex2\r
  63         msnyjxLvI3yvv9+o09FlUbz++eYoHelH5002HTr4+7Nqr+h7dZ8qHrGHy9qLDKp3fVxpFfVc\r
  64         9O+EW0osxRmJhlrMRcWJAKXlQ/AWAwAA\r
  65 Cc: notmuch@notmuchmail.org\r
  66 X-BeenThere: notmuch@notmuchmail.org\r
  67 X-Mailman-Version: 2.1.13\r
  68 Precedence: list\r
  69 List-Id: "Use and development of the notmuch mail system."\r
  70         <notmuch.notmuchmail.org>\r
  71 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  72         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  73 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  74 List-Post: <mailto:notmuch@notmuchmail.org>\r
  75 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  76 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  77         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  78 X-List-Received-Date: Mon, 07 Oct 2013 22:50:07 -0000\r
  79 \r
  80 Quoth Mark Walters on Oct 06 at  9:14 pm:\r
  81 > \r
  82 > This whole series looks good to me. If you are rolling another version\r
  83 > for any reason I have one trivial comment\r
  84 > \r
  85 > On Sun, 06 Oct 2013, Austin Clements <amdragon@MIT.EDU> wrote:\r
  86 > > Traditionally, function documentation strings are intended primarily\r
  87 > > for programmers, rather than users.  They're written from the\r
  88 > > perspective of calling the function, not interactively invoking it.\r
  89 > > They're only ever displayed along with the function prototype (and\r
  90 > > often refer to argument names).  And built-in help commands like\r
  91 > > `describe-bindings' show the name of the command, not its\r
  92 > > documentation.\r
  93 > >\r
  94 > > The notmuch help system is like `describe-bindings', but tries to be\r
  95 > > more user-friendly by displaying documentation strings, rather than\r
  96 > > Elisp command names.  For most commands, this is fine, but for some\r
  97 > > the "programmer description" is inappropriate for interactive use.\r
  98 > > This is particularly noticeable for commands that take an optional\r
  99 > > prefix argument.\r
 100 > >\r
 101 > > This patch adds support for two symbol properties: notmuch-doc and\r
 102 > > notmuch-prefix-doc, which let a command override its interactive\r
 103 > > documentation and provide separate documentation for its prefixed\r
 104 > > invocation.  If notmuch-prefix-doc is present, we add an extra line to\r
 105 > > the help giving the prefixed key sequence along with the documentation\r
 106 > > for the prefixed command.\r
 107 > > ---\r
 108 > >  emacs/notmuch.el | 29 ++++++++++++++++++++++++-----\r
 109 > >  1 file changed, 24 insertions(+), 5 deletions(-)\r
 110 > >\r
 111 > > diff --git a/emacs/notmuch.el b/emacs/notmuch.el\r
 112 > > index a36849f..278bd35 100644\r
 113 > > --- a/emacs/notmuch.el\r
 114 > > +++ b/emacs/notmuch.el\r
 115 > > @@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."\r
 116 > >     "M-"\r
 117 > >        (concat desc " "))))\r
 118 > >  \r
 119 > > -(defun notmuch-describe-keymap (keymap &optional prefix tail)\r
 120 > > +(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)\r
 121 > >    "Return a list of strings, each describing one key in KEYMAP.\r
 122 > >  \r
 123 > >  Each string gives a human-readable description of the key and the\r
 124 > \r
 125 > It would be nice to document the ua-keys variable here. It took me some\r
 126 > time to work out what was going in (and I worked out based on the\r
 127 > caller).\r
 128 \r
 129 Just sent a follow-up patch that improves this function documentation.\r
 130 \r
 131 > Best wishes\r
 132 > \r
 133 > Mark\r
 134 > \r
 135 > > @@ -151,10 +151,19 @@ first line of documentation for the bound function."\r
 136 > >        ((keymapp binding)\r
 137 > >         (setq tail\r
 138 > >               (notmuch-describe-keymap\r
 139 > > -              binding (notmuch-prefix-key-description key) tail)))\r
 140 > > +              binding ua-keys (notmuch-prefix-key-description key) tail)))\r
 141 > >        (t\r
 142 > > +       (when (and ua-keys (symbolp binding)\r
 143 > > +                  (get binding 'notmuch-prefix-doc))\r
 144 > > +         ;; Documentation for prefixed command\r
 145 > > +         (let ((ua-desc (key-description ua-keys)))\r
 146 > > +           (push (concat ua-desc " " prefix (format-kbd-macro (vector key))\r
 147 > > +                         "\t" (get binding 'notmuch-prefix-doc))\r
 148 > > +                 tail)))\r
 149 > > +       ;; Documentation for command\r
 150 > >         (push (concat prefix (format-kbd-macro (vector key)) "\t"\r
 151 > > -                     (notmuch-documentation-first-line binding))\r
 152 > > +                     (or (and (symbolp binding) (get binding 'notmuch-doc))\r
 153 > > +                         (notmuch-documentation-first-line binding)))\r
 154 > >               tail))))\r
 155 > >     keymap)\r
 156 > >    tail)\r
 157 > > @@ -165,14 +174,24 @@ first line of documentation for the bound function."\r
 158 > >      (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)\r
 159 > >        (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))\r
 160 > >          (keymap (symbol-value (intern keymap-name)))\r
 161 > > -        (desc-list (notmuch-describe-keymap keymap))\r
 162 > > +        (ua-keys (where-is-internal 'universal-argument keymap t))\r
 163 > > +        (desc-list (notmuch-describe-keymap keymap ua-keys))\r
 164 > >          (desc (mapconcat #'identity desc-list "\n")))\r
 165 > >     (setq doc (replace-match desc 1 1 doc)))\r
 166 > >        (setq beg (match-end 0)))\r
 167 > >      doc))\r
 168 > >  \r
 169 > >  (defun notmuch-help ()\r
 170 > > -  "Display help for the current notmuch mode."\r
 171 > > +  "Display help for the current notmuch mode.\r
 172 > > +\r
 173 > > +This is similar to `describe-function' for the current major\r
 174 > > +mode, but bindings tables are shown with documentation strings\r
 175 > > +rather than command names.  By default, this uses the first line\r
 176 > > +of each command's documentation string.  A command can override\r
 177 > > +this by setting the 'notmuch-doc property of its command symbol.\r
 178 > > +A command that supports a prefix argument can explicitly document\r
 179 > > +its prefixed behavior by setting the 'notmuch-prefix-doc property\r
 180 > > +of its command symbol."\r
 181 > >    (interactive)\r
 182 > >    (let* ((mode major-mode)\r
 183 > >      (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))\r