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

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

[Hong Xu]

[-- Attachment #1.1: Type: text/plain, Size: 470 bytes --]

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

Hong


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Drew Adams]

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

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

[Hong Xu]

[-- Attachment #1.1: Type: text/plain, Size: 2306 bytes --]

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Andreas Schwab]

On Mär 27 2018, Hong Xu <hong@topbug.net> wrote:

> However, I searched the document, and could not find any useful
> information regarding the value of the binding.

It is whatever you've put there, see define-key.  A keymap is really
just a mapping from a key to an arbitrary value, though if the keymap is
to be used as a local keymap each value should have one of the forms as
listed in the doc for define-key.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

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

[Drew Adams]

> > However, I searched the document, and could not find any useful
> > information regarding the value of the binding.
> 
> It is whatever you've put there, see define-key.  A keymap is really
> just a mapping from a key to an arbitrary value, though if the keymap is
> to be used as a local keymap each value should have one of the forms as
> listed in the doc for define-key.

Yes, I think that is the point: what a keymap is, and so
what its entries are that are being mapped over.

The key is to know or look up what a keymap is.  Maybe
this needs to be pointed out better in the doc string?
Maybe the doc string should point users to the doc about
keymaps?  Typically we don't do that - if a user sees a
term that is unclear we count on them looking it up.

But maybe it's not clear from the doc string that the
key here is to know what keymap is?  I would think that
that would be obvious, given that it is a function that
maps over keymap entries.  But maybe it's not.

I don't really have a suggestion for this, but maybe
Hong Xu does.

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

[Hong Xu]

[-- Attachment #1.1: Type: text/plain, Size: 1596 bytes --]

On 03/27/2018 07:27 AM, Drew Adams wrote:
>>> However, I searched the document, and could not find any useful
>>> information regarding the value of the binding.
>>
>> It is whatever you've put there, see define-key.  A keymap is really
>> just a mapping from a key to an arbitrary value, though if the keymap is
>> to be used as a local keymap each value should have one of the forms as
>> listed in the doc for define-key.
> 
> Yes, I think that is the point: what a keymap is, and so
> what its entries are that are being mapped over.
> 
> The key is to know or look up what a keymap is.  Maybe
> this needs to be pointed out better in the doc string?
> Maybe the doc string should point users to the doc about
> keymaps?  Typically we don't do that - if a user sees a
> term that is unclear we count on them looking it up.
> 
> But maybe it's not clear from the doc string that the
> key here is to know what keymap is?  I would think that
> that would be obvious, given that it is a function that
> maps over keymap entries.  But maybe it's not.
> 
> I don't really have a suggestion for this, but maybe
> Hong Xu does.
> 

Thanks, Drew. Actually it's also obvious for me to look up for a keymap
is. What is unobvious is the value of the binding. Even if you go to
"Format of Keymaps", it still does not talk about the actual value of
the binding. The reason it is important for `map-keymap' is that this
seems to be the only place that users need to know the exact value of
binding---in other places, they are operated by some provided functions.

Hong


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Stefan Kangas]

Hong Xu <hong@topbug.net> writes:

> Thanks, Drew. Actually it's also obvious for me to look up for a keymap
> is. What is unobvious is the value of the binding. Even if you go to
> "Format of Keymaps", it still does not talk about the actual value of
> the binding. The reason it is important for `map-keymap' is that this
> seems to be the only place that users need to know the exact value of
> binding---in other places, they are operated by some provided functions.

The docstring of `map-keymap' says:

    Call FUNCTION once for each event binding in KEYMAP.
    FUNCTION is called with two arguments: the event that is bound, and
    the definition it is bound to.  The event may be a character range.

A keymap is fundamentally either a list or a char table with
mappings from events to a definition.  The event could be e.g. a key
sequence, and the definitions might be commands or other things.

I find "the event that is bound" to be clear enough, in the sense that
you know what to look for in the manual.

I also find "the definition it is bound to" clear in the same sense.

I don't see what to add to make this any clearer, without pulling in the
entire reference manual worth of stuff to explain all possible types of
values.  IOW, I think the answer here is that to use this particular
function, you cannot just read the docstring, you must study the info
node `(elisp) Keymaps' in detail.  I don't see any way around that.

So maybe you are right, but maybe also there is just not much we can do
about it.  Or there is some way to explain this that none of us have
seen so far.  Perhaps you have a suggestion for what we could add here?

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

[Drew Adams]

I agree with Stefan that the (1) doc is clear as
far as it goes, (2) the set of possible key-binding
representations is large and complex, and (3) to
understand this stuff you really need to carefully
study the carefully specified doc in the Elisp
manual for this.

(There are some other complex areas like this.  One
is font-lock-keywords forms.)

My suggestion would be to help users by providing
a middle ground between (1) a correct but sparse
and little-explanatory doc string and (2) "pulling
in the entire reference manual worth of stuff to
explain all possible types of values":

Just add a link to the relevant section in the
manual.  That way, instead of closing the door on
an interested reader of the doc string, you open
the door to a full understanding.  An uninterested
reader might not follow the link - no harm, no foul.

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

[Stefan Kangas]

close 30958 28.1
thanks

Drew Adams <drew.adams@oracle.com> writes:

> Just add a link to the relevant section in the
> manual.  That way, instead of closing the door on
> an interested reader of the doc string, you open
> the door to a full understanding.  An uninterested
> reader might not follow the link - no harm, no foul.

Yes, that seems like the best thing to do here.  So I've now done that
change on the emacs-28 branch (commit 0651c2d77b).

I'm consequently closing this bug report.