From unknown Wed Jun 18 23:03:53 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#60859 <60859@debbugs.gnu.org> To: bug#60859 <60859@debbugs.gnu.org> Subject: Status: [PATCH] Remove reference to the kbd function from documentation Reply-To: bug#60859 <60859@debbugs.gnu.org> Date: Thu, 19 Jun 2025 06:03:53 +0000 retitle 60859 [PATCH] Remove reference to the kbd function from documentati= on reassign 60859 emacs submitter 60859 Panagiotis Koutsourakis severity 60859 normal tag 60859 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 16 07:03:12 2023 Received: (at submit) by debbugs.gnu.org; 16 Jan 2023 12:03:12 +0000 Received: from localhost ([127.0.0.1]:60646 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHOCl-00062E-VY for submit@debbugs.gnu.org; Mon, 16 Jan 2023 07:03:12 -0500 Received: from lists.gnu.org ([209.51.188.17]:37024) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHNSg-0002G3-4w for submit@debbugs.gnu.org; Mon, 16 Jan 2023 06:15:34 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHNSf-00073b-F6 for bug-gnu-emacs@gnu.org; Mon, 16 Jan 2023 06:15:33 -0500 Received: from wout4-smtp.messagingengine.com ([64.147.123.20]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHNSa-0005ro-Sx for bug-gnu-emacs@gnu.org; Mon, 16 Jan 2023 06:15:33 -0500 Received: from compute3.internal (compute3.nyi.internal [10.202.2.43]) by mailout.west.internal (Postfix) with ESMTP id 987BA32004E7 for ; Mon, 16 Jan 2023 06:15:25 -0500 (EST) Received: from mailfrontend1 ([10.202.2.162]) by compute3.internal (MEProxy); Mon, 16 Jan 2023 06:15:25 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= slartibartfast.net; h=cc:content-type:date:date:from:from :in-reply-to:message-id:mime-version:reply-to:sender:subject :subject:to:to; s=fm1; t=1673867725; x=1673954125; bh=5EFXDkvq+g gpva0GX55yLE53RSmus5rNu6FRe8xyFkg=; b=mkkfelngwGhFwyPGxoYdCe2Uxr FksCq7BQcQM/USsli24yo48sjxyuvku+O3KBCZCvftxLXG9ruu1Bzf9nJWKMtqP/ KlID89or5l2iF5P27PzpIqPriK+2FZRik+RhNGx6Oj2ybLKunh9AHSpFV0+6v/C/ mtCKbPm42i77JtkX6oy4F65ghSMSjkIC+b4wK1zzeRsL+CKv/V7l62Zh1LFKcLO7 0fEbMSI4VxOzPTc+cNHuNjoXOu4Rm0GmEvDn6ttSTtl5D8h9rT+awUkQTRV1TTqG vfUshnoB10XmwvtYznO08aG/ebhGjrSm7TSAu8ehgNxxn05YpVFp9gnVsPCw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-type:date:date:feedback-id :feedback-id:from:from:in-reply-to:message-id:mime-version :reply-to:sender:subject:subject:to:to:x-me-proxy:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm3; t=1673867725; x= 1673954125; bh=5EFXDkvq+ggpva0GX55yLE53RSmus5rNu6FRe8xyFkg=; b=r s06/H8GyFyAwWcQV+XnVHV17dDJKSsvdhZ7Vl6CUDYA7ZMxR23pmIDfWguehFAvQ 705FKWG3tiNFMWv/XZJW94Y6Ia3brfzAvQFoVWAcp4jWSNZlt55mTeJWJ8R+lDXG gHX1yRq6nQFAj0qpG8c79tFOYS0HkrsHKYWcUXgUO/qmX8i6vfh+x+E4hpfNfKnV WX3GZOi7vtQzliY/l47ZgoCmv8wuy52j8CLmprKCR8N5LI6Nt2KjqM//wiXz5HmS RG2Cp/UtVFg61RKOHp5PR7xujoOoG/y0dlqfKYc6nZFAN88JJoL5j5uUgNuYNYx1 Sqtjg8owQhhF8TxOtcuWw== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedruddtgedgvdehucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefhvffufffkfgggtgesmhdtreertd ertdenucfhrhhomheprfgrnhgrghhiohhtihhsucfmohhuthhsohhurhgrkhhishcuoehk uhhtshhurhgrkhesshhlrghrthhisggrrhhtfhgrshhtrdhnvghtqeenucggtffrrghtth gvrhhnpedvudeviefggeelgeffleelfffgjedttdegudejfeehieejvdehjedujefgudek ieenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehkuh htshhurhgrkhesshhlrghrthhisggrrhhtfhgrshhtrdhnvght X-ME-Proxy: Feedback-ID: iaac9463b:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA for ; Mon, 16 Jan 2023 06:15:24 -0500 (EST) From: Panagiotis Koutsourakis To: bug-gnu-emacs@gnu.org Subject: [PATCH] Remove reference to the kbd function from documentation Date: Mon, 16 Jan 2023 13:15:22 +0200 Message-ID: <87pmbeivcl.fsf@panoramix.zarniwoop.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=64.147.123.20; envelope-from=kutsurak@slartibartfast.net; helo=wout4-smtp.messagingengine.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.6 (-) X-Debbugs-Envelope-To: submit X-Mailman-Approved-At: Mon, 16 Jan 2023 07:03:10 -0500 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.6 (--) --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Remove-reference-to-the-kbd-function-from-documentat.patch >From c0de146a194603a463147a819d96c9f7d0eb61e3 Mon Sep 17 00:00:00 2001 From: Panagiotis Koutsourakis 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 --=-=-= Content-Type: text/plain 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. --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 16 09:47:37 2023 Received: (at 60859) by debbugs.gnu.org; 16 Jan 2023 14:47:37 +0000 Received: from localhost ([127.0.0.1]:32807 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHQls-0000jj-Jz for submit@debbugs.gnu.org; Mon, 16 Jan 2023 09:47:36 -0500 Received: from eggs.gnu.org ([209.51.188.92]:51870) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHQlo-0000jG-9Z for 60859@debbugs.gnu.org; Mon, 16 Jan 2023 09:47:32 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHQlh-0000dK-CS; Mon, 16 Jan 2023 09:47:26 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=o2TcFBIFPGEXMyYt0U5OX1IjDnX+smxd87j07YHSHGA=; b=BTPqcEuRjZV9 50Je5uUqEsXaBPmshx+KUJ03Xch2W7ug+T6aNAnYbIPqDcmEV3pc5d3YCZM1l63pA1Vm2Cyr7Pqeq d8Tzb3hhcR0X0m0tukTu/hDjv0HAFSVoRiQDInDyk8B0aVJXgrMgKHzWiM4Ak78Tz8lkS7KQCcKv4 tEsdIkGt1d3g3qtfuh4xNzSYPylx9z27gw0hi2aoT2LlhmNg2/8vbrddO3IQAHMaDfWDJfa25qkPL KWFZWVvGw116Hl8juuSYcwS7RATC0QdImje/S/duHaZu4OK3JPAPAuUgbntIrEE57mThQUcSJtz1P WPuZoEjdfCTxQ7U3afwDzg==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHQlg-0000vD-9o; Mon, 16 Jan 2023 09:47:25 -0500 Date: Mon, 16 Jan 2023 16:47:32 +0200 Message-Id: <83ilh64juj.fsf@gnu.org> From: Eli Zaretskii To: Panagiotis Koutsourakis In-Reply-To: <87pmbeivcl.fsf@panoramix.zarniwoop.org> (message from Panagiotis Koutsourakis on Mon, 16 Jan 2023 13:15:22 +0200) Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 60859 Cc: 60859@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Panagiotis Koutsourakis > 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. From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 16 11:56:37 2023 Received: (at 60859) by debbugs.gnu.org; 16 Jan 2023 16:56:37 +0000 Received: from localhost ([127.0.0.1]:34540 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHSmj-00070H-5L for submit@debbugs.gnu.org; Mon, 16 Jan 2023 11:56:37 -0500 Received: from eggs.gnu.org ([209.51.188.92]:58718) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHSmh-000703-84 for 60859@debbugs.gnu.org; Mon, 16 Jan 2023 11:56:36 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHSmb-0006YR-S9; Mon, 16 Jan 2023 11:56:29 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=vMCEA8cDJ0LLehdbfgj6oKqiNhy1uWJk2Fb/FG6KXhc=; b=amrXzI4NSMFb 9edpwbmq2Ixsvlil9s7tnglZaNwvz1DnNdFSd/D/a9Dw0z/SLOWyVKcLd3AZbCj84iDoXQT9PUeyY kXbQdc68vXqJqlc0LGiKFeXCoTJQC9ijckSS31cKK2FfwBrEwSAbUeWYUu3+It1aln71yj3VaY70q 9WoisGFtTt9EcT/zOddWkKuzKMkOuhov1xxnjAKhp/S3EfcW2ZCGCEQ/jt/kD/DgLTf2r1HjxPKZT jhkh/WdF1QkstikbHbe6ZlpvZ34X16IBvyuk1yDNmxbfdLBTjXLSVRqwO5XuQNwdxawmrKX9iOYAZ +V8LYLcYjeuE1dLdNfZJBg==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHSmb-0005IX-0z; Mon, 16 Jan 2023 11:56:29 -0500 Date: Mon, 16 Jan 2023 18:56:37 +0200 Message-Id: <83cz7e4dve.fsf@gnu.org> From: Eli Zaretskii To: Panagiotis Koutsourakis In-Reply-To: <87o7qyo3nc.fsf@panoramix.zarniwoop.org> (message from Panagiotis Koutsourakis on Mon, 16 Jan 2023 18:17:11 +0200) Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> <87o7qyo3nc.fsf@panoramix.zarniwoop.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 60859 Cc: 60859@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Panagiotis Koutsourakis > 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?] From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 16 12:51:19 2023 Received: (at 60859) by debbugs.gnu.org; 16 Jan 2023 17:51:19 +0000 Received: from localhost ([127.0.0.1]:34653 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHTdc-0008U5-Es for submit@debbugs.gnu.org; Mon, 16 Jan 2023 12:51:19 -0500 Received: from out4-smtp.messagingengine.com ([66.111.4.28]:48159) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHSAj-0003dC-1y for 60859@debbugs.gnu.org; Mon, 16 Jan 2023 11:17:22 -0500 Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailout.nyi.internal (Postfix) with ESMTP id F0C365C0229; Mon, 16 Jan 2023 11:17:14 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute5.internal (MEProxy); Mon, 16 Jan 2023 11:17:14 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= slartibartfast.net; h=cc:cc:content-type:date:date:from:from :in-reply-to:in-reply-to:message-id:mime-version:references :reply-to:sender:subject:subject:to:to; s=fm1; t=1673885834; x= 1673972234; bh=ReOPxjPojHbP7CR0uOIuQAEnPOXvZSoDPjsy11qHWh8=; b=e irNkZO8MIvv2xwXHUG6kXvoQNairwe9yo5+CoUS1bY2lUPHK5p0NxXs9P3hMK9wj GselOEy4Os0yl19yUzqa8FLwbA4nVzkt02LCeZeUlC40FcddmsALrH1XZhehVpsP lfxZOFzVqfzcaHWMEwIUzWd7CQT2ZlCSNZLZpRJUFkkBVg61ZmWIE0KVj8j+KNX0 oiFNnw7WKJ07HVR/7B17OB0qa5dCZQlIxUCJB9f9YF4zxLfwXVhT4Xa41WMZbpAa pT3Vu+XvQP0gOCLStlIr22Befkikmu1zLZtZMWNlkEewOpX06i8FvfexmTy72iAc BKVjLynf8/ZeI1ZSc0jtA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:date:date:feedback-id :feedback-id:from:from:in-reply-to:in-reply-to:message-id :mime-version:references:reply-to:sender:subject:subject:to:to :x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1673885834; x=1673972234; bh=ReOPxjPojHbP7CR0uOIuQAEnPOXv ZSoDPjsy11qHWh8=; b=dHMhng73V2rUIWHNInrgk0ucu+6ituf9BBB5JzEuJ3a0 7FvMwcap2bsaJ+Z47oOCkSrZEl/peqKsw1eCM4nGyQ3OyW+Ct0btVXbI79eyfweU mbjm1PEcC1wdhDrOnT+pEak/XjysFx2VM28cSXbXubIRg2cMGPPpdEazuskPpO9G a9tJ4aEsTGjPyJQ5hQY/auOf7jJAMzQJZEymB22zkqD5i2+umn8lAiNIW8n3UVPw NmMgREKwMGz6F0I+voM99+lZNvSLUDJ6F9BaMRDAL8CiBTmajNmRjkDKL8oo8eaJ gBUAhzZN2HTHxE1IAkW4wp+BrgfKrfQ06NdbgxvD6g== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedruddtgedgkeeiucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvvefujghffffkfgggtgesthdtredttdertdenucfhrhhomheprfgrnhgr ghhiohhtihhsucfmohhuthhsohhurhgrkhhishcuoehkuhhtshhurhgrkhesshhlrghrth hisggrrhhtfhgrshhtrdhnvghtqeenucggtffrrghtthgvrhhnpeduhfeiffekuedvheej ueegiedtheffueeigeetleetteekudfhudegtdegheeiveenucevlhhushhtvghrufhiii gvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehkuhhtshhurhgrkhesshhlrghrthhi sggrrhhtfhgrshhtrdhnvght X-ME-Proxy: Feedback-ID: iaac9463b:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Mon, 16 Jan 2023 11:17:14 -0500 (EST) From: Panagiotis Koutsourakis To: Eli Zaretskii Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation In-Reply-To: <83ilh64juj.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 16 Jan 2023 16:47:32 +0200") References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> Date: Mon, 16 Jan 2023 18:17:11 +0200 Message-ID: <87o7qyo3nc.fsf@panoramix.zarniwoop.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 60859 X-Mailman-Approved-At: Mon, 16 Jan 2023 12:51:15 -0500 Cc: 60859@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) On Mon, Jan 16 2023, Eli Zaretskii wrote: >> From: Panagiotis Koutsourakis >> 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. > > > > From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 09:21:00 2023 Received: (at 60859) by debbugs.gnu.org; 17 Jan 2023 14:21:00 +0000 Received: from localhost ([127.0.0.1]:36169 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHmpg-0000oN-BE for submit@debbugs.gnu.org; Tue, 17 Jan 2023 09:21:00 -0500 Received: from wout2-smtp.messagingengine.com ([64.147.123.25]:43565) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHmpe-0000o9-9N for 60859@debbugs.gnu.org; Tue, 17 Jan 2023 09:20:59 -0500 Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailout.west.internal (Postfix) with ESMTP id F159C3200033 for <60859@debbugs.gnu.org>; Tue, 17 Jan 2023 09:20:51 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute1.internal (MEProxy); Tue, 17 Jan 2023 09:20:52 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= slartibartfast.net; h=cc:content-type:date:date:from:from :in-reply-to:in-reply-to:message-id:mime-version:references :reply-to:sender:subject:subject:to:to; s=fm1; t=1673965251; x= 1674051651; bh=jTfegDTmFoHWTnyZ57FmjSAeWy4t+GoKFqrJw5pFrxI=; b=T ShGoR2CYYssMZUjPuHtZj8aNGOVYtuP2IY1SIG75jQzlgXWfHnC7w9HbKRA7FM70 3Dp3m68VvAV5588JyS4OkQVebRUhxe3pdUcaDr43zgumSgIJWqosNuK0YD47hqvc Y685ILErD3AeK/dIhBqthE/CRaEneea95C36V/QYIfC2jz70d8SiMZ3/1xbBD6tn KfDqEGoPkGy+sLk16T2G2p90VuQ/0SshauQwg2/DZe082H10+68mponj73rbsrte jj8q6f9OGXeJkgMpsVVlSb7lAOwAX0eo6fVAYXjjWpZaf3Vfm2qgZqeP76YgO1Oq PITAXe8X6bo9JpPZVQKNg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-type:date:date:feedback-id :feedback-id:from:from:in-reply-to:in-reply-to:message-id :mime-version:references:reply-to:sender:subject:subject:to:to :x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1673965251; x=1674051651; bh=jTfegDTmFoHWTnyZ57FmjSAeWy4t +GoKFqrJw5pFrxI=; b=SxkI/WEam2lpz16zLW3rc76kQblJHJ6gFD9rVv53pNLZ tkkmADvsvtMlORQm4fdCXkepK/79w9DawC2K6/FeDEy2z4w31j+Hv8tDTBZTq+/U Kem0jicQ+OfR8mbgS8FRAY0TSDSshn/Ng7qJObOifAuj4TYsKs8MTAGJlhbGVsdL H//ORXz3McDEalj7M2ZXFKIoCAEujRnt3bap5HZonEeGlUivFKKUbJoWhAfIPfSH 7z4hAT4Y47OC+ltGH2MXy8cbOLDOMvkP70+x9gTsDX+LW9H03QnWIUvoOpFRsGiY YrQl/FzXegB529+FVs/rmq4VJE63skm6PjF0q9QalQ== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedruddtiedgieduucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefhvffujghffffkfgggtgesmhdtre ertdertdenucfhrhhomheprfgrnhgrghhiohhtihhsucfmohhuthhsohhurhgrkhhishcu oehkuhhtshhurhgrkhesshhlrghrthhisggrrhhtfhgrshhtrdhnvghtqeenucggtffrrg htthgvrhhnpeetfeevteevhfegkeejheegheekgfdvffduhfeigedtleehfeegudekleet jeejfeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpe hkuhhtshhurhgrkhesshhlrghrthhisggrrhhtfhgrshhtrdhnvght X-ME-Proxy: Feedback-ID: iaac9463b:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA for <60859@debbugs.gnu.org>; Tue, 17 Jan 2023 09:20:50 -0500 (EST) From: Panagiotis Koutsourakis To: 60859@debbugs.gnu.org Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation In-Reply-To: <83cz7e4dve.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 16 Jan 2023 18:56:37 +0200") References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> <87o7qyo3nc.fsf@panoramix.zarniwoop.org> <83cz7e4dve.fsf@gnu.org> Date: Tue, 17 Jan 2023 16:20:38 +0200 Message-ID: <87edrt6y4p.fsf@panoramix.zarniwoop.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 60859 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Reword-user-documentation-on-binding-keys-in-lisp.patch >From 5f338f0c7cad1898825c9b1b17ae92c08224c5f8 Mon Sep 17 00:00:00 2001 From: Panagiotis Koutsourakis 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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 09:56:39 2023 Received: (at 60859) by debbugs.gnu.org; 17 Jan 2023 14:56:39 +0000 Received: from localhost ([127.0.0.1]:37891 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHnOA-0002Cb-RV for submit@debbugs.gnu.org; Tue, 17 Jan 2023 09:56:39 -0500 Received: from mail-wr1-f54.google.com ([209.85.221.54]:46021) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHnO7-0002CO-5S for 60859@debbugs.gnu.org; Tue, 17 Jan 2023 09:56:37 -0500 Received: by mail-wr1-f54.google.com with SMTP id h16so30845462wrz.12 for <60859@debbugs.gnu.org>; Tue, 17 Jan 2023 06:56:35 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:from:to:cc:subject:date:message-id:reply-to; bh=srG8hapxzWxRaTC6J42SSp++PT/C06/CjSLco1RW+V0=; b=SccCOI5vxcl8Gj1keyG41+WebDuoAMBAa308xNi29w9ur2ldeEg722boMWoCbeIHuZ QnM14q2Km9B5ofdDNt8KOIAbbiuWCoN2zT/UM9QhD4kCsgpat4foMpDl00zwDT6tBB0V tNLFZyd72jRhPcjwWyGPTDhdRR9Mn3lQ+/frKWy8HgWZInyWvWIFV9s5kHhK04IFTr8r H0IdDs1+C4jHpmBMGcNFsO5fltOg9pAOfHg3604zSdCLgpduj4yRV2RqeYufbA2PJPzF vUavSAvb4khBjb9pxjFWhbQKo1vn+lRYNqcJ0MQs+JoL/+VH3Jazrd0EcpyG8Kpse/I8 U6fw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=srG8hapxzWxRaTC6J42SSp++PT/C06/CjSLco1RW+V0=; b=Aqok64c5jHmyISDZfO/RaAbSVOObxyDzAOJzQQLcU7U/xWEDIoKdrQ1b0JbXAEaiV0 dJeJAKPHGhuBaQbNKDa99XiRTK64f+Jh0TyOHGlwN12KjNQrK4TnZJyxkIvyl2jeeeLq Iqrut/EfP4lH2b9HJpKZDJbL/okVMLxn7uoUI8wL3Q5GS2nymm4DLrtonf9jOWdfPc4U dNGioId4TH4QIsOqwfDdTItbmJoeTVBPdoPg6vHt/uygWWqoGz1mexweZjMfsieuleOm TDEAsjRCIGBQ8WS5cENHvI7tqcxd8yDO/yeskLb1LQAfbTYRH+/ye2cLhS7d+lWt0JV+ yq6Q== X-Gm-Message-State: AFqh2kr66XuqkIuoE0axAxSf49d9fR6UCe04xwzmO/pZZbF+6h3VW4JS zzn61DmVEC//bg56wEnAUkvFMw5mp38= X-Google-Smtp-Source: AMrXdXuKQRQrsIfn0UWw1GyNt9cAA+uv2G4JxfxQyxotjw5jQRUaPxuQxaOEoTvkppWOLkvDIugoHw== X-Received: by 2002:a5d:4b46:0:b0:2bd:be3b:49f4 with SMTP id w6-20020a5d4b46000000b002bdbe3b49f4mr3328278wrs.22.1673967388538; Tue, 17 Jan 2023 06:56:28 -0800 (PST) Received: from rltb ([82.66.8.55]) by smtp.gmail.com with ESMTPSA id i15-20020a05600011cf00b00294176c2c01sm28643309wrx.86.2023.01.17.06.56.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 17 Jan 2023 06:56:27 -0800 (PST) From: Robert Pluim To: Panagiotis Koutsourakis Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation In-Reply-To: <87edrt6y4p.fsf@panoramix.zarniwoop.org> (Panagiotis Koutsourakis's message of "Tue, 17 Jan 2023 16:20:38 +0200") References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> <87o7qyo3nc.fsf@panoramix.zarniwoop.org> <83cz7e4dve.fsf@gnu.org> <87edrt6y4p.fsf@panoramix.zarniwoop.org> Date: Tue, 17 Jan 2023 15:56:27 +0100 Message-ID: <875yd5ciqs.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 60859 Cc: 60859@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) >>>>> On Tue, 17 Jan 2023 16:20:38 +0200, Panagiotis Koutsourakis 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 -- From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 11:10:02 2023 Received: (at 60859) by debbugs.gnu.org; 17 Jan 2023 16:10:03 +0000 Received: from localhost ([127.0.0.1]:38060 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHoXC-0000QZ-3C for submit@debbugs.gnu.org; Tue, 17 Jan 2023 11:10:02 -0500 Received: from wout4-smtp.messagingengine.com ([64.147.123.20]:42581) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHoXA-0000Q9-8N for 60859@debbugs.gnu.org; Tue, 17 Jan 2023 11:10:01 -0500 Received: from compute3.internal (compute3.nyi.internal [10.202.2.43]) by mailout.west.internal (Postfix) with ESMTP id 8EAE6320095A; Tue, 17 Jan 2023 11:09:53 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute3.internal (MEProxy); Tue, 17 Jan 2023 11:09:53 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= slartibartfast.net; h=cc:cc:content-type:date:date:from:from :in-reply-to:in-reply-to:message-id:mime-version:references :reply-to:sender:subject:subject:to:to; s=fm1; t=1673971793; x= 1674058193; bh=lKEauVmCl3qDjESn20MT5Fqhb6Gsnen8MAgWIWGwROA=; b=Z dEKAQj0CVkEOdhhon9zYZf7Mx3mVmMy19dpOid0bubYw98u2DITZzpQ9TlaoRQFw xTi8oZenfcdgFDQ64NlTVNzG2zaNkA7szD2ktJKqFeFhUHCJH3I/+wx/zdn/0Bgf CagEotB4qaPC3irppeiH4cJrcEBAXpxLQFQnwqrqHt/8uOztEy9kYn/tS9vCDCKU WvMrK2LZZcCsFP9o6o0cfxMS3PD1GrAvUVUguLezVjgiDXcFYmjQJwahFn7NbIH+ GM2UPC8ddsBXOY7zhQ8qpuWMee9LVrD0ayUAjAl/4uUJZK7+WM7VlAvIL63dhzxi 8jFcaZNGMsxyIIQwEPlvg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:date:date:feedback-id :feedback-id:from:from:in-reply-to:in-reply-to:message-id :mime-version:references:reply-to:sender:subject:subject:to:to :x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1673971793; x=1674058193; bh=lKEauVmCl3qDjESn20MT5Fqhb6Gs nen8MAgWIWGwROA=; b=Magj6Q3wAAI45gfzusEEFdPydeLChFxcW+I47HSxKocj 136WWBqhdxuviEsbM3dK/irbQs4dH12pb6ebLRJn6fVYhKuJM9GN+mYhh+F9FzRl k01rnVPqjhiGv+51m85CH6T7xNOcOyBKBprBumgffUAUoUPczq48+RhwDm6esCi0 EifLSL+qT75uE0IweOeJVSeiaTEztK/ZY1OjGWWfZdJU6haSNrMlHEXGs0j/KRw1 OywGSGX5uOyPdxoJOGQwkx8xJAyU385OyfQgZ/XwCJl6ceG9ZCxw9rYRrzNTfNe0 qypcHCDmLsq2ZbZJb7ASUtqS5mY6XbcvjKDh75lPWw== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedruddtiedgkedvucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvvefujghffffkfgggtgesthdtredttdertdenucfhrhhomheprfgrnhgr ghhiohhtihhsucfmohhuthhsohhurhgrkhhishcuoehkuhhtshhurhgrkhesshhlrghrth hisggrrhhtfhgrshhtrdhnvghtqeenucggtffrrghtthgvrhhnpeduhfeiffekuedvheej ueegiedtheffueeigeetleetteekudfhudegtdegheeiveenucevlhhushhtvghrufhiii gvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehkuhhtshhurhgrkhesshhlrghrthhi sggrrhhtfhgrshhtrdhnvght X-ME-Proxy: Feedback-ID: iaac9463b:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 17 Jan 2023 11:09:52 -0500 (EST) From: Panagiotis Koutsourakis To: Robert Pluim Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation In-Reply-To: <875yd5ciqs.fsf@gmail.com> (Robert Pluim's message of "Tue, 17 Jan 2023 15:56:27 +0100") References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> <87o7qyo3nc.fsf@panoramix.zarniwoop.org> <83cz7e4dve.fsf@gnu.org> <87edrt6y4p.fsf@panoramix.zarniwoop.org> <875yd5ciqs.fsf@gmail.com> Date: Tue, 17 Jan 2023 18:09:50 +0200 Message-ID: <87fsc9jg6p.fsf@panoramix.zarniwoop.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 60859 Cc: 60859@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) On Tue, Jan 17 2023, Robert Pluim wrote: >>>>>> On Tue, 17 Jan 2023 16:20:38 +0200, Panagiotis Koutsourakis 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. From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 12:17:04 2023 Received: (at 60859) by debbugs.gnu.org; 17 Jan 2023 17:17:04 +0000 Received: from localhost ([127.0.0.1]:38111 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHpa4-00024T-7G for submit@debbugs.gnu.org; Tue, 17 Jan 2023 12:17:04 -0500 Received: from mail-wm1-f48.google.com ([209.85.128.48]:42921) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHpa1-00023s-4n for 60859@debbugs.gnu.org; Tue, 17 Jan 2023 12:17:02 -0500 Received: by mail-wm1-f48.google.com with SMTP id f25-20020a1c6a19000000b003da221fbf48so8715759wmc.1 for <60859@debbugs.gnu.org>; Tue, 17 Jan 2023 09:17:01 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:from:to:cc:subject:date:message-id:reply-to; bh=uRiCSDz+dtdl8EZAD4EziAPIKISWol28wbg63tiGvvU=; b=Ishusrr0DKegixMyaZZ9+qjzKAjgtqN0ggE9VedMNOWkdCW2p9DADU940U5tdUewxr K9NhHiKuUbhk1buQvVop/lePD3w7kWF32uShIdnuilaZbIJEG1F3wm/Amjn9KCFmjG8/ FrpSE/iGXl77rn3tpX/GyeJeezqXorQbpgrA30WmgxVq2sUMX6ovpi2J41AWL0yo0CgO HLelrkXU2/uajipXjCk7GNuxc7udpMkk6Htq5CWcY2RZFeXVg6JaWYQ5vUO20uufoX3G bkFAzVvLmLe4eVCYucITwo2zJPXi8tRsaTZDoerVS9yF+cVb60y+IHT7gk1Zw6maMK0h LgHg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=uRiCSDz+dtdl8EZAD4EziAPIKISWol28wbg63tiGvvU=; b=2hyPC7O4IUuxeBYzcLWfoO4X1Bjx1fIcgzXkMmM6EvUVj6xnBMKBoyno6uXxWh8Xnt zEYeRYJPDGyYDDShEEYR9FKr1gk91ffWFTpo5EAdoo4vZqXjCPDvOGeDAEtuJ82mTR4j 3CSxFPKZMfngbSJN5nsb6cRS6XrHTUr2rPzsVpV9trQnpMBL9L0LBZ1AhQ7JzEPUXMH1 xgtPBKUqQLyfcFPzYh2QdbuB3WM5EmWKcN33/sNmT0XQZBtPrL8vAQ7E16KApK6Xtq6U WfoRgYkziDnCO9X/cwO/8CWVaCiSMTDwKaivPwsl2xSK7hZ9pmv+3upJmJSr9y1LV2Fp rW5g== X-Gm-Message-State: AFqh2kqkFxQ2vDP231KP3+tLmuk2NXNY+wWb3JgW6wq4rbAm4rSP9NST 8CDc8JsvF4NfSWY7DIaOl8AF1qt5A4s= X-Google-Smtp-Source: AMrXdXvbGiOTK23K0hoihJ5ov1WQrO9DNEto0GQ01QYsxVW+OTf0yZcgy8eqsTz+70yajXpZQw2CqQ== X-Received: by 2002:a05:600c:3596:b0:3da:1357:4ca2 with SMTP id p22-20020a05600c359600b003da13574ca2mr3886736wmq.11.1673975815182; Tue, 17 Jan 2023 09:16:55 -0800 (PST) Received: from rltb ([82.66.8.55]) by smtp.gmail.com with ESMTPSA id u2-20020a05600c210200b003d98f92692fsm15707126wml.17.2023.01.17.09.16.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 17 Jan 2023 09:16:54 -0800 (PST) From: Robert Pluim To: Panagiotis Koutsourakis Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation In-Reply-To: <87fsc9jg6p.fsf@panoramix.zarniwoop.org> (Panagiotis Koutsourakis's message of "Tue, 17 Jan 2023 18:09:50 +0200") References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> <87o7qyo3nc.fsf@panoramix.zarniwoop.org> <83cz7e4dve.fsf@gnu.org> <87edrt6y4p.fsf@panoramix.zarniwoop.org> <875yd5ciqs.fsf@gmail.com> <87fsc9jg6p.fsf@panoramix.zarniwoop.org> Date: Tue, 17 Jan 2023 18:16:54 +0100 Message-ID: <87mt6haxo9.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 60859 Cc: 60859@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) >>>>> On Tue, 17 Jan 2023 18:09:50 +0200, Panagiotis Koutsourakis 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 -- From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 12:32:32 2023 Received: (at 60859) by debbugs.gnu.org; 17 Jan 2023 17:32:32 +0000 Received: from localhost ([127.0.0.1]:38142 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHpp2-0002UJ-35 for submit@debbugs.gnu.org; Tue, 17 Jan 2023 12:32:32 -0500 Received: from eggs.gnu.org ([209.51.188.92]:50812) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHpp0-0002U6-CT for 60859@debbugs.gnu.org; Tue, 17 Jan 2023 12:32:30 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHpou-00083v-Ns; Tue, 17 Jan 2023 12:32:24 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=7VjdgU3F+gZglpypbghytBNH5WXqoaNFf+7vuOScUos=; b=R9iorQ24xdaq U29B/s8qFMz0ucady9GhnM5KIATe9rdEHAAJ5vy+CCtP8j1koKq6pKt6c50gZc/YNpXGOnB+xWUlk GKiADGrK9jrKTHUXUn3AXf60PYm1owsuFSdFJtALvgIFagQV2k/rTYc5q999rTK60Qbrq0BNy0rJc FLTiJmmk6n6O/mpTAinuSFIbb9Y+6A/iKZNa+/adp7tNjuHiYJFuoKTNiuj+uto5U1GV0dPie+vJg eocZO79mGRY5rb/7MfI8GEYcrnU1I7KzIoSBs0PMOuscuc68CVqXFgDJ07Au++Ed10iNUJJSyhcB5 wtFO0FhFOtugWa1HgqG4xQ==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHpot-0005b6-M1; Tue, 17 Jan 2023 12:32:23 -0500 Date: Tue, 17 Jan 2023 19:32:34 +0200 Message-Id: <83lem12hjh.fsf@gnu.org> From: Eli Zaretskii To: Panagiotis Koutsourakis In-Reply-To: <87fsc9jg6p.fsf@panoramix.zarniwoop.org> (message from Panagiotis Koutsourakis on Tue, 17 Jan 2023 18:09:50 +0200) Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> <87o7qyo3nc.fsf@panoramix.zarniwoop.org> <83cz7e4dve.fsf@gnu.org> <87edrt6y4p.fsf@panoramix.zarniwoop.org> <875yd5ciqs.fsf@gmail.com> <87fsc9jg6p.fsf@panoramix.zarniwoop.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 60859 Cc: rpluim@gmail.com, 60859@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Cc: 60859@debbugs.gnu.org > From: Panagiotis Koutsourakis > 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. From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 14:40:39 2023 Received: (at 60859) by debbugs.gnu.org; 17 Jan 2023 19:40:39 +0000 Received: from localhost ([127.0.0.1]:38328 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHrp1-0001vp-4n for submit@debbugs.gnu.org; Tue, 17 Jan 2023 14:40:39 -0500 Received: from out3-smtp.messagingengine.com ([66.111.4.27]:48675) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHroz-0001vb-LJ for 60859@debbugs.gnu.org; Tue, 17 Jan 2023 14:40:38 -0500 Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailout.nyi.internal (Postfix) with ESMTP id 949985C00DC; Tue, 17 Jan 2023 14:40:32 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute4.internal (MEProxy); Tue, 17 Jan 2023 14:40:32 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= slartibartfast.net; h=cc:cc:content-type:date:date:from:from :in-reply-to:in-reply-to:message-id:mime-version:references :reply-to:sender:subject:subject:to:to; s=fm1; t=1673984432; x= 1674070832; bh=PJLygxqCC+0lXXkBnqrjYknDVyHUCagzxgVrxp0bLgw=; b=Q iFGRV1aleOAoTDC1GzHo42oaria0G4MFLWuiwPyMhdbAC7XgCYwYRZNQAuiYvMDp qjm8auYNH7BMZrWC96EgjUgG7BR/PAiR51HKl51ejVzyXlzv+xcG240o71tUn7t+ Wf6ztwC6fGBtHjv75gOkMQKCsc4bXaQAXGALUU0msO93HrBKXiF4iDoqwovTC6aa jvjGrUUytGTMb4JZ3OcHtGJ+nCdvcoqxbBVl030/4nAOYyNKSFCIjT2U6rmscIEO pvqGk/r2auiZMpEEoxqCu/gV0pBPabVZyUNrZrNQAB7fS/txmZ/kNzCAqXHvm0z3 WD/Z3ly/8DyzvK3aQhLkw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:date:date:feedback-id :feedback-id:from:from:in-reply-to:in-reply-to:message-id :mime-version:references:reply-to:sender:subject:subject:to:to :x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1673984432; x=1674070832; bh=PJLygxqCC+0lXXkBnqrjYknDVyHU CagzxgVrxp0bLgw=; b=AoivzFpBN+ao9tjyFU0VrMKj1Pe3AAKRGwEsHvQoYXFl Jqwv5/S3lnyW0pfI/zUFB4JglHsc+Qjq0Zrk5yeQAKUQGyFiYcy3QhhKm3kohBJn BHQWFFIDp35HP5D7e8z+wWEamgmQKQZ0sRQHXfac7UFZgHKWFz7vp2wBs/91LmGQ 4qYG2yLHVrDgqyfQ2ZttIpCnLj6e1t4kZUz1sYEDC0GAIwXAV1tCPs3FTZiC5ren uA0HkTUiworY3lb6BUQVTCQiV0Cxnbf25XLw8aDpPSVkY979j2iI6IFd0BbOOScM aUkjl2xhKJxokCxww4WpLN3SrdKqcDeYKnW2QYIQ3g== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedruddtiedguddvjecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh necuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmd enucfjughrpefhvfevufgjfhffkfgfgggtsehmtderredtredtnecuhfhrohhmpefrrghn rghgihhothhishcumfhouhhtshhouhhrrghkihhsuceokhhuthhsuhhrrghksehslhgrrh htihgsrghrthhfrghsthdrnhgvtheqnecuggftrfgrthhtvghrnhepudetgeejuddtfeef gefgueeltdejudeiveehgffhveeftdejteevjedvteejledtnecuvehluhhsthgvrhfuih iivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepkhhuthhsuhhrrghksehslhgrrhht ihgsrghrthhfrghsthdrnhgvth X-ME-Proxy: Feedback-ID: iaac9463b:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 17 Jan 2023 14:40:31 -0500 (EST) From: Panagiotis Koutsourakis To: Eli Zaretskii Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation In-Reply-To: <83lem12hjh.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 17 Jan 2023 19:32:34 +0200") References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> <87o7qyo3nc.fsf@panoramix.zarniwoop.org> <83cz7e4dve.fsf@gnu.org> <87edrt6y4p.fsf@panoramix.zarniwoop.org> <875yd5ciqs.fsf@gmail.com> <87fsc9jg6p.fsf@panoramix.zarniwoop.org> <83lem12hjh.fsf@gnu.org> Date: Tue, 17 Jan 2023 21:40:28 +0200 Message-ID: <874jspj6fn.fsf@panoramix.zarniwoop.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 60859 Cc: rpluim@gmail.com, 60859@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Reword-user-documentation-on-binding-keys-in-lisp.patch >From a8d959fed720618c03993311110fa87cf52cf13f Mon Sep 17 00:00:00 2001 From: Panagiotis Koutsourakis 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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Sat Jan 21 02:52:30 2023 Received: (at 60859-done) by debbugs.gnu.org; 21 Jan 2023 07:52:30 +0000 Received: from localhost ([127.0.0.1]:47899 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pJ8fu-0001pY-8t for submit@debbugs.gnu.org; Sat, 21 Jan 2023 02:52:30 -0500 Received: from eggs.gnu.org ([209.51.188.92]:37326) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pJ8fs-0001pI-Bc for 60859-done@debbugs.gnu.org; Sat, 21 Jan 2023 02:52:28 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pJ8fn-0002xb-1O; Sat, 21 Jan 2023 02:52:23 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=6aB/S+X72IGotVAvrKVQ6/aiO3wcdNQ8AwDTXmfmfjA=; b=rpp6Eo8ukGsi vn1VN+3SEwCwlWfhzd/TbpAi0xJEGf43IsXrez06yt1HcttYd4Iw3UIujKWwoawkAqAEAk34CHJrx ss0vFlyxCDFTezapUbDTm+DcRAFEBkka6cp7hlq39yJIYdg3ggmKdG+e6QM3s22htosTf07hrZi+t mwXWQbhnaAGNY9xj3ruN9DZYd/URKEnEwzWfZXl30C8RSylXkOEnlSCqjwzvHlnawSvfrZIbXqPzD 5/tDyvG4UJDV92WYpwufIUUud1RvGah5G3KGa1XpzcGRC0uKuLzhvi367FljBZap1Q703U+8OsheB JvrzfDD069++VekrfI9QDA==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pJ8fm-0007E1-AO; Sat, 21 Jan 2023 02:52:22 -0500 Date: Sat, 21 Jan 2023 09:52:23 +0200 Message-Id: <835yd0miiw.fsf@gnu.org> From: Eli Zaretskii To: Panagiotis Koutsourakis In-Reply-To: <874jspj6fn.fsf@panoramix.zarniwoop.org> (message from Panagiotis Koutsourakis on Tue, 17 Jan 2023 21:40:28 +0200) Subject: Re: bug#60859: [PATCH] Remove reference to the kbd function from documentation References: <87pmbeivcl.fsf@panoramix.zarniwoop.org> <83ilh64juj.fsf@gnu.org> <87o7qyo3nc.fsf@panoramix.zarniwoop.org> <83cz7e4dve.fsf@gnu.org> <87edrt6y4p.fsf@panoramix.zarniwoop.org> <875yd5ciqs.fsf@gmail.com> <87fsc9jg6p.fsf@panoramix.zarniwoop.org> <83lem12hjh.fsf@gnu.org> <874jspj6fn.fsf@panoramix.zarniwoop.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 60859-done Cc: rpluim@gmail.com, 60859-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Panagiotis Koutsourakis > 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. From unknown Wed Jun 18 23:03:53 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sat, 18 Feb 2023 12:24:08 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator