RE: map-keymap doc not clear

[Drew Adams]

    Obviously, it's not clear to you, so it could use some
    improvement.  I only explained it, in the hope that we can
    then come up with a better wording, once you understand it.

    > My impression is that the doc generally speaks of, say, `C-k'
    > as a "key sequence" not as an "event".

    For most functions, we manipulate sequences of input events (i.e. key
    sequences) rather than single input events.

    > In particular, "a sequence of one event is always a key sequence".

    Right, just like a list of one element is still a list.
    map-keymap's function argument is called with an event as argument, not
    a sequence of events.

I understand more now, I think.

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? 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? If not, then I guess I don't understand what it means for a single
key or event to have a binding in KEYMAP.

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.

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

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.

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

    2. Is FUNCTION really called once for each binding in KEYMAP,
    or is it called once for each key sequence in KEYMAP? If two
    key sequences are bound to the same command in KEYMAP, is
    FUNCTION called twice for that command (once for each key
    sequence) or once (once for the "binding"). If the latter,
    which key sequence is used as the first arg?

    If FUNCTION is called once for each key sequence in KEYMAP,
    then that's what the first line of the doc string should say.

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.