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

[Drew Adams <drew.adams@oracle.com>]

[-- 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 "}")))))))