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.
>
>
>
>