set-temporary-overlay-map seems poorly named

set-temporary-overlay-map seems poorly named

[Chong Yidong]

This function, new in Emacs 24.4, seems to have nothing to do with
overlays in the usual Emacs sense.  So it's a bad name.

How about renaming it to `set-transient-keymap'?

Re: set-temporary-overlay-map seems poorly named

[Jambunathan K]

Chong Yidong <cyd@gnu.org> writes:

> This function, new in Emacs 24.4, seems to have nothing to do with
> overlays in the usual Emacs sense.  So it's a bad name.
>
> How about renaming it to `set-transient-keymap'?

How about `set-temporary-keymap'?

Emacs users/programmers have differing level of proficiency in English.
The word "temporary" will be more easy on international users.

Re: set-temporary-overlay-map seems poorly named

[Eli Zaretskii]

> From: Chong Yidong <cyd@gnu.org>
> Date: Sat, 21 Dec 2013 13:45:53 +0800
> 
> This function, new in Emacs 24.4, seems to have nothing to do with
> overlays in the usual Emacs sense.  So it's a bad name.
> 
> How about renaming it to `set-transient-keymap'?

'set-temporary-overriding-map', perhaps?

Re: set-temporary-overlay-map seems poorly named

[Chong Yidong]

Eli Zaretskii <eliz@gnu.org> writes:

>> This function, new in Emacs 24.4, seems to have nothing to do with
>> overlays in the usual Emacs sense.  So it's a bad name.
>> 
>> How about renaming it to `set-transient-keymap'?
>
> 'set-temporary-overriding-map', perhaps?

This might be confusing, since overriding-local-map takes precedence
over the temporary map.

The reason I think "transient" is a good term to use is that we already
use that word in Emacs in `transient-mode-map' to mean the same sort of
behavior: a mode of operation which features disappears after doing
something, returning you to the previous behavior.  (We also use the
word "electric" similarly, but that is a lot more cryptic.)

Re: set-temporary-overlay-map seems poorly named

[Bozhidar Batsov]

[-- Attachment #1: Type: text/plain, Size: 822 bytes --]

+1 for "transient".


On 22 December 2013 02:36, Chong Yidong <cyd@gnu.org> wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> This function, new in Emacs 24.4, seems to have nothing to do with
> >> overlays in the usual Emacs sense.  So it's a bad name.
> >>
> >> How about renaming it to `set-transient-keymap'?
> >
> > 'set-temporary-overriding-map', perhaps?
>
> This might be confusing, since overriding-local-map takes precedence
> over the temporary map.
>
> The reason I think "transient" is a good term to use is that we already
> use that word in Emacs in `transient-mode-map' to mean the same sort of
> behavior: a mode of operation which features disappears after doing
> something, returning you to the previous behavior.  (We also use the
> word "electric" similarly, but that is a lot more cryptic.)
>
>

[-- Attachment #2: Type: text/html, Size: 1313 bytes --]

Re: set-temporary-overlay-map seems poorly named

[Stefan Monnier]

>>> This function, new in Emacs 24.4, seems to have nothing to do with
>>> overlays in the usual Emacs sense.  So it's a bad name.
>>> How about renaming it to `set-transient-keymap'?
>> 'set-temporary-overriding-map', perhaps?

FWIW, I don't have any preference in this respect, so feel free to
change it after you agree on it.

> This might be confusing, since overriding-local-map takes precedence
> over the temporary map.

AFAIK it doesn't.


        Stefan

Re: set-temporary-overlay-map seems poorly named

[Chong Yidong]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>> This might be confusing, since overriding-local-map takes precedence
>> over the temporary map.
>
> AFAIK it doesn't.

The docstring says:

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

Re: set-temporary-overlay-map seems poorly named

[Jambunathan K]

Jambunathan K <kjambunathan@gmail.com> writes:

> Chong Yidong <cyd@gnu.org> writes:
>
>> This function, new in Emacs 24.4, seems to have nothing to do with
>> overlays in the usual Emacs sense.  So it's a bad name.
>>
>> How about renaming it to `set-transient-keymap'?
>
> How about `set-temporary-keymap'?

The following node already uses TEMP-MAP to designate this.

,---- (info "(elisp) Searching Keymaps")
|
| TEMP-MAP is a pseudo variable that represents the effect of a
| `set-temporary-overlay-map' call.
|
`----

----------------------------------------------------------------


,----  C-h f set-temporary-overlay-map
|
| Normally, MAP is used only once.  If the optional argument
| KEEP-PRED is t, MAP stays active if a key from MAP is used.
| KEEP-PRED can also be a function of no arguments: if it returns
| non-nil then MAP stays active.
|
`----

In essence the map is "self-destructive".  The installer ALSO tells when
the transient map goes belly up.

I believe the notion of "self-destructive" is semantically more richer
than "transient" or "temporary".

----------------------------------------------------------------

Looking at instances where `set-temporary-keymap' is used, it seems it
helps to "extend" a command to an arbitrary length.

   C-x {z}+
   C-x TAB {left or right}+
   C-x C-+ {+ or - or 0}+

It is looks as if a "common prefix" is factored out of a key sequence.
So a key sequence like

   AB AC AD

becomes "reduced" to

  A B C D

i.e., A is "factored out".

So overlay-map in effects helps to create "command local" maps or to
create "sub-commands".

----------------------------------------------------------------

Re: set-temporary-overlay-map seems poorly named

[Jambunathan K]

Jambunathan K <kjambunathan@gmail.com> writes:

> Looking at instances where `set-temporary-keymap' is used

As an additional qualifier to my earlier comment what I am saying is
this:

The name of the API, INSTEAD of trying to capture where in the keymap
heirarchy it fits in, can try to capture how a user will RELATE to it
(or put it into a practice).  May be user-specific-approach will give a
more sensible name for the function.

Re: set-temporary-overlay-map seems poorly named

[Stefan Monnier]

>>> This might be confusing, since overriding-local-map takes precedence
>>> over the temporary map.
>> AFAIK it doesn't.
> The docstring says:
> Note that this does NOT take precedence over the "overriding" maps
> `overriding-terminal-local-map' and `overriding-local-map' (or the
> `keymap' text property).  Unlike those maps, if no match for a key is
> found in MAP, the normal key lookup sequence then continues.

Thanks, I forgot to update the docstring when I fixed this problem.


        Stefan