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.