GNU bug report logs - #60859
[PATCH] Remove reference to the kbd function from documentation

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 60859 in the body.
You can then email your comments to 60859 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Remove reference to the kbd function from documentation
Date: Mon, 16 Jan 2023 13:15:22 +0200

[0001-Remove-reference-to-the-kbd-function-from-documentat.patch (text/x-patch, attachment)]

[Message part 2 (text/plain, inline)]

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.

Message #8 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
Cc: 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Mon, 16 Jan 2023 16:47:32 +0200

> From: Panagiotis Koutsourakis <kutsurak <at> 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.

Message #11 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
Cc: 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Mon, 16 Jan 2023 18:56:37 +0200

> From: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
> Cc: 60859 <at> 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 <at> 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?]

Message #14 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Mon, 16 Jan 2023 18:17:11 +0200

On Mon, Jan 16 2023, Eli Zaretskii wrote:


>> From: Panagiotis Koutsourakis <kutsurak <at> 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.
>
>
>
>

Message #17 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
To: 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Tue, 17 Jan 2023 16:20:38 +0200

[Message part 1 (text/plain, inline)]

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.

[0001-Reword-user-documentation-on-binding-keys-in-lisp.patch (text/x-patch, attachment)]

Message #20 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
Cc: 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Tue, 17 Jan 2023 15:56:27 +0100

>>>>> On Tue, 17 Jan 2023 16:20:38 +0200, Panagiotis Koutsourakis <kutsurak <at> 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
-- 

Message #23 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Tue, 17 Jan 2023 18:09:50 +0200

On Tue, Jan 17 2023, Robert Pluim wrote:

>>>>>> On Tue, 17 Jan 2023 16:20:38 +0200, Panagiotis Koutsourakis <kutsurak <at> 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.

Message #26 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
Cc: 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Tue, 17 Jan 2023 18:16:54 +0100

>>>>> On Tue, 17 Jan 2023 18:09:50 +0200, Panagiotis Koutsourakis <kutsurak <at> 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
-- 

Message #29 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
Cc: rpluim <at> gmail.com, 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Tue, 17 Jan 2023 19:32:34 +0200

> Cc: 60859 <at> debbugs.gnu.org
> From: Panagiotis Koutsourakis <kutsurak <at> 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.

Message #32 received at 60859 <at> debbugs.gnu.org (full text, mbox):

From: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: rpluim <at> gmail.com, 60859 <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Tue, 17 Jan 2023 21:40:28 +0200

[Message part 1 (text/plain, inline)]

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.

[0001-Reword-user-documentation-on-binding-keys-in-lisp.patch (text/x-patch, attachment)]

Message #37 received at 60859-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
Cc: rpluim <at> gmail.com, 60859-done <at> debbugs.gnu.org
Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from
 documentation
Date: Sat, 21 Jan 2023 09:52:23 +0200

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.