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

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

[Panagiotis Koutsourakis]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: 0001-Remove-reference-to-the-kbd-function-from-documentat.patch --]
[-- Type: text/x-patch, Size: 1249 bytes --]

From c0de146a194603a463147a819d96c9f7d0eb61e3 Mon Sep 17 00:00:00 2001
From: Panagiotis Koutsourakis <kutsurak@slartibartfast.net>
Date: Mon, 16 Jan 2023 11:49:05 +0200
Subject: [PATCH] Remove reference to the kbd function from documentation

---
 doc/emacs/custom.texi | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 91df15a21d7..650a96f14b1 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1887,12 +1887,8 @@ 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
+  The simplest way to write a key binding using Lisp is to use the
+@code{keymap-global-set} function.  For example, here's how to bind
 @kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
 
 @example
-- 
2.39.0


[-- Attachment #2: Type: text/plain, Size: 392 bytes --]


Hi emacs devs,

I am attaching a patch to the manual for emacs 29 that removes from the
text a reference to the `kbd' function when creating a key binding in
Lisp. The example that follows is correct (i.e. it works for me), but
the explanation seems outdated.

I think that this change qualifies as "small", but let me know if you
think I need to assign copyright.

-- 
Best regards,
Panos.

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

[Eli Zaretskii]

> From: Panagiotis Koutsourakis <kutsurak@slartibartfast.net>
> Date: Mon, 16 Jan 2023 13:15:22 +0200
> 
> diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
> index 91df15a21d7..650a96f14b1 100644
> --- a/doc/emacs/custom.texi
> +++ b/doc/emacs/custom.texi
> @@ -1887,12 +1887,8 @@ 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
> +  The simplest way to write a key binding using Lisp is to use the
> +@code{keymap-global-set} function.  For example, here's how to bind
>  @kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):

I'm not sure we want to stop talking about 'kbd' in the manual.  How
about just adding the 'keymap-global-set' alternative without removing
'kbd'?

> I think that this change qualifies as "small", but let me know if you
> think I need to assign copyright.

You don't need for this change, but if you intend to contribute to
Emacs in the future, I recommend to start your legal paperwork now, so
that we will have it ready when you submit your next contribution.

If you agree, I will send you the form to fill.

Thanks.

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

[Panagiotis Koutsourakis]

On Mon, Jan 16 2023, Eli Zaretskii wrote:


>> From: Panagiotis Koutsourakis <kutsurak@slartibartfast.net>
>> Date: Mon, 16 Jan 2023 13:15:22 +0200
>> 
>> diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
>> index 91df15a21d7..650a96f14b1 100644
>> --- a/doc/emacs/custom.texi
>> +++ b/doc/emacs/custom.texi
>> @@ -1887,12 +1887,8 @@ 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
>> +  The simplest way to write a key binding using Lisp is to use the
>> +@code{keymap-global-set} function.  For example, here's how to bind
>>  @kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
>
> I'm not sure we want to stop talking about 'kbd' in the manual.  How
> about just adding the 'keymap-global-set' alternative without removing
> 'kbd'?


The reasoning behind the submitted patch is twofold:


Firstly, in the current wording the description is inconsistent with the
example: "The simplest way is to use @code{kbd} function..." but then in
the example `kbd' is not used at all.


Secondly, similar changes happened in the elisp reference manual between
emacs 28 and 29: Compare section 23.15 in emacs 28 with section 23.16 in
emacs 29 (both titled "Commands for Binding Keys"). Moreover, section
23.13 of the same manual in emacs 29 documents the legacy ways to bind
keys and explicitly says that they should not be used in new code.


Having said all that, I have no problem to rewrite it keeping `kbd' both
in text and in a code example, and maybe adding some links to the
relevant sections of the elisp reference. Let me know how I should
proceed.


>
>> I think that this change qualifies as "small", but let me know if you
>> think I need to assign copyright.
>
> You don't need for this change, but if you intend to contribute to
> Emacs in the future, I recommend to start your legal paperwork now, so
> that we will have it ready when you submit your next contribution.
>
> If you agree, I will send you the form to fill.


Sure, that's fine with me. Is this form different than the one mentioned
in the CONTRIBUTE file in the source tree?


Best regards,
Panos.


>
> Thanks.
>
>
>
>

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

[Eli Zaretskii]

> From: Panagiotis Koutsourakis <kutsurak@slartibartfast.net>
> Cc: 60859@debbugs.gnu.org
> Date: Mon, 16 Jan 2023 18:17:11 +0200
> 
> On Mon, Jan 16 2023, Eli Zaretskii wrote:
> 
> > I'm not sure we want to stop talking about 'kbd' in the manual.  How
> > about just adding the 'keymap-global-set' alternative without removing
> > 'kbd'?
> 
> 
> The reasoning behind the submitted patch is twofold:
> 
> 
> Firstly, in the current wording the description is inconsistent with the
> example: "The simplest way is to use @code{kbd} function..." but then in
> the example `kbd' is not used at all.
> 
> 
> Secondly, similar changes happened in the elisp reference manual between
> emacs 28 and 29: Compare section 23.15 in emacs 28 with section 23.16 in
> emacs 29 (both titled "Commands for Binding Keys"). Moreover, section
> 23.13 of the same manual in emacs 29 documents the legacy ways to bind
> keys and explicitly says that they should not be used in new code.
> 
> 
> Having said all that, I have no problem to rewrite it keeping `kbd' both
> in text and in a code example, and maybe adding some links to the
> relevant sections of the elisp reference. Let me know how I should
> proceed.

I prefer to keep the description of 'kbd' in the manual.  We can (and
probably should) reword the text if we are going to the
'keymap-global-set' alternative, and we should probably describe the
latter first.

> >> I think that this change qualifies as "small", but let me know if you
> >> think I need to assign copyright.
> >
> > You don't need for this change, but if you intend to contribute to
> > Emacs in the future, I recommend to start your legal paperwork now, so
> > that we will have it ready when you submit your next contribution.
> >
> > If you agree, I will send you the form to fill.
> 
> 
> Sure, that's fine with me. Is this form different than the one mentioned
> in the CONTRIBUTE file in the source tree?

It isn't, but then you don't need to go fetch it.  Attached, with the
instructions.

Thanks.

----------------------------------------------------------------------
Please email the following information to assign@gnu.org, and we
will send you the assignment form for your past and future changes.

Please use your full legal name (in ASCII characters) as the subject
line of the message.
----------------------------------------------------------------------
REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES

[What is the name of the program or package you're contributing to?]


[Did you copy any files or text written by someone else in these changes?
Even if that material is free software, we need to know about it.]


[Do you have an employer who might have a basis to claim to own
your changes?  Do you attend a school which might make such a claim?]


[For the copyright registration, what country are you a citizen of?]


[What year were you born?]


[Please write your email address here.]


[Please write your postal address here.]





[Which files have you changed so far, and which new files have you written
so far?]

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

[Panagiotis Koutsourakis]

[-- Attachment #1: Type: text/plain, Size: 470 bytes --]

On Mon, Jan 16 2023, Eli Zaretskii wrote:
>
> I prefer to keep the description of 'kbd' in the manual.  We can (and
> probably should) reword the text if we are going to the
> 'keymap-global-set' alternative, and we should probably describe the
> latter first.

Here's a second attempt. I added a brief example using `global-set-key'
and `kbd'. I also added a link to the relevant section in the elisp
reference manual and some findex directives.

Best regards,
Panos.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Reword-user-documentation-on-binding-keys-in-lisp.patch --]
[-- Type: text/x-patch, Size: 2348 bytes --]

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

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

[Robert Pluim]

>>>>> On Tue, 17 Jan 2023 16:20:38 +0200, Panagiotis Koutsourakis <kutsurak@slartibartfast.net> said:
    Panagiotis> +Please note that these functions do not accept a simple string to
    Panagiotis> +specify the binding but need a key sequence. The easiest way to
    Panagiotis> +produce one is to use the function @code{kbd}.  For more details about
    Panagiotis> +binding keys using Lisp @ref{Keymaps,,, elisp, The Emacs Lisp
    Panagiotis> +Reference Manual}.
    Panagiotis> +

Those functions *do* accept simple strings, you just have to write them
a certain way, eg "\C-ca" :-)

How about

--begin--
There are several syntaxes that can be used to specify the binding,
but the simplest and most consistent is the one accepted by
@code{kbd}, which is basically a series of characters separated by
spaces.  Keys with modifiers can be specified by prepending the
modifier, such as @samp{C-} for Control, or @samp{M-} for Meta.  For
example, to bind @samp{C-x} followed by @samp{a}, use

@example
kbd("C-x a")
@end example
--end--

Robert
-- 

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

[Panagiotis Koutsourakis]

On Tue, Jan 17 2023, Robert Pluim wrote:

>>>>>> On Tue, 17 Jan 2023 16:20:38 +0200, Panagiotis Koutsourakis <kutsurak@slartibartfast.net> said:
>     Panagiotis> +Please note that these functions do not accept a simple string to
>     Panagiotis> +specify the binding but need a key sequence. The easiest way to
>     Panagiotis> +produce one is to use the function @code{kbd}.  For more details about
>     Panagiotis> +binding keys using Lisp @ref{Keymaps,,, elisp, The Emacs Lisp
>     Panagiotis> +Reference Manual}.
>     Panagiotis> +
>
> Those functions *do* accept simple strings, you just have to write them
> a certain way, eg "\C-ca" :-)

I would argue that escape sequences complicate strings somewhat :) 

For reference this, is the part from emacs 28.2 I am updating:

> > @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{global-set-key}.  For example, here's how to bind
> > @kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
> >
> > @example
> > (global-set-key (kbd "C-z") 'shell)
> > @end example

The current situation is that the explanation refers to "kbd" as an easy
way to write a key binding, but the code example has changed and makes
no reference to it.

>
> How about
>
> --begin--
> There are several syntaxes that can be used to specify the binding,
> but the simplest and most consistent is the one accepted by
> @code{kbd}, which is basically a series of characters separated by
> spaces.  Keys with modifiers can be specified by prepending the
> modifier, such as @samp{C-} for Control, or @samp{M-} for Meta.  For
> example, to bind @samp{C-x} followed by @samp{a}, use
>
> @example
> kbd("C-x a")
> @end example
> --end--

This goes into some detail for a currently deprecated way to bind keys
(or at least that's what the current lisp reference manual says). 

So, to recap:

1. I think currently there is a documentation bug: "kbd" is mentioned in
text but not used in the example immediately following it.

2. Other documentation sources (emacs lisp reference manual in emacs-29
branch) explicitly state that the preferred way to bind keys in emacs 29
is using "the syntax supported by 'key-valid-p'" and that "[the old
functions] should not be used in new code." (section 23.13 of elisp
reference in emacs-29)

So, assuming that we want the documentation as a whole to be consistent,
I see two ways forward: either we eliminate or reduce the importance of
the old functions in the user manual, or we remove the effective
deprecation of the old functions in the emacs lisp reference manual and
expand on the use of 'kbd', 'global-set-key' and 'define-key'.

What do you think?

Panos.

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

[Robert Pluim]

>>>>> On Tue, 17 Jan 2023 18:09:50 +0200, Panagiotis Koutsourakis <kutsurak@slartibartfast.net> said:


    Panagiotis> The current situation is that the explanation refers to "kbd" as an easy
    Panagiotis> way to write a key binding, but the code example has changed and makes
    Panagiotis> no reference to it.

right

    >> 
    >> How about
    >> 
    >> --begin--
    >> There are several syntaxes that can be used to specify the binding,
    >> but the simplest and most consistent is the one accepted by
    >> @code{kbd}, which is basically a series of characters separated by
    >> spaces.  Keys with modifiers can be specified by prepending the
    >> modifier, such as @samp{C-} for Control, or @samp{M-} for Meta.  For
    >> example, to bind @samp{C-x} followed by @samp{a}, use
    >> 
    >> @example
    >> kbd("C-x a")
    >> @end example
    >> --end--

    Panagiotis> This goes into some detail for a currently deprecated way to bind keys
    Panagiotis> (or at least that's what the current lisp reference manual says). 

    Panagiotis> So, to recap:

    Panagiotis> 1. I think currently there is a documentation bug: "kbd" is mentioned in
    Panagiotis> text but not used in the example immediately following it.

yes

    Panagiotis> 2. Other documentation sources (emacs lisp reference manual in emacs-29
    Panagiotis> branch) explicitly state that the preferred way to bind keys in emacs 29
    Panagiotis> is using "the syntax supported by 'key-valid-p'" and that "[the old
    Panagiotis> functions] should not be used in new code." (section 23.13 of elisp
    Panagiotis> reference in emacs-29)

yes

    Panagiotis> So, assuming that we want the documentation as a whole to be consistent,
    Panagiotis> I see two ways forward: either we eliminate or reduce the importance of
    Panagiotis> the old functions in the user manual, or we remove the effective
    Panagiotis> deprecation of the old functions in the emacs lisp reference manual and
    Panagiotis> expand on the use of 'kbd', 'global-set-key' and 'define-key'.

    Panagiotis> What do you think?

The syntax accepted by the new functions is that of `kbd', so as long
as that syntax is explained somewhere I guess we can remove references
to `kbd' itself.

Robert
-- 

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

[Eli Zaretskii]

> Cc: 60859@debbugs.gnu.org
> From: Panagiotis Koutsourakis <kutsurak@slartibartfast.net>
> Date: Tue, 17 Jan 2023 18:09:50 +0200
> 
> So, assuming that we want the documentation as a whole to be consistent,
> I see two ways forward: either we eliminate or reduce the importance of
> the old functions in the user manual, or we remove the effective
> deprecation of the old functions in the emacs lisp reference manual and
> expand on the use of 'kbd', 'global-set-key' and 'define-key'.
> 
> What do you think?

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.

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

[Panagiotis Koutsourakis]

[-- Attachment #1: Type: text/plain, Size: 1212 bytes --]

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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Reword-user-documentation-on-binding-keys-in-lisp.patch --]
[-- Type: text/x-patch, Size: 3468 bytes --]

From a8d959fed720618c03993311110fa87cf52cf13f 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 | 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

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

[Eli Zaretskii]

> From: Panagiotis Koutsourakis <kutsurak@slartibartfast.net>
> Cc: rpluim@gmail.com,  60859@debbugs.gnu.org
> 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.

Thanks, installed on the emacs-29 branch (with some changes), and
closing the bug.