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

[Drew Adams]

> 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?

Eli has pointed out elsewhere that "character property" properly belongs
to the sense of node "Character Properties", so that it should not be
used also to refer to both text properties and overlay properties.

IOW, `get-char-property' is misnamed.  Its name should not be taken as
a guide to documenting text & overlay properties as "character"
properties.

I too was confused about this, and had suggested updating some doc
to use "character property" to refer to both text & overlay properties.
In fact, I used it that way in my own code (doc and function names).
Based on Eli's explanation, I corrected my code in this regard.

It might even be good to rename `get-char-property' (keeping the
original name for backward compatibility, of course).