Functionality of overriding-local-map

[xenodasein]

At first I thought I made a mistake and asked about this on help list.

https://lists.gnu.org/archive/html/help-gnu-emacs/2022-01/msg00014.html
https://lists.gnu.org/archive/html/help-gnu-emacs/2022-01/msg00018.html
https://lists.gnu.org/archive/html/help-gnu-emacs/2022-01/msg00019.html
https://lists.gnu.org/archive/html/help-gnu-emacs/2022-01/msg00022.html

What happened was I had the wrong assumption on how keymaps work,
caused by dated documentation.

According to "(elisp) Searching Keymaps":

(or (if overriding-terminal-local-map
             (FIND-IN overriding-terminal-local-map))
    (if overriding-local-map
             (FIND-IN overriding-local-map)
           (or (FIND-IN (get-char-property (point) 'keymap))
               (FIND-IN-ANY emulation-mode-map-alists)
               (FIND-IN-ANY minor-mode-overriding-map-alist)
               (FIND-IN-ANY minor-mode-map-alist)
               (if (get-text-property (point) 'local-map)
                   (FIND-IN (get-char-property (point) 'local-map))
                 (FIND-IN (current-local-map)))))
    (FIND-IN (current-global-map)))

When both overriding-terminal-local-map and overriding-local-map
are active, key lookup should be done in these three maps:
o-t-l-m   ->   o-l-m   ->   global-map

But this is wrong, the correct behavior is what
"(elisp) Controlling Active Maps" explains, by contradicting the former:

-- Variable: overriding-terminal-local-map
     If non-‘nil’, this variable holds a keymap to use instead of
     ‘overriding-local-map’, the buffer’s local keymap, text property or
     overlay keymaps, and all the minor mode keymaps.

If o-t-l-m is active, o-l-m is out of the equation.

Stefan M:
> The code says:
>
>  if (!NILP (olp)
>      /* The doc said that overriding-terminal-local-map should
>         override overriding-local-map.  The code used them both,
>         but it seems clearer to use just one.  rms, jan 2005.  */
>      && NILP (KVAR (current_kboard, Voverriding_terminal_local_map))
>      && !NILP (Voverriding_local_map))
>    keymaps = Fcons (Voverriding_local_map, keymaps);
>
> It seems the doc isn't clear cut and there's not much more info to
> accompany this commit d64cdc59724b7caca47913d5beb2b4a54f7b7c91.
> I you want to change this behavior (or fix/improve the doc)
> I recommend you `M-x report-emacs-bug`.

I encountered this while using o-l-m as a buffer local map that
overrides other buffer local maps, as it is intended.  o-t-l-m
does not do this; the latter (current) behavior results in a
loss of functionality.

In my case, it prevented the use of universal-argument with commands
in overriding-local-map.  As universal-argument uses set-transient-map,
if next command isn't bound in universal-argument-map, it is looked up
in next active keymap (current-global-map).  IMO, what should happen is
that the next active keymap be overriding-local-map, as per
"(elisp) Searching Keymaps."