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

[Hong Xu <hong@topbug.net>]

[-- 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 --]