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

[Rah Guzar]

Juri Linkov <juri@linkov.net> writes:

> 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?

I think this is a good idea since people who have already keys bound
on outline-minor-mode-cycle-map are likely to be as surprised as I was.

But I also think that it is more important to mention this in the
docstring for outline-minor-mode-cycle-map. Since its current
docstring "Keymap used by outline-minor-mode-cycle." is misleading in
my opinion, especially since any key there is going to be active
if outline-minor-mode is on, regardless of the value of
`outline-minor-mode-cycle`.

Also I was confused by the two hyphens in the name
outline-minor-mode-cycle--bind and thought that it was a private
function even though in retrospect they are in the wrong place
for it to be private. By the way I also think that the MAP
argument outline-minor-mode-cycle--bind of should be optional.

Thanks!