Subject: 24.3.50; Docstring fix for `set-transient-map' (and tangents...)

From: Phil Sainty <[email-masked]>
Date: Wed, 01 Jan 2014 16:09:46 +1300

The docstring for `set-transient-map' states:

> Note that MAP will take precedence over the \"overriding\" maps
> `overriding-terminal-local-map' and `overriding-local-map' (and
> over the `keymap' text property).  Unlike those maps, if no match
> for a key is found in MAP, Emacs continues the normal key lookup
> sequence.

The NEWS file suggests that this info is now incorrect for the
former of those two:

> * Incompatible Lisp Changes in Emacs 24.4
>
> ** `overriding-terminal-local-map' no longer replaces the local keymaps.
> It used to disable the minor mode, major mode, and text-property keymaps,
> whereas now it simply has higher precedence.

So perhaps that docstring paragraph should now simply read:

"Note that MAP will take precedence over the \"overriding\" maps
`overriding-terminal-local-map' and `overriding-local-map' (and
over the `keymap' text property).  If no match for a key is found
in MAP, Emacs continues the normal key lookup sequence."

I also see the phrase "the keymap char property" in the docstring for
`overriding-local-map'. Should that read "the keymap text property"? Or
is this because there's a keymap Overlay property as well, and the
`get-char-property' function checks them both? (This seems likely, but
might imply that the reference to "the `keymap' text property" in
set-transient-map is insufficient, iff that also needs to cover overlay
properties?)

I'm afraid I'm not very familiar with text properties and overlays, so
I'm not sure which is the preferred term here. I would imagine that
this issue (with two types of 'keymap' properties) might crop up in
a number of places, so perhaps there's already an agreed way of
describing it for documentation purposes?

I suspect this would be less confusing were it not for the info node
"(elisp) Character Properties" which is unconnected to `get-char-property'
(instead we have `get-char-code-property' to obtain these "Character
Properties". It seems to me that this is mostly an unfortunate naming
clash with a standard Unicode term, but as such the info nodes could
probably benefit from some up-front clarifications to make the distinction
between the two types of "char property" and associated function naming
schemes clear from the outset?

Perhaps the "Character Properties" node should even be renamed to
"Character Code Properties" to better align with the function names?
This concept in Emacs sounds as if it's a super-set of the Unicode
Character Property Model, so it possibly doesn't *need* to have that
exact name?