ad/9fec1ea5aba71f18e71be334907f9ac9fc043e

   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 07D34431FDC\r
   6         for <notmuch@notmuchmail.org>; Thu,  7 Nov 2013 11:47:18 -0800 (PST)\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 sfU0r7Nhzvgt for <notmuch@notmuchmail.org>;\r
  16         Thu,  7 Nov 2013 11:47:09 -0800 (PST)\r
  17 Received: from dmz-mailsec-scanner-1.mit.edu (dmz-mailsec-scanner-1.mit.edu\r
  18         [18.9.25.12])\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 AFB9D431FCF\r
  22         for <notmuch@notmuchmail.org>; Thu,  7 Nov 2013 11:47:09 -0800 (PST)\r
  23 X-AuditID: 1209190c-b7f058e000005fd9-48-527bee3cac01\r
  24 Received: from mailhub-auth-4.mit.edu ( [18.7.62.39])\r
  25         (using TLS with cipher AES256-SHA (256/256 bits))\r
  26         (Client did not present a certificate)\r
  27         by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP\r
  28         id C3.84.24537.D3EEB725; Thu,  7 Nov 2013 14:47:09 -0500 (EST)\r
  29 Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
  30         by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id rA7Jl7e6032410; \r
  31         Thu, 7 Nov 2013 14:47:08 -0500\r
  32 Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
  33         (authenticated bits=0)\r
  34         (User authenticated as amdragon@ATHENA.MIT.EDU)\r
  35         by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id rA7Jl5hY011187\r
  36         (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT);\r
  37         Thu, 7 Nov 2013 14:47:06 -0500\r
  38 Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80)\r
  39         (envelope-from <amdragon@mit.edu>)\r
  40         id 1VeVXl-0004Cf-8R; Thu, 07 Nov 2013 14:47:05 -0500\r
  41 From: Austin Clements <aclements@csail.mit.edu>\r
  42 To: Mark Walters <markwalters1009@gmail.com>, notmuch@notmuchmail.org\r
  43 Subject: Re: [PATCH 3/4] emacs: help: remap support\r
  44 In-Reply-To: <1382821479-23384-4-git-send-email-markwalters1009@gmail.com>\r
  45 References: <1382821479-23384-1-git-send-email-markwalters1009@gmail.com>\r
  46         <1382821479-23384-4-git-send-email-markwalters1009@gmail.com>\r
  47 User-Agent: Notmuch/0.16+110~g45444ee (http://notmuchmail.org) Emacs/23.4.1\r
  48         (i486-pc-linux-gnu)\r
  49 Date: Thu, 07 Nov 2013 14:47:05 -0500\r
  50 Message-ID: <87habokn9i.fsf@awakening.csail.mit.edu>\r
  51 MIME-Version: 1.0\r
  52 Content-Type: text/plain; charset=us-ascii\r
  53 X-Brightmail-Tracker:\r
  54  H4sIAAAAAAAAA+NgFnrIIsWRmVeSWpSXmKPExsUixG6nrmv7rjrIYN0SNovVc3ksrt+cyezA\r
  55         5LFz1l12j2erbjEHMEVx2aSk5mSWpRbp2yVwZWya3cZacE6hYt2vBawNjNskuxg5OSQETCT+\r
  56         dGxkhLDFJC7cW8/WxcjFISQwm0niwebNYAkhgQ2MEmt3R0EkTjFJNDx7ww7hLGGUOPX3E1gV\r
  57         m4C+xIq1k1hBbBEBV4mn3z4zg9jCAsYSEyZNBbM5Bbwkts95ygTR3M4osXTRDrBmUYF4ianf\r
  58         5rCD2CwCqhJf5vwHa+AFum/VxmOMELagxMmZT1hAbGYBLYkb/14yTWAUmIUkNQtJagEj0ypG\r
  59         2ZTcKt3cxMyc4tRk3eLkxLy81CJdQ73czBK91JTSTYygkOSU5NnB+Oag0iFGAQ5GJR7eggvV\r
  60         QUKsiWXFlbmHGCU5mJREeZXeAIX4kvJTKjMSizPii0pzUosPMUpwMCuJ8B5ZCJTjTUmsrEot\r
  61         yodJSXOwKInz3uSwDxISSE8sSc1OTS1ILYLJynBwKEnwnn0L1ChYlJqeWpGWmVOCkGbi4AQZ\r
  62         zgM0/AlIDW9xQWJucWY6RP4Uo6KUOO8DkIQASCKjNA+uF5YyXjGKA70izLsOpIoHmG7gul8B\r
  63         DWYCGhzyqxJkcEkiQkqqgbHhT6Fb7rTJeqc+bW26/vw3w4SMOxN/XbsnNn3DOy371DXphqtU\r
  64         leqT+/8fWakQoZ45+/BuuxcZ/B63FhUcON83lXdnGStH5IGVHt2LtjyS4l3gp71tncBt64x7\r
  65         QWlrDqlNeXZPbkOQ8k1r++0sez8z5ZhZcljN2s8vxRi4XD9wk+abo6mT4xyUWIozEg21mIuK\r
  66         EwGEff5l9AIAAA==\r
  67 X-BeenThere: notmuch@notmuchmail.org\r
  68 X-Mailman-Version: 2.1.13\r
  69 Precedence: list\r
  70 List-Id: "Use and development of the notmuch mail system."\r
  71         <notmuch.notmuchmail.org>\r
  72 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  73         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  74 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  75 List-Post: <mailto:notmuch@notmuchmail.org>\r
  76 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  77 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  78         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  79 X-List-Received-Date: Thu, 07 Nov 2013 19:47:18 -0000\r
  80 \r
  81 I originally wanted to see these concerns separated -- to have a\r
  82 separate function that took care of resolving remaps to keep the logic\r
  83 out of notmuch-describe-keymap -- but then I tried to write that\r
  84 function and gave up.  If you can think of a way to do that, I think it\r
  85 would make this code clearer, but if not that's fine, too.\r
  86 \r
  87 On Sat, 26 Oct 2013, Mark Walters <markwalters1009@gmail.com> wrote:\r
  88 > If a user or mode uses remap to rebind a keybinding then it appears in\r
  89 > the help as a line <remap><function> New function docstring. Special\r
  90 > case these remapping lines so that we print the actual binding.\r
  91 > ---\r
  92 >  emacs/notmuch.el |   21 ++++++++++++++-------\r
  93 >  1 files changed, 14 insertions(+), 7 deletions(-)\r
  94 >\r
  95 > diff --git a/emacs/notmuch.el b/emacs/notmuch.el\r
  96 > index b9db9ba..c354b05 100644\r
  97 > --- a/emacs/notmuch.el\r
  98 > +++ b/emacs/notmuch.el\r
  99 > @@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."\r
 100 >       "M-"\r
 101 >        (concat desc " "))))\r
 102 >  \r
 103 > -(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)\r
 104 > +(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail remap)\r
 105 >    "Return a list of cons cells, each describing one binding in KEYMAP.\r
 106 >  \r
 107 >  Each cons cell consists of a string giving a human-readable\r
 108 > @@ -150,16 +150,23 @@ documentation is extracted.\r
 109 >  \r
 110 >  UA-KEYS should be a key sequence bound to `universal-argument'.\r
 111 >  It will be used to describe bindings of commands that support a\r
 112 > -prefix argument.  PREFIX and TAIL are used internally."\r
 113 > +prefix argument.  PREFIX, TAIL and REMAP are used internally."\r
 114 >    (map-keymap\r
 115 >     (lambda (key binding)\r
 116 >       (cond ((mouse-event-p key) nil)\r
 117 >          ((keymapp binding)\r
 118 \r
 119 I think it would be worth documenting what's going on with remaps here.\r
 120 I didn't get it until I wrote some of my own test code *and* chatted\r
 121 with you on IRC.  Perhaps something like:\r
 122 \r
 123   ;; Remapping are represented as a binding whose first "event" is\r
 124   ;; 'remap.  Hence, if the keymap has any remappings, it will have a\r
 125   ;; binding whose "key" is 'remap, and whose "binding" is itself a\r
 126   ;; keymap that maps not from keys to commands, but from old (remapped)\r
 127   ;; functions to the commands to use in their stead.\r
 128 \r
 129 > -         (setq tail\r
 130 > -               (notmuch-describe-keymap\r
 131 > -                binding ua-keys (notmuch-prefix-key-description key) tail)))\r
 132 > +         (if (equal key 'remap)\r
 133 \r
 134 `eq' would be more standard here.\r
 135 \r
 136 > +             (setq tail\r
 137 > +                   (notmuch-describe-keymap\r
 138 > +                    binding ua-keys prefix tail t))\r
 139 > +           (setq tail\r
 140 > +                 (notmuch-describe-keymap\r
 141 > +                  binding ua-keys (notmuch-prefix-key-description key) tail))))\r
 142 >          (t\r
 143 > -         (let ((key-string (concat prefix (format-kbd-macro (vector key)))))\r
 144 > +         (let* ((actual-key (if remap\r
 145 > +                                (where-is-internal key nil t)\r
 146 \r
 147 Is it okay to use nil for the keymap to `where-is-internal' here?  It\r
 148 seems like maybe we have to pass down a "root" keymap from\r
 149 `notmuch-substitute-command-keys' so it knows what to resolve the\r
 150 remappings relative to.  Arguably the original caller should provide\r
 151 just the root keymap, while the "current" sub-keymap should be one of\r
 152 the internal recursive arguments.\r
 153 \r
 154 > +                              (vector key)))\r
 155 > +                (key-string (concat prefix (format-kbd-macro actual-key))))\r
 156 >             ;; We don't include documentation if the key-binding is\r
 157 >             ;; over-ridden. Note, over-riding a binding\r
 158 >             ;; automatically hides the prefixed version too.\r
 159 > @@ -168,7 +175,7 @@ prefix argument.  PREFIX and TAIL are used internally."\r
 160 >                          (get binding 'notmuch-prefix-doc))\r
 161 >                 ;; Documentation for prefixed command\r
 162 >                 (let ((ua-desc (key-description ua-keys)))\r
 163 > -                 (push (cons (concat ua-desc " " prefix (format-kbd-macro (vector key)))\r
 164 > +                 (push (cons (concat ua-desc " " prefix (format-kbd-macro actual-key))\r
 165 >                               (get binding 'notmuch-prefix-doc))\r
 166 >                         tail)))\r
 167 >               ;; Documentation for command\r
 168 > -- \r
 169 > 1.7.9.1\r
 170 >\r
 171 > _______________________________________________\r
 172 > notmuch mailing list\r
 173 > notmuch@notmuchmail.org\r
 174 > http://notmuchmail.org/mailman/listinfo/notmuch\r