From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#30660: mention describe-bindings on (info "(emacs) Keymaps") Date: Thu, 07 Nov 2019 01:18:45 +0100 Message-ID: <87y2wswnbu.fsf@marxist.se> References: <831b5f34-28c7-4753-bed9-0a28de484aa8@default> <87tv8bul5g.fsf@gnus.org> <8336fvhxt0.fsf@gnu.org> <83k193bjra.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="230587"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: Robert Pluim , 30660@debbugs.gnu.org, Lars Ingebrigtsen , =?UTF-8?Q?=E7=A9=8D=E4=B8=B9=E5=B0=BC?= Dan Jacobson To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Nov 07 01:20:12 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iSVX2-000xm2-JN for geb-bug-gnu-emacs@m.gmane.org; Thu, 07 Nov 2019 01:20:12 +0100 Original-Received: from localhost ([::1]:37960 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iSVX1-00052D-2V for geb-bug-gnu-emacs@m.gmane.org; Wed, 06 Nov 2019 19:20:11 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:55149) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iSVWu-00051v-5o for bug-gnu-emacs@gnu.org; Wed, 06 Nov 2019 19:20:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iSVWs-0000l5-K6 for bug-gnu-emacs@gnu.org; Wed, 06 Nov 2019 19:20:04 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60846) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iSVWs-0000km-GI for bug-gnu-emacs@gnu.org; Wed, 06 Nov 2019 19:20:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iSVWs-0007QE-A1 for bug-gnu-emacs@gnu.org; Wed, 06 Nov 2019 19:20:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 07 Nov 2019 00:20:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 30660 X-GNU-PR-Package: emacs Original-Received: via spool by 30660-submit@debbugs.gnu.org id=B30660.157308597328476 (code B ref 30660); Thu, 07 Nov 2019 00:20:02 +0000 Original-Received: (at 30660) by debbugs.gnu.org; 7 Nov 2019 00:19:33 +0000 Original-Received: from localhost ([127.0.0.1]:41434 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iSVWO-0007PE-L6 for submit@debbugs.gnu.org; Wed, 06 Nov 2019 19:19:33 -0500 Original-Received: from host.gofardesign.uk ([208.79.239.190]:59869) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iSVVr-0007Ny-Mz for 30660@debbugs.gnu.org; Wed, 06 Nov 2019 19:19:30 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=marxist.se; s=default; h=Content-Type:MIME-Version:Message-ID:Date:References: In-Reply-To:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=LYasSKnLjBdD9KTZINdKHJuA7bZugIHTApFxC9qBQmY=; b=mTOUn8iz6UqIl0EWwQLtCNN+Nn SibGcCEieaeLIehNTTudNyS4KeqRdlmBEmeCKqNSB0OwfM97kDNOp7ivW9msrBgVm3zy6tkxHfarr 6tErkDS7EAQDPPxcAdc5RD/BN3oeF7q5wHzaZ7yX5DaOqWkmrHHpYyj6ABs5qtC/iaaw=; Original-Received: from h-70-69.a785.priv.bahnhof.se ([155.4.70.69]:53054 helo=localhost) by host.gofardesign.uk with esmtpsa (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.92) (envelope-from ) id 1iSVVf-0001Hm-Ki; Wed, 06 Nov 2019 18:18:48 -0600 In-Reply-To: (Stefan Kangas's message of "Thu, 17 Oct 2019 15:30:48 +0200") X-OutGoing-Spam-Status: No, score=-1.0 X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - host.gofardesign.uk X-AntiAbuse: Original Domain - debbugs.gnu.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - marxist.se X-Get-Message-Sender-Via: host.gofardesign.uk: authenticated_id: stefan@marxist.se X-Authenticated-Sender: host.gofardesign.uk: stefan@marxist.se X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:171055 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Stefan Kangas writes: > Eli Zaretskii writes: > >> > I=CA=BCm not clear on why it needs such a convoluted API >> >> Yes, I was wondering about that as well. It looks somewhat artificial >> to me. > > I'd be happy to simplify it, but Drew felt that this was an important > use case. Perhaps that could be covered by Robert Pluim's suggestion > to add a separate function 'find-keymap' instead. I've thought about this some more, and I think it's better to simplify the API of 'describe-keymap'. We could consider adding a separate function 'find-keymap' later. Please find attached a patch without the optional argument, and let me know if there are any further comments. Best regards, Stefan Kangas --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-Add-new-help-command-describe-keymap.patch >From 63952f2062d981c49d16e8643e287de00b19ffe3 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 24 Aug 2019 01:02:04 +0200 Subject: [PATCH] Add new help command describe-keymap * lisp/help-fns.el (describe-keymap): New command to show key bindings for a given keymap. (Bug#30660) * doc/lispref/keymaps.texi (Scanning Keymaps): Document it. * etc/NEWS: Announce it. * test/lisp/help-fns-tests.el (help-fns-test-describe-keymap/symbol) (help-fns-test-describe-keymap/value) (help-fns-test-describe-keymap/not-keymap) (help-fns-test-describe-keymap/let-bound) (help-fns-test-describe-keymap/dynamically-bound-no-file): New tests. Co-authored-by: Drew Adams --- doc/lispref/keymaps.texi | 6 ++++ etc/NEWS | 3 ++ lisp/help-fns.el | 59 +++++++++++++++++++++++++++++++++++++ test/lisp/help-fns-tests.el | 29 ++++++++++++++++++ 4 files changed, 97 insertions(+) diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 8ff329bdac..9fc0420b7e 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -2010,6 +2010,12 @@ Scanning Keymaps instead of the current buffer's. @end deffn +@deffn Command describe-keymap keymap &optional search-symbols +This function creates a listing of all key bindings in variable +@var{keymap}, and displays it in a buffer named @file{*Help*}. When +called interactively, prompt for a variable that has a keymap value. +@end deffn + @node Menu Keymaps @section Menu Keymaps @cindex menu keymaps diff --git a/etc/NEWS b/etc/NEWS index 737053a099..cc98705cd3 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1443,6 +1443,9 @@ The maximum level is used by default; customize ** Help ++++ +*** New command 'describe-keymap' describes keybindings in a keymap. + --- *** Description of variables and functions give an estimated first release. diff --git a/lisp/help-fns.el b/lisp/help-fns.el index 14dea7de9b..333eda0aac 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -1561,6 +1561,65 @@ describe-categories (insert "\nThe parent category table is:") (describe-vector table 'help-describe-category-set)))))) +;;;###autoload +(defun describe-keymap (keymap) + "Describe key bindings in KEYMAP. +When called interactively, prompt for a variable that has a +keymap value." + (interactive (list + (intern (completing-read "Keymap: " obarray + (lambda (m) + (and (boundp m) + (keymapp (symbol-value m)))) + t nil 'variable-name-history)))) + (let (used-gentemp) + (unless (and (symbolp keymap) + (boundp keymap) + (keymapp (symbol-value keymap))) + (when (not (keymapp keymap)) + (if (symbolp keymap) + (error "Not a keymap variable: %S" keymap) + (error "Not a keymap"))) + (let ((sym nil)) + (unless sym + (setq sym (cl-gentemp "KEYMAP OBJECT (no variable) ")) + (setq used-gentemp t) + (set sym keymap)) + (setq keymap sym))) + ;; Follow aliasing. + (setq keymap (or (ignore-errors (indirect-variable keymap)) keymap)) + (help-setup-xref (list #'describe-keymap keymap) + (called-interactively-p 'interactive)) + (let* ((name (symbol-name keymap)) + (doc (documentation-property keymap 'variable-documentation)) + (file-name (find-lisp-object-file-name keymap 'defvar))) + (with-help-window (help-buffer) + (with-current-buffer standard-output + (unless used-gentemp + (princ (format-message "%S is a keymap variable" keymap)) + (if (not file-name) + (princ ".\n\n") + (princ (format-message + " defined in `%s'.\n\n" + (if (eq file-name 'C-source) + "C source code" + (file-name-nondirectory file-name)))) + (save-excursion + (re-search-backward (substitute-command-keys + "`\\([^`']+\\)'") + nil t) + (help-xref-button 1 'help-variable-def + keymap file-name)))) + (when (and (not (equal "" doc)) doc) + (princ "Documentation:\n") + (princ (format-message "%s\n\n" doc))) + ;; Use `insert' instead of `princ', so control chars (e.g. \377) + ;; insert correctly. + (insert (substitute-command-keys (concat "\\{" name "}")))))) + ;; Cleanup. + (when used-gentemp + (makunbound keymap)))) + ;;; Replacements for old lib-src/ programs. Don't seem especially useful. diff --git a/test/lisp/help-fns-tests.el b/test/lisp/help-fns-tests.el index da4d25d0a6..3921b59f2c 100644 --- a/test/lisp/help-fns-tests.el +++ b/test/lisp/help-fns-tests.el @@ -123,4 +123,33 @@ help-fns-test-describe-symbol (goto-char (point-min)) (should (looking-at "^font-lock-comment-face is ")))) + + +;;; Tests for describe-keymap +(ert-deftest help-fns-test-describe-keymap/symbol () + (describe-keymap 'minibuffer-local-must-match-map) + (with-current-buffer "*Help*" + (should (looking-at "^minibuffer-local-must-match-map is")))) + +(ert-deftest help-fns-test-describe-keymap/value () + (describe-keymap minibuffer-local-must-match-map) + (with-current-buffer "*Help*" + (should (looking-at "^key")))) + +(ert-deftest help-fns-test-describe-keymap/not-keymap () + (should-error (describe-keymap nil)) + (should-error (describe-keymap emacs-version))) + +(ert-deftest help-fns-test-describe-keymap/let-bound () + (let ((foobar minibuffer-local-must-match-map)) + (describe-keymap foobar) + (with-current-buffer "*Help*" + (should (looking-at "^key"))))) + +(ert-deftest help-fns-test-describe-keymap/dynamically-bound-no-file () + (setq help-fns-test--describe-keymap-foo minibuffer-local-must-match-map) + (describe-keymap 'help-fns-test--describe-keymap-foo) + (with-current-buffer "*Help*" + (should (looking-at "^help-fns-test--describe-keymap-foo is")))) + ;;; help-fns-tests.el ends here -- 2.20.1 --=-=-=--