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: Hong Xu <hong <at> topbug.net>
Subject: bug#74999: closed (Re: bug#74999: [PATCH v4] Use `keymap*-set'
 over `global-set-key'/`define-key' in elisp intro)
Date: Sat, 04 Jan 2025 12:35:03 +0000

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

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 74999 <at> debbugs.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: 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.

[Message part 3 (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

Previous Next

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