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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#74999: closed ([PATCH v2] Recommend `keymap-set' instead of
 `define-key' in emacs lisp intro)
Date: Sat, 04 Jan 2025 12:35:02 +0000

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

Your message dated Sat, 04 Jan 2025 14:34:30 +0200
with message-id <861pxiep0p.fsf <at> gnu.org>
and subject line Re: bug#74999: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro
has caused the debbugs.gnu.org bug report #74999,
regarding [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
74999: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74999
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs
 lisp intro
Date: Fri, 20 Dec 2024 13:42:29 -0800

* 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

[Message part 3 (message/rfc822, inline)]

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 74999-done <at> debbugs.gnu.org
Subject: Re: bug#74999: [PATCH v4] Use `keymap*-set' over
 `global-set-key'/`define-key' in elisp intro
Date: Sat, 04 Jan 2025 14:34:30 +0200

> From: Hong Xu <hong <at> topbug.net>
> Cc: 74999 <at> debbugs.gnu.org
> Date: Sat, 28 Dec 2024 11:56:05 -0800
> 
> On 2024-12-28 Sat 04:17 GMT-08, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
> >> From: Hong Xu <hong <at> topbug.net>
> >> Date: Thu, 26 Dec 2024 13:46:39 -0800
> >> 
> >> * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since
> >> `global-set-key' and `define-key' are considered legacy, we encourage
> >> `keymap-global-set' and `keymap-set' now.
> >> ---
> >>  doc/lispintro/emacs-lisp-intro.texi | 119 +++++++++++++++++++---------
> >>  1 file changed, 81 insertions(+), 38 deletions(-)
> >
> > Thanks, I have a few minor comments:
> >
> >>  @cindex Setting a key globally
> >> -@cindex Global set key
> >> +@cindex Keymap global set
> >>  @cindex Key setting globally
> >> -@findex global-set-key
> >
> > Please add index entries for the new APIs, but do not remove the index
> > entries for old ones.  Readers could still need to look up the old
> > interfaces via index search.
> >
> >> -@findex global-unset-key
> >> +@findex keymap-global-unset
> >
> > Same here.
> 
> I moved these two indices to the legacy subsection, which is now the
> place that describes these functions.
> 
> >
> >> +@subsection Legacy Global Key Binding Commands
> >> +
> >> +@findex global-set-key
> >> +@cindex Global set key
> >> +Historically, keys are bound globally using a lower-level function,
> >> +@code{global-set-key}, which is now considered legacy.  While you are
> >> +encouraged to use @code{keymap-global-set}, you likely would encounter
> >> +@code{global-set-key} in various places.  The first example can be
> >> +rewritten using @code{global-set-key} as:
> >> +
> >> +@smallexample
> >> +@group
> >> +(global-set-key "\C-cw" 'compare-windows)
> >> +@end group
> >> +@end smallexample
> >
> > The text says "first example", but which example is that?  There are
> > no examples in this subsection.
> >
> >> +Historically, keys are unbound globally using a lower-function,
> >> +@code{global-unset-key}, which is now considered legacy.  Its key
> >> +binding format follows that of @code{global-set-key}.  The above key
> >> +unbinding example can be rewritten as:
> >
> > Same here: "the above key unbinding example" refers to an example in a
> > different subsection.
> 
> The updated patch now adds an "in this section" qualifier. Please see
> the attachment.

Thanks, installed on the emacs-30 branch, and closing the bug.

Previous Next

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