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

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

[Phil Sainty]

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?

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).

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

[Phil Sainty]

On 2/01/2014 04:54, Drew Adams wrote:
> It might even be good to rename `get-char-property' (keeping the
> original name for backward compatibility, of course).

I certainly think it would be an improvement to rename *something*
here. I'm not sure what to suggest, but inconsistent naming is
generally a bad thing, and this example is definitely confusing.

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

[Lars Ingebrigtsen]

Phil Sainty <psainty@orcon.net.nz> writes:

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

It seems like this was fixed in:

commit ec00f20f553cdd37c1261a5a228ec762fc9b5497
Author:     Stefan Monnier <monnier@iro.umontreal.ca>
AuthorDate: Mon Jan 6 14:29:39 2014 -0500

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

Yup.  I've now clarified this in the doc string in Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no