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

[Stefan Kangas <stefan@marxist.se>]

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