From: Stefan Kangas <stefan@marxist.se>
To: Hong Xu <hong@topbug.net>
Cc: Andreas Schwab <schwab@suse.de>, 30958@debbugs.gnu.org
Subject: bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap'
Date: Sat, 23 Oct 2021 11:03:26 -0700 [thread overview]
Message-ID: <CADwFkmmimrTk8=GsgmCo0+8gFYUSovUhOsHg9PpWdXWWGwV8Jg@mail.gmail.com> (raw)
In-Reply-To: <b6b4c767-ead0-ad06-901b-f1b154865950@topbug.net> (Hong Xu's message of "Tue, 27 Mar 2018 10:39:09 -0700")
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?
next prev parent reply other threads:[~2021-10-23 18:03 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
2021-10-23 19:03 ` bug#30958: [External] : " Drew Adams
2021-10-24 6:26 ` Stefan Kangas
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CADwFkmmimrTk8=GsgmCo0+8gFYUSovUhOsHg9PpWdXWWGwV8Jg@mail.gmail.com' \
--to=stefan@marxist.se \
--cc=30958@debbugs.gnu.org \
--cc=hong@topbug.net \
--cc=schwab@suse.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.