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

[Hong Xu <hong@topbug.net>]

* Since `define-key' is considered legacy and we encourage `keymap-set'
  now.
---
 doc/lispintro/emacs-lisp-intro.texi | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 49916235fbf9..b3b4141a3c5f 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -17358,11 +17358,22 @@ 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.  Historically, keymaps
+are bound using a lower-level function, @code{define-key}, which
+is now considered legacy.  The above key binding can be rewritten using
+@code{define-key} as:
 
 @smallexample
 @group
@@ -17396,9 +17407,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