From a91b435d0d543f747bbdbd359ab708a3bab67c71 Mon Sep 17 00:00:00 2001
From: Panagiotis Koutsourakis <kutsurak@slartibartfast.net>
Date: Tue, 17 Jan 2023 20:57:41 +0200
Subject: [PATCH] ; Reword user documentation on binding keys in Lisp

* doc/emacs/custom.texi (Init Rebinding): Move the description of
'kbd' farther down.  (Bug#60859)
---
 doc/emacs/custom.texi | 46 +++++++++++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 10 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 91df15a21d7..44c37d3ac83 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1887,22 +1887,29 @@ command is less work to invoke when you really want to.
 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)
 @end example
 
+@cindex key sequence syntax
 @noindent
-The single-quote before the command name, @code{shell}, marks it as a
-constant symbol rather than a variable.  If you omit the quote, Emacs
-would try to evaluate @code{shell} as a variable.  This probably
+The second argument that describes the key sequence, is a string
+containing a series of characters separated by spaces with each
+character corresponding to a key.  Keys with modifiers can be
+specified by prepending the modifier, such as @samp{C-} for Control,
+or @samp{M-} for Meta. Special keys, such as @kbd{TAB} and @kbd{RET},
+can be specified within angle brackets as in @kbd{@key{TAB}} and
+@kbd{@key{RET}}.
+
+  The single-quote before the command name, @code{shell}, marks it as
+a constant symbol rather than a variable.  If you omit the quote,
+Emacs would try to evaluate @code{shell} as a variable.  This probably
 causes an error; it certainly isn't what you want.
 
   Here are some additional examples, including binding function keys
@@ -1920,6 +1927,25 @@ and mouse events:
   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
+There are various ways to specify the key sequence but the simplest is
+to use the function @code{kbd} as shown in the example above.
+@code{kbd} takes a single string argument specifying a key sequence in
+the syntax described earlier for @code{keymap-global-set}.  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.2