bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[積丹尼 Dan Jacobson]

(info "(emacs) Keymaps") should mention the best way to view a keymap.

If the user just uses describe-variable, he will see

 (67108910 . flyspell-auto-correct-word)

etc. So mention he should use describe-bindings.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Drew Adams]

> (info "(emacs) Keymaps") should mention the best way to view a keymap.
> If the user just uses describe-variable, he will see
>  (67108910 . flyspell-auto-correct-word)
> etc. So mention he should use `describe-bindings'.

`describe-bindings' does not describe the bindings of a given
keymap.

S?he should use `describe-keymap' (`C-h M-k'), from `help-fns+.el'.

It describes the bindings in a keymap in the usual human-readable
way.  You are prompted for a keymap variable (e.g., `ctl-x-map`),
with completion.  (Non-interactively, the argument can be a keymap
itself or a keymap variable.)

This or similar code should be in vanilla Emacs.  (I've offered
any and all of my code.)

https://www.emacswiki.org/emacs/download/help-fns%2b.el

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

>> (info "(emacs) Keymaps") should mention the best way to view a keymap.
>> If the user just uses describe-variable, he will see
>>  (67108910 . flyspell-auto-correct-word)
>> etc. So mention he should use `describe-bindings'.
>
> `describe-bindings' does not describe the bindings of a given
> keymap.
>
> S?he should use `describe-keymap' (`C-h M-k'), from `help-fns+.el'.
>
> It describes the bindings in a keymap in the usual human-readable
> way.  You are prompted for a keymap variable (e.g., `ctl-x-map`),
> with completion.  (Non-interactively, the argument can be a keymap
> itself or a keymap variable.)
>
> This or similar code should be in vanilla Emacs.  (I've offered
> any and all of my code.)
>
> https://www.emacswiki.org/emacs/download/help-fns%2b.el

I copied and  evaluated the describe-keymap function, but when I typed
M-x describe-keymap I got the following error:

save-current-buffer: Symbol’s function definition is void:
Info-make-manuals-xref

I couldn't find the definition of a function by that name in the file
you indicated, so I'm guessing there's some dependencies involved and
that I don't have.  Could you provide a version of this function which
works on current master without requiring these extra packages?

Thanks,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Drew Adams]

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

> > `describe-bindings' does not describe the bindings of a given
> > keymap.
> >
> > S?he should use `describe-keymap' (`C-h M-k'), from `help-fns+.el'.
> >
> > It describes the bindings in a keymap in the usual human-readable
> > way.  You are prompted for a keymap variable (e.g., `ctl-x-map`),
> > with completion.  (Non-interactively, the argument can be a keymap
> > itself or a keymap variable.)
> >
> > This or similar code should be in vanilla Emacs.  (I've offered
> > any and all of my code.)
> >
> > https://urldefense.proofpoint.com/v2/url?u=https-
> 3A__www.emacswiki.org_emacs_download_help-2Dfns-
> 252b.el&d=DwIFaQ&c=RoP1YumCXCgaWHvlZYR8PZh8Bv7qIrMUB65eapI_JnE&r=kI3P6l
> jGv6CTHIKju0jqInF6AOwMCYRDQUmqX22rJ98&m=yA0xm3W_AykCUU9THjbJlpxhVhQlA3X
> AncZSWRe2Wc0&s=P11PKX0Nhl4PaaXOh-0ZYcfDDhlprpw4pnWG5QqizvQ&e=
> 
> I copied and  evaluated the describe-keymap function, but when I typed
> M-x describe-keymap I got the following error:
> 
> save-current-buffer: Symbol’s function definition is void:
> Info-make-manuals-xref
> 
> I couldn't find the definition of a function by that name in the file
> you indicated, so I'm guessing there's some dependencies involved and
> that I don't have.  Could you provide a version of this function which
> works on current master without requiring these extra packages?

`Info-make-manuals-xref' _is_ defined in
help-fns+.el.  And no extra packages are needed
for help-fns+.el.

But adding the functionality of
`Info-make-manuals-xref' is not necessarily
something that vanilla Emacs would want now.
That should probably be discussed separately.

Similarly, there are other features used by
`describe-keymap' that I'm not sure you want to
add now to vanilla Emacs.  And you definitely
don't need the code that supports older Emacs
versions.

Bottom line, if you want to add only bare-bones
`describe-keymap' to vanilla Emacs then just
use the attached definition.


[-- Attachment #2: throw-describe-keymap-for-vanilla.el --]
[-- Type: application/octet-stream, Size: 2324 bytes --]

(defun describe-keymap (keymap &optional search-symbols-p) ; Bound to `C-h M-k'
  "Describe key bindings in KEYMAP.
Interactively, prompt for a variable that has a keymap value.
Completion is available for the variable name.

Non-interactively:
* KEYMAP can be such a keymap variable or a keymap.
* Non-nil optional arg SEARCH-SYMBOLS-P means that if KEYMAP is not a
  symbol then search all variables for one whose value is KEYMAP."
  (interactive (list (intern (completing-read "Keymap: " obarray
                                              (lambda (m) (and (boundp m)  (keymapp (symbol-value m))))
                                              t nil 'variable-name-history))))
  (unless (and (symbolp keymap)  (boundp keymap)  (keymapp (symbol-value keymap)))
    (if (not (keymapp keymap))
        (error "%sot a keymap%s"
               (if (symbolp keymap) (format "`%S' is n" keymap) "N")
               (if (symbolp keymap) " variable" ""))
      (let ((sym  nil))
        (when search-symbols-p
          (setq sym  (catch 'describe-keymap
                       (mapatoms (lambda (symb) (when (and (boundp symb)
                                                      (eq (symbol-value symb) keymap)
                                                      (not (eq symb 'keymap))
                                                      (throw 'describe-keymap symb)))))
                       nil)))
        (unless sym
          (setq sym  (gentemp "KEYMAP OBJECT (no variable) "))
          (set sym keymap))
        (setq keymap  sym))))
  (setq keymap  (or (ignore-errors (indirect-variable keymap))  keymap)) ; Follow aliasing.
  (let* ((name  (symbol-name keymap))
         (doc   (let ((raw-doc  (documentation-property keymap 'variable-documentation 'RAW)))
                  (substitute-command-keys raw-doc)))
         (doc   (and (not (equal "" doc))  doc)))
    (help-setup-xref (list #'describe-keymap keymap) (called-interactively-p 'interactive))
    (with-help-window (help-buffer)
      (princ name) (terpri) (princ (make-string (length name) ?-)) (terpri) (terpri)
      (when doc (princ doc) (terpri) (terpri))
      ;; Use `insert' instead of `princ', so control chars (e.g. \377) insert correctly.
      (with-current-buffer "*Help*" (insert (substitute-command-keys (concat "\\{" name "}")))))))

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> `Info-make-manuals-xref' _is_ defined in
> help-fns+.el.

OK, sorry about that.  I must have missed it.

> Bottom line, if you want to add only bare-bones
> `describe-keymap' to vanilla Emacs then just
> use the attached definition.

Thanks.  I tried it, and I personally think it's a useful addition.
Maybe others disagree.  I was going to pack it up as a patch for
review but I have some questions about the code first.

> Non-interactively:
> * KEYMAP can be such a keymap variable or a keymap.
> * Non-nil optional arg SEARCH-SYMBOLS-P means that if KEYMAP is not a
>   symbol then search all variables for one whose value is KEYMAP."

Is the purpose of SEARCH-SYMBOLS-P just to allow for calling it like this:

    (describe-keymap 'my-keymap t)
    (describe-keymap my-keymap t)

And have it work automatically?  Or am I missing something?  Also see below.

>   (unless (and (symbolp keymap)  (boundp keymap)  (keymapp (symbol-value keymap)))
>     (if (not (keymapp keymap))
>         (error "%sot a keymap%s"
>                (if (symbolp keymap) (format "`%S' is n" keymap) "N")
>                (if (symbolp keymap) " variable" ""))
>       (let ((sym  nil))
>         (when search-symbols-p
>           (setq sym  (catch 'describe-keymap
>                        (mapatoms (lambda (symb) (when (and (boundp symb)
>                                                       (eq (symbol-value symb) keymap)
>                                                       (not (eq symb 'keymap))
>                                                       (throw 'describe-keymap symb)))))
>                        nil)))
>         (unless sym
>           (setq sym  (gentemp "KEYMAP OBJECT (no variable) "))
>           (set sym keymap))
>         (setq keymap  sym))))

I admit that I find this code a bit hard to follow.  If I understand
correctly, then most of this can be removed if we don't want to
support SEARCH-SYMBOLS-P, and instead just require that the KEYMAP
argument is a symbol.  Is that correct or am I missing something?

I'm sort of leaning towards simplifying this by removing the
SEARCH-SYMBOLS-P argument, but I might not understand the use case
here.  If I'm missing something, could you please briefly describe the
use case for that and if and why it's important to keep?

>   (setq keymap  (or (ignore-errors (indirect-variable keymap))  keymap)) ; Follow aliasing.
>   (let* ((name  (symbol-name keymap))
>          (doc   (let ((raw-doc  (documentation-property keymap 'variable-documentation 'RAW)))
>                   (substitute-command-keys raw-doc)))

Why not just say (documentation-property keymap 'variable-documentation)
without the 'RAW argument?  That should have the same effect as
passing the 'RAW argument and then calling substitute-command-keys on
the result, AFAICT.

>          (doc   (and (not (equal "" doc))  doc)))

Is this to allow us to simply say (when doc ...) below instead of
(when (not (equal "" doc)) ...) or am I missing something?

Thanks,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Drew Adams]

> > Non-interactively:
> > * KEYMAP can be such a keymap variable or a keymap.
> > * Non-nil optional arg SEARCH-SYMBOLS-P means that if KEYMAP is not a
> >   symbol then search all variables for one whose value is KEYMAP."
> 
> Is the purpose of SEARCH-SYMBOLS-P just to allow for calling it like
> this:
>     (describe-keymap 'my-keymap t)
>     (describe-keymap my-keymap t)
> 
> And have it work automatically?  Or am I missing something?  Also see
> below.

KEYMAP can be a keymap, instead of a symbol.

(This was not the case originally.  I added handling
this case later, as it was requested and turned out
to be useful.  It's not rare to have a keymap object
ready-to-hand and without its variable.  This lets
you not only see the bindings but also identify the
keymap.)

If it's not a symbol there might still be a symbol
that has it as value.  Non-nil SEARCH-SYMBOLS-P
means try to find such a symbol.

If such a symbol is found then the help is better -
it tells you more about the keymap and its context,
by (1) providing its doc (in addition to listing the
key bindings) and even just (2) providing its name,
letting you know (typically) what mode or other
context defines it.

If the search finds no symbol with KEYMAP as its
value then the behavior is the same as if no search
was made (except for the time wasted on a failed
search): a symbol is generated for the map (just to
use the same code path).  The other difference is
that because you provided SEARCH-SYMBOLS-P you know
that a search turned up no symbol - more information.

> I admit that I find this code a bit hard to follow.  If I understand
> correctly, then most of this can be removed if we don't want to
> support SEARCH-SYMBOLS-P, and instead just require that the KEYMAP
> argument is a symbol.  Is that correct or am I missing something?

Who's "we"?  If a _user_ or calling code doesn't
want to search existing symbols then SEARCH-SYMBOLS-P
is supplied.  Nothing is lost by having it as a
behavior option, and something (quite a lot, actually)
is gained by making it available.  Putting a name on
a keymap object can be quite helpful.

The case where a user (or calling code) has a keymap
but no variable for it is not uncommon, even if it
is not the most common case.  Being able to find the
variable and see its doc is helpful.

> I'm sort of leaning towards simplifying this by removing the
> SEARCH-SYMBOLS-P argument, but I might not understand the use case
> here.  If I'm missing something, could you please briefly describe the
> use case for that and if and why it's important to keep?

See above.

> >   (let* ((name  (symbol-name keymap))
> >          (doc   (let ((raw-doc  (documentation-property keymap
> 'variable-documentation 'RAW)))
> >                   (substitute-command-keys raw-doc)))
> 
> Why not just say (documentation-property keymap 'variable-
> documentation)
> without the 'RAW argument?  That should have the same effect as
> passing the 'RAW argument and then calling substitute-command-keys on
> the result, AFAICT.

Yes; sorry.  My code uses `help-documentation-property'
and `help-substitute-command-keys'.  I too quickly
substituted the body of `help-documentation-property',
changing its occurrence of `help-substitute-command-keys'
to just `substitute-command-keys'.  None of `h-d-p' is
needed here if you don't have `h-s-c-k'.

IOW, if neither of those is available then yes, all
you need is (documentation-property keymap
'variable-documentation).  Sorry about that mistake.

You might want to take a look at the full code,
in help-fns+.el, to see what the differences are.
Some are to support older Emacs versions too, others
are to provide additional features.

> > (doc   (and (not (equal "" doc))  doc)))
> 
> Is this to allow us to simply say (when doc ...) below

Yes.  It makes DOC be either nil or real doc.

> instead of (when (not (equal "" doc)) ...)

[aka (unless (equal "" doc)...)]

No.  That's not the same.  That does `...' when doc
is nil.  The code should do `...' only when doc is
non-nil and not "".

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

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

Drew Adams <drew.adams@oracle.com> writes:

> KEYMAP can be a keymap, instead of a symbol.

Thanks for the clarifications.

I've now packaged up a proposed patch with some cleanups and
adaptions.  It would be great if someone could review this.

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Add-new-help-function-describe-keymap.patch --]
[-- Type: application/octet-stream, Size: 5165 bytes --]

From 91f4a8f10e2aa0df9ceee1c8c823ef82b856c122 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 function describe-keymap

This code was written by Drew Adams with minor cleanups and stylistic
changes by Stefan Kangas.
Ref: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=30660

* lisp/help-fns.el (describe-keymap): New function to show key
bindings for a given keymap.  (Bug#30660)
* lisp/help.el (help-map): Bind the new function to "C-h M".
* lisp/help.el (help-for-help-internal): Document what "C-h M" does
when user types "C-h C-h".
---
 lisp/help-fns.el | 66 ++++++++++++++++++++++++++++++++++++++++++++++++
 lisp/help.el     |  2 ++
 2 files changed, 68 insertions(+)

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 90a3571520..b64bbbe4c6 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -1390,6 +1390,72 @@ describe-categories
 	  (insert "\nThe parent category table is:")
 	  (describe-vector table 'help-describe-category-set))))))
 
+;;;###autoload
+(defun describe-keymap (keymap &optional search-symbols-p)
+  "Describe key bindings in KEYMAP.
+When called interactively, prompt for a variable that has a
+keymap value.  Completion is available for the variable name.
+
+If optional argument SEARCH-SYMBOLS-P is non-nil, and KEYMAP is
+not a symbol, search all variables for one whose value is KEYMAP
+and use that to describe the key bindings.  This makes it
+possible to not only see the bindings but also to identify the
+name of the keymap in question."
+  (interactive (list
+                (intern (completing-read "Keymap: " obarray
+                                         (lambda (m)
+                                           (and (boundp m)
+                                                (keymapp (symbol-value m))))
+                                         t nil 'variable-name-history))))
+  (unless (and (symbolp keymap)
+               (boundp keymap)
+               (keymapp (symbol-value keymap)))
+    (if (not (keymapp keymap))
+        (if (symbolp keymap)
+            (error "Not a keymap variable: %S" keymap)
+          (error "Not a keymap"))
+      (let ((sym nil))
+        (when search-symbols-p
+          (setq sym (catch 'describe-keymap
+                      (mapatoms (lambda (symb)
+                                  (when (and (boundp symb)
+                                             (eq (symbol-value symb) keymap)
+                                             (not (eq symb 'keymap))
+                                             (throw 'describe-keymap symb)))))
+                      nil)))
+        (unless sym
+          (setq sym (cl-gentemp "KEYMAP OBJECT (no variable) "))
+          (set sym keymap))
+        (setq keymap sym))))
+  ;; Follow aliasing.
+  (setq keymap (or (ignore-errors (indirect-variable keymap)) keymap))
+  (let* ((name (symbol-name keymap))
+         (doc (documentation-property keymap 'variable-documentation))
+         (file-name (find-lisp-object-file-name keymap 'defvar)))
+    (help-setup-xref (list #'describe-keymap keymap)
+                     (called-interactively-p 'interactive))
+    (with-help-window (help-buffer)
+      (princ (format-message "%S" keymap))
+      (princ (format-message
+              " is a keymap variable defined in `%s'.\n\n"
+              (if (eq file-name 'C-source)
+                  "C source code"
+                (file-name-nondirectory file-name))))
+      (with-current-buffer standard-output
+        (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.
+      (with-current-buffer "*Help*"
+        (insert (substitute-command-keys (concat "\\{" name "}")))))))
+
 \f
 ;;; Replacements for old lib-src/ programs.  Don't seem especially useful.
 
diff --git a/lisp/help.el b/lisp/help.el
index e40178de96..18f1219ca0 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -96,6 +96,7 @@ help-map
     (define-key map "k" 'describe-key)
     (define-key map "l" 'view-lossage)
     (define-key map "m" 'describe-mode)
+    (define-key map "M" 'describe-keymap)
     (define-key map "o" 'describe-symbol)
     (define-key map "n" 'view-emacs-news)
     (define-key map "p" 'finder-by-keyword)
@@ -219,6 +220,7 @@ 'help-for-help
 L LANG-ENV  Describes a specific language environment, or RET for current.
 m           Display documentation of current minor modes and current major mode,
               including their special commands.
+M KEYMAP    Describe the given keymap and its bindings.
 n           Display news of recent Emacs changes.
 o SYMBOL    Display the given function or variable's documentation and value.
 p TOPIC     Find packages matching a given topic keyword.
-- 
2.22.0

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Drew Adams]

> I've now packaged up a proposed patch

Thanks for working on this.  Looks mostly OK to me.
However:

1. I object to the use of `C-h M' as the key binding.
   Please use `C-h M-k'.  The letter `M/m' has other,
   and more useful, associations (mode, mail, .  And
   `M' currently is translated to the often used
   `C-h m'.  `K' is often associated in Emacs with
   "key" or "kill".  And it's as easy to use Meta as
   it is to use Shift.

   [And users of `help-fns+.el', which has the same
   command but with additional features, are used to
   `C-h M-k'.  Because the vanilla version will lack
   those additional features I'll continue to maintain
   `describe-keymap' in `help-fns+.el'.  If those
   features are also added to vanilla Emacs someday
   then I won't need to maintain it.]

2. When testing with `emacs -Q' (but perhaps because
   I ran into the error of #3?), and also using
   `C-h f' etc., I somehow ended up with two [back]
   links at the bottom of *Help*, like this:

   [back]

   [back]

   Please check that what you end up with doesn't
   lead to this.

3. The code raises this error when KEYMAP is not a
   symbol and SEARCH-SYMBOLS-P is nil, because
   FILE-NAME is nil.

(describe-keymap isearch-mode-map) => 

Debugger entered--Lisp error: (wrong-type-argument stringp nil)
  file-name-nondirectory(nil)
  (if (eq file-name (quote C-source)) "C source code" (file-name-nondirectory file-name))
  ...

4. When fixing that bug, please be sure not to print
   a generated name ("KEYMAP OBJECT (no variable)")
   for a non-existent or not found variable.

5. When fixing that bug, if the keymap is fine, and
   it has a variable that is not defined in a file,
   don't try to print a file for it.  Don't try to
   print a file for the non-variable case either.

Wrt 3-5: It's not right to blindly print a variable
name and a file for it.  The code needs to handle
cases such as variable not given, no variable at all,
and variable not defined in a file.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> I've now packaged up a proposed patch with some cleanups and
> adaptions.  It would be great if someone could review this.

[...]

> This code was written by Drew Adams with minor cleanups and stylistic
> changes by Stefan Kangas.
> Ref: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=30660
>
> * lisp/help-fns.el (describe-keymap): New function to show key
> bindings for a given keymap.  (Bug#30660)

This looks like a useful addition...

> * lisp/help.el (help-map): Bind the new function to "C-h M".
> * lisp/help.el (help-for-help-internal): Document what "C-h M" does
> when user types "C-h C-h".

`C-h m' is already used and `C-h M' auto-maps to it currently, so I'm
not sure that's the best binding.  But perhaps that's not a problem in
practice. 

Other than that, I have no comments, and I think it should be applied to
Emacs 27.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 14 Oct 2019 22:28:27 +0200
> Cc: 30660@debbugs.gnu.org,
>  積丹尼 Dan Jacobson <jidanni@jidanni.org>
> 
> This looks like a useful addition...
> 
> > * lisp/help.el (help-map): Bind the new function to "C-h M".
> > * lisp/help.el (help-for-help-internal): Document what "C-h M" does
> > when user types "C-h C-h".
> 
> `C-h m' is already used and `C-h M' auto-maps to it currently, so I'm
> not sure that's the best binding.  But perhaps that's not a problem in
> practice. 
> 
> Other than that, I have no comments, and I think it should be applied to
> Emacs 27.

Fine with me, but let's not give it any key binding yet, and please
mention this command in NEWS.

Thanks.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Drew Adams]

> > * lisp/help.el (help-map): Bind the new function to "C-h M".
> > * lisp/help.el (help-for-help-internal): Document what "C-h M" does
> > when user types "C-h C-h".
> 
> `C-h m' is already used and `C-h M' auto-maps to it currently, so I'm
> not sure that's the best binding.  But perhaps that's not a problem in
> practice.

I wrote the code for this command and have been using
it since 2007.

I already objected here two months ago to Emacs using
`C-h M' for this - in the message just after the one
you chose to reply to.

I requested that `C-h M-k' be used.  That's the key
I and others have been using for years.  And it's
mnemonic with "keymap" and "key".

Is there a good reason my input is just ignored?

For more info, including other problems with the
patch provided:

https://debbugs.gnu.org/cgi/bugreport.cgi?bug=30660#26

And I do suggest that the other features provided
in the original code be included in the vanilla
version as well.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> > I've now packaged up a proposed patch
>
> Thanks for working on this.  Looks mostly OK to me.
> However:

Thanks for the review.  I've fixed all your comments in a patch I'll send soon.

Best regards,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> I requested that `C-h M-k' be used.

I'll add no keybinding at all, as Eli requested.

> Is there a good reason my input is just ignored?

I'm sorry if it looked like your input was being ignored.  I was busy
working on other things.

> And I do suggest that the other features provided
> in the original code be included in the vanilla
> version as well.

I'm not sure which features this refers to, but perhaps you could take
a look when I send the new patch and give your feedback.

Best regards,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

> Fine with me, but let's not give it any key binding yet, and please
> mention this command in NEWS.

Please find attached an updated patch fixing your comments as well as
earlier comments by Drew Adams.

In addition to adding this to NEWS, I've also updated the elisp manual.

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Add-new-help-function-describe-keymap.patch --]
[-- Type: application/octet-stream, Size: 8342 bytes --]

From 323f7eeb7eee3f0d3a7e9d38c189db40d40eba42 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 function describe-keymap

This code was written by Drew Adams.  Stefan Kangas adapted it for
inclusion in Emacs, added unit tests and documentation.

* lisp/help-fns.el (describe-keymap): New function 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/value+search-symbols)
(help-fns-test-describe-keymap/symbol+search-symbols)
(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.
---
 doc/lispref/keymaps.texi    | 12 ++++++
 etc/NEWS                    |  3 ++
 lisp/help-fns.el            | 73 +++++++++++++++++++++++++++++++++++++
 test/lisp/help-fns-tests.el | 45 +++++++++++++++++++++++
 4 files changed, 133 insertions(+)

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 532e537026..569e6137e6 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2004,6 +2004,18 @@ 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.
+
+If optional argument @var{search-symbols} is non-nil, and @var{keymap}
+is not a symbol, search all variables for one whose value is KEYMAP
+and use that to describe the key bindings.  This makes it possible to
+not only see the bindings but also to identify the name of a keymap
+when you have its value.
+@end deffn
+
 @node Menu Keymaps
 @section Menu Keymaps
 @cindex menu keymaps
diff --git a/etc/NEWS b/etc/NEWS
index e1eb74f86e..05c2940a92 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1337,6 +1337,9 @@ directories in the destination.
 
 ** 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 235aa9a6e1..276d44958b 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -1557,6 +1557,79 @@ describe-categories
 	  (insert "\nThe parent category table is:")
 	  (describe-vector table 'help-describe-category-set))))))
 
+;;;###autoload
+(defun describe-keymap (keymap &optional search-symbols)
+  "Describe key bindings in KEYMAP.
+When called interactively, prompt for a variable that has a
+keymap value.  Completion is available for the variable name.
+
+If optional argument SEARCH-SYMBOLS is non-nil, and KEYMAP is
+not a symbol, search all variables for one whose value is KEYMAP
+and use that to describe the key bindings.  This makes it
+possible to not only see the bindings but also to identify the
+name of the keymap in question."
+  (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))
+        (when search-symbols
+          (setq sym (catch 'describe-keymap
+                      (mapatoms (lambda (symb)
+                                  (when (and (boundp symb)
+                                             (eq (symbol-value symb) keymap)
+                                             (not (eq symb 'keymap))
+                                             (throw 'describe-keymap symb)))))
+                      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..30c8faa8a8 100644
--- a/test/lisp/help-fns-tests.el
+++ b/test/lisp/help-fns-tests.el
@@ -123,4 +123,49 @@ 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/value+search-symbols ()
+  (describe-keymap minibuffer-local-must-match-map t)
+  (with-current-buffer "*Help*"
+    (message "##############################")
+    ;; (message "%S" minibuffer-local-must-match-map)
+    (message (buffer-string))
+    (message "##############################")
+    (should (looking-at "^minibuffer-local-must-match-map is"))))
+
+(ert-deftest help-fns-test-describe-keymap/symbol+search-symbols ()
+  (describe-keymap 'minibuffer-local-must-match-map t)
+  (with-current-buffer "*Help*"
+    (should (looking-at "^minibuffer-local-must-match-map is"))))
+
+(ert-deftest help-fns-test-describe-keymap/not-keymap ()
+  (should-error (describe-keymap nil))
+  (should-error (describe-keymap emacs-version))
+  (should-error (describe-keymap nil t))
+  (should-error (describe-keymap emacs-version t)))
+
+(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.23.0

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

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

Stefan Kangas <stefan@marxist.se> writes:

> Please find attached an updated patch fixing your comments as well as
> earlier comments by Drew Adams.
>
> In addition to adding this to NEWS, I've also updated the elisp manual.

Second try; I'd forgotten to remove some debug printouts from the tests.

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Add-new-help-function-describe-keymap.patch --]
[-- Type: application/octet-stream, Size: 8158 bytes --]

From 10f4c070302a2b2bc0cb2115a0dd91921208b9ac 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 function describe-keymap

This code was written by Drew Adams.  Stefan Kangas adapted it for
inclusion in Emacs, added unit tests and documentation.

* lisp/help-fns.el (describe-keymap): New function 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/value+search-symbols)
(help-fns-test-describe-keymap/symbol+search-symbols)
(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.
---
 doc/lispref/keymaps.texi    | 12 ++++++
 etc/NEWS                    |  3 ++
 lisp/help-fns.el            | 73 +++++++++++++++++++++++++++++++++++++
 test/lisp/help-fns-tests.el | 41 +++++++++++++++++++++
 4 files changed, 129 insertions(+)

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 532e537026..569e6137e6 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2004,6 +2004,18 @@ 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.
+
+If optional argument @var{search-symbols} is non-nil, and @var{keymap}
+is not a symbol, search all variables for one whose value is KEYMAP
+and use that to describe the key bindings.  This makes it possible to
+not only see the bindings but also to identify the name of a keymap
+when you have its value.
+@end deffn
+
 @node Menu Keymaps
 @section Menu Keymaps
 @cindex menu keymaps
diff --git a/etc/NEWS b/etc/NEWS
index e1eb74f86e..05c2940a92 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1337,6 +1337,9 @@ directories in the destination.
 
 ** 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 235aa9a6e1..276d44958b 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -1557,6 +1557,79 @@ describe-categories
 	  (insert "\nThe parent category table is:")
 	  (describe-vector table 'help-describe-category-set))))))
 
+;;;###autoload
+(defun describe-keymap (keymap &optional search-symbols)
+  "Describe key bindings in KEYMAP.
+When called interactively, prompt for a variable that has a
+keymap value.  Completion is available for the variable name.
+
+If optional argument SEARCH-SYMBOLS is non-nil, and KEYMAP is
+not a symbol, search all variables for one whose value is KEYMAP
+and use that to describe the key bindings.  This makes it
+possible to not only see the bindings but also to identify the
+name of the keymap in question."
+  (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))
+        (when search-symbols
+          (setq sym (catch 'describe-keymap
+                      (mapatoms (lambda (symb)
+                                  (when (and (boundp symb)
+                                             (eq (symbol-value symb) keymap)
+                                             (not (eq symb 'keymap))
+                                             (throw 'describe-keymap symb)))))
+                      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..0bdfd8c39c 100644
--- a/test/lisp/help-fns-tests.el
+++ b/test/lisp/help-fns-tests.el
@@ -123,4 +123,45 @@ 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/value+search-symbols ()
+  (describe-keymap minibuffer-local-must-match-map t)
+  (with-current-buffer "*Help*"
+    (should (looking-at "^minibuffer-local-must-match-map is"))))
+
+(ert-deftest help-fns-test-describe-keymap/symbol+search-symbols ()
+  (describe-keymap 'minibuffer-local-must-match-map t)
+  (with-current-buffer "*Help*"
+    (should (looking-at "^minibuffer-local-must-match-map is"))))
+
+(ert-deftest help-fns-test-describe-keymap/not-keymap ()
+  (should-error (describe-keymap nil))
+  (should-error (describe-keymap emacs-version))
+  (should-error (describe-keymap nil t))
+  (should-error (describe-keymap emacs-version t)))
+
+(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.23.0

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Robert Pluim]

>>>>> On Thu, 17 Oct 2019 11:42:25 +0200, Stefan Kangas <stefan@marxist.se> said:

    Stefan> * lisp/help-fns.el (describe-keymap): New function to show key
    Stefan> bindings for a given keymap.  (Bug#30660)
    Stefan> * doc/lispref/keymaps.texi (Scanning Keymaps): Document it.
    Stefan> * etc/NEWS: Announce it.

    Stefan> * test/lisp/help-fns-tests.el (help-fns-test-describe-keymap/symbol)
    Stefan> (help-fns-test-describe-keymap/value)
    Stefan> (help-fns-test-describe-keymap/value+search-symbols)
    Stefan> (help-fns-test-describe-keymap/symbol+search-symbols)
    Stefan> (help-fns-test-describe-keymap/not-keymap)
    Stefan> (help-fns-test-describe-keymap/let-bound)
    Stefan> (help-fns-test-describe-keymap/dynamically-bound-no-file): New tests.
    Stefan> ---
    Stefan>  doc/lispref/keymaps.texi    | 12 ++++++
    Stefan>  etc/NEWS                    |  3 ++
    Stefan>  lisp/help-fns.el            | 73 +++++++++++++++++++++++++++++++++++++
    Stefan>  test/lisp/help-fns-tests.el | 41 +++++++++++++++++++++
    Stefan>  4 files changed, 129 insertions(+)

    Stefan> diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
    Stefan> index 532e537026..569e6137e6 100644
    Stefan> --- a/doc/lispref/keymaps.texi
    Stefan> +++ b/doc/lispref/keymaps.texi
    Stefan> @@ -2004,6 +2004,18 @@ Scanning Keymaps
    Stefan>  instead of the current buffer's.
    Stefan>  @end deffn
 
    Stefan> +@deffn Command describe-keymap keymap &optional search-symbols
    Stefan> +This function creates a listing of all key bindings in variable

s/variable//

    Stefan> +@var{keymap}, and displays it in a buffer named @file{*Help*}.  When
    Stefan> +called interactively, prompt for a variable that has a keymap value.
    Stefan> +
    Stefan> +If optional argument @var{search-symbols} is non-nil, and @var{keymap}
    Stefan> +is not a symbol, search all variables for one whose value is KEYMAP

@var{keymap}

Iʼm not clear on why it needs such a convoluted API, but I guess itʼs
useful to someone. Could the searching not be split into a
'find-keymap' function?

Robert

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 17 Oct 2019 11:39:31 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 30660@debbugs.gnu.org, 
> 	積丹尼 Dan Jacobson <jidanni@jidanni.org>
> 
> > Fine with me, but let's not give it any key binding yet, and please
> > mention this command in NEWS.
> 
> Please find attached an updated patch fixing your comments as well as
> earlier comments by Drew Adams.
> 
> In addition to adding this to NEWS, I've also updated the elisp manual.

Thanks.  However, I think that the right manual for this is the user
manual, not the ELisp manual.  It is, after all, a command whose
purpose is to show documentation to the user, right?

> Subject: [PATCH] Add new help function describe-keymap
> 
> This code was written by Drew Adams.  Stefan Kangas adapted it for
> inclusion in Emacs, added unit tests and documentation.

I think CONTRIBUTE advises to use Co-authored-by for these situations.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Lars Ingebrigtsen <larsi@gnus.org>,
>   30660@debbugs.gnu.org,  積丹尼 Dan Jacobson
>  <jidanni@jidanni.org>
> Date: Thu, 17 Oct 2019 14:07:10 +0200
> 
> 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.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Eli Zaretskii <eliz@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.

Best regards,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

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

Stefan Kangas <stefan@marxist.se> writes:

> Eli Zaretskii <eliz@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


[-- 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: 6331 bytes --]

From 63952f2062d981c49d16e8643e287de00b19ffe3 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/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@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))))
+
 \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

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Drew Adams]

Well, I obviously disagree.  Another reason
I'll have to keep maintaining the version
in `help-fns+.el', I guess.  Oh well.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> In addition to adding this to NEWS, I've also updated the elisp manual.
>
> Thanks.  However, I think that the right manual for this is the user
> manual, not the ELisp manual.  It is, after all, a command whose
> purpose is to show documentation to the user, right?

I had missed fixing this before sending my recent updated patch.  I
think what you say here makes sense, so I'll move documentation to the
user manual and send a new patch.  Thanks.

Best regards,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

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

Stefan Kangas <stefan@marxist.se> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> In addition to adding this to NEWS, I've also updated the elisp manual.
>>
>> Thanks.  However, I think that the right manual for this is the user
>> manual, not the ELisp manual.  It is, after all, a command whose
>> purpose is to show documentation to the user, right?
>
> I had missed fixing this before sending my recent updated patch.  I
> think what you say here makes sense, so I'll move documentation to the
> user manual and send a new patch.  Thanks.

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.

WDYT?

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: 7422 bytes --]

From 3a24ecd11256014e53c464bf8c181239b443c7cd 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):
* 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@oracle.com>
---
 doc/emacs/help.texi         |  5 +++-
 doc/lispref/keymaps.texi    |  6 ++++
 etc/NEWS                    |  3 ++
 lisp/help-fns.el            | 59 +++++++++++++++++++++++++++++++++++++
 test/lisp/help-fns-tests.el | 29 ++++++++++++++++++
 5 files changed, 101 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/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 4134f7bb5f..6609bd3111 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

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: larsi@gnus.org,  30660@debbugs.gnu.org,  jidanni@jidanni.org
> Date: Mon, 11 Nov 2019 16:04:10 +0100
> 
> 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).

Thanks.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

> 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).

Here's a separate patch to remove it, while preserving the information
by moving it to the doc string of 'describe-bindings'.

WDYT?

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Remove-describe-bindings-from-elisp-manual.patch --]
[-- Type: text/x-diff, Size: 3943 bytes --]

From 872d71f8667d68ac449d89993f9f85138eb3c1bb Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 15 Nov 2019 05:05:00 +0100
Subject: [PATCH] Remove describe-bindings from elisp manual

Ref: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=30660#74

* doc/lispref/keymaps.texi (Scanning Keymaps): Remove
'describe-bindings'.
* lisp/help.el (describe-bindings): Add some information removed from
the elisp manual to the doc string instead.
---
 doc/lispref/keymaps.texi | 23 -----------------------
 lisp/help.el             | 28 +++++++++++++++++++++-------
 2 files changed, 21 insertions(+), 30 deletions(-)

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 8ff329bdac..1162abfc2b 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1987,29 +1987,6 @@ Scanning Keymaps
 @end table
 @end defun
 
-@deffn Command describe-bindings &optional prefix buffer-or-name
-This function creates a listing of all current key bindings, and
-displays it in a buffer named @file{*Help*}.  The text is grouped by
-modes---minor modes first, then the major mode, then global bindings.
-
-If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
-listing includes only keys that start with @var{prefix}.
-
-When several characters with consecutive @acronym{ASCII} codes have the
-same definition, they are shown together, as
-@samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to
-know the @acronym{ASCII} codes to understand which characters this means.
-For example, in the default global map, the characters @samp{@key{SPC}
-..@: ~} are described by a single line.  @key{SPC} is @acronym{ASCII} 32,
-@kbd{~} is @acronym{ASCII} 126, and the characters between them include all
-the normal printing characters, (e.g., letters, digits, punctuation,
-etc.@:); all these characters are bound to @code{self-insert-command}.
-
-If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
-buffer name.  Then @code{describe-bindings} lists that buffer's bindings,
-instead of the current buffer's.
-@end deffn
-
 @node Menu Keymaps
 @section Menu Keymaps
 @cindex menu keymaps
diff --git a/lisp/help.el b/lisp/help.el
index 3b3d1f977e..7b5f4b4b31 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -492,13 +492,27 @@ view-lossage
 
 (defun describe-bindings (&optional prefix buffer)
   "Display a buffer showing a list of all defined keys, and their definitions.
-The keys are displayed in order of precedence.
-
-The optional argument PREFIX, if non-nil, should be a key sequence;
-then we display only bindings that start with that prefix.
-The optional argument BUFFER specifies which buffer's bindings
-to display (default, the current buffer).  BUFFER can be a buffer
-or a buffer name."
+The keys are displayed in order of precedence: first local
+bindings of minor modes, then local bindings defined by the
+current major mode, and finally global bindings.
+
+If optional argument PREFIX is non-nil, it should be a key
+sequence and means to display only bindings starting with that
+prefix.
+
+If optional argument BUFFER is non-nil, it specifies which
+buffer's bindings to display (by default, the current buffer).
+BUFFER can be a buffer or a buffer name.
+
+When several characters with consecutive ASCII codes have the same
+definition, they are shown together, as `FIRSTCHAR..LASTCHAR'.  In
+this instance, you need to know the ASCII codes to understand which
+characters this means.  For example, in the default global map, the
+characters `<SPC> .. ~' are described by a single line.  <SPC> is
+ASCII 32, `~' is ASCII 126, and the characters between them include
+all the normal printing characters, (e.g., letters, digits,
+punctuation, etc.); all these characters are bound to
+`self-insert-command'."
   (interactive)
   (or buffer (setq buffer (current-buffer)))
   (help-setup-xref (list #'describe-bindings prefix buffer)
-- 
2.20.1

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

[-- 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

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: larsi@gnus.org,  30660@debbugs.gnu.org,  jidanni@jidanni.org
> Date: Sun, 17 Nov 2019 21:51:04 +0100
> 
> 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.

This seems to do the opposite of what I've been talking about, no?
What am I missing?

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: larsi@gnus.org,  30660@debbugs.gnu.org,  jidanni@jidanni.org
> Date: Sun, 17 Nov 2019 21:36:53 +0100
> 
> > 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).
> 
> Here's a separate patch to remove it, while preserving the information
> by moving it to the doc string of 'describe-bindings'.

Why move that to the doc string? why not to the user manual?

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > 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).

I think I included it in the Lisp Manual because it is useful for debugging
the bindings of a mode you are working on.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> > 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.
>>
>> OK, I've removed it in the attached patch.
>
> This seems to do the opposite of what I've been talking about, no?
> What am I missing?

I'm not sure; I might have misunderstood you.

In the quote above, you write "I'd prefer to have just one description
in the user manual".  In the patch, I therefore removed the addition
to the elisp manual, while keeping the addition to the user manual.

Re-reading your message, I see that you also asked for a
"cross-reference in the elisp manual which points to that".  My patch
did not add such a reference.  That was an oversight on my part.

Perhaps we could add the reference in the separate patch that removes
describe-bindings from the elisp manual instead.  I think that
logically makes more sense, since these commands are related and could
be better explained if they're kept together in one brief paragraph.

Please clarify if any of the above is incorrect.  Thanks in advance
and sorry for any confusion.

Best regards,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, larsi@gnus.org, 30660@debbugs.gnu.org,
> 	jidanni@jidanni.org
> Date: Tue, 19 Nov 2019 01:07:46 -0500
> 
>   > > 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).
> 
> I think I included it in the Lisp Manual because it is useful for debugging
> the bindings of a mode you are working on.

I didn't suggest to remove any mention of it, I suggested to mention
it, but send the reader to the Emacs manual to read about the details.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 19 Nov 2019 15:14:45 +0100
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 30660@debbugs.gnu.org, 
> 	積丹尼 Dan Jacobson <jidanni@jidanni.org>
> 
> Re-reading your message, I see that you also asked for a
> "cross-reference in the elisp manual which points to that".  My patch
> did not add such a reference.  That was an oversight on my part.

Yes, that's what I was missing.  Also, the log message says

  * 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.

but I see no patch part that describes describe-keymap in help.texi...

> Perhaps we could add the reference in the separate patch that removes
> describe-bindings from the elisp manual instead.

I meant to have a reference to the description of describe-keymap.
What to do with describe-bindings is a separate issue.  I'm okay with
removing it as well, leaving its only description in the user manual,
and having a cross-reference to that in the ELisp manual.

Thanks.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: larsi@gnus.org,  30660@debbugs.gnu.org,  jidanni@jidanni.org
> Date: Thu, 16 Jan 2020 23:01:50 +0100
> 
> >> Re-reading your message, I see that you also asked for a
> >> "cross-reference in the elisp manual which points to that".  My patch
> >> did not add such a reference.  That was an oversight on my part.
> >
> > Yes, that's what I was missing.  Also, the log message says
> >
> >   * 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.
> >
> > but I see no patch part that describes describe-keymap in help.texi...
> 
> Please find attached an updated patch below.

Thanks.

> +@findex describe-keymap
> +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.

This should mention the completion on keymaps:

  "...prompts for the name of a keymap, with completion, and displays
  the listing of all the key bindings in that keymap."

Also, do we want to have some reasonable default value for this
prompt?

Otherwise, LGTM.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> +@findex describe-keymap
>> +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.
>
> This should mention the completion on keymaps:
>
>   "...prompts for the name of a keymap, with completion, and displays
>   the listing of all the key bindings in that keymap."

Fixed, thanks.  I now have:

    @findex describe-keymap
    Finally, @kbd{M-x describe-keymap} prompts for the name of a keymap,
    with completion, and displays a listing of all key bindings in that
    keymap.

> Also, do we want to have some reasonable default value for this
> prompt?

I'm not sure, what would be a reasonable default?  The keymap of the
current major mode?

Best regards,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: larsi@gnus.org,  30660@debbugs.gnu.org,  jidanni@jidanni.org
> Date: Sat, 18 Jan 2020 03:16:30 +0100
> 
> > Also, do we want to have some reasonable default value for this
> > prompt?
> 
> I'm not sure, what would be a reasonable default?  The keymap of the
> current major mode?

I thought about the description in "Active Keymaps".

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> > Also, do we want to have some reasonable default value for this
>> > prompt?
>> 
>> I'm not sure, what would be a reasonable default?  The keymap of the
>> current major mode?
>
> I thought about the description in "Active Keymaps".

Do you mean to use the first active keymap?

I can see how that make sense, and would probably be intuitive when
trying to figure out what keymap is active in different parts of a
buffer (for example over a button).

If that's what you're thinking of, I wonder if there's any way to get
the name of the highest precedent keymap among the active keymaps?

This was the first thing I tried, but it didn't work:

   (car (current-active-maps t (point)))

Best regards,
Stefan Kangas

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: larsi@gnus.org,  30660@debbugs.gnu.org,  jidanni@jidanni.org
> Date: Sat, 18 Jan 2020 10:12:08 +0100
> 
> >> I'm not sure, what would be a reasonable default?  The keymap of the
> >> current major mode?
> >
> > I thought about the description in "Active Keymaps".
> 
> Do you mean to use the first active keymap?
> 
> I can see how that make sense, and would probably be intuitive when
> trying to figure out what keymap is active in different parts of a
> buffer (for example over a button).
> 
> If that's what you're thinking of, I wonder if there's any way to get
> the name of the highest precedent keymap among the active keymaps?
> 
> This was the first thing I tried, but it didn't work:
> 
>    (car (current-active-maps t (point)))

Does the pseudo-code at the beginning of "Searching Keymaps" give any
ideas?

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

> Does the pseudo-code at the beginning of "Searching Keymaps" give any
> ideas?

It does, yes.

The pseudo-code only gives us the *value* of the keymap.  This is
probably part of the reason why Drew wanted us to be able to find
keymap *symbols* from values.  I have added a separate function
help-fns-find-keymap-name to get the symbol from the value based on
his code.

I'm not sure exactly where the new functions in the second patch
should go, so I just kept them in help-fns.el.  I suspect people might
want to use at least help-fns-find-keymap-name outside of help-fns.el,
so maybe we could find a better place to add them (and better names?).

Attached is an updated patchset.  The first patch is as before,
updated with the above doc fix, and the second patch adds the
reasonable default you asked for.  WDYT?

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: 7275 bytes --]

From be09c3a807239804284430cd316530235b48da19 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 24 Aug 2019 01:02:04 +0200
Subject: [PATCH 1/2] 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 the new command.
* doc/lispref/keymaps.texi (Scanning Keymaps): Add a cross-reference
to the above documentation.
* etc/NEWS: Announce the new command.

* 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 ++++
 doc/lispref/keymaps.texi    |  7 +++--
 etc/NEWS                    |  5 ++++
 lisp/help-fns.el            | 59 +++++++++++++++++++++++++++++++++++++
 test/lisp/help-fns-tests.el | 28 ++++++++++++++++++
 5 files changed, 102 insertions(+), 2 deletions(-)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index fce6720b93..49c53c5cbc 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -601,6 +601,11 @@ Misc Help
 which marks a defun.  However, @w{@kbd{@key{ESC} @key{F1}}} and
 @w{@kbd{@key{ESC} ?}} work fine.)
 
+@findex describe-keymap
+Finally, @kbd{M-x describe-keymap} prompts for the name of a keymap,
+with completion, and displays a listing of all key bindings in that
+keymap.
+
 @node Help Files
 @section Help Files
 
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 259efea324..4d513132e9 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1846,8 +1846,11 @@ Scanning Keymaps
 @cindex scanning keymaps
 @cindex keymaps, scanning
 
-  This section describes functions used to scan all the current keymaps
-for the sake of printing help information.
+  This section describes functions used to scan all the current
+keymaps for the sake of printing help information.  To display the
+bindings in a particular keymap, you can use the
+@code{describe-keymap} command (@pxref{Misc Help, , Other Help
+Commands, emacs, The GNU Emacs Manual})
 
 @defun accessible-keymaps keymap &optional prefix
 This function returns a list of all the keymaps that can be reached (via
diff --git a/etc/NEWS b/etc/NEWS
index 73ed3d739e..e4ed0e0bf6 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -44,6 +44,11 @@ It was declared obsolete in Emacs 27.1.
 \f
 * Changes in Specialized Modes and Packages in Emacs 28.1
 
+** Help
+
++++
+*** New command 'describe-keymap' describes keybindings in a keymap.
+
 ---
 ** The sb-image.el library is now marked obsolete.
 This file was a compatibility kludge which is no longer needed.
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 0e2ae6b3c3..017bb3ae74 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -1562,6 +1562,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 4c808d8372..1ac27fef3a 100644
--- a/test/lisp/help-fns-tests.el
+++ b/test/lisp/help-fns-tests.el
@@ -123,4 +123,32 @@ 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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-Provide-default-for-describe-keymap-prompt.patch --]
[-- Type: text/x-diff, Size: 4199 bytes --]

From 3a7a39f241dcb1988abd47dff0070b2abca20c02 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sun, 19 Jan 2020 00:17:42 +0100
Subject: [PATCH 2/2] Provide default for describe-keymap prompt

* lisp/help-fns.el (describe-keymap): Provide a reasonable
default for prompt.  (Bug#30660)
(help-fns-find-keymap-name)
(help-fns--most-relevant-active-keymap): New functions.

* test/lisp/help-fns-tests.el
(help-fns-test-find-keymap-name): New test.
---
 lisp/help-fns.el            | 50 ++++++++++++++++++++++++++++++++-----
 test/lisp/help-fns-tests.el |  9 +++++++
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 017bb3ae74..36c2a8b186 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -1562,17 +1562,55 @@ describe-categories
 	  (insert "\nThe parent category table is:")
 	  (describe-vector table 'help-describe-category-set))))))
 
+(defun help-fns-find-keymap-name (keymap)
+  "Find the name of the variable with value KEYMAP.
+Return nil if KEYMAP is not a valid keymap, or if there is no
+variable with value KEYMAP."
+  (when (keymapp keymap)
+    (let ((name (catch 'found-keymap
+                  (mapatoms (lambda (symb)
+                              (when (and (boundp symb)
+                                         (eq (symbol-value symb) keymap)
+                                         (not (eq symb 'keymap))
+                                         (throw 'found-keymap symb)))))
+                  nil)))
+      ;; Follow aliasing.
+      (or (ignore-errors (indirect-variable name)) name))))
+
+(defun help-fns--most-relevant-active-keymap ()
+  "Return the name of the most relevant active keymap.
+The heuristic to determine which keymap is most likely to be
+relevant to a user follows this order:
+
+1. 'keymap' text property at point
+2. 'local-map' text property at point
+3. the `current-local-map'
+
+This is used to set the default value for the interactive prompt
+in `describe-keymap'.  See also `Searching the Active Keymaps'."
+  (help-fns-find-keymap-name (or (get-char-property (point) 'keymap)
+                         (if (get-text-property (point) 'local-map)
+                             (get-char-property (point) 'local-map)
+                           (current-local-map)))))
+
 ;;;###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))))
+  (interactive
+   (let* ((km (help-fns--most-relevant-active-keymap))
+          (val (completing-read
+                (format "Keymap (default %s): " km)
+                obarray
+                (lambda (m) (and (boundp m) (keymapp (symbol-value m))))
+                t nil 'keymap-name-history
+                (symbol-name km))))
+     (unless (equal val "")
+       (setq km (intern val)))
+     (unless (and km (keymapp (symbol-value km)))
+       (user-error "Not a keymap: %s" km))
+     (list km)))
   (let (used-gentemp)
     (unless (and (symbolp keymap)
                  (boundp keymap)
diff --git a/test/lisp/help-fns-tests.el b/test/lisp/help-fns-tests.el
index 1ac27fef3a..89f732d244 100644
--- a/test/lisp/help-fns-tests.el
+++ b/test/lisp/help-fns-tests.el
@@ -125,6 +125,15 @@ help-fns-test-describe-symbol
 
 \f
 ;;; Tests for describe-keymap
+(ert-deftest help-fns-test-find-keymap-name ()
+  (should (equal (help-fns-find-keymap-name lisp-mode-map) 'lisp-mode-map))
+  ;; Follow aliasing.
+  (unwind-protect
+      (progn
+        (defvaralias 'foo-test-map 'lisp-mode-map)
+        (should (equal (help-fns-find-keymap-name foo-test-map) 'lisp-mode-map)))
+    (makunbound 'foo-test-map)))
+
 (ert-deftest help-fns-test-describe-keymap/symbol ()
   (describe-keymap 'minibuffer-local-must-match-map)
   (with-current-buffer "*Help*"
-- 
2.20.1

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Drew Adams]

> The pseudo-code only gives us the *value* of the keymap.  This is
> probably part of the reason why Drew wanted us to be able to find
> keymap *symbols* from values.

Yes, part of the reason.  And my version doesn't
just try to find keymap symbols from values.  It
also handles real keymap args (non-interactively),
that is, keymaps for which no symbol is found (and
perhaps not even sought).

As I said, users reported the use case of having a
keymap without any symbol (in 2015, whereas I added
`describe-keymap' in 2007 - 8 years earlier).

And a keymap can be composed, or it can be modified
without updating any associated symbol name(s).
Keymaps are not necessarily always with variables,
and a user can want to see, in human terms, what
the keys are in a given map.  This represents real,
non-interactive use cases.

And as I also said, as long as the version you add
to vanilla Emacs doesn't offer at least what my
version provides I'll feel obliged to continue to
offer my version, even for the most recent Emacs
versions - something I'd prefer not to have to do.

That is apparently still not so - the proposed
`describe-keymap' code still doesn't allow for a
non-symbol keymap argument.

I don't recall ever seeing a good argument as to
why you refuse to provide this feature.  I hope
you might reconsider this continuing lack.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: larsi@gnus.org,  30660@debbugs.gnu.org,  jidanni@jidanni.org
> Date: Sun, 19 Jan 2020 00:42:05 +0100
> 
> Attached is an updated patchset.  The first patch is as before,
> updated with the above doc fix, and the second patch adds the
> reasonable default you asked for.  WDYT?

Fine with me, thanks.

bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas]

close 30660 28.1
thanks

Eli Zaretskii <eliz@gnu.org> writes:

> Fine with me, thanks.

Pushed to master as commit 557b790e0a and 330228d5c7.

Best regards,
Stefan Kangas