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

From: [email-masked] (GNU bug Tracking System)
Date: Sat, 21 Jan 2023 07:53:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
60859: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=60859
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation
From: Eli Zaretskii <[email-masked]>
To: Panagiotis Koutsourakis <[email-masked]>
Cc: [email-masked], [email-masked]
Date: Sat, 21 Jan 2023 09:52:23 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Panagiotis Koutsourakis <[email-masked]>
> Cc: [email-masked],  [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.

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

Subject: [PATCH] Remove reference to the kbd function from documentation
From: Panagiotis Koutsourakis <[email-masked]>
To: [email-masked]
Date: Mon, 16 Jan 2023 13:15:22 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

>From c0de146a194603a463147a819d96c9f7d0eb61e3 Mon Sep 17 00:00:00 2001
From: Panagiotis Koutsourakis <[email-masked]>
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

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.