Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

From: Sean Whitton <[email-masked]>
Date: Wed, 09 Jul 2025 11:40:07 +0100

Hello,

On Tue 08 Jul 2025 at 02:08pm -04, Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" wrote:

>> The reason for this is, I think, simple: C-h m describes the major
>> mode's own map, diff-mode-map, but the TAB binding does not appear in
>> that map.  It's only in diff-mode-shared-map, the parent of
>> diff-mode-map.
>
> `diff-mode-shared-map` is not a parent of `diff-mode-map`.
> It's a parent of the ESC submap of `diff-mode-map`, and its bindings
> appear just fine, e.g.:
>
>     C-M-i		diff-hunk-next
>
> `C-M-i` is another name for `M-TAB`.
>
>> We probably don't want C-h m to include bindings from the parents of
>> major mode maps.
>
> We do, and AFAIK, it does.
>
>> But there is something about diff-mode-shared-map that I can't figure
>> out.  How do its bindings get overridden/deactivated in the case that
>> the buffer is not read-only?
>
> `diff-mode-shared-map` is used as a minor-mode map, (de)activated
> according to ``diff-mode-read-only`:
>
>     (or (assq 'diff-mode-read-only minor-mode-map-alist)
>         (nconc minor-mode-map-alist
>                (list (cons 'diff-mode-read-only
>                            (make-composed-keymap diff-mode-shared-map
>                                                  special-mode-map)))))

Thanks.  I had missed

- that diff-mode-shared-map is the parent of diff-minor-mode-map, not
  diff-mode-map, d'oh
- that diff-minor-mode is the mechanism by which the keys are made
  available when the buffer is read only.

What do you think about replacing activating a minor mode with just
switching the major mode map?  So far as I can tell the disadvantage
would be repeating keymap definitions, and the advantage would be more
standardised *Help* output.

-- 
Sean Whitton