From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Panagiotis Koutsourakis Newsgroups: gmane.emacs.bugs Subject: bug#60859: [PATCH] Remove reference to the kbd function from documentation Date: Tue, 17 Jan 2023 18:09:50 +0200 Message-ID: <87fsc9jg6p.fsf@panoramix.zarniwoop.org> 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> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="22688"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 60859@debbugs.gnu.org To: Robert Pluim Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Jan 17 17:11:21 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1pHoYP-0005aX-2I for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 17 Jan 2023 17:11:18 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pHoYG-0008O3-34; Tue, 17 Jan 2023 11:11:10 -0500 Original-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 1pHoYC-0008NU-EE for bug-gnu-emacs@gnu.org; Tue, 17 Jan 2023 11:11:06 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pHoYA-0003jO-Sa for bug-gnu-emacs@gnu.org; Tue, 17 Jan 2023 11:11:04 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pHoYA-0000S6-CH for bug-gnu-emacs@gnu.org; Tue, 17 Jan 2023 11:11:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Panagiotis Koutsourakis Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 17 Jan 2023 16:11:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 60859 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 60859-submit@debbugs.gnu.org id=B60859.16739718031664 (code B ref 60859); Tue, 17 Jan 2023 16:11:02 +0000 Original-Received: (at 60859) by debbugs.gnu.org; 17 Jan 2023 16:10:03 +0000 Original-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 Original-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 Original-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) Original-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 Original-Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 17 Jan 2023 11:09:52 -0500 (EST) In-Reply-To: <875yd5ciqs.fsf@gmail.com> (Robert Pluim's message of "Tue, 17 Jan 2023 15:56:27 +0100") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:253563 Archived-At: 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.