unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro
@ 2024-12-19 22:36 Hong Xu
  2024-12-20  7:01 ` Eli Zaretskii
  0 siblings, 1 reply; 12+ messages in thread
From: Hong Xu @ 2024-12-19 22:36 UTC (permalink / raw)
  To: 74983

* 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






^ permalink raw reply related	[flat|nested] 12+ messages in thread

* bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-19 22:36 bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro Hong Xu
@ 2024-12-20  7:01 ` Eli Zaretskii
  2024-12-20  9:35   ` Stefan Kangas
                     ` (2 more replies)
  0 siblings, 3 replies; 12+ messages in thread
From: Eli Zaretskii @ 2024-12-20  7:01 UTC (permalink / raw)
  To: Hong Xu, Stefan Kangas; +Cc: 74983

> From: Hong Xu <hong@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?





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-20  7:01 ` Eli Zaretskii
@ 2024-12-20  9:35   ` Stefan Kangas
  2024-12-20 21:42     ` bug#74999: [PATCH v2] Recommend " Hong Xu
  2024-12-20 15:43   ` bug#74983: [PATCH] Use " Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2024-12-20 21:50   ` Hong Xu
  2 siblings, 1 reply; 12+ messages in thread
From: Stefan Kangas @ 2024-12-20  9:35 UTC (permalink / raw)
  To: Eli Zaretskii, Hong Xu; +Cc: 74983

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Hong Xu <hong@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.





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-20  7:01 ` Eli Zaretskii
  2024-12-20  9:35   ` Stefan Kangas
@ 2024-12-20 15:43   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2024-12-20 21:50   ` Hong Xu
  2 siblings, 0 replies; 12+ messages in thread
From: Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2024-12-20 15:43 UTC (permalink / raw)
  To: Eli Zaretskii, Hong Xu, Stefan Kangas; +Cc: 74983@debbugs.gnu.org

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





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#74999: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-20  9:35   ` Stefan Kangas
@ 2024-12-20 21:42     ` Hong Xu
  2024-12-21  7:19       ` Eli Zaretskii
  0 siblings, 1 reply; 12+ messages in thread
From: Hong Xu @ 2024-12-20 21:42 UTC (permalink / raw)
  To: 74999

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

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 49916235fbf9..ba671e60ffcf 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -17358,11 +17358,21 @@ 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
+(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group)
+@end group
+@end smallexample
+
+While you are encouraged to use @code{keymap-set}, you likely would
+encounter @code{define-key} in various places. @code{define-key} is an
+older function to create keymaps, and is now considered legacy. The
+above key map can be rewritten in @code{define-key} as:
 
 @smallexample
 @group
@@ -17396,9 +17406,9 @@ 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
-@file{loaddefs.el} as well as in the various mode libraries, such as
-@file{cc-mode.el} and @file{lisp-mode.el}.
+You will see numerous @code{keymap-set} and @code{define-key}
+expressions in @file{loaddefs.el} as well as in the various mode
+libraries, such as @file{cc-mode.el} and @file{lisp-mode.el}.
 
 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
-- 
2.47.1






^ permalink raw reply related	[flat|nested] 12+ messages in thread

* bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-20  7:01 ` Eli Zaretskii
  2024-12-20  9:35   ` Stefan Kangas
  2024-12-20 15:43   ` bug#74983: [PATCH] Use " Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2024-12-20 21:50   ` Hong Xu
  2024-12-21  7:20     ` Eli Zaretskii
  2 siblings, 1 reply; 12+ messages in thread
From: Hong Xu @ 2024-12-20 21:50 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Stefan Kangas, 74983

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

>> From: Hong Xu <hong@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





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#74999: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-20 21:42     ` bug#74999: [PATCH v2] Recommend " Hong Xu
@ 2024-12-21  7:19       ` Eli Zaretskii
  2024-12-21  8:03         ` bug#74999: [PATCH v3] " Hong Xu
  2024-12-21  8:06         ` bug#74999: [PATCH v2] " Hong Xu
  0 siblings, 2 replies; 12+ messages in thread
From: Eli Zaretskii @ 2024-12-21  7:19 UTC (permalink / raw)
  To: Hong Xu; +Cc: 74999

> From: Hong Xu <hong@topbug.net>
> Date: Fri, 20 Dec 2024 13:42:29 -0800
> 
> -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
> +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group)
> +@end group
> +@end smallexample
> +
> +While you are encouraged to use @code{keymap-set}, you likely would
> +encounter @code{define-key} in various places. @code{define-key} is an
> +older function to create keymaps, and is now considered legacy.

This should say that historically, Emacs used 'define-key', and
therefore you are likely to see 'define-key' in various places etc.
In addition "older function" is not really accurate: 'keymap-set'
calls 'define-key' internally, so 'define-key' will not disappear from
Emacs any time soon.  We just prefer using 'keymap-set' in Lisp
programs because it is higher-level.  So instead of saying "older
function", I think we should say "more low-level function".

Also, please make sure to leave two spaces between sentences, per our
conventions.

>                                                             The
> +above key map can be rewritten in @code{define-key} as:

Not "key map", but "key binding".  The example doesn't show a complete
key map, it only shows a single binding within a key map.  Since this
is an introductory manual, we must be very accurate and clear in our
text, to avoid confusing newcomers to Lisp, who are probably confused
already to begin with...

Thanks.





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-20 21:50   ` Hong Xu
@ 2024-12-21  7:20     ` Eli Zaretskii
  0 siblings, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2024-12-21  7:20 UTC (permalink / raw)
  To: Hong Xu; +Cc: stefankangas, 74983

merge 74983 74999
thanks

> From: Hong Xu <hong@topbug.net>
> Cc: Stefan Kangas <stefankangas@gmail.com>,  74983@debbugs.gnu.org
> Date: Fri, 20 Dec 2024 13:50:15 -0800
> 
> On 2024-12-19 Thu 23:01 GMT-08, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >> From: Hong Xu <hong@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.





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#74999: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-21  7:19       ` Eli Zaretskii
@ 2024-12-21  8:03         ` Hong Xu
  2024-12-23 20:42           ` Hong Xu
  2024-12-21  8:06         ` bug#74999: [PATCH v2] " Hong Xu
  1 sibling, 1 reply; 12+ messages in thread
From: Hong Xu @ 2024-12-21  8:03 UTC (permalink / raw)
  To: 74999

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

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 49916235fbf9..b3b4141a3c5f 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -17358,11 +17358,22 @@ 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
+(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group)
+@end group
+@end smallexample
+
+While you are encouraged to use @code{keymap-set}, you likely would
+encounter @code{define-key} in various places.  Historically, keymaps
+are bound using a lower-level function, @code{define-key}, which
+is now considered legacy.  The above key binding can be rewritten using
+@code{define-key} as:
 
 @smallexample
 @group
@@ -17396,9 +17407,9 @@ 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
-@file{loaddefs.el} as well as in the various mode libraries, such as
-@file{cc-mode.el} and @file{lisp-mode.el}.
+You will see numerous @code{keymap-set} and @code{define-key}
+expressions in @file{loaddefs.el} as well as in the various mode
+libraries, such as @file{cc-mode.el} and @file{lisp-mode.el}.
 
 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
-- 
2.47.1






^ permalink raw reply related	[flat|nested] 12+ messages in thread

* bug#74999: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-21  7:19       ` Eli Zaretskii
  2024-12-21  8:03         ` bug#74999: [PATCH v3] " Hong Xu
@ 2024-12-21  8:06         ` Hong Xu
  1 sibling, 0 replies; 12+ messages in thread
From: Hong Xu @ 2024-12-21  8:06 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 74999

On 2024-12-20 Fri 23:19 GMT-08, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Hong Xu <hong@topbug.net>
>> Date: Fri, 20 Dec 2024 13:42:29 -0800
>> 
>> -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
>> +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group)
>> +@end group
>> +@end smallexample
>> +
>> +While you are encouraged to use @code{keymap-set}, you likely would
>> +encounter @code{define-key} in various places. @code{define-key} is an
>> +older function to create keymaps, and is now considered legacy.
>
> This should say that historically, Emacs used 'define-key', and
> therefore you are likely to see 'define-key' in various places etc.
> In addition "older function" is not really accurate: 'keymap-set'
> calls 'define-key' internally, so 'define-key' will not disappear from
> Emacs any time soon.  We just prefer using 'keymap-set' in Lisp
> programs because it is higher-level.  So instead of saying "older
> function", I think we should say "more low-level function".
>
> Also, please make sure to leave two spaces between sentences, per our
> conventions.
>
>>                                                             The
>> +above key map can be rewritten in @code{define-key} as:
>
> Not "key map", but "key binding".  The example doesn't show a complete
> key map, it only shows a single binding within a key map.  Since this
> is an introductory manual, we must be very accurate and clear in our
> text, to avoid confusing newcomers to Lisp, who are probably confused
> already to begin with...
>

I agree, please see my follow-up patch.

-- 
Thanks,
Hong





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#74999: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-21  8:03         ` bug#74999: [PATCH v3] " Hong Xu
@ 2024-12-23 20:42           ` Hong Xu
  2024-12-24  3:27             ` Eli Zaretskii
  0 siblings, 1 reply; 12+ messages in thread
From: Hong Xu @ 2024-12-23 20:42 UTC (permalink / raw)
  To: 74999, Eli Zaretskii

References: <86y1098pvj.fsf@gnu.org> <20241221080552.259664-1-hong@topbug.net>
User-Agent: mu4e 1.12.8; emacs 29.4
Date: Mon, 23 Dec 2024 12:42:29 -0800

On 2024-12-21 Sat 00:03 GMT-08, Hong Xu <hong@topbug.net> wrote:

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

In case you missed this, are you still interested in reviewing this patch?


-- 
Hong





^ permalink raw reply	[flat|nested] 12+ messages in thread

* bug#74999: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro
  2024-12-23 20:42           ` Hong Xu
@ 2024-12-24  3:27             ` Eli Zaretskii
  0 siblings, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2024-12-24  3:27 UTC (permalink / raw)
  To: Hong Xu; +Cc: 74999

> From: Hong Xu <hong@topbug.net>
> Date: Mon, 23 Dec 2024 12:42:34 -0800
> 
> References: <86y1098pvj.fsf@gnu.org> <20241221080552.259664-1-hong@topbug.net>
> User-Agent: mu4e 1.12.8; emacs 29.4
> Date: Mon, 23 Dec 2024 12:42:29 -0800
> 
> On 2024-12-21 Sat 00:03 GMT-08, Hong Xu <hong@topbug.net> wrote:
> 
> > * Since `define-key' is considered legacy and we encourage `keymap-set'
> >   now.
> > ---
> >  doc/lispintro/emacs-lisp-intro.texi | 25 ++++++++++++++++++-------
> >  1 file changed, 18 insertions(+), 7 deletions(-)
> >
> > <...>
> 
> In case you missed this, are you still interested in reviewing this patch?

I didn't miss it.  It's in my queue.





^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2024-12-24  3:27 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-12-19 22:36 bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro Hong Xu
2024-12-20  7:01 ` Eli Zaretskii
2024-12-20  9:35   ` Stefan Kangas
2024-12-20 21:42     ` bug#74999: [PATCH v2] Recommend " Hong Xu
2024-12-21  7:19       ` Eli Zaretskii
2024-12-21  8:03         ` bug#74999: [PATCH v3] " Hong Xu
2024-12-23 20:42           ` Hong Xu
2024-12-24  3:27             ` Eli Zaretskii
2024-12-21  8:06         ` bug#74999: [PATCH v2] " Hong Xu
2024-12-20 15:43   ` bug#74983: [PATCH] Use " Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-12-20 21:50   ` Hong Xu
2024-12-21  7:20     ` Eli Zaretskii

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).