bug#39802: (info "(emacs) Init Rebinding") needs to say it is impossible to unbind local keys

[Noam Postavsky]

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

積丹尼 Dan Jacobson <jidanni@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.

>From 980d36d8748ff4598132b704487487691e165334 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@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