bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap'

[Hong Xu]

On 03/26/2018 09:15 PM, Drew Adams wrote:
>> A callback function should be passed to `map-keymap'. However,
>> the description of the callback function seems to be missing
>> (undocumented). For example, the value does not seems to always be a
>> function. It is sometimes an alist, sometimes a more complicated list.
>>
>> I think this might have never been documented. If it is documented, it
>> would be greatly appreciated if a pointer to the actual documentation
>> can be added to the document of `map-keymap'.
> 
> (If this report is clear to others then don't worry about it,
> but it's not clear to me.)
> 
> I wouldn't call the FUNCTION arg a "callback" function, but
> it's the only function that is passed, AFAIK, so I guess
> that's the one you mean.
> 
> What makes you think it doesn't always need to be a function?
> Grepping the Emacs Lisp files, I don't see any cases where it
> is not a function (or where the KEYMAP arg is a function).
> 
> FUNCTION is described pretty well in the doc, I think - the
> args it is passed are described.
> 
> If you instead meant the KEYMAP arg (whose value is not a
> function, AFAIK), then there is a whole section of the Elisp
> manual devoted do describing that, including the various
> forms a keymap can take (e.g. particular kinds of alists).
> 
> See https://www.gnu.org/software/emacs/manual/html_node/elisp/Keymaps.html
> and its child nodes.
> 
> (I'm probably missing something that you meant.  If so,
> please ignore.)
> 

Thanks for your reply and sorry for the confusion -- I wrote those in a
hurry.

What is confusing in the current document, IMO, is the VALUE arg of the
FUNCTION arg of `map-keymap'. The document reads:

"It passes two arguments, the event type and the value of the binding."

However, I searched the document, and could not find any useful
information regarding the value of the binding. According to my own
experiments, in most cases, it is a function, but sometimes it is an
alist, or keymap, or of other types. I guess this may be obvious to many
of you and may be documented somewhere, but a link to those is somehow
missing; or it may be completely undocumented. I would appreciate it if
the value of the binding is well documented (or a link to it is added).

signature.asc
Description: OpenPGP digital signature