Subject: 31.0.50; minor-mode-overriding-map-alist doesn't have higher priority than local map, which differs from docs

From: [email-masked]
Date: Wed, 14 Aug 2024 17:45:03 +0200 (CEST)

NOTE: please view
https://codeberg.org/meow_king/typst-ts-mode/issues/6#issuecomment-2174390
for rendered markdown view.

According to docs `(elisp) Active Keymaps` :

> Emacs contains many keymaps, but at any time only a few keymaps are
“active”.  When Emacs receives user input, it translates the input event
(*note Translation Keymaps::), and looks for a key binding in the active
keymaps.
>
>   Usually, the active keymaps are: (i) the keymap specified by the
‘keymap’ property, (ii) the keymaps of enabled minor modes, (iii) the
current buffer's local keymap, and (iv) the global keymap, in that
order.  Emacs searches for each input key sequence in all these keymaps.
>
>   Of these usual keymaps, the highest-precedence one is specified by
the ‘keymap’ text or overlay property at point, if any.  (For a mouse
input event, Emacs uses the event position instead of point; *note
Searching Keymaps::.)
>
>   Next in precedence are keymaps specified by enabled minor modes.
These keymaps, if any, are specified by the variables
‘emulation-mode-map-alists’, ‘minor-mode-overriding-map-alist’, and
‘minor-mode-map-alist’.  *Note Controlling Active Maps::.
>
>   Next in precedence is the buffer's “local keymap”, containing key
bindings specific to the buffer.  The minibuffer also has a local keymap
(*note Intro to Minibuffers::).  If there is a ‘local-map’ text or
overlay property at point, that specifies the local keymap to use, in
place of the buffer's default local keymap.

‘minor-mode-overriding-map-alist` should have higher priority than the buffer local keymap.
However, the actual behavior is different than what the docs say.

Here is my test:

```elisp
;;;###autoload
(defvar-keymap typst-ts-mode-map
;; ..
"RET" #'typst-ts-mode-return)

(defvar-keymap mk/test-map
"RET" #'(lambda () (interactive) (message "mk/test-map")))

;;;###autoload
(define-derived-mode typst-ts-mode text-mode "Typst"
"Major mode for editing Typst, powered by tree-sitter."
:group 'typst
:syntax-table typst-ts-mode-syntax-table
:after-hook
(typst-ts-mode-after-hook-function)

(setq minor-mode-overriding-map-alist '((outline-minor-mode . nil)))
(setcdr (assq #'outline-minor-mode minor-mode-overriding-map-alist) mk/test-map)

;; ...
)
```
In this situation, `typst-ts-mode-return` will be executed. 

If we execute this elisp code and then re-enter `typst-ts-mode`
```elisp 
(keymap-set outline-minor-mode-map "<return>" #'(lambda () (interactive) (message "outline-minor-mode-map")))
```
it will still execute `typst-ts-mode-return` function.

However, in addition of the previous code, if we then remove the following code in `typst-ts-mode` setup process:
```elisp
(setq minor-mode-overriding-map-alist '((outline-minor-mode . nil)))
(setcdr (assq #'outline-minor-mode minor-mode-overriding-map-alist) mk/test-map)
```
then the lambda function in `outline-minor-mode-map` will be executed. 

--- 

In GNU Emacs 31.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
3.24.43, cairo version 1.18.0)
Repository revision: 643b564bd38cf037c55dba1a160b7d0c4c8355a9
Repository branch: master
System Description: NixOS 24.11 (Vicuna)

Configured using:
'configure
--prefix=/nix/store/dj6bh0vp6gzqdmb3ilri3aw5kcq62myf-emacs-pgtk-20240811.0
--disable-build-details --with-modules --with-pgtk
--with-compress-install --with-toolkit-scroll-bars
--with-native-compilation --without-imagemagick --with-mailutils
--without-small-ja-dic --with-tree-sitter --without-xinput2
--with-xwidgets --with-dbus --with-selinux'