Subject: bug#74999: closed (Re: bug#74999: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro)

From: [email-masked] (GNU bug Tracking System)
Date: Sat, 04 Jan 2025 12:35:03 +0000

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 [email-masked].

-- 
74999: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74999
GNU Bug Tracking System
Contact [email-masked] with problems

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

> From: Hong Xu <[email-masked]>
> Cc: [email-masked]
> Date: Sat, 28 Dec 2024 11:56:05 -0800
> 
> On 2024-12-28 Sat 04:17 GMT-08, Eli Zaretskii <[email-masked]> wrote:
> 
> >> From: Hong Xu <[email-masked]>
> >> 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.

Subject: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro
From: Hong Xu <[email-masked]>
To: [email-masked]
Date: Fri, 20 Dec 2024 13:42:29 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

* 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