GNU bug report logs - #34080
27.0.50, 26.1; undocumented key bindings for *vc-diff*

Previous Next

To reply to this bug, email your comments to 34080 AT debbugs.gnu.org.
There is no need to reopen the bug first.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Tue, 15 Jan 2019 16:29:56 +1100

Hello,

The *Help* buffer for diff-mode.el is better 
if the following key bindings are documented 

#+NAME: undocumented-key-bindings
| key   | binding        |
|-------+----------------|
| TAB   | diff-hunk-next |
| S-TAB | diff-hunk-prev |

the above make more sense than the following

#+NAME: existing-key-bindings-documented
| key   | binding        |
|-------+----------------|
| C-M-i | diff-hunk-next |
| M-n   |                |
|-------+----------------|
| M-p   | diff-hunk-prev |

And, for the word "hunk" to link to a Glossary's 
entry like for example

http://www-history.mcs.st-and.ac.uk/Glossary/oblong_number.html

is a feature to have unless it is already therein.

Message #8 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Van L <van <at> scratch.space>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Sat, 19 Jan 2019 23:24:03 +0200

> The *Help* buffer for diff-mode.el is better
> if the following key bindings are documented
>
> #+NAME: undocumented-key-bindings
> | key   | binding        |
>
> |-------+----------------|
> | TAB   | diff-hunk-next |
> | S-TAB | diff-hunk-prev |
>
> the above make more sense than the following
>
> #+NAME: existing-key-bindings-documented
> | key   | binding        |
>
> |-------+----------------|
> | C-M-i | diff-hunk-next |
> | M-n   |                |
> |-------+----------------|
> | M-p   | diff-hunk-prev |

It seems what you want is:

(put 'diff-hunk-next :advertised-binding [tab])
(put 'diff-hunk-prev :advertised-binding [(shift tab)])

> And, for the word "hunk" to link to a Glossary's
> entry like for example
>
> http://www-history.mcs.st-and.ac.uk/Glossary/oblong_number.html
>
> is a feature to have unless it is already therein.

Better to link to the Info manual (info "(diffutils) Hunks")

Message #11 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: Juri Linkov <juri <at> linkov.net>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Mon, 21 Jan 2019 00:25:21 +1100

> Juri Linkov wrote:
> 
>> And, for the word "hunk" to link to a Glossary's
>> entry like for example
>> 
>> http://www-history.mcs.st-and.ac.uk/Glossary/oblong_number.html
>> 
>> is a feature to have unless it is already therein.
> 
> Better to link to the Info manual (info "(diffutils) Hunks”)

The Emacs’s Concept Index leads to (info “(emacs) Diff Mode”) paragraph two, where hunk is explained.

I was hoping for a Glossary at the same level as Concept Index in the Info navigation. 

It would collect single paragraph explanations for easy finding, perhaps, the top-100 most frequently used jargonwords.

My plain Emacs and Slime installation doesn’t have diffutils in Info docs, but *vc-diff* works.

Message #14 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: Juri Linkov <juri <at> linkov.net>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Mon, 21 Jan 2019 09:28:05 +1100

[Message part 1 (text/plain, inline)]

> (put 'diff-hunk-next :advertised-binding [tab])
> (put 'diff-hunk-prev :advertised-binding [(shift tab)])

The above, I've put in a patch for emacs-mac port, see below.

The development master as of now has

— quote

(easy-mmode-defmap diff-mode-shared-map
  '(("n" . diff-hunk-next)
    ("N" . diff-file-next)
    ("p" . diff-hunk-prev)
    ("P" . diff-file-prev)
    ("\t" . diff-hunk-next)
    ([backtab] . diff-hunk-prev)

— quote ends

[0005-List-key-bindings-for-describe-mode.patch (application/octet-stream, attachment)]

Message #17 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Van L <van <at> scratch.space>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Mon, 21 Jan 2019 22:35:06 +0200

>> (put 'diff-hunk-next :advertised-binding [tab])
>> (put 'diff-hunk-prev :advertised-binding [(shift tab)])
>
> The above, I've put in a patch for emacs-mac port, see below.

Please attach the output after this change.  I would be interesting
to see how it is formatted on emacs-mac port.

Message #20 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Van L <van <at> scratch.space>
To: Juri Linkov <juri <at> linkov.net>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Tue, 22 Jan 2019 13:59:36 +1100

>>> (put 'diff-hunk-next :advertised-binding [tab])
>>> (put 'diff-hunk-prev :advertised-binding [(shift tab)])
>> 
>> The above, I've put in a patch for emacs-mac port, see below.
> 
> Please attach the output after this change.  I would be interesting
> to see how it is formatted on emacs-mac port.

— quote

Compiling /Applications/MacPorts/EmacsMac.app/Contents/Resources/lisp/vc/diff-mode.el.gz...done
Wrote /Applications/MacPorts/EmacsMac.app/Contents/Resources/lisp/vc/diff-mode.elc

— quote ends

The change has had no desired effect.

: ESC <backtab>	diff-hunk-prev

There is that, from describe-mode by searching for 'tab.

Message #23 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Van L <van <at> scratch.space>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Sun, 13 Oct 2019 01:02:17 +0200

Van L <van <at> scratch.space> writes:

> The *Help* buffer for diff-mode.el is better 
> if the following key bindings are documented 
>
> #+NAME: undocumented-key-bindings
> | key   | binding        |
>
> |-------+----------------|
> | TAB   | diff-hunk-next |
> | S-TAB | diff-hunk-prev |

There are several modes defined in diff-mode.el.

Do you mean `diff-mode' itself?  TAB is not bound in `diff-mode', as far
as I can tell.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #26 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Van L <van <at> scratch.space>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Sun, 13 Oct 2019 01:05:34 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Van L <van <at> scratch.space> writes:
>
>> The *Help* buffer for diff-mode.el is better 
>> if the following key bindings are documented 
>>
>> #+NAME: undocumented-key-bindings
>> | key   | binding        |
>>
>> |-------+----------------|
>> | TAB   | diff-hunk-next |
>> | S-TAB | diff-hunk-prev |
>
> There are several modes defined in diff-mode.el.
>
> Do you mean `diff-mode' itself?  TAB is not bound in `diff-mode', as far
> as I can tell.

It wasn't bound if I said `M-x diff-mode', but it is bound in *vc-diff*
buffers...

And if I `C-h b' in that buffer, I get

key             binding
---             -------

TAB		diff-hunk-next
[...]
<backtab>	diff-hunk-prev

But it's right that they are not listed in `C-h m'.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #29 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Van L <van <at> scratch.space>
Cc: 34080 <at> debbugs.gnu.org, Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Fri, 25 Sep 2020 14:21:51 +0200

Van L <van <at> scratch.space> writes:

> +;; List key bindings for describe-mode
> +(put 'diff-hunk-next :advertised-binding [tab])
> +(put 'diff-hunk-prev :advertised-binding [(shift tab)])
> +

I tried this patch, but `M-x describe-mode' in a *vc-diff* buffer did
not seem to care that much -- it listed diff-hunk-prev on M-p and ESC
<backtab> and -next on C-M-i/M-n only, with or without this patch.

Is :advertised-binding not working here, or is ... er ... something else
wrong?  The actual bindings are:

    ("\t" . diff-hunk-next)
    ([backtab] . diff-hunk-prev)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #32 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Van L <van <at> scratch.space>,  34080 <at> debbugs.gnu.org,  Juri Linkov
 <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Thu, 15 May 2025 16:46:57 +0100

Hello,

On Fri 25 Sep 2020 at 02:21pm +02, Lars Ingebrigtsen wrote:

> Van L <van <at> scratch.space> writes:
>
>> +;; List key bindings for describe-mode
>> +(put 'diff-hunk-next :advertised-binding [tab])
>> +(put 'diff-hunk-prev :advertised-binding [(shift tab)])
>> +
>
> I tried this patch, but `M-x describe-mode' in a *vc-diff* buffer did
> not seem to care that much -- it listed diff-hunk-prev on M-p and ESC
> <backtab> and -next on C-M-i/M-n only, with or without this patch.
>
> Is :advertised-binding not working here, or is ... er ... something else
> wrong?  The actual bindings are:
>
>     ("\t" . diff-hunk-next)
>     ([backtab] . diff-hunk-prev)

Searching the code base, :advertised-binding is meant to affect
where-is-internal, and only that function, I think.
But it does seem to be broken:

    (progn (put 'diff-hunk-next :advertised-binding "n") ; or '("n")
           (with-current-buffer "*vc-diff*"
             (mapcar #'key-description
                     (where-is-internal 'diff-hunk-next))))

    => ("TAB" "n" "C-M-i" "M-n" "<menu-bar> <diff> <Next Hunk>")

i.e. there is no prioritisation for the "n" binding.
Indeed, TAB comes first.

Then it seems like a separate issue why the "TAB" binding is not
appearing in 'M-x describe-mode'.  So there are two problems here.

-- 
Sean Whitton

Message #35 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Thu, 15 May 2025 19:54:25 +0300

>>> +;; List key bindings for describe-mode
>>> +(put 'diff-hunk-next :advertised-binding [tab])
>>> +(put 'diff-hunk-prev :advertised-binding [(shift tab)])
>>> +
>>
>> I tried this patch, but `M-x describe-mode' in a *vc-diff* buffer did
>> not seem to care that much -- it listed diff-hunk-prev on M-p and ESC
>> <backtab> and -next on C-M-i/M-n only, with or without this patch.
>>
>> Is :advertised-binding not working here, or is ... er ... something else
>> wrong?  The actual bindings are:
>>
>>     ("\t" . diff-hunk-next)
>>     ([backtab] . diff-hunk-prev)
>
> Searching the code base, :advertised-binding is meant to affect
> where-is-internal, and only that function, I think.
> But it does seem to be broken:
>
>     (progn (put 'diff-hunk-next :advertised-binding "n") ; or '("n")
>            (with-current-buffer "*vc-diff*"
>              (mapcar #'key-description
>                      (where-is-internal 'diff-hunk-next))))
>
>     => ("TAB" "n" "C-M-i" "M-n" "<menu-bar> <diff> <Next Hunk>")
>
> i.e. there is no prioritisation for the "n" binding.
> Indeed, TAB comes first.
>
> Then it seems like a separate issue why the "TAB" binding is not
> appearing in 'M-x describe-mode'.  So there are two problems here.

There is no 'n' binding in 'diff-mode-map'.  'n' inherited
from 'diff-mode-shared-map' becomes 'M-n' (via the ESC prefix).
And its advertised-binding works correctly:

  (put 'diff-hunk-next :advertised-binding "\M-n")
  (substitute-command-keys "Type `\\<diff-mode-map>\\[diff-hunk-next]'.")
  => #("Type ‘M-n’." 6 9 (font-lock-face help-key-binding face help-key-binding))

Message #38 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Juri Linkov <juri <at> linkov.net>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Sun, 18 May 2025 10:51:34 +0100

Hello,

On Thu 15 May 2025 at 07:54pm +03, Juri Linkov wrote:

>> Searching the code base, :advertised-binding is meant to affect
>> where-is-internal, and only that function, I think.
>> But it does seem to be broken:
>>
>>     (progn (put 'diff-hunk-next :advertised-binding "n") ; or '("n")
>>            (with-current-buffer "*vc-diff*"
>>              (mapcar #'key-description
>>                      (where-is-internal 'diff-hunk-next))))
>>
>>     => ("TAB" "n" "C-M-i" "M-n" "<menu-bar> <diff> <Next Hunk>")
>>
>> i.e. there is no prioritisation for the "n" binding.
>> Indeed, TAB comes first.
>>
>> Then it seems like a separate issue why the "TAB" binding is not
>> appearing in 'M-x describe-mode'.  So there are two problems here.
>
> There is no 'n' binding in 'diff-mode-map'.  'n' inherited
> from 'diff-mode-shared-map' becomes 'M-n' (via the ESC prefix).
> And its advertised-binding works correctly:
>
>   (put 'diff-hunk-next :advertised-binding "\M-n")
>   (substitute-command-keys "Type `\\<diff-mode-map>\\[diff-hunk-next]'.")
>   => #("Type ‘M-n’." 6 9 (font-lock-face help-key-binding face help-key-binding))

If you change "n" and "\M-n" in my example the return value of
where-is-internal does not change.  Therefore I think your example is
working accidentally and there is still a problem here.

-- 
Sean Whitton

Message #41 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Mon, 19 May 2025 09:30:20 +0300

>>> Searching the code base, :advertised-binding is meant to affect
>>> where-is-internal, and only that function, I think.
>>> But it does seem to be broken:
>>>
>>>     (progn (put 'diff-hunk-next :advertised-binding "n") ; or '("n")
>>>            (with-current-buffer "*vc-diff*"
>>>              (mapcar #'key-description
>>>                      (where-is-internal 'diff-hunk-next))))
>>>
>>>     => ("TAB" "n" "C-M-i" "M-n" "<menu-bar> <diff> <Next Hunk>")
>>>
>>> i.e. there is no prioritisation for the "n" binding.
>>> Indeed, TAB comes first.
>>>
>>> Then it seems like a separate issue why the "TAB" binding is not
>>> appearing in 'M-x describe-mode'.  So there are two problems here.
>>
>> There is no 'n' binding in 'diff-mode-map'.  'n' inherited
>> from 'diff-mode-shared-map' becomes 'M-n' (via the ESC prefix).
>> And its advertised-binding works correctly:
>>
>>   (put 'diff-hunk-next :advertised-binding "\M-n")
>>   (substitute-command-keys "Type `\\<diff-mode-map>\\[diff-hunk-next]'.")
>>   => #("Type ‘M-n’." 6 9 (font-lock-face help-key-binding face help-key-binding))
>
> If you change "n" and "\M-n" in my example the return value of
> where-is-internal does not change.  Therefore I think your example is
> working accidentally and there is still a problem here.

The Info node (info "(elisp) Standard Properties") says:

  ‘:advertised-binding’
       This property value specifies the preferred key binding, when
       showing documentation, for the named function.  *Note Keys in
       Documentation::.

Then the referred node (info "(elisp) Keys in Documentation")
mentions 'substitute-command-keys' that I used in my example.
OTOH, I can't find any reference to 'where-is-internal'.

Message #44 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Juri Linkov <juri <at> linkov.net>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Mon, 19 May 2025 09:30:11 +0100

Hello,

On Mon 19 May 2025 at 09:30am +03, Juri Linkov wrote:

> The Info node (info "(elisp) Standard Properties") says:
>
>   ‘:advertised-binding’
>        This property value specifies the preferred key binding, when
>        showing documentation, for the named function.  *Note Keys in
>        Documentation::.
>
> Then the referred node (info "(elisp) Keys in Documentation")
> mentions 'substitute-command-keys' that I used in my example.
> OTOH, I can't find any reference to 'where-is-internal'.

The only place in the code that makes reference to :advertised-binding
other than calls to `put' is in where-is-internal.  I.e.,
where-is-internal is where :advertised-binding is implemented.

Do a 'C-x p g' for QCadvertised_binding.

-- 
Sean Whitton

Message #47 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: 34080 <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Mon, 19 May 2025 20:41:49 +0300

>> The Info node (info "(elisp) Standard Properties") says:
>>
>>   ‘:advertised-binding’
>>        This property value specifies the preferred key binding, when
>>        showing documentation, for the named function.  *Note Keys in
>>        Documentation::.
>>
>> Then the referred node (info "(elisp) Keys in Documentation")
>> mentions 'substitute-command-keys' that I used in my example.
>> OTOH, I can't find any reference to 'where-is-internal'.
>
> The only place in the code that makes reference to :advertised-binding
> other than calls to `put' is in where-is-internal.  I.e.,
> where-is-internal is where :advertised-binding is implemented.
>
> Do a 'C-x p g' for QCadvertised_binding.

Indeed, I can't find more functions that use :advertised-binding.

Message #50 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Van L <van <at> scratch.space>,  34080 <at> debbugs.gnu.org,  Juri Linkov
 <juri <at> linkov.net>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Tue, 08 Jul 2025 18:17:09 +0100

Hello,

Putting aside the possible bug in where-is-internal, the basic issue in
this report is how the TAB and <backtab> bindings don't appear in C-h m
for *vc-diff* buffers.

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.

We probably don't want C-h m to include bindings from the parents of
major mode maps.  Right?  It seems like that would mean including too
much.

So I am wondering whether we should consider copying the bindings from
diff-mode-shared-map into the maps that share it.  It means more
repetition in our definitions but better *Help* output.  Usually we
write these maps out longform even if it means duplication.

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?  Adding Stefan to the CC -- can you point
me to what I'm missing about how diff-mode-shared-map is meant to work?

Thanks.

-- 
Sean Whitton

Message #53 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: Van L <van <at> scratch.space>, 34080 <at> debbugs.gnu.org,
 Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Tue, 08 Jul 2025 14:08:15 -0400

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


- Stefan

Message #56 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Van L <van <at> scratch.space>, 34080 <at> debbugs.gnu.org,
 Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
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

Message #59 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: Van L <van <at> scratch.space>, 34080 <at> debbugs.gnu.org,
 Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Wed, 09 Jul 2025 17:47:05 -0400

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

Fine by me.

> So far as I can tell the disadvantage would be repeating keymap
> definitions, and the advantage would be more standardised
> *Help* output.

We definitely do not want to repeat keymap definitions (users may have
their own and may want to change the ones we provide).

But you can do things like

    (use-local-map (make-composed-map diff-mode-shared-map diff-mode-map))


- Stefan

Message #62 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Van L <van <at> scratch.space>, 34080 <at> debbugs.gnu.org,
 Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Thu, 10 Jul 2025 18:59:19 +0100

Hello,

On Wed 09 Jul 2025 at 05:47pm -04, Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" wrote:

>> - 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?
>
> Fine by me.
>
>> So far as I can tell the disadvantage would be repeating keymap
>> definitions, and the advantage would be more standardised
>> *Help* output.
>
> We definitely do not want to repeat keymap definitions (users may have
> their own and may want to change the ones we provide).
>
> But you can do things like
>
>     (use-local-map (make-composed-map diff-mode-shared-map diff-mode-map))

I don't think getting users to repeat their configuration for a few
different maps is too bad but certainly if it can be done with composed
maps then that's better.  I'll investigate, thanks!

-- 
Sean Whitton

Message #65 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 34080 <at> debbugs.gnu.org, Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Fri, 18 Jul 2025 10:58:53 +0100

Hello,

On Wed 09 Jul 2025 at 11:40am +01, Sean Whitton wrote:

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

I spent some time seeing how this change would be implemented and I now
think that, instead, diff-minor-mode should be renamed
diff-read-only-mode.  Am I right that diff-minor-mode is only intended
as a way to add bindings when diff-mode buffers are read-only?

I'm given pause by diff-minor-mode-prefix.  Why do we have this?  Aren't
all the bindings available without this prefix whenever diff-minor-mode
is active?  If I'm right then I'd propose to obsolete it and tidy things
up.

-- 
Sean Whitton

Message #68 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: 34080 <at> debbugs.gnu.org, Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Fri, 18 Jul 2025 09:24:31 -0400

> I spent some time seeing how this change would be implemented and I now
> think that, instead, diff-minor-mode should be renamed
> diff-read-only-mode.  Am I right that diff-minor-mode is only intended
> as a way to add bindings when diff-mode buffers are read-only?

No, `diff-minor-mode` is intended for use in buffers that need to use
another major mode than `diff-mode`.
[ Like the difference between `outline-mode` and `outline-minor-mode`.  ]

Not sure how important it is in practice: IIRC, I implemented this
because it existed in other people's "diff modes" (when I started
diff-mode I tried to make it a superset of all the diff/patch modes
I could find), rather than because I saw a need for it.


        Stefan

Message #71 received at 34080 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 34080 <at> debbugs.gnu.org, Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Sat, 19 Jul 2025 09:57:47 +0100

Hello,

On Fri 18 Jul 2025 at 09:24am -04, Stefan Monnier wrote:

>> I spent some time seeing how this change would be implemented and I now
>> think that, instead, diff-minor-mode should be renamed
>> diff-read-only-mode.  Am I right that diff-minor-mode is only intended
>> as a way to add bindings when diff-mode buffers are read-only?
>
> No, `diff-minor-mode` is intended for use in buffers that need to use
> another major mode than `diff-mode`.
> [ Like the difference between `outline-mode` and `outline-minor-mode`.  ]
>
> Not sure how important it is in practice: IIRC, I implemented this
> because it existed in other people's "diff modes" (when I started
> diff-mode I tried to make it a superset of all the diff/patch modes
> I could find), rather than because I saw a need for it.

Okay, thanks.

Renaming it wouldn't prevent it being used in this way and would improve
comprehensibility for 90% of users, so I'll go ahead with that.

I'll also experimentally mark diff-minor-mode-prefix as obsolete.

-- 
Sean Whitton

Message #76 received at 34080-done <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>, 34080-done <at> debbugs.gnu.org
Subject: Re: bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*
Date: Sat, 19 Jul 2025 11:18:53 +0100

Hello,

On Sat 19 Jul 2025 at 09:57am +01, Sean Whitton wrote:

> Hello,
>
> On Fri 18 Jul 2025 at 09:24am -04, Stefan Monnier wrote:
>
>>> I spent some time seeing how this change would be implemented and I now
>>> think that, instead, diff-minor-mode should be renamed
>>> diff-read-only-mode.  Am I right that diff-minor-mode is only intended
>>> as a way to add bindings when diff-mode buffers are read-only?
>>
>> No, `diff-minor-mode` is intended for use in buffers that need to use
>> another major mode than `diff-mode`.
>> [ Like the difference between `outline-mode` and `outline-minor-mode`.  ]
>>
>> Not sure how important it is in practice: IIRC, I implemented this
>> because it existed in other people's "diff modes" (when I started
>> diff-mode I tried to make it a superset of all the diff/patch modes
>> I could find), rather than because I saw a need for it.
>
> Okay, thanks.
>
> Renaming it wouldn't prevent it being used in this way and would improve
> comprehensibility for 90% of users, so I'll go ahead with that.
>
> I'll also experimentally mark diff-minor-mode-prefix as obsolete.

No, that's not right, diff-minor-mode isn't used at all in read-only
diff-mode buffers.  The short bindings are activated in those in another
way.

As can be seen by my messages to this bug, all this has really confused
me, and I think it would confuse the next person, too.  I've tried to
add a clarificatory comment.  Also, I've fixed the original reported
issue, so I'm closing the bug with this message.

If the bug I thought I'd found in where-is-internal is real, it'll come
up again in a context where fixing it is more important.

-- 
Sean Whitton

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.