From b9cc3beefb0f03a5b2e0af59aa1d20923561ed5c Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Fri, 8 Nov 2013 14:47:05 +1900 Subject: [PATCH] Re: [PATCH 3/4] emacs: help: remap support --- ad/9fec1ea5aba71f18e71be334907f9ac9fc043e | 174 ++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 ad/9fec1ea5aba71f18e71be334907f9ac9fc043e diff --git a/ad/9fec1ea5aba71f18e71be334907f9ac9fc043e b/ad/9fec1ea5aba71f18e71be334907f9ac9fc043e new file mode 100644 index 000000000..be72bd9b7 --- /dev/null +++ b/ad/9fec1ea5aba71f18e71be334907f9ac9fc043e @@ -0,0 +1,174 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 07D34431FDC + for ; Thu, 7 Nov 2013 11:47:18 -0800 (PST) +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 sfU0r7Nhzvgt for ; + Thu, 7 Nov 2013 11:47:09 -0800 (PST) +Received: from dmz-mailsec-scanner-1.mit.edu (dmz-mailsec-scanner-1.mit.edu + [18.9.25.12]) + (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id AFB9D431FCF + for ; Thu, 7 Nov 2013 11:47:09 -0800 (PST) +X-AuditID: 1209190c-b7f058e000005fd9-48-527bee3cac01 +Received: from mailhub-auth-4.mit.edu ( [18.7.62.39]) + (using TLS with cipher AES256-SHA (256/256 bits)) + (Client did not present a certificate) + by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP + id C3.84.24537.D3EEB725; Thu, 7 Nov 2013 14:47:09 -0500 (EST) +Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11]) + by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id rA7Jl7e6032410; + Thu, 7 Nov 2013 14:47:08 -0500 +Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91]) + (authenticated bits=0) + (User authenticated as amdragon@ATHENA.MIT.EDU) + by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id rA7Jl5hY011187 + (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT); + Thu, 7 Nov 2013 14:47:06 -0500 +Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80) + (envelope-from ) + id 1VeVXl-0004Cf-8R; Thu, 07 Nov 2013 14:47:05 -0500 +From: Austin Clements +To: Mark Walters , notmuch@notmuchmail.org +Subject: Re: [PATCH 3/4] emacs: help: remap support +In-Reply-To: <1382821479-23384-4-git-send-email-markwalters1009@gmail.com> +References: <1382821479-23384-1-git-send-email-markwalters1009@gmail.com> + <1382821479-23384-4-git-send-email-markwalters1009@gmail.com> +User-Agent: Notmuch/0.16+110~g45444ee (http://notmuchmail.org) Emacs/23.4.1 + (i486-pc-linux-gnu) +Date: Thu, 07 Nov 2013 14:47:05 -0500 +Message-ID: <87habokn9i.fsf@awakening.csail.mit.edu> +MIME-Version: 1.0 +Content-Type: text/plain; charset=us-ascii +X-Brightmail-Tracker: + H4sIAAAAAAAAA+NgFnrIIsWRmVeSWpSXmKPExsUixG6nrmv7rjrIYN0SNovVc3ksrt+cyezA + 5LFz1l12j2erbjEHMEVx2aSk5mSWpRbp2yVwZWya3cZacE6hYt2vBawNjNskuxg5OSQETCT+ + dGxkhLDFJC7cW8/WxcjFISQwm0niwebNYAkhgQ2MEmt3R0EkTjFJNDx7ww7hLGGUOPX3E1gV + m4C+xIq1k1hBbBEBV4mn3z4zg9jCAsYSEyZNBbM5Bbwkts95ygTR3M4osXTRDrBmUYF4ianf + 5rCD2CwCqhJf5vwHa+AFum/VxmOMELagxMmZT1hAbGYBLYkb/14yTWAUmIUkNQtJagEj0ypG + 2ZTcKt3cxMyc4tRk3eLkxLy81CJdQ73czBK91JTSTYygkOSU5NnB+Oag0iFGAQ5GJR7eggvV + QUKsiWXFlbmHGCU5mJREeZXeAIX4kvJTKjMSizPii0pzUosPMUpwMCuJ8B5ZCJTjTUmsrEot + yodJSXOwKInz3uSwDxISSE8sSc1OTS1ILYLJynBwKEnwnn0L1ChYlJqeWpGWmVOCkGbi4AQZ + zgM0/AlIDW9xQWJucWY6RP4Uo6KUOO8DkIQASCKjNA+uF5YyXjGKA70izLsOpIoHmG7gul8B + DWYCGhzyqxJkcEkiQkqqgbHhT6Fb7rTJeqc+bW26/vw3w4SMOxN/XbsnNn3DOy371DXphqtU + leqT+/8fWakQoZ45+/BuuxcZ/B63FhUcON83lXdnGStH5IGVHt2LtjyS4l3gp71tncBt64x7 + QWlrDqlNeXZPbkOQ8k1r++0sez8z5ZhZcljN2s8vxRi4XD9wk+abo6mT4xyUWIozEg21mIuK + EwGEff5l9AIAAA== +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: Thu, 07 Nov 2013 19:47:18 -0000 + +I originally wanted to see these concerns separated -- to have a +separate function that took care of resolving remaps to keep the logic +out of notmuch-describe-keymap -- but then I tried to write that +function and gave up. If you can think of a way to do that, I think it +would make this code clearer, but if not that's fine, too. + +On Sat, 26 Oct 2013, Mark Walters wrote: +> If a user or mode uses remap to rebind a keybinding then it appears in +> the help as a line New function docstring. Special +> case these remapping lines so that we print the actual binding. +> --- +> emacs/notmuch.el | 21 ++++++++++++++------- +> 1 files changed, 14 insertions(+), 7 deletions(-) +> +> diff --git a/emacs/notmuch.el b/emacs/notmuch.el +> index b9db9ba..c354b05 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 ua-keys &optional prefix tail) +> +(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail remap) +> "Return a list of cons cells, each describing one binding in KEYMAP. +> +> Each cons cell consists of a string giving a human-readable +> @@ -150,16 +150,23 @@ documentation is extracted. +> +> UA-KEYS should be a key sequence bound to `universal-argument'. +> It will be used to describe bindings of commands that support a +> -prefix argument. PREFIX and TAIL are used internally." +> +prefix argument. PREFIX, TAIL and REMAP are used internally." +> (map-keymap +> (lambda (key binding) +> (cond ((mouse-event-p key) nil) +> ((keymapp binding) + +I think it would be worth documenting what's going on with remaps here. +I didn't get it until I wrote some of my own test code *and* chatted +with you on IRC. Perhaps something like: + + ;; Remapping are represented as a binding whose first "event" is + ;; 'remap. Hence, if the keymap has any remappings, it will have a + ;; binding whose "key" is 'remap, and whose "binding" is itself a + ;; keymap that maps not from keys to commands, but from old (remapped) + ;; functions to the commands to use in their stead. + +> - (setq tail +> - (notmuch-describe-keymap +> - binding ua-keys (notmuch-prefix-key-description key) tail))) +> + (if (equal key 'remap) + +`eq' would be more standard here. + +> + (setq tail +> + (notmuch-describe-keymap +> + binding ua-keys prefix tail t)) +> + (setq tail +> + (notmuch-describe-keymap +> + binding ua-keys (notmuch-prefix-key-description key) tail)))) +> (t +> - (let ((key-string (concat prefix (format-kbd-macro (vector key))))) +> + (let* ((actual-key (if remap +> + (where-is-internal key nil t) + +Is it okay to use nil for the keymap to `where-is-internal' here? It +seems like maybe we have to pass down a "root" keymap from +`notmuch-substitute-command-keys' so it knows what to resolve the +remappings relative to. Arguably the original caller should provide +just the root keymap, while the "current" sub-keymap should be one of +the internal recursive arguments. + +> + (vector key))) +> + (key-string (concat prefix (format-kbd-macro actual-key)))) +> ;; We don't include documentation if the key-binding is +> ;; over-ridden. Note, over-riding a binding +> ;; automatically hides the prefixed version too. +> @@ -168,7 +175,7 @@ prefix argument. PREFIX and TAIL are used internally." +> (get binding 'notmuch-prefix-doc)) +> ;; Documentation for prefixed command +> (let ((ua-desc (key-description ua-keys))) +> - (push (cons (concat ua-desc " " prefix (format-kbd-macro (vector key))) +> + (push (cons (concat ua-desc " " prefix (format-kbd-macro actual-key)) +> (get binding 'notmuch-prefix-doc)) +> tail))) +> ;; Documentation for command +> -- +> 1.7.9.1 +> +> _______________________________________________ +> notmuch mailing list +> notmuch@notmuchmail.org +> http://notmuchmail.org/mailman/listinfo/notmuch -- 2.26.2