bug#30659: Only local map define-key examples

bug#30659: Only local map define-key examples

[積丹尼 Dan Jacobson]

At the end of (info "(emacs) Init Rebinding")
there is an example,

     (add-hook 'texinfo-mode-hook
               (lambda ()
                 (define-key texinfo-mode-map "\C-cp"
                             'backward-paragraph)
                 (define-key texinfo-mode-map "\C-cn"
                             'forward-paragraph)))


Please add to this example also an example of undefining an existing key.
Else users will use local-unset-key that they find on (info "(emacs) Rebinding"),
which may or may not be correct.

If such example already exists, then please link it from this page.

bug#30659: Only local map define-key examples

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson
> 	<jidanni@jidanni.org>
> Date: Thu, 01 Mar 2018 04:13:16 +0800
> 
> At the end of (info "(emacs) Init Rebinding")
> there is an example,
> 
>      (add-hook 'texinfo-mode-hook
>                (lambda ()
>                  (define-key texinfo-mode-map "\C-cp"
>                              'backward-paragraph)
>                  (define-key texinfo-mode-map "\C-cn"
>                              'forward-paragraph)))
> 
> 
> Please add to this example also an example of undefining an existing key.
> Else users will use local-unset-key that they find on (info "(emacs) Rebinding"),
> which may or may not be correct.

I'm not sure I understand what's wrong with local-unset-key.  (And
"Rebinding" also mentions global-unset-key, btw.)

bug#30659: Only local map define-key examples

[積丹尼 Dan Jacobson]

>>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:
>> From: 積丹尼 Dan Jacobson
>> <jidanni@jidanni.org>
>> Date: Thu, 01 Mar 2018 04:13:16 +0800
>> 
>> At the end of (info "(emacs) Init Rebinding")
>> there is an example,
>> 
>> (add-hook 'texinfo-mode-hook
>> (lambda ()
>> (define-key texinfo-mode-map "\C-cp"
>> 'backward-paragraph)
>> (define-key texinfo-mode-map "\C-cn"
>> 'forward-paragraph)))
>> 
>> 
>> Please add to this example also an example of undefining an existing key.
>> Else users will use local-unset-key that they find on (info "(emacs) Rebinding"),
>> which may or may not be correct.

EZ> I'm not sure I understand what's wrong with local-unset-key.

OK then please add it to the example there.
Else they will look for "undefine-key".

EZ>  (And "Rebinding" also mentions global-unset-key, btw.)
No it doesn't.
https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html

bug#30659: Only local map define-key examples

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson <jidanni@jidanni.org>
> Cc: 30659@debbugs.gnu.org
> Date: Sat, 03 Mar 2018 14:26:27 +0800
> 
> >> Please add to this example also an example of undefining an existing key.
> >> Else users will use local-unset-key that they find on (info "(emacs) Rebinding"),
> >> which may or may not be correct.
> 
> EZ> I'm not sure I understand what's wrong with local-unset-key.
> 
> OK then please add it to the example there.
> Else they will look for "undefine-key".

I don't see why they would look for undefine-key.

> EZ>  (And "Rebinding" also mentions global-unset-key, btw.)
> No it doesn't.
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html

I said "Rebinding", not "Init Rebinding".

bug#30659: Only local map define-key examples

[積丹尼 Dan Jacobson]

C-, runs the command flyspell-goto-next-error
It is bound to C-,.

And is very hard to unbind in one's .emacs.
It is a special case.

bug#30659: Only local map define-key examples

[Eli Zaretskii]

> From: 積丹尼 Dan Jacobson <jidanni@jidanni.org>
> Cc: 30659@debbugs.gnu.org
> Date: Sat, 03 Mar 2018 14:29:01 +0800
> 
> C-, runs the command flyspell-goto-next-error
> It is bound to C-,.
> 
> And is very hard to unbind in one's .emacs.
> It is a special case.

What is hard about unbinding it, and what makes it a special case?

bug#30659: Only local map define-key examples

[積丹尼 Dan Jacobson]

(info "(emacs) Init Examples")
only has
          (global-unset-key "\C-x\C-v")
example.

(info "(emacs) Rebinding") mentions
‘M-x global-unset-key <RET> KEY’
     Make KEY undefined in the global map.
‘M-x local-unset-key <RET> KEY’
     Make KEY undefined locally (in the major mode now in effect).


However they all lack proper local map .emacs undefine key examples.

An undefine local key example needs to be wrapped in the proper hook,
else, unlike a global undefine key example, it will not work.

And, without such proper tested working example in the manual, I cannot
proceed in unbinding local keys. Thank you.

bug#30659: Only local map define-key examples

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: 積丹尼 Dan Jacobson <jidanni@jidanni.org>
>> Cc: 30659@debbugs.gnu.org
>> Date: Sat, 03 Mar 2018 14:29:01 +0800
>> 
>> C-, runs the command flyspell-goto-next-error
>> It is bound to C-,.
>> 
>> And is very hard to unbind in one's .emacs.
>> It is a special case.
>
> What is hard about unbinding it, and what makes it a special case?

If I understand the complaint correctly, Dan wants an example in the
manual that says

     (add-hook 'texinfo-mode-hook
               (lambda ()
                 (local-unset-key "\C-cp")))

I think that's a pretty superfluous example (it seems the obvious thing
to do), so I'm closing this bug report.

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