Documentation for overriding-terminal-local-map is confusing?

Documentation for overriding-terminal-local-map is confusing?

[Jan Synacek]

Hello,

I currently have this piece of elisp in my init.el:
...
(setf jsynacek-terminal-map (make-sparse-keymap))
(setf overriding-terminal-local-map jsynacek-terminal-map)
(define-key jsynacek-terminal-map (kbd "C-b") 'ido-switch-buffer)
(define-key jsynacek-terminal-map (kbd "C-o") 'find-file)
...

It works until I use isearch-forward, which resets
overriding-terminal-local-map. It took me a while to figure out, until I
noticed this in "22.9 Controlling the Active Keymaps" in the ELisp
manual:

"This variable is always local to the current terminal and cannot be
buffer-local.  *Note Multiple Terminals::.  It is used to implement
incremental search mode."

That basically means that the keymap is pretty much useless for
overriding anything, doesn't it? Because it always gets reset whenever
the user starts searching for something. Also, the rest of the manual
that mentions overriding-terminal-local-map kind of suggests that it's
supposed to be used exactly how I wanted to use it - to make one's own
global keybindings that work no matter what the current modes are.

So my questions are:

1) Is this actually a "bug" in the manual? That is, shouldn't the manual
be changed to be clearer? If yes, I can file a bug report.

2) What is the proper way to make my own keymap that overrides
everything? I know that the 'use-package/bind-key' package does this by
creating a minor mode and then using emulation-mode-map-alists, but the
variable's documentation doesn't even remotely suggest to use it that
way.

Regards,
Jan

Re: Documentation for overriding-terminal-local-map is confusing?

[Stefan Monnier]

> I currently have this piece of elisp in my init.el:
> ...
> (setf jsynacek-terminal-map (make-sparse-keymap))
> (setf overriding-terminal-local-map jsynacek-terminal-map)
> (define-key jsynacek-terminal-map (kbd "C-b") 'ido-switch-buffer)
> (define-key jsynacek-terminal-map (kbd "C-o") 'find-file)
> ...
>
> It works until I use isearch-forward, which resets
> overriding-terminal-local-map.  It took me a while to figure out,
> until I noticed this in "22.9 Controlling the Active Keymaps" in the
> ELisp manual:

I guess you're victim of the fact that the ELisp manual is not written
for people editing their init.el but for people writing Elisp packages.

> 2) What is the proper way to make my own keymap that overrides
> everything? I know that the 'use-package/bind-key' package does this by
> creating a minor mode and then using emulation-mode-map-alists, but the
> variable's documentation doesn't even remotely suggest to use it that
> way.

emulation-mode-map-alists is meant for that, yes.
(think of it as emulating the UI of an editor that binds C-b to
switch-buffer, ...)


        Stefan

Re: Documentation for overriding-terminal-local-map is confusing?

[Jan Synacek]

On Mon, May 25, 2020 at 4:08 PM Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>
> > I currently have this piece of elisp in my init.el:
> > ...
> > (setf jsynacek-terminal-map (make-sparse-keymap))
> > (setf overriding-terminal-local-map jsynacek-terminal-map)
> > (define-key jsynacek-terminal-map (kbd "C-b") 'ido-switch-buffer)
> > (define-key jsynacek-terminal-map (kbd "C-o") 'find-file)
> > ...
> >
> > It works until I use isearch-forward, which resets
> > overriding-terminal-local-map.  It took me a while to figure out,
> > until I noticed this in "22.9 Controlling the Active Keymaps" in the
> > ELisp manual:
>
> I guess you're victim of the fact that the ELisp manual is not written
> for people editing their init.el but for people writing Elisp packages.

Yes, that's what also came to my mind. And that's actually fine.
But, I still think that the manual could be improved in this regard a bit.

> > 2) What is the proper way to make my own keymap that overrides
> > everything? I know that the 'use-package/bind-key' package does this by
> > creating a minor mode and then using emulation-mode-map-alists, but the
> > variable's documentation doesn't even remotely suggest to use it that
> > way.
>
> emulation-mode-map-alists is meant for that, yes.
> (think of it as emulating the UI of an editor that binds C-b to
> switch-buffer, ...)

I see.

Thank you,
-- 
Jan Synacek
Software Engineer, Red Hat