From 5f338f0c7cad1898825c9b1b17ae92c08224c5f8 Mon Sep 17 00:00:00 2001
From: Panagiotis Koutsourakis <kutsurak@slartibartfast.net>
Date: Tue, 17 Jan 2023 15:42:35 +0200
Subject: [PATCH] ; Reword user documentation on binding keys in lisp

---
 doc/emacs/custom.texi | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 91df15a21d7..5abe92ed43c 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1887,13 +1887,11 @@ Init Rebinding
 you can specify them in your initialization file by writing Lisp code.
 @xref{Init File}, for a description of the initialization file.
 
-@findex kbd
-  There are several ways to write a key binding using Lisp.  The
-simplest is to use the @code{kbd} function, which converts a textual
-representation of a key sequence---similar to how we have written key
-sequences in this manual---into a form that can be passed as an
-argument to @code{keymap-global-set}.  For example, here's how to bind
-@kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
+@findex keymap-global-set
+  The recommended way to write a key binding using Lisp is to use one
+of the @code{keymap-global-set}, or @code{keymap-set} functions.  For
+example, here's how to bind @kbd{C-z} to the @code{shell} command in
+the global keymap (@pxref{Interactive Shell}):
 
 @example
 (keymap-global-set "C-z" 'shell)
@@ -1920,6 +1918,24 @@ Init Rebinding
   Language and coding systems may cause problems with key bindings for
 non-@acronym{ASCII} characters.  @xref{Init Non-ASCII}.
 
+@findex global-set-key
+@findex define-key
+  Alternatively you can use the low level functions @code{define-key}
+and @code{global-set-key}.  For example to bind @kbd{C-z} to the
+@code{shell} command as in the above example, use:
+
+@example
+(global-set-key (kbd "C-z") 'shell)
+@end example
+
+@findex kbd
+@noindent
+Please note that these functions do not accept a simple string to
+specify the binding but need a key sequence. The easiest way to
+produce one is to use the function @code{kbd}.  For more details about
+binding keys using Lisp @ref{Keymaps,,, elisp, The Emacs Lisp
+Reference Manual}.
+
 @findex keymap-set
 @findex keymap-unset
   As described in @ref{Local Keymaps}, major modes and minor modes can
-- 
2.39.0