From unknown Fri Jun 20 05:34:49 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#75366 <75366@debbugs.gnu.org> To: bug#75366 <75366@debbugs.gnu.org> Subject: Status: [PATCH] Improve the doc of key-valid-p Reply-To: bug#75366 <75366@debbugs.gnu.org> Date: Fri, 20 Jun 2025 12:34:49 +0000 retitle 75366 [PATCH] Improve the doc of key-valid-p reassign 75366 emacs submitter 75366 Hong Xu severity 75366 minor tag 75366 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Sat Jan 04 15:40:16 2025 Received: (at submit) by debbugs.gnu.org; 4 Jan 2025 20:40:16 +0000 Received: from localhost ([127.0.0.1]:57597 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tUAwS-0003pV-B3 for submit@debbugs.gnu.org; Sat, 04 Jan 2025 15:40:16 -0500 Received: from lists.gnu.org ([2001:470:142::17]:55228) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tUAwN-0003mb-U8 for submit@debbugs.gnu.org; Sat, 04 Jan 2025 15:40:14 -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 1tUAwI-0004wp-1z for bug-gnu-emacs@gnu.org; Sat, 04 Jan 2025 15:40:06 -0500 Received: from sender4-of-o54.zoho.com ([136.143.188.54]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tUAwF-00065K-Rz for bug-gnu-emacs@gnu.org; Sat, 04 Jan 2025 15:40:05 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1736023197; cv=none; d=zohomail.com; s=zohoarc; b=REVhaj/0qJh8yjNF6WSd4aB3wK9xJneWFEFB442ZgtwqrkEttkBQKjT/7vCmElfw/ucRlV18HkG/OKWKXv10oVU5fm7xDhqsUiry0wg6slabnr5cOmzZkwH8efGjQFtsFmVzzTyA5vmWhiqZPOlJAdcrGQZL2f7YZWqsdPUekNc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1736023197; h=Content-Transfer-Encoding:Date:Date:From:From:MIME-Version:Message-ID:Subject:Subject:To:To:Message-Id:Reply-To:Cc; bh=DbGahLqLrEIktB63qI2aj/FWwPn+oYpRh7s+8Q31hn0=; b=ODvkv1pEKBMYkbW5eNZEbndgf3B0/5hbDS/vYxhZNdc9Exg5V8dOGJ9cn2y6u9+LD0Hs5k2l0cHrdl9+TxH+HtcUy/si+gmvblcG7R+P+Zh4vAZr6PKGzQYWujOpKctU0x9q9q1Gxfw9TCsCe5Gbhly3Q1uV7R2GZSoGdCdNHYU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=topbug.net; spf=pass smtp.mailfrom=hong@topbug.net; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1736023197; s=zoho; d=topbug.net; i=hong@topbug.net; h=From:From:To:To:Subject:Subject:Date:Date:Message-ID:MIME-Version:Content-Transfer-Encoding:Message-Id:Reply-To:Cc; bh=DbGahLqLrEIktB63qI2aj/FWwPn+oYpRh7s+8Q31hn0=; b=Jryy0Vmt4HT3PDByeGKAU/3hPBph6y5AByIK1YC6nQYsSWmPnP3WNY3saKTlF0Pk P+NIJRivHANqxD2Rl9gf+osRtPJGvH9g+OTY6JETh/uM/XdRT8qQkpkJdI2p2x+W3MS yT3sIMYqvJ8tzvcbbsn6OV1NoafNJ/asP7XwIfXg= Received: by mx.zohomail.com with SMTPS id 1736023195926161.3190665673103; Sat, 4 Jan 2025 12:39:55 -0800 (PST) From: Hong Xu To: bug-gnu-emacs@gnu.org Subject: [PATCH] Improve the doc of key-valid-p Date: Sat, 4 Jan 2025 12:37:53 -0800 Message-ID: <20250104203955.139589-1-hong@topbug.net> X-Mailer: git-send-email 2.47.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-ZohoMailClient: External Received-SPF: pass client-ip=136.143.188.54; envelope-from=hong@topbug.net; helo=sender4-of-o54.zoho.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 1.0 (+) X-Debbugs-Envelope-To: submit 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: -0.0 (/) * lisp/keymap.el (key-valid-p): Add an function key example. Mention as a cursor control key instead of a function key. Rename some "characters" to "key strokes" to be consistent with the terminology in the first paragraph. Briefly explain what an event may be. --- lisp/keymap.el | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/lisp/keymap.el b/lisp/keymap.el index 3aed1d4b4cac..e447bf648a10 100644 --- a/lisp/keymap.el +++ b/lisp/keymap.el @@ -327,21 +327,23 @@ key-valid-p with a single space character separating one key stroke from another. Each key stroke is either a single character, or the name of an -event, surrounded by angle brackets . In addition, any -key stroke may be preceded by one or more modifier keys. Finally, -a limited number of characters have a special shorthand syntax. +event, surrounded by angle brackets . An event may be a key +stroke or a menu item. In addition, any key stroke may be preceded by +one or more modifier keys. Finally, a limited number of key strokes +have a special shorthand syntax. Here are some example of valid key sequences. \"f\" (the key `f') + \"\" (the function key named \"F6\") \"S o m\" (a three-key sequence of the keys `S', `o' and `m') \"C-c o\" (a two-key sequence: the key `c' with the control modifier followed by the key `o') - \"H-\" (the function key named \"left\" with the hyper modifier) + \"H-\" (the cursor control key named \"left\" with the hyper modifier) \"M-RET\" (the \"return\" key with a meta modifier) \"C-M-\" (the \"space\" key with both the control and meta modifiers) -These are the characters that have special shorthand syntax: +These key strokes have special shorthand syntax: NUL, RET, TAB, LFD, ESC, SPC, DEL. Modifiers have to be specified in this order: -- 2.47.1 From debbugs-submit-bounces@debbugs.gnu.org Sat Jan 04 15:44:21 2025 Received: (at 75366) by debbugs.gnu.org; 4 Jan 2025 20:44:21 +0000 Received: from localhost ([127.0.0.1]:57602 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tUB0P-0003w2-3E for submit@debbugs.gnu.org; Sat, 04 Jan 2025 15:44:21 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21241) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tUB0N-0003vt-Hl for 75366@debbugs.gnu.org; Sat, 04 Jan 2025 15:44:20 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1736023455; cv=none; d=zohomail.com; s=zohoarc; b=hvlY+t3yq04F4Sd4FXt44DZ/fyh0kSkmKGL1ZKb9cc/HzLcI91kvtXs9bTV2XTFL7RW6GQJ51JB+izv5WRRdJuNA3hYz+rZMIStJTE38Q09cg56z4mCxvYohUbK3nveH2X+Jmllvw7T0+mPd3oqLjDD/ni9UtggMoVZIHYGWowE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1736023455; h=Content-Type:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:Subject:To:To:Message-Id:Reply-To:Cc; bh=ZrvRQLUy9PBldgamoN3ewkiVsFu9cP7NgTtNkooGUg8=; b=EEEAgEJdk2X8s6K68Z08Ioisy5ildnXCFU1WgFYyVjTiz+MBSIOs/ieo1qn0norsKAgIHKKwDSq0ccl4oPKkIjBJx+p+/6fD9wS+OC+m4wVD+W6eQsX3wOiSaQ9NLNNt2vS45lO2nBNrRUgqGS/vycIeQ7KsH1yjGM8s/h/knIg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=topbug.net; spf=pass smtp.mailfrom=hong@topbug.net; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1736023455; s=zoho; d=topbug.net; i=hong@topbug.net; h=From:From:To:To:Subject:Subject:In-Reply-To:References:Date:Date:Message-ID:MIME-Version:Content-Type:Message-Id:Reply-To:Cc; bh=ZrvRQLUy9PBldgamoN3ewkiVsFu9cP7NgTtNkooGUg8=; b=ZunQXL3nqUx+HIYbwc/RGi96Ec2npx63XSSCsj8VwIoNzndD6bauQpHNqF4qUVJr EF9aSdaljy7GugcaRxsCl6HKIQrPE8mG/xgIywdEftDHFVwTr7MexyKU+teVSWk5o7U c2Vu7XUka04tHoAg/UPDP7CgWG3xTQ2AhVziO2kw= Received: by mx.zohomail.com with SMTPS id 1736023453459890.1551473551901; Sat, 4 Jan 2025 12:44:13 -0800 (PST) From: Hong Xu To: 75366@debbugs.gnu.org Subject: Re: [PATCH] Improve the doc of key-valid-p In-Reply-To: <20250104203955.139589-1-hong@topbug.net> (Hong Xu's message of "Sat, 4 Jan 2025 12:37:53 -0800") References: <20250104203955.139589-1-hong@topbug.net> User-Agent: mu4e 1.12.8; emacs 29.4 Date: Sat, 04 Jan 2025 12:44:12 -0800 Message-ID: <874j2eux5v.fsf@topbug.net> MIME-Version: 1.0 Content-Type: text/plain X-ZohoMailClient: External X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 75366 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 2025-01-04 Sat 12:37 GMT-08, Hong Xu wrote: > - \"H-\" (the function key named \"left\" with the hyper modifier) > + \"H-\" (the cursor control key named \"left\" with the hyper modifier) This naming is based on the Wikipedia article "Function Key": https://en.wikipedia.org/wiki/Function_key (See the first figure in the article) -- Hong From debbugs-submit-bounces@debbugs.gnu.org Sat Jan 04 15:50:28 2025 Received: (at 75366) by debbugs.gnu.org; 4 Jan 2025 20:50:28 +0000 Received: from localhost ([127.0.0.1]:57615 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tUB6K-0004HT-1V for submit@debbugs.gnu.org; Sat, 04 Jan 2025 15:50:28 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:55886) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tUB6F-0004HA-0q for 75366@debbugs.gnu.org; Sat, 04 Jan 2025 15:50:26 -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 1tUB68-0000p1-Rv; Sat, 04 Jan 2025 15:50:16 -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=wATXh/IW4cVz92YDXe2TAUp5CUxyLUSEQlYFbVT2nGc=; b=I/iDPoM3cqs8 Y4qQpyE0evohnSiNXMs2feGkYNUxPN7b0fRTVgDtPiQNnibQ41uczRGFg3JtT0r0Xr6Er9ulvsF80 /GYLIOjLvD8ckPsrDjQWcEQAgttuqdOqpMbKRC1dHthl0P2RNYXpqCjUbqVlx9z6eEC+JGhNoOL5T aIgcZWeUOrW94yKzNhueb/7segJZlN8wj03IYYdufgizOX8TaaEzljU99CJjRvChU6ZFyejOEf/cV xm4iPNKzeiaNzL5abSRVEJ22Fy1GKWElfpqGXgIdubPmrRuCFVYmTH4cm5pxaKx4eqrb2M6IzDm7B I/75pPOrQ9jyEozXbm04Vg==; Date: Sat, 04 Jan 2025 22:49:37 +0200 Message-Id: <864j2eb8ym.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <20250104203955.139589-1-hong@topbug.net> (message from Hong Xu on Sat, 4 Jan 2025 12:37:53 -0800) Subject: Re: bug#75366: [PATCH] Improve the doc of key-valid-p References: <20250104203955.139589-1-hong@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 75366 Cc: 75366@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: Hong Xu > Date: Sat, 4 Jan 2025 12:37:53 -0800 > > * lisp/keymap.el (key-valid-p): Add an function key example. Mention > as a cursor control key instead of a function key. Rename > some "characters" to "key strokes" to be consistent with the terminology > in the first paragraph. Briefly explain what an event may be. Thanks, but the changes you suggest to make are not really correct or at least inaccurate (with the exception of adding ""). For example, saying that "event may be a key stroke or a menu item" is inaccurate, because is neither and so is . What is wrong with the current text that you think it needs these changes? > -These are the characters that have special shorthand syntax: > +These key strokes have special shorthand syntax: > NUL, RET, TAB, LFD, ESC, SPC, DEL. They are all characters, not key strokes. From debbugs-submit-bounces@debbugs.gnu.org Sat Jan 04 16:43:39 2025 Received: (at 75366) by debbugs.gnu.org; 4 Jan 2025 21:43:39 +0000 Received: from localhost ([127.0.0.1]:57729 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tUBvm-0006br-Qe for submit@debbugs.gnu.org; Sat, 04 Jan 2025 16:43:39 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21248) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tUBvj-0006bg-LP for 75366@debbugs.gnu.org; Sat, 04 Jan 2025 16:43:37 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1736027005; cv=none; d=zohomail.com; s=zohoarc; b=SVyqWwulYxhK+9WPV4nQuIkLj8NxBJf6+KNbt1kG81HQFM/YauNxQS6QOBa60VHulXUYFNCDGbUhZrtMGFQJTWOUG6O24VYycVSLCYzHoiDwCOC84V8PCruLUAMwinDgNDGtNWdkHismzlgg9oOM/sHEuP+JUu02w0Fqv0U/AKA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1736027005; h=Content-Type:Cc:Cc:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:Subject:To:To:Message-Id:Reply-To; bh=gKBSSHFa/GJZlrRrJCcUsZum4dt9FedaVcolayoA+RU=; b=Vq6VgplOkwPuhe/HsNdxkv89UIiwexad+KJUCW5pIFpWUrKiL2W+3aJ0QWiUim0MFVCbBxm98SZlO5yFeFMMh15Mn4SVE3wKRTh5ZWC/5DDyq2vuUvofDBssN5eyEMvxNCWiSquWDgJQK7woRxLj5Fvc0AERmT/GZJtbUyrXrq0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=topbug.net; spf=pass smtp.mailfrom=hong@topbug.net; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1736027005; s=zoho; d=topbug.net; i=hong@topbug.net; h=From:From:To:To:Cc:Cc:Subject:Subject:In-Reply-To:References:Date:Date:Message-ID:MIME-Version:Content-Type:Message-Id:Reply-To; bh=gKBSSHFa/GJZlrRrJCcUsZum4dt9FedaVcolayoA+RU=; b=LwPe2xEotqT0riQGSYesJMyUfMTMqz/ziRK1MS26dBGFrbeVlaT0h8pHsS5OuM2n E976nFMKwGYrhmR9fSNFE58n5WPUWOOI4mXOg0YuimxrCKf01eSp8rSjfOpJRyjOjSg Vg+PxKaRNhgkXdUNOo45Ghcp95bzrekPLLVvqb2A= Received: by mx.zohomail.com with SMTPS id 1736027003912110.68443935750008; Sat, 4 Jan 2025 13:43:23 -0800 (PST) From: Hong Xu To: Eli Zaretskii Subject: Re: bug#75366: [PATCH] Improve the doc of key-valid-p In-Reply-To: <864j2eb8ym.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 04 Jan 2025 22:49:37 +0200") References: <20250104203955.139589-1-hong@topbug.net> <864j2eb8ym.fsf@gnu.org> User-Agent: mu4e 1.12.8; emacs 29.4 Date: Sat, 04 Jan 2025 13:43:23 -0800 Message-ID: <87y0zqtfus.fsf@topbug.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-ZohoMailClient: External X-Zoho-Virus-Status: 1 X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 75366 Cc: 75366@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 (-) --=-=-= Content-Type: text/plain On 2025-01-04 Sat 12:49 GMT-08, Eli Zaretskii wrote: >> From: Hong Xu >> Date: Sat, 4 Jan 2025 12:37:53 -0800 >> >> * lisp/keymap.el (key-valid-p): Add an function key example. Mention >> as a cursor control key instead of a function key. Rename >> some "characters" to "key strokes" to be consistent with the terminology >> in the first paragraph. Briefly explain what an event may be. > > Thanks, but the changes you suggest to make are not really correct or > at least inaccurate (with the exception of adding ""). For > example, saying that "event may be a key stroke or a menu item" is > inaccurate, because is neither and so is . I attached an updated version to correct the event description. > > What is wrong with the current text that you think it needs these > changes? The current text reads a bit confusing to me. The function, based on its name and the current text, gives me an impression that this is only about key strokes as those on a keyboard. However, it's actually more than key strokes as those on a keyboard. (I've added a mouse example in the updated patch to further clarify this.) For example, the "Modifying Menus" node (correctly) cites this function in the context of binding a menu item. The docstring of this function and the citing text together can confuse a unfamiliar reader quite a bit. Perhaps the ultimate confusion point is the name of the function and the definition of key sequences and key strokes in the docstring, but these may be harder to change. > >> -These are the characters that have special shorthand syntax: >> +These key strokes have special shorthand syntax: >> NUL, RET, TAB, LFD, ESC, SPC, DEL. > > They are all characters, not key strokes. I changed them back to characters in the updated version. But based on the definition earlier, "each key stroke is either a single character, or the name of an event...", they are also key strokes. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=v2-0001-Improve-the-doc-of-key-valid-p.patch >From 73a686feae4327dd23a2d7c350b528ceed5d5119 Mon Sep 17 00:00:00 2001 From: Hong Xu Date: Sat, 4 Jan 2025 12:32:24 -0800 Subject: [PATCH v2] Improve the doc of key-valid-p * lisp/keymap.el (key-valid-p): Add an function key and mouse button example. Mention as a cursor control key instead of a function key. Briefly explain what an event may be. --- lisp/keymap.el | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/lisp/keymap.el b/lisp/keymap.el index 3aed1d4b4cac..d1ff52ea3974 100644 --- a/lisp/keymap.el +++ b/lisp/keymap.el @@ -327,21 +327,26 @@ key-valid-p with a single space character separating one key stroke from another. Each key stroke is either a single character, or the name of an -event, surrounded by angle brackets . In addition, any -key stroke may be preceded by one or more modifier keys. Finally, -a limited number of characters have a special shorthand syntax. +event, surrounded by angle brackets . An event may be +pushing a key, clicking on a menu item, pressing a mouse button, etc. +In addition, any key stroke may be preceded by one or more modifier +keys. Finally, a limited number of characters have a special shorthand +syntax. Here are some example of valid key sequences. \"f\" (the key `f') + \"\" (the function key named \"F6\") + \"\" (the mouse button named \"mouse-1\", commonly referred to as + the left button) \"S o m\" (a three-key sequence of the keys `S', `o' and `m') \"C-c o\" (a two-key sequence: the key `c' with the control modifier followed by the key `o') - \"H-\" (the function key named \"left\" with the hyper modifier) + \"H-\" (the cursor control key named \"left\" with the hyper modifier) \"M-RET\" (the \"return\" key with a meta modifier) \"C-M-\" (the \"space\" key with both the control and meta modifiers) -These are the characters that have special shorthand syntax: +These characters have special shorthand syntax: NUL, RET, TAB, LFD, ESC, SPC, DEL. Modifiers have to be specified in this order: -- 2.47.1 --=-=-= Content-Type: text/plain -- Hong --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Sun Jan 05 01:35:21 2025 Received: (at 75366-done) by debbugs.gnu.org; 5 Jan 2025 06:35:21 +0000 Received: from localhost ([127.0.0.1]:59276 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tUKEL-0006Yn-Ce for submit@debbugs.gnu.org; Sun, 05 Jan 2025 01:35:21 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43432) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tUKEJ-0006VS-Gc for 75366-done@debbugs.gnu.org; Sun, 05 Jan 2025 01:35:20 -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 1tUKED-0003cY-Lq; Sun, 05 Jan 2025 01:35:13 -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=6c4rb+k9kYBp4YVcE0++vSjBcuDaywVXeBfeal9EKdw=; b=e9VR+JoCJtjy 6pRRohe89Vi8erVmFRG1Z2sD4nrzzmmKU/dlH8oFixrgaqgIF9KwPem2qfuPzr2f4xjfDOgPQuuW7 ATZleiMxs4VV/pQinlXY1o6p71RgxMl54SZBsqR6soLyxauAC6CDdnzmIL2OeoHj+7DA6X/TqVej9 wgQaFDTyOSsr4A353DDlgQq+vGcB8IokdetfkV8z9lLo9bEvrZghkqM8IOTS03yEWQM+rjQb6liKK Fg55Lm4LeKyPf/SN8LlW5iM9QImny/3CeR6tyDECPpqpfLAtrZjgEznvgleiZyggEhiXeFzMDv1og LMZFt9R+riHFv7G0dQ+7Rg==; Date: Sun, 05 Jan 2025 08:35:11 +0200 Message-Id: <86ttadahuo.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <87y0zqtfus.fsf@topbug.net> (message from Hong Xu on Sat, 04 Jan 2025 13:43:23 -0800) Subject: Re: bug#75366: [PATCH] Improve the doc of key-valid-p References: <20250104203955.139589-1-hong@topbug.net> <864j2eb8ym.fsf@gnu.org> <87y0zqtfus.fsf@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 75366-done Cc: 75366-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: Hong Xu > Cc: 75366@debbugs.gnu.org > Date: Sat, 04 Jan 2025 13:43:23 -0800 > > On 2025-01-04 Sat 12:49 GMT-08, Eli Zaretskii wrote: > > > What is wrong with the current text that you think it needs these > > changes? > > The current text reads a bit confusing to me. > > The function, based on its name and the current text, gives me an > impression that this is only about key strokes as those on a keyboard. > However, it's actually more than key strokes as those on a keyboard. > (I've added a mouse example in the updated patch to further clarify > this.) > > For example, the "Modifying Menus" node (correctly) cites this function > in the context of binding a menu item. The docstring of this function > and the citing text together can confuse a unfamiliar reader quite a > bit. > > Perhaps the ultimate confusion point is the name of the function and the > definition of key sequences and key strokes in the docstring, but these > may be harder to change. Thanks, installed on the emacs-30 branch, and closing the bug. From unknown Fri Jun 20 05:34:49 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sun, 02 Feb 2025 12:24:16 +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