all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Stefan Kangas <stefan@marxist.se>
To: Eli Zaretskii <eliz@gnu.org>
Cc: larsi@gnus.org, 30660@debbugs.gnu.org, jidanni@jidanni.org
Subject: bug#30660: mention describe-bindings on (info "(emacs) Keymaps")
Date: Sun, 17 Nov 2019 21:51:04 +0100	[thread overview]
Message-ID: <87h832mdl3.fsf@marxist.se> (raw)
In-Reply-To: <83h8367luj.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 14 Nov 2019 13:12:36 +0200")

[-- Attachment #1: Type: text/plain, Size: 646 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> In the attached patch, I've added it to the user manual in addition to
>> the elisp manual.  I followed the example of describe-bindings which
>> is documented in both.
>
> I'd prefer to have just one description in the user manual, and have a
> cross-reference in the ELisp manual which points to that.  I don't
> know why describe-bindings was documented in both manuals, and see no
> reason to continue doing so (the ELisp manual prints in 2 large
> volumes, so avoiding any unnecessary bloat there is generally a good
> idea).

OK, I've removed it in the attached patch.

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-help-command-describe-keymap.patch --]
[-- Type: text/x-diff, Size: 6736 bytes --]

From 94a94c833fd75225fb96e0de17000fa604945c97 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@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/emacs/help.texi (Misc Help): 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@oracle.com>
---
 doc/emacs/help.texi         |  5 +++-
 etc/NEWS                    |  3 ++
 lisp/help-fns.el            | 59 +++++++++++++++++++++++++++++++++++++
 test/lisp/help-fns-tests.el | 29 ++++++++++++++++++
 4 files changed, 95 insertions(+), 1 deletion(-)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 4851659b8b..ce40a15abe 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -581,6 +581,7 @@ Misc Help
 @findex describe-bindings
 @kindex C-h s
 @findex describe-syntax
+@findex describe-keymap
   @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
 (@code{describe-syntax}) show other information about the current
 environment within Emacs.  @kbd{C-h b} displays a list of all the key
@@ -589,7 +590,9 @@ Misc Help
 finally the global bindings (@pxref{Key Bindings}).  @kbd{C-h s}
 displays the contents of the syntax table, with explanations of each
 character's syntax (@pxref{Syntax Tables,, Syntax Tables, elisp, The
-Emacs Lisp Reference Manual}).
+Emacs Lisp Reference Manual}).  Finally, @kbd{M-x describe-keymap}
+prompts for the name of a keymap variable and displays a listing of
+all key bindings in that keymap.
 
 @findex describe-prefix-bindings
   You can get a list of subcommands for a particular prefix key by
diff --git a/etc/NEWS b/etc/NEWS
index 485d2b1fdf..83d6b0f416 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1461,6 +1461,9 @@ killed when pdbtracking session is finished.
 
 ** 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))))
+
 \f
 ;;; 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 "))))
 
+\f
+
+;;; 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


  parent reply	other threads:[~2019-11-17 20:51 UTC|newest]

Thread overview: 41+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-02-28 20:25 bug#30660: mention describe-bindings on (info "(emacs) Keymaps") 積丹尼 Dan Jacobson
2018-02-28 23:29 ` Drew Adams
2019-08-23  7:18 ` Stefan Kangas
2019-08-23 18:44   ` Drew Adams
2019-08-23 22:40     ` Stefan Kangas
2019-08-24  1:46       ` Drew Adams
2019-08-24  3:01         ` Stefan Kangas
2019-08-24 15:06           ` Drew Adams
2019-10-16 22:42             ` Stefan Kangas
2019-10-14 20:28           ` Lars Ingebrigtsen
2019-10-14 20:33             ` Eli Zaretskii
2019-10-17  9:39               ` Stefan Kangas
2019-10-17  9:42                 ` Stefan Kangas
2019-10-17 12:07                   ` Robert Pluim
2019-10-17 13:10                     ` Eli Zaretskii
2019-10-17 13:30                       ` Stefan Kangas
2019-11-07  0:18                         ` Stefan Kangas
2019-11-07  0:40                           ` Drew Adams
2019-10-17 13:00                 ` Eli Zaretskii
2019-11-07  1:00                   ` Stefan Kangas
2019-11-11 15:04                     ` Stefan Kangas
2019-11-14 11:12                       ` Eli Zaretskii
2019-11-17 20:36                         ` Stefan Kangas
2019-11-18 16:23                           ` Eli Zaretskii
2019-11-19  6:07                           ` Richard Stallman
2019-11-19 16:04                             ` Eli Zaretskii
2019-11-17 20:51                         ` Stefan Kangas [this message]
2019-11-18 16:20                           ` Eli Zaretskii
2019-11-19 14:14                             ` Stefan Kangas
2019-11-19 17:03                               ` Eli Zaretskii
     [not found]                                 ` <87zhen2h81.fsf@marxist.se>
2020-01-17  8:07                                   ` Eli Zaretskii
2020-01-18  2:16                                     ` Stefan Kangas
2020-01-18  8:31                                       ` Eli Zaretskii
2020-01-18  9:12                                         ` Stefan Kangas
2020-01-18  9:41                                           ` Eli Zaretskii
2020-01-18 23:42                                             ` Stefan Kangas
2020-01-19  2:09                                               ` Drew Adams
2020-01-31 10:15                                               ` Eli Zaretskii
2020-02-04  1:32                                                 ` Stefan Kangas
2019-10-14 20:50             ` Drew Adams
2019-10-16 22:48               ` Stefan Kangas

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87h832mdl3.fsf@marxist.se \
    --to=stefan@marxist.se \
    --cc=30660@debbugs.gnu.org \
    --cc=eliz@gnu.org \
    --cc=jidanni@jidanni.org \
    --cc=larsi@gnus.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.