GNU bug report logs - #74983
[PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro

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 74983 in the body.
You can then email your comments to 74983 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: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro
Date: Thu, 19 Dec 2024 14:36:29 -0800

* Since `define-key' is considered legacy and we encourage `keymap-set'
  now.
---
 doc/lispintro/emacs-lisp-intro.texi | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 49916235fbf9..32ad07785c20 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -17358,15 +17358,14 @@ Keymaps
 (global-set-key "\C-x\C-b" 'buffer-menu)
 @end smallexample
 
-Mode-specific keymaps are bound using the @code{define-key} function,
+Mode-specific keymaps are bound using the @code{keymap-set} function,
 which takes a specific keymap as an argument, as well as the key and
-the command.  For example, my @file{.emacs} file contains the
-following expression to bind the @code{texinfo-insert-@@group} command
-to @kbd{C-c C-c g}:
+the command.  For example, the following expression binds the
+@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}:
 
 @smallexample
 @group
-(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
+(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@group)
 @end group
 @end smallexample
 
@@ -17396,7 +17395,7 @@ Keymaps
 write a function to insert a word; but I prefer key strokes consistent
 with other Texinfo mode key bindings.)
 
-You will see numerous @code{define-key} expressions in
+You will see numerous @code{keymap-set} expressions in
 @file{loaddefs.el} as well as in the various mode libraries, such as
 @file{cc-mode.el} and @file{lisp-mode.el}.
 
-- 
2.47.1

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>, Stefan Kangas <stefankangas <at> gmail.com>
Cc: 74983 <at> debbugs.gnu.org
Subject: Re: bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in
 emacs lisp intro
Date: Fri, 20 Dec 2024 09:01:29 +0200

> From: Hong Xu <hong <at> topbug.net>
> Date: Thu, 19 Dec 2024 14:36:29 -0800
> 
> * Since `define-key' is considered legacy and we encourage `keymap-set'
>   now.

Thanks.  But the second chunk is not really right, since we have many
more define-key there than keymap-set.

So my suggestion is not to _replace_ define-key with keymap-set, but
instead describe _both_, explaining that as of Emacs 29 we are
migrating towards keymap-set, which is preferred.

Stefan, WDYT?

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Hong Xu <hong <at> topbug.net>
Cc: 74983 <at> debbugs.gnu.org
Subject: Re: bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in
 emacs lisp intro
Date: Fri, 20 Dec 2024 04:35:30 -0500

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

>> From: Hong Xu <hong <at> topbug.net>
>> Date: Thu, 19 Dec 2024 14:36:29 -0800
>>
>> * Since `define-key' is considered legacy and we encourage `keymap-set'
>>   now.
>
> Thanks.  But the second chunk is not really right, since we have many
> more define-key there than keymap-set.
>
> So my suggestion is not to _replace_ define-key with keymap-set, but
> instead describe _both_, explaining that as of Emacs 29 we are
> migrating towards keymap-set, which is preferred.
>
> Stefan, WDYT?

I'd tend to agree.  Users will have to recognize define-key for a long
time indeed, not just in our sources (which are relatively easily
fixable in comparison) but also in online forums, third-party packages,
and so on.

I didn't yet look at the patch though.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Hong Xu <hong <at> topbug.net>, Stefan Kangas
 <stefankangas <at> gmail.com>
Cc: "74983 <at> debbugs.gnu.org" <74983 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#74983: [PATCH] Use `keymap-set' instead of
 `define-key' in emacs lisp intro
Date: Fri, 20 Dec 2024 15:43:15 +0000

> So my suggestion is not to _replace_ define-key with keymap-set, but
> instead describe _both_, explaining that as of Emacs 29 we are
> migrating towards keymap-set, which is preferred.

+1.

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

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Stefan Kangas <stefankangas <at> gmail.com>, 74983 <at> debbugs.gnu.org
Subject: Re: bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in
 emacs lisp intro
Date: Fri, 20 Dec 2024 13:50:15 -0800

On 2024-12-19 Thu 23:01 GMT-08, Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Hong Xu <hong <at> topbug.net>
>> Date: Thu, 19 Dec 2024 14:36:29 -0800
>> 
>> * Since `define-key' is considered legacy and we encourage `keymap-set'
>>   now.
>
> Thanks.  But the second chunk is not really right, since we have many
> more define-key there than keymap-set.
>
> So my suggestion is not to _replace_ define-key with keymap-set, but
> instead describe _both_, explaining that as of Emacs 29 we are
> migrating towards keymap-set, which is preferred.

Thanks, I agree. I've made a followup patch. For some reason the
followup patch didn't attach to the Message ID of this thread and a new
bug 74999 was created.

-- 
Hong

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: stefankangas <at> gmail.com, 74983 <at> debbugs.gnu.org
Subject: Re: bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in
 emacs lisp intro
Date: Sat, 21 Dec 2024 09:20:38 +0200

merge 74983 74999
thanks

> From: Hong Xu <hong <at> topbug.net>
> Cc: Stefan Kangas <stefankangas <at> gmail.com>,  74983 <at> debbugs.gnu.org
> Date: Fri, 20 Dec 2024 13:50:15 -0800
> 
> On 2024-12-19 Thu 23:01 GMT-08, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
> >> From: Hong Xu <hong <at> topbug.net>
> >> Date: Thu, 19 Dec 2024 14:36:29 -0800
> >> 
> >> * Since `define-key' is considered legacy and we encourage `keymap-set'
> >>   now.
> >
> > Thanks.  But the second chunk is not really right, since we have many
> > more define-key there than keymap-set.
> >
> > So my suggestion is not to _replace_ define-key with keymap-set, but
> > instead describe _both_, explaining that as of Emacs 29 we are
> > migrating towards keymap-set, which is preferred.
> 
> Thanks, I agree. I've made a followup patch. For some reason the
> followup patch didn't attach to the Message ID of this thread and a new
> bug 74999 was created.

I've now merged them.

Previous Next

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