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

Previous Next

Full log

Message #53 received at 74999-done <at> debbugs.gnu.org (full text, mbox):

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.