Package: emacs;
Reported by: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
Date: Wed, 28 Feb 2018 22:45:05 UTC
Severity: wishlist
Fixed in version 28.1
Done: Stefan Kangas <stefan <at> marxist.se>
Bug is archived. No further changes may be made.
View this message in rfc822 format
From: Stefan Kangas <stefan <at> marxist.se> To: Eli Zaretskii <eliz <at> gnu.org> Cc: Robert Pluim <rpluim <at> gmail.com>, 30660 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>, Drew Adams <drew.adams <at> oracle.com>, 積丹尼 Dan Jacobson <jidanni <at> jidanni.org> Subject: bug#30660: mention describe-bindings on (info "(emacs) Keymaps") Date: Thu, 07 Nov 2019 01:18:45 +0100
[Message part 1 (text/plain, inline)]
Stefan Kangas <stefan <at> marxist.se> writes: > Eli Zaretskii <eliz <at> gnu.org> writes: > >> > Iʼm 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
[0001-Add-new-help-command-describe-keymap.patch (text/x-diff, inline)]
From 63952f2062d981c49d16e8643e287de00b19ffe3 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas <at> gmail.com>
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 <drew.adams <at> oracle.com>
---
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
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.