Re: map-keymap doc not clear

[Stefan Monnier]

> If key sequence `C-x 4 f' is bound to command `find-file-other-window',
> then, IIUC, the events or keys here are `C-x', `4', and `k'.  Is that what
> you mean?

Yes.

> I guess that the bindings for these events correspond to the
> keymap that is the value of `ctl-x-map', the keymap that is the value of
> `ctl-x-4-map', and `find-file-other-window', respectively - is that the way
> it works?

Yes.  If you apply map-keymap to the global-map, one of the calls will pass
"?C-x" as the `event' and ctl-x-map as the `binding'.
If you apply map-keymap to ctl-x-map, one of the calls will pass ?4 as the
`event' and `ctl-x-4-map' as the binding.

> The doc says that FUNCTION is called on the event (not on a multi-event key
> sequence) and on its binding, but I guess I'm unclear as to what the binding
> of such an event is.

I hope that clears it up a bit.

>> 2. I still have the question about whether FUNCTION is called for each
>> binding or each key sequence.

>     I don't understand the question.

> I'm not sure what part you don't understand, or whether repeating it might
> help. Can you tell me what part you don't understand?

Give me some examples and ask me what they should do.

> The doc string uses "binding" to refer to the command (or the keymap etc.)
> that is bound to the key - that's not the same as the tuple (key . binding).
> I'm asking if it is correct that FUNCTION is called once for each such
> binding in KEYMAP.

Oh, I see.  Yes there's an ambiguity: "binding" is sometimes used to refer
to the pair (KEY + COMMAND) and sometimes only to COMMAND.  Which is meant
is normally clear from context.

E.g. in the case of map-keymap, if "Call FUNCTION for every binding in
KEYMAP" were to mean it's called once per command (or sub-keymap) in the
keymap, we have a problem: since each such command can be bound to several
key-sequences but the docstring says "FUNCTION is called with two arguments:
the event and its binding", that means that which `event' is passed is
unspecified, or arbitrarily chosen.

> I'm guessing that this might be incorrect, that, instead, FUNCTION is called
> once for each bound key, not once for each command (or keymap etc.) that is
> bound to a key. This makes a difference in case two keys are bound to the
> same command (or keymap). If FUNCTION is called for each binding, not each
> key, then which key (event) is supplied as the arg for a binding bound to
> more than one key?

> E.g given (key1 . binding) and (key2 . binding), which is called,
>     (FUNCTION key1 binding) or (FUNCTION key2 binding)?

Exactly.  Which is why it's clearly a bad interpretation of the meaning of
the docstring.  Of course, the docstring shouldn't need to be
interpreted so carefully.

> I'm hoping you understand my confusion better now. If so, maybe you can
> propose some language that would make the behavior clearer to someone who
> might be confused in the same way as I.

Maybe you have some suggestion?
My proposition would be to just use:

   Call FUNCTION for every event bound in KEYMAP.
   FUNCTION is called with two arguments: the event and its binding.
   If KEYMAP has a parent, the parent's bindings are included as well.
   This works recursively: if the parent has itself a parent, then the
   grandparent's bindings are also included and so on.

but it doesn't fix your confusion between key-sequences and just
single keys.  I'm not sure how to improve it.


-- Stefan