* bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' @ 2018-03-25 21:44 Hong Xu 2018-03-27 4:15 ` Drew Adams 0 siblings, 1 reply; 9+ messages in thread From: Hong Xu @ 2018-03-25 21:44 UTC (permalink / raw) To: 30958 [-- 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 --] ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' 2018-03-25 21:44 bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' Hong Xu @ 2018-03-27 4:15 ` Drew Adams 2018-03-27 8:07 ` Hong Xu 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2018-03-27 4:15 UTC (permalink / raw) To: Hong Xu, 30958 > 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.) ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' 2018-03-27 4:15 ` Drew Adams @ 2018-03-27 8:07 ` Hong Xu 2018-03-27 9:35 ` Andreas Schwab 0 siblings, 1 reply; 9+ messages in thread From: Hong Xu @ 2018-03-27 8:07 UTC (permalink / raw) To: Drew Adams, 30958 [-- 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 --] ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' 2018-03-27 8:07 ` Hong Xu @ 2018-03-27 9:35 ` Andreas Schwab 2018-03-27 14:27 ` Drew Adams 0 siblings, 1 reply; 9+ messages in thread From: Andreas Schwab @ 2018-03-27 9:35 UTC (permalink / raw) To: Hong Xu; +Cc: 30958 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." ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' 2018-03-27 9:35 ` Andreas Schwab @ 2018-03-27 14:27 ` Drew Adams 2018-03-27 17:39 ` Hong Xu 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2018-03-27 14:27 UTC (permalink / raw) To: Andreas Schwab, Hong Xu; +Cc: 30958 > > 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. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' 2018-03-27 14:27 ` Drew Adams @ 2018-03-27 17:39 ` Hong Xu 2021-10-23 18:03 ` Stefan Kangas 0 siblings, 1 reply; 9+ messages in thread From: Hong Xu @ 2018-03-27 17:39 UTC (permalink / raw) To: Drew Adams, Andreas Schwab; +Cc: 30958 [-- 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 --] ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' 2018-03-27 17:39 ` Hong Xu @ 2021-10-23 18:03 ` Stefan Kangas 2021-10-23 19:03 ` bug#30958: [External] : " Drew Adams 0 siblings, 1 reply; 9+ messages in thread From: Stefan Kangas @ 2021-10-23 18:03 UTC (permalink / raw) To: Hong Xu; +Cc: Andreas Schwab, 30958 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? ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#30958: [External] : Re: bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' 2021-10-23 18:03 ` Stefan Kangas @ 2021-10-23 19:03 ` Drew Adams 2021-10-24 6:26 ` Stefan Kangas 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2021-10-23 19:03 UTC (permalink / raw) To: Stefan Kangas, Hong Xu; +Cc: Andreas Schwab, 30958@debbugs.gnu.org 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. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#30958: [External] : Re: bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' 2021-10-23 19:03 ` bug#30958: [External] : " Drew Adams @ 2021-10-24 6:26 ` Stefan Kangas 0 siblings, 0 replies; 9+ messages in thread From: Stefan Kangas @ 2021-10-24 6:26 UTC (permalink / raw) To: Drew Adams, Hong Xu; +Cc: Andreas Schwab, 30958 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. ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2021-10-24 6:26 UTC | newest] Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2018-03-25 21:44 bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' Hong Xu 2018-03-27 4:15 ` Drew Adams 2018-03-27 8:07 ` Hong Xu 2018-03-27 9:35 ` Andreas Schwab 2018-03-27 14:27 ` Drew Adams 2018-03-27 17:39 ` Hong Xu 2021-10-23 18:03 ` Stefan Kangas 2021-10-23 19:03 ` bug#30958: [External] : " Drew Adams 2021-10-24 6:26 ` Stefan Kangas
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).