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.  (Bug#74999)

(cherry picked from commit 6d8c3c0cbe42c4b288679456f0eec9a78593e2a5)

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 2fc792298f846ff80a367f649bbca639cde00173..c53eb919283f49fb1fd80383a2c80efb06bdc217 100644 (file)
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -13808,7 +13808,7 @@ syntax table determines which characters these are."
 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
@@ -14760,7 +14760,7 @@ almost the same code as for the recursive version of
 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
@@ -17227,7 +17227,7 @@ Now for some personal 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
 
@@ -17240,20 +17240,18 @@ each window as far as they match.  I use this command all the time.
 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
@@ -17282,7 +17280,7 @@ Here is another key binding, with a comment:
 @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
 
@@ -17294,7 +17292,7 @@ uses the entire buffer.
 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
@@ -17304,7 +17302,7 @@ work:
 @smallexample
 @group
 ;;; Unbind 'C-x f'
-(global-unset-key "\C-xf")
+(keymap-global-unset "C-x f")
 @end group
 @end smallexample
 
@@ -17322,7 +17320,7 @@ The following rebinds an existing key:
 @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
 
@@ -17334,33 +17332,80 @@ window, I prefer the  @code{buffer-menu}
 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
@@ -17394,9 +17439,9 @@ Here is the @code{texinfo-insert-@@group} function definition:
 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
@@ -17438,13 +17483,12 @@ window.
 
 @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
 
@@ -17606,7 +17650,7 @@ I bind @code{line-to-top-of-window} to my @key{F6} function key like
 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
@@ -18789,7 +18833,7 @@ Here is the @code{the-the} function, as I include it in my
 
 @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