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

[Hong Xu <hong@topbug.net>]

[-- Attachment #1: Type: text/plain, Size: 2140 bytes --]

On 2024-12-28 Sat 04:17 GMT-08, Eli Zaretskii <eliz@gnu.org> wrote:

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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v5-0001-Use-keymap-set-over-global-set-key-define-key-in-.patch --]
[-- Type: text/x-patch, Size: 9068 bytes --]

From b25a4cd7fedaec382b0d486493a1208276e618de Mon Sep 17 00:00:00 2001
From: Hong Xu <hong@topbug.net>
Date: Thu, 19 Dec 2024 14:33:35 -0800
Subject: [PATCH v5] Use `keymap*-set' over `global-set-key'/`define-key' in
 elisp intro

* 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 | 120 +++++++++++++++++++---------
 1 file changed, 82 insertions(+), 38 deletions(-)

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 49916235fbf9..863e06346edc 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -13810,7 +13810,7 @@ Whitespace Bug
 If you wish, you can also install this key binding by evaluating it:
 
 @smallexample
-(global-set-key "\C-c=" '@value{COUNT-WORDS})
+(keymap-global-set "C-c =" '@value{COUNT-WORDS})
 @end smallexample
 
 To conduct the first test, set mark and point to the beginning and end
@@ -14762,7 +14762,7 @@ count-words-in-defun
 Let's reuse @kbd{C-c =} as a convenient key binding:
 
 @smallexample
-(global-set-key "\C-c=" 'count-words-defun)
+(keymap-global-set "C-c =" 'count-words-defun)
 @end smallexample
 
 Now we can try out @code{count-words-defun}: install both
@@ -17229,7 +17229,7 @@ Key Bindings
 @smallexample
 @group
 ;;; Compare windows
-(global-set-key "\C-cw" 'compare-windows)
+(keymap-global-set "C-c w" 'compare-windows)
 @end group
 @end smallexample
 
@@ -17242,20 +17242,18 @@ Key Bindings
 This also shows how to set a key globally, for all modes.
 
 @cindex Setting a key globally
-@cindex Global set key
+@cindex Keymap global set
 @cindex Key setting globally
-@findex global-set-key
-The command is @code{global-set-key}.  It is followed by the
-key binding.  In a @file{.emacs} file, the keybinding is written as
-shown: @code{\C-c} stands for Control-C, which means to press the
-control key and the @kbd{c} key at the same time.  The @code{w} means
-to press the @kbd{w} key.  The key binding is surrounded by double
-quotation marks.  In documentation, you would write this as
-@w{@kbd{C-c w}}.  (If you were binding a @key{META} key, such as
-@kbd{M-c}, rather than a @key{CTRL} key, you would write
-@w{@code{\M-c}} in your @file{.emacs} file.  @xref{Init Rebinding, ,
-Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
-details.)
+@findex keymap-global-set
+The key setting command is @code{keymap-global-set}.  It is followed by
+the key binding.  In a @file{.emacs} file, the keybinding is written as
+shown: @code{C-c} stands for Control-C, which means to press the control
+key and the @kbd{c} key at the same time.  The @code{w} means to press
+the @kbd{w} key.  The key binding is surrounded by double quotation
+marks.  (If you were binding a @key{META} key, rather than a @key{CTRL}
+key, you would write @w{@code{M-c}} in your @file{.emacs} file.
+@xref{Init Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU
+Emacs Manual}, for details.)
 
 The command invoked by the keys is @code{compare-windows}.  Note that
 @code{compare-windows} is preceded by a single-quote; otherwise, Emacs
@@ -17284,7 +17282,7 @@ Key Bindings
 @group
 ;;; Key binding for 'occur'
 ; I use occur a lot, so let's bind it to a key:
-(global-set-key "\C-co" 'occur)
+(keymap-global-set "C-c o" 'occur)
 @end group
 @end smallexample
 
@@ -17296,7 +17294,7 @@ Key Bindings
 Matching lines are shown in a buffer called @file{*Occur*}.
 That buffer serves as a menu to jump to occurrences.
 
-@findex global-unset-key
+@findex keymap-global-unset
 @cindex Unbinding key
 @cindex Key unbinding
 @need 1250
@@ -17306,7 +17304,7 @@ Key Bindings
 @smallexample
 @group
 ;;; Unbind 'C-x f'
-(global-unset-key "\C-xf")
+(keymap-global-unset "C-x f")
 @end group
 @end smallexample
 
@@ -17324,7 +17322,7 @@ Key Bindings
 @smallexample
 @group
 ;;; Rebind 'C-x C-b' for 'buffer-menu'
-(global-set-key "\C-x\C-b" 'buffer-menu)
+(keymap-global-set "C-x C-b" 'buffer-menu)
 @end group
 @end smallexample
 
@@ -17336,33 +17334,80 @@ Key Bindings
 command, which not only lists the buffers,
 but moves point into that window.
 
+@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 in this
+section can be rewritten using @code{global-set-key} as:
+
+@smallexample
+@group
+(global-set-key "\C-cw" 'compare-windows)
+@end group
+@end smallexample
+
+It is very similar to @code{keymap-global-set}, with the keybinding
+following a slightly different format.  Control-C is represented by
+@code{\C-c}, instead of @code{C-c}.  There is no space between key
+strokes, like @code{\C-c} and @code{w} in this example.  Despite the
+difference, in documentation, this is still written as @w{@kbd{C-c w}}
+for readability.
+
+@findex global-unset-key
+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 key unbinding
+example in this section can be rewritten as:
+
+@smallexample
+@group
+;;; Unbind 'C-x f'
+(global-unset-key "\C-xf")
+@end group
+@end smallexample
+
 @node Keymaps
 @section Keymaps
 @cindex Keymaps
 @cindex Rebinding keys
 
 Emacs uses @dfn{keymaps} to record which keys call which commands.
-When you use @code{global-set-key} to set the key binding for a single
-command in all parts of Emacs, you are specifying the key binding in
-@code{current-global-map}.
+When you use @code{keymap-global-set} to set the key binding for a
+single command in all parts of Emacs, you are specifying the key binding
+in @code{current-global-map}.
 
 Specific modes, such as C mode or Text mode, have their own keymaps;
 the mode-specific keymaps override the global map that is shared by
 all buffers.
 
-The @code{global-set-key} function binds, or rebinds, the global
+The @code{keymap-global-set} function binds, or rebinds, the global
 keymap.  For example, the following binds the key @kbd{C-x C-b} to the
 function @code{buffer-menu}:
 
 @smallexample
-(global-set-key "\C-x\C-b" 'buffer-menu)
+(keymap-global-set "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
+
+Historically, keymaps are bound using a lower-level function,
+@code{define-key}, which is now considered legacy.  While you are
+encouraged to use @code{keymap-set}, you likely would encounter
+@code{define-key} in various places.  The above key binding can be
+rewritten using @code{define-key} as:
 
 @smallexample
 @group
@@ -17396,9 +17441,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
@@ -17440,13 +17485,12 @@ Loading Files
 
 @need 1250
 To replace the key binding for the default
-@code{split-window-vertically}, you must also unset that key and bind
-the keys to @code{split-window-quietly}, like this:
+@code{split-window-vertically}, you must bind the keys to
+@code{split-window-quietly}, like this:
 
 @smallexample
 @group
-(global-unset-key "\C-x2")
-(global-set-key "\C-x2" 'split-window-quietly)
+(keymap-global-set "C-x 2" 'split-window-quietly)
 @end group
 @end smallexample
 
@@ -17608,7 +17652,7 @@ Simple Extension
 this:
 
 @smallexample
-(global-set-key [f6] 'line-to-top-of-window)
+(keymap-global-set "<f6>" 'line-to-top-of-window)
 @end smallexample
 
 For more information, see @ref{Init Rebinding, , Rebinding Keys in
@@ -18791,7 +18835,7 @@ the-the
 
 @group
 ;; Bind 'the-the' to  C-c \
-(global-set-key "\C-c\\" 'the-the)
+(keymap-global-set "C-c \\" 'the-the)
 @end group
 @end smallexample
 
-- 
2.47.1


[-- Attachment #3: Type: text/plain, Size: 10 bytes --]


-- 
Hong