Subject: bug#60426: 29.0.60; Binding to outline-minor-mode-cycle-map correctly is unintuitive and hard

From: Juri Linkov <[email-masked]>
Date: Thu, 05 Jan 2023 19:45:37 +0200

>   Looking around I found that it was because the implementation had
>   changed, it no longer used `outline-minor-mode-cycle-map` as
>   the value of keymap text property on headings but rather used an
>   extended menu item. After looking through the source I finally
>   figured that the way to achieve what I wanted was to bind
>
>   `(menu-item "" outline-cycle :filter ,(lambda (cmd) (when (outline-on-heading-p) cmd)))`
>
>   to `<tab>`.
>
>   I think this is very confusing and is going to lead to some head
>   scratching for people who might have other keys bound on
>   `outline-minor-mode-cycle-map` since that map is now the parent
>   of `outline-minor-mode-map`. I think with the current approach it
>   will be better to entirely remove `outline-minor-mode-cycle-map`
>   and bind the extended menu items directly on `outline-minor-mode-map`
>   (the bindings are actually already on the `outline-minor-mode-map`).
>   Another way can be to not make `outline-minor-mode-cycle-map` make
>   a parent of `outline-minor-mode-map`, obsolete it and add to its
>   docstring a description of how to achieve the same effect using
>   extended menu items.

We expected this change to be backwards-compatible assuming
that users would define keys in outline-minor-mode-cycle-map
using the same helper as is seen in the default definition:

  (outline-minor-mode-cycle--bind map (kbd "TAB") #'outline-cycle)

Maybe this requirement should be documented in the docstring
and mentioned in NEWS?