Subject: bug#60859: [PATCH] Remove reference to the kbd function from documentation

From: Panagiotis Koutsourakis <[email-masked]>
Date: Tue, 17 Jan 2023 21:40:28 +0200

On Tue, Jan 17 2023, Eli Zaretskii wrote:

>
> There's no need to generalize so much.  Let's handle this specific
> issue, and then move on.
>
> For now, I don't want to remove references to 'kbd' from the manual,
> because many people still use it.  So please accept that as the
> baseline, and let's find the best way to describe the new APIs as
> well.

Eli, I am not sure if you saw my earlier message with the second
proposed patch taking into account your feedback from yesterday.
Apologies for any confusion I caused.

Robert raised some valid points in his reply about it:

1. it does not describe accurately the arguments accepted by the old API:
lisp strings and vectors of input events are missing. I think that
pointing the users to the reference manual is enough to remedy this.

2. The syntax accepted by the new API and 'kbd' is not explicit. This
is, I believe, a more serious issue. I don't think that the previous
versions of the manual had an explicit description of it at this point,
but since we are re-examining the section anyway, we should write a few
words. I adapted the description Robert wrote in his e-mail (thank you
Robert!).

I am attaching the patch with these changes.

Panos.

>From a8d959fed720618c03993311110fa87cf52cf13f Mon Sep 17 00:00:00 2001
From: Panagiotis Koutsourakis <[email-masked]>
Date: Tue, 17 Jan 2023 20:57:41 +0200
Subject: [PATCH] ; Reword user documentation on binding keys in lisp

---
 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 @@ 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)
 @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 @@ 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
+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.0