RE: map-keymap doc not clear

[Drew Adams]

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

Exactly what I meant. In the first doc-string line, "binding" is meant to
mean the pair (KEY + COMMAND). In the rest of the doc string, "binding"
refers to the COMMAND (or keymap) that is bound to KEY. I think the first
line should be changed to something like

 Call FUNCTION for each key bound in KEYMAP.

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

There is no need to complicate things by using the two different senses of
"binding". It is sufficient to say that FUNCTION is called for each key (or
event), because the set of bound keys maps one-to-one to the set of binding
pairs (KEY + COMMAND).

    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.

I'm not sure either. Upon rereading Elisp manual page "Keymap Terminology"
the doc string seems pretty clear to me now (except for the first line,
which I would change to "Call FUNCTION for each event bound in KEYMAP").

I don't think there is a good way to avoid the confusion I had, short of
reminding people that a key sequence is composed of one or more events, and
that although we often speak of the binding of a key sequence, it is in fact
the individual events that are bound. I don't think the doc string is the
place for that. I'd say don't worry about it.