GNU bug report logs - #39802
(info "(emacs) Init Rebinding") doesn't explain how to unbind local keys

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 39802 in the body.
You can then email your comments to 39802 AT debbugs.gnu.org in the normal way.

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

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

From: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
To: bug-gnu-emacs <at> gnu.org
Subject: (info "(emacs) Init Rebinding") needs to say it is impossible to
 unbind local keys
Date: Wed, 26 Feb 2020 23:48:43 +0800

On(info "(emacs) Init Rebinding")
at the end, please have the page "admit" that their is no way to unbind a key from a
local map. That would save the user a lot of guessing.
Currently the page just ends in an example of binding a key in a local
map. Users need to know it is in fact impossible to unbind them.
https://stackoverflow.com/questions/22834506/how-to-unset-a-keybinding-in-a-map-locally-to-a-mode
https://github.com/jwiegley/use-package/issues/103
emacs-version "26.3"

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
Cc: 39802 <at> debbugs.gnu.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Wed, 26 Feb 2020 11:17:35 -0500

積丹尼 Dan Jacobson <jidanni <at> jidanni.org> writes:

> On(info "(emacs) Init Rebinding")
> at the end, please have the page "admit" that their is no way to unbind a key from a
> local map.

Your terminology is a bit confusing here.  From this description I might
think that you are looking for local-unset-key (that is, "local map" ==
current major mode map, which is how the manual is using it).  But based
on the links you posted, I guess you are actually talking about the lack
of buffer-local keymap values?

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

From: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 39802 <at> debbugs.gnu.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Thu, 27 Feb 2020 00:31:53 +0800

If

  C-. runs the command flyspell-auto-correct-word (found in
  flyspell-mode-map), which is an interactive compiled Lisp function in
 ‘flyspell.el’.

  It is bound to C-., C-M-i.

And the user wants to unbind it, well,
(info "(emacs) Init Rebinding")
won't break the bad news to him that it is just not possible.

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
Cc: 39802 <at> debbugs.gnu.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Wed, 26 Feb 2020 12:04:05 -0500

積丹尼 Dan Jacobson <jidanni <at> jidanni.org> writes:

> If
>
>   C-. runs the command flyspell-auto-correct-word (found in
>   flyspell-mode-map), which is an interactive compiled Lisp function in
>  ‘flyspell.el’.
>
>   It is bound to C-., C-M-i.
>
> And the user wants to unbind it, well,
> (info "(emacs) Init Rebinding")
> won't break the bad news to him that it is just not possible.

If I understood correctly, then

    (define-key flyspell-mode-map (kbd "C-.") nil)

would work.

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

From: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 39802 <at> debbugs.gnu.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Thu, 27 Feb 2020 07:22:10 +0800

OK!
Please add this patch (i.e., fix the source file) to
(info "(emacs) Init Rebinding")

    For example, Texinfo mode runs the hook ‘texinfo-mode-hook’.  Here’s
-how you can use the hook to add local bindings for ‘C-c n’ and ‘C-c p’
-in Texinfo mode:
+how you can use the hook to add local bindings for ‘C-c n’ and ‘C-c p’,
+and remove one for C-c C-c x, in Texinfo mode:
 
      (add-hook 'texinfo-mode-hook
                (lambda ()
                  (define-key texinfo-mode-map "\C-cp"
                              'backward-paragraph)
                  (define-key texinfo-mode-map "\C-cn"
-                             'forward-paragraph)))
-
+                             'forward-paragraph)
+                 (define-key texinfo-mode-map "\C-c\C-cx"
+                             nil)))

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
Cc: 39802 <at> debbugs.gnu.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Thu, 27 Feb 2020 08:14:56 -0500

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

retitle 39802 (info "(emacs) Init Rebinding") doesn't explain how to unbind local keys
tags 39802 + patch
quit

積丹尼 Dan Jacobson <jidanni <at> jidanni.org> writes:

> OK!
> Please add this patch (i.e., fix the source file) to
> (info "(emacs) Init Rebinding")

I think it would be useful to explain what to do outside of the example,
so I propose a slightly different patch.

[0001-Explain-how-to-unset-mode-bindings-Bug-39802.patch (text/x-diff, inline)]

From 980d36d8748ff4598132b704487487691e165334 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs <at> gmail.com>
Date: Thu, 27 Feb 2020 08:09:44 -0500
Subject: [PATCH] Explain how to unset mode bindings (Bug#39802)

* doc/emacs/custom.texi (Init Rebinding): Explain that passing nil to
define-key will unbind keys, and extend the example accordingly.
---
 doc/emacs/custom.texi | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index f39ce40931..5232ab5cc7 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1873,15 +1873,18 @@ Init Rebinding
   Language and coding systems may cause problems with key bindings for
 non-@acronym{ASCII} characters.  @xref{Init Non-ASCII}.
 
+@findex define-key
   As described in @ref{Local Keymaps}, major modes and minor modes can
-define local keymaps.  These keymaps are constructed when the mode is
-used for the first time in a session.  If you wish to change one of
-these keymaps, you must use the @dfn{mode hook} (@pxref{Hooks}).
+define local keymaps.  The function @code{define-key} can be used to
+make changes in a specific keymap.  This function can also unset keys,
+when passed @code{nil} as the binding.
 
-@findex define-key
-  For example, Texinfo mode runs the hook @code{texinfo-mode-hook}.
-Here's how you can use the hook to add local bindings for @kbd{C-c n}
-and @kbd{C-c p} in Texinfo mode:
+  Since a mode's keymaps are not constructed until it has been loaded,
+you must delay running code which modifies them until, e.g., by
+putting it no a @dfn{mode hook} (pxref{(Hooks)}).  For example,
+Texinfo mode runs the hook @code{texinfo-mode-hook}.  Here's how you
+can use the hook to add local bindings for @kbd{C-c n} and @kbd{C-c
+p}, and remove the one for @kbd{C-c C-x x} in Texinfo mode:
 
 @example
 (add-hook 'texinfo-mode-hook
@@ -1890,6 +1893,7 @@ Init Rebinding
                         'backward-paragraph)
             (define-key texinfo-mode-map "\C-cn"
                         'forward-paragraph)))
+            (define-key texinfo-mode-map "\C-c\C-xx" nil)
 @end example
 
 @node Modifier Keys
-- 
2.11.0

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

From: Robert Pluim <rpluim <at> gmail.com>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 39802 <at> debbugs.gnu.org,
 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Thu, 27 Feb 2020 14:26:11 +0100

>>>>> On Thu, 27 Feb 2020 08:14:56 -0500, Noam Postavsky <npostavs <at> gmail.com> said:

The text looks good, except for...

    Noam> -@findex define-key
    Noam> -  For example, Texinfo mode runs the hook @code{texinfo-mode-hook}.
    Noam> -Here's how you can use the hook to add local bindings for @kbd{C-c n}
    Noam> -and @kbd{C-c p} in Texinfo mode:
    Noam> +  Since a mode's keymaps are not constructed until it has been loaded,
    Noam> +you must delay running code which modifies them until, e.g., by
    Noam> +putting it no a @dfn{mode hook} (pxref{(Hooks)}).  For example,
                      ^^
                      
Robert

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 39802 <at> debbugs.gnu.org, jidanni <at> jidanni.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Fri, 28 Feb 2020 09:52:22 +0200

> From: Noam Postavsky <npostavs <at> gmail.com>
> Date: Thu, 27 Feb 2020 08:14:56 -0500
> Cc: 39802 <at> debbugs.gnu.org
> 
> +@findex define-key
>    As described in @ref{Local Keymaps}, major modes and minor modes can
> -define local keymaps.  These keymaps are constructed when the mode is
> -used for the first time in a session.  If you wish to change one of
> -these keymaps, you must use the @dfn{mode hook} (@pxref{Hooks}).
> +define local keymaps.  The function @code{define-key} can be used to
> +make changes in a specific keymap.  This function can also unset keys,
> +when passed @code{nil} as the binding.

This loses useful information in the sentence that starts with "These
keymaps".

Otherwise I'm okay with the proposed change.

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: jidanni <at> jidanni.org, Noam Postavsky <npostavs <at> gmail.com>,
 39802 <at> debbugs.gnu.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Fri, 28 Feb 2020 21:48:19 +1300

Perhaps my answer at https://stackoverflow.com/a/13966287/324105
also provides some helpful wording?  (It can be appropriated for
the manual if it's useful.)

-Phil

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 39802 <at> debbugs.gnu.org, jidanni <at> jidanni.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Fri, 28 Feb 2020 05:04:57 -0500

Eli Zaretskii <eliz <at> gnu.org> writes:

>>    As described in @ref{Local Keymaps}, major modes and minor modes can
>> -define local keymaps.  These keymaps are constructed when the mode is
>> -used for the first time in a session.

> This loses useful information in the sentence that starts with "These
> keymaps".

I moved that information to the next paragraph:
 
    +  Since a mode's keymaps are not constructed until it has been loaded,

(I think "until it has been loaded" is more accurate than "used for the
first time", since the file can be loaded without actually using the
mode defined within.)

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

From: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: Eli Zaretskii <eliz <at> gnu.org>, Noam Postavsky <npostavs <at> gmail.com>,
 39802 <at> debbugs.gnu.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Fri, 28 Feb 2020 20:30:09 +0800

>>>>> "PS" == Phil Sainty <psainty <at> orcon.net.nz> writes:
PS> Perhaps my answer at https://stackoverflow.com/a/13966287/324105
PS> also provides some helpful wording?  (It can be appropriated for
PS> the manual if it's useful.)

So maybe the patch should say "in addition to
(define-key ...-map ... nil)
one can use
(local-set-key ... ... ...)"
I suppose. But maybe it is "less powerful" but I don't know.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 39802 <at> debbugs.gnu.org, jidanni <at> jidanni.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Fri, 28 Feb 2020 14:56:27 +0200

> From: Noam Postavsky <npostavs <at> gmail.com>
> Cc: 39802 <at> debbugs.gnu.org,  jidanni <at> jidanni.org
> Date: Fri, 28 Feb 2020 05:04:57 -0500
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >>    As described in @ref{Local Keymaps}, major modes and minor modes can
> >> -define local keymaps.  These keymaps are constructed when the mode is
> >> -used for the first time in a session.
> 
> > This loses useful information in the sentence that starts with "These
> > keymaps".
> 
> I moved that information to the next paragraph:
>  
>     +  Since a mode's keymaps are not constructed until it has been loaded,

I saw it, but that "Since" strikes me as "a bolt out of the blue",
because no text before that explained or mentioned this fact.  Leaving
that sentence in place will then go a long way towards making the
"Since" part crystal clear.

IOW, in this and similar cases, repetition facilitates understanding,
and should not be avoided, because we are dealing with something that
won't necessarily be evident to the reader.

> (I think "until it has been loaded" is more accurate than "used for the
> first time", since the file can be loaded without actually using the
> mode defined within.)

I'm okay with rephrasing the original sentence along these lines.  But
I think we should not remove it entirely.  (Obviously, this is a minor
point.)

Thanks.

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

From: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
To: 39630 <at> debbugs.gnu.org, 39802 <at> debbugs.gnu.org, 39631 <at> debbugs.gnu.org
Subject: Actually 39802 solves the need for 39630 and 39631
Date: Sat, 29 Feb 2020 12:51:58 +0800

Actually 39802 solves the need for 39630 and 39631.

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

From: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, Stefan Kangas <stefan <at> marxist.se>,
 39631 <at> debbugs.gnu.org, 39802 <at> debbugs.gnu.org
Subject: Zapping a whole keymap
Date: Sat, 29 Feb 2020 13:17:41 +0800

NP> I don't know about 39631

OK, I suppose to solve 39631 somebody could use the lisp equivalent of
for(all the keys present in a given keymap){use the method of 39802 to unbind it}

So maybe document that in some elisp manual or something, mentioning
that maybe there is no way to zap the whole keymap with one line of lisp(?).

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 39630 <at> debbugs.gnu.org, 39802 <at> debbugs.gnu.org,
 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
Subject: Re: bug#39630: Mention how to unset keys in Your Init File
Date: Sat, 29 Feb 2020 06:22:58 +0100

Noam Postavsky <npostavs <at> gmail.com> writes:

> I don't know about 39631, but 39630 is clearly the same as 39802 (I did
> have a feeling of familiarity when I initially read that one), so it
> doesn't make sense to mark it as wontfix when we are actually fixing it.

Thanks.  I had missed the ongoing work in Bug#39802.

Best regards,
Stefan Kangas

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 39802 <at> debbugs.gnu.org, jidanni <at> jidanni.org
Subject: Re: bug#39802: (info "(emacs) Init Rebinding") needs to say it is
 impossible to unbind local keys
Date: Tue, 03 Mar 2020 22:13:22 -0500

tags 39802 fixed
close 39802 27.1
quit

Eli Zaretskii <eliz <at> gnu.org> writes:

> I saw it, but that "Since" strikes me as "a bolt out of the blue",
> because no text before that explained or mentioned this fact.  Leaving
> that sentence in place will then go a long way towards making the
> "Since" part crystal clear.
>
> IOW, in this and similar cases, repetition facilitates understanding,
> and should not be avoided, because we are dealing with something that
> won't necessarily be evident to the reader.

Okay, I see what you mean.  I put that sentence back in (with "used"
changed to "loaded") and pushed to emacs-27.

[1: 60418a1ab2]: 2020-03-03 22:04:48 -0500
  Explain how to unset mode bindings (Bug#39802)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=60418a1ab21b86cb2d46470ae187e74a25d33212

Previous Next

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