From unknown Sat Jun 21 05:14:21 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#74999 <74999@debbugs.gnu.org> To: bug#74999 <74999@debbugs.gnu.org> Subject: Status: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro Reply-To: bug#74999 <74999@debbugs.gnu.org> Date: Sat, 21 Jun 2025 12:14:21 +0000 retitle 74999 [PATCH v2] Recommend `keymap-set' instead of `define-key' in = emacs lisp intro reassign 74999 emacs submitter 74999 Hong Xu severity 74999 wishlist tag 74999 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Fri Dec 20 16:44:03 2024 Received: (at submit) by debbugs.gnu.org; 20 Dec 2024 21:44:03 +0000 Received: from localhost ([127.0.0.1]:44294 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOkmx-00083F-AB for submit@debbugs.gnu.org; Fri, 20 Dec 2024 16:44:03 -0500 Received: from lists.gnu.org ([209.51.188.17]:50412) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOkmt-00082f-8t for submit@debbugs.gnu.org; Fri, 20 Dec 2024 16:44:02 -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 1tOkms-000527-Vz for bug-gnu-emacs@gnu.org; Fri, 20 Dec 2024 16:43:59 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tOkmr-0003Pb-51 for bug-gnu-emacs@gnu.org; Fri, 20 Dec 2024 16:43:58 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1734731034; cv=none; d=zohomail.com; s=zohoarc; b=ddT5qcLsQz9PQhNOL63Kn8nVL2Gth9OGeqlrXUvbGV2xZXgZHbI+0caQkKF/Pwr/tjYHLfUpNyXGoxEwLmMK5l9YDB+FmOLU2wbO8xXEg1QtGR4k+gVlVv/aeJrB+EGWbhkjQuoV6CAb7CWStvyKRd1Z71SwPyYGoJiFRngJ3L0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1734731034; h=Content-Transfer-Encoding:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:Subject:To:To:Message-Id:Reply-To:Cc; bh=+hqSqYOkASyZa7DdTkKYd+TlThk9CtS12aArCb0lYvc=; b=GVJMtN+CvNUmKXMt4WwryCNYA+VeIyp1z8I/0BiBVpJv1vepTf21zHq8rJ/1MMLAaC64T+N6JHei1pUwzD9wXKgyxv8cvXD5Qe2NhRAAmhU0UBM8PGx6/Su8yfNlmGl/ssk2GpeN6UCOFthv7q7lo9VNjz7NIl82gyOTcWQqRWQ= 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=1734731034; s=zoho; d=topbug.net; i=hong@topbug.net; h=From:From:To:To:Subject:Subject:Date:Date:Message-ID:In-Reply-To:References:MIME-Version:Content-Transfer-Encoding:Message-Id:Reply-To:Cc; bh=+hqSqYOkASyZa7DdTkKYd+TlThk9CtS12aArCb0lYvc=; b=B49GsNdbAhtJ/RFKFdyXdXktSBM1DmN0GreuuY+2YFxOjBOltyxGBIoMRBnXGkBY CGQ2Yu7x3xfHQIUY98xfzyJDiDSCbURCH5fLd5EkTIRM59uAgRb8bcS2UxUvfsq/ELJ E2BXtwQKWevh+Mh0xHmul3+q7BG6wYFSv+/sHtPs= Received: by mx.zohomail.com with SMTPS id 1734731031891799.9926349286576; Fri, 20 Dec 2024 13:43:51 -0800 (PST) From: Hong Xu To: bug-gnu-emacs@gnu.org Subject: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro Date: Fri, 20 Dec 2024 13:42:29 -0800 Message-ID: <20241220214351.57036-1-hong@topbug.net> X-Mailer: git-send-email 2.47.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-ZohoMailClient: External Received-SPF: pass client-ip=136.143.188.52; envelope-from=hong@topbug.net; helo=sender4-of-o52.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_H3=0.001, RCVD_IN_MSPIKE_WL=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.3 (-) 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: -2.3 (--) * Since `define-key' is considered legacy and we encourage `keymap-set' now. --- doc/lispintro/emacs-lisp-intro.texi | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 49916235fbf9..ba671e60ffcf 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -17358,11 +17358,21 @@ Keymaps (global-set-key "\C-x\C-b" 'buffer-menu) @end smallexample -Mode-specific keymaps are bound using the @code{define-key} function, +Mode-specific keymaps are bound using the @code{keymap-set} function, which takes a specific keymap as an argument, as well as the key and -the command. For example, my @file{.emacs} file contains the -following expression to bind the @code{texinfo-insert-@@group} command -to @kbd{C-c C-c g}: +the command. For example, the following expression binds the +@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}: + +@smallexample +@group +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group) +@end group +@end smallexample + +While you are encouraged to use @code{keymap-set}, you likely would +encounter @code{define-key} in various places. @code{define-key} is an +older function to create keymaps, and is now considered legacy. The +above key map can be rewritten in @code{define-key} as: @smallexample @group @@ -17396,9 +17406,9 @@ Keymaps write a function to insert a word; but I prefer key strokes consistent with other Texinfo mode key bindings.) -You will see numerous @code{define-key} expressions in -@file{loaddefs.el} as well as in the various mode libraries, such as -@file{cc-mode.el} and @file{lisp-mode.el}. +You will see numerous @code{keymap-set} and @code{define-key} +expressions in @file{loaddefs.el} as well as in the various mode +libraries, such as @file{cc-mode.el} and @file{lisp-mode.el}. @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp -- 2.47.1 From debbugs-submit-bounces@debbugs.gnu.org Sat Dec 21 02:19:39 2024 Received: (at 74999) by debbugs.gnu.org; 21 Dec 2024 07:19:39 +0000 Received: from localhost ([127.0.0.1]:45040 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOtly-0000zB-MH for submit@debbugs.gnu.org; Sat, 21 Dec 2024 02:19:39 -0500 Received: from eggs.gnu.org ([209.51.188.92]:35590) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOtlw-0000yr-A7 for 74999@debbugs.gnu.org; Sat, 21 Dec 2024 02:19:37 -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 1tOtlq-0003O6-Jm; Sat, 21 Dec 2024 02:19:31 -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=ervWYEXn6hMJKBS2r309M/lZ7s8bK5gpBeXNYfiGT+Y=; b=F/5gTN3K2ARc cWEkc9L854yfUy7VA/m/P2fclfMYCDT7Hr7g5oTcgeyqgvs49Eyzdi1Qz7WtFXKvwcUC+Y4N3bMXm PINwu8B2yHXr4bzzoOiYuC7INKPMKIN25YBo7Rmio/AQnOeed0wWqL5maWTD0Wq8YbLwvbchlI+hh IsR2yHt95l+qVGNd7tZHEJZ2TCKfSVME8UK/RDKe7A0WhvcWeFvRg9zQWJqOZKbw4NM00i+uTwZ8X 3EMLvV0fx4T3xjDu539Dxh1ywGgO6la0uyksKydYxKSy9VTPm0LwDhDJnZL7Q2LGiEzCS7nrrvwCD +D8OgGctpn61tisL5EIwCw==; Date: Sat, 21 Dec 2024 09:19:28 +0200 Message-Id: <86y1098pvj.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <20241220214351.57036-1-hong@topbug.net> (message from Hong Xu on Fri, 20 Dec 2024 13:42:29 -0800) Subject: Re: bug#74999: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro References: <20241220214351.57036-1-hong@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 74999 Cc: 74999@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: Fri, 20 Dec 2024 13:42:29 -0800 > > -Mode-specific keymaps are bound using the @code{define-key} function, > +Mode-specific keymaps are bound using the @code{keymap-set} function, > which takes a specific keymap as an argument, as well as the key and > -the command. For example, my @file{.emacs} file contains the > -following expression to bind the @code{texinfo-insert-@@group} command > -to @kbd{C-c C-c g}: > +the command. For example, the following expression binds the > +@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}: > + > +@smallexample > +@group > +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group) > +@end group > +@end smallexample > + > +While you are encouraged to use @code{keymap-set}, you likely would > +encounter @code{define-key} in various places. @code{define-key} is an > +older function to create keymaps, and is now considered legacy. This should say that historically, Emacs used 'define-key', and therefore you are likely to see 'define-key' in various places etc. In addition "older function" is not really accurate: 'keymap-set' calls 'define-key' internally, so 'define-key' will not disappear from Emacs any time soon. We just prefer using 'keymap-set' in Lisp programs because it is higher-level. So instead of saying "older function", I think we should say "more low-level function". Also, please make sure to leave two spaces between sentences, per our conventions. > The > +above key map can be rewritten in @code{define-key} as: Not "key map", but "key binding". The example doesn't show a complete key map, it only shows a single binding within a key map. Since this is an introductory manual, we must be very accurate and clear in our text, to avoid confusing newcomers to Lisp, who are probably confused already to begin with... Thanks. From debbugs-submit-bounces@debbugs.gnu.org Sat Dec 21 02:20:48 2024 Received: (at control) by debbugs.gnu.org; 21 Dec 2024 07:20:48 +0000 Received: from localhost ([127.0.0.1]:45051 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOtn5-00017C-KE for submit@debbugs.gnu.org; Sat, 21 Dec 2024 02:20:47 -0500 Received: from eggs.gnu.org ([209.51.188.92]:59304) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOtn2-00016s-QU; Sat, 21 Dec 2024 02:20:45 -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 1tOtmx-0003k6-EW; Sat, 21 Dec 2024 02:20:39 -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=yZzVyMsSxf14Ha7Q2f3GPeolQ0FL9hJKH8hs/TDPOXk=; b=O6es5nZYM3xs lM/dDeVeyVFMxKbYwmyYUjMObRzkWpnYQ66e7CxIr53AfDYmEvQKYPDnuyGAN8ysRq51dfLyPkW2B T2hrRHS85NJlWzV+3R8Up6b4EQtsI8ADdw2ADz188T6X3BxQEiXChzW13KSgunGpFZ8G4Hx/wzWt/ jLaUaIL5XXfj6bkTn6xEkfE5/sTNIKnc+1sSpuShxn6rNfG1VMHvDrSm5xxEOTrmh+OqOnqmVNWFh Q1mDCRZbOT7AzCGXx5b5prRojPv2u3xvPmT3v6TQrOCb4FYozh1Hd6NVQj1BGrQCFfYjXFvZ8OuHg +cQNwGTHPAevgT7cj4Uxrw==; Date: Sat, 21 Dec 2024 09:20:38 +0200 Message-Id: <86wmft8ptl.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <877c7u58iw.fsf@topbug.net> (message from Hong Xu on Fri, 20 Dec 2024 13:50:15 -0800) Subject: Re: bug#74983: [PATCH] Use `keymap-set' instead of `define-key' in emacs lisp intro References: <20241219223632.37894-1-hong@topbug.net> <86pllmkfcm.fsf@gnu.org> <877c7u58iw.fsf@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control Cc: stefankangas@gmail.com, 74983@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 (---) merge 74983 74999 thanks > From: Hong Xu > Cc: Stefan Kangas , 74983@debbugs.gnu.org > Date: Fri, 20 Dec 2024 13:50:15 -0800 > > On 2024-12-19 Thu 23:01 GMT-08, Eli Zaretskii wrote: > > >> From: Hong Xu > >> Date: Thu, 19 Dec 2024 14:36:29 -0800 > >> > >> * Since `define-key' is considered legacy and we encourage `keymap-set' > >> now. > > > > Thanks. But the second chunk is not really right, since we have many > > more define-key there than keymap-set. > > > > So my suggestion is not to _replace_ define-key with keymap-set, but > > instead describe _both_, explaining that as of Emacs 29 we are > > migrating towards keymap-set, which is preferred. > > Thanks, I agree. I've made a followup patch. For some reason the > followup patch didn't attach to the Message ID of this thread and a new > bug 74999 was created. I've now merged them. From debbugs-submit-bounces@debbugs.gnu.org Sat Dec 21 03:06:02 2024 Received: (at 74999) by debbugs.gnu.org; 21 Dec 2024 08:06:02 +0000 Received: from localhost ([127.0.0.1]:45109 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOuUr-0003I7-Vm for submit@debbugs.gnu.org; Sat, 21 Dec 2024 03:06:02 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21286) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOuUo-0003Hd-E6 for 74999@debbugs.gnu.org; Sat, 21 Dec 2024 03:06:01 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1734768355; cv=none; d=zohomail.com; s=zohoarc; b=X0+Puec/zPTAC9YpBGJ4hrlMWxAuQ+lGIjU9zg/vxpYtP6+kKc1fLHtFmE9r8ROoz/Uiv+HKAq83XG6KLMf9nnpPyLKNkxbjA+E2+dVjqH3ASR38BCpLJv9bEw4sWJ594o5RQpqAMh5jPPJ2FE9jlRGrzFfNw0mVQkZZCZ+Yu0E= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1734768355; h=Content-Transfer-Encoding:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:Subject:To:To:Message-Id:Reply-To:Cc; bh=wVENP7nTAdK0vwplHgr/Ufv9xjDULgWJPKnKg2Vmnbw=; b=aZCdk7BqPOXHTGmmbiPqeMPcKlLN1s5JW6THIMCkw74ODGHAuw17mz/9HXNE5xYc67FVLKRWVNTAqHjiFY7kE8JDtjKe+l/iq5a8qtTPxS1vciC+lIPdpC0EAy3iXAupqjR8DXjPiEaWZGD1VVhXpnT3XKF5qFHNpx/tXYRn2oo= 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=1734768355; s=zoho; d=topbug.net; i=hong@topbug.net; h=From:From:To:To:Subject:Subject:Date:Date:Message-ID:In-Reply-To:References:MIME-Version:Content-Transfer-Encoding:Message-Id:Reply-To:Cc; bh=wVENP7nTAdK0vwplHgr/Ufv9xjDULgWJPKnKg2Vmnbw=; b=Jd/8NcnDfSJ+3jx4qtMwRv5CjR4qldNWmp/nqhcEr2sDacKNwXxFYvaNUFceHtl+ 0fs9MjQFxpPaGGdtiNRrAcpSwaWEqEZlbNjwJtI6HIhG4/122TkAY4f4/zHvMy7DDaq iKznVCcykhm9ya6iqGWfMWKWa9ZXuYu9dT3ZWDm4= Received: by mx.zohomail.com with SMTPS id 1734768352997620.4018781471116; Sat, 21 Dec 2024 00:05:52 -0800 (PST) From: Hong Xu To: 74999@debbugs.gnu.org Subject: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro Date: Sat, 21 Dec 2024 00:03:54 -0800 Message-ID: <20241221080552.259664-1-hong@topbug.net> X-Mailer: git-send-email 2.47.1 In-Reply-To: <86y1098pvj.fsf@gnu.org> References: <86y1098pvj.fsf@gnu.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-ZohoMailClient: External X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 74999 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 (-) * Since `define-key' is considered legacy and we encourage `keymap-set' now. --- doc/lispintro/emacs-lisp-intro.texi | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 49916235fbf9..b3b4141a3c5f 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -17358,11 +17358,22 @@ Keymaps (global-set-key "\C-x\C-b" 'buffer-menu) @end smallexample -Mode-specific keymaps are bound using the @code{define-key} function, +Mode-specific keymaps are bound using the @code{keymap-set} function, which takes a specific keymap as an argument, as well as the key and -the command. For example, my @file{.emacs} file contains the -following expression to bind the @code{texinfo-insert-@@group} command -to @kbd{C-c C-c g}: +the command. For example, the following expression binds the +@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}: + +@smallexample +@group +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group) +@end group +@end smallexample + +While you are encouraged to use @code{keymap-set}, you likely would +encounter @code{define-key} in various places. Historically, keymaps +are bound using a lower-level function, @code{define-key}, which +is now considered legacy. The above key binding can be rewritten using +@code{define-key} as: @smallexample @group @@ -17396,9 +17407,9 @@ Keymaps write a function to insert a word; but I prefer key strokes consistent with other Texinfo mode key bindings.) -You will see numerous @code{define-key} expressions in -@file{loaddefs.el} as well as in the various mode libraries, such as -@file{cc-mode.el} and @file{lisp-mode.el}. +You will see numerous @code{keymap-set} and @code{define-key} +expressions in @file{loaddefs.el} as well as in the various mode +libraries, such as @file{cc-mode.el} and @file{lisp-mode.el}. @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp -- 2.47.1 From debbugs-submit-bounces@debbugs.gnu.org Sat Dec 21 03:07:07 2024 Received: (at 74999) by debbugs.gnu.org; 21 Dec 2024 08:07:07 +0000 Received: from localhost ([127.0.0.1]:45113 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOuVt-0003K7-N1 for submit@debbugs.gnu.org; Sat, 21 Dec 2024 03:07:07 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21220) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOuVr-0003Jv-4W for 74999@debbugs.gnu.org; Sat, 21 Dec 2024 03:07:04 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1734768415; cv=none; d=zohomail.com; s=zohoarc; b=daHaC45KMXaaQCtwvImMR8dVMcnq/Qhk1uA6CyPuyD0g1JJai39mSBwYVTwHmcNAGx0kq1iD8Lna7kFRywnwRPMbDmFamQ7dB62CJcqBepU4EufKRupgjJ9ymUgR0Os+UPjtmbX60AOo7/PLItlaNEWQCRvAk1OpdWEsxVmGcQo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1734768415; 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=NR7IjW+/ZGbVg3zzGdSmPRsdHGHLQ2252j/T8VL3fU8=; b=OBWMXEFgTq6rxoKZwD+sRYX9dwiVxjLqub81kLsz3M84Teb9IlNei4PgD3GYno0cAwcMC9IvXrXRkQUA5P8Ltoxm3EWN+4gUp0pTRzehCeGOYOhIJQl2bqVcC0q0OA1Wdpr8Y+Wlct2X7TAnsEkjWeNFN7fS8VCVaBjIdvU01TM= 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=1734768415; 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=NR7IjW+/ZGbVg3zzGdSmPRsdHGHLQ2252j/T8VL3fU8=; b=TIo97VeMFob/a+JZT9d/YGvzMFpWOEj4XWIaSBe8D7aWmVgWwiTTQ7H3EImE+l4a Mn6FSZeemw4TolfR36+bvI3rVnNscVLy54RFvvCZFU+XEbdBcqv7U0Cwl4T+SDJC6a4 Sz7ud2TcaInaQHmTM5ep0ElR/RMRnceNRgBcXl1E= Received: by mx.zohomail.com with SMTPS id 1734768413983731.5270865322598; Sat, 21 Dec 2024 00:06:53 -0800 (PST) From: Hong Xu To: Eli Zaretskii Subject: Re: bug#74999: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro In-Reply-To: <86y1098pvj.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 21 Dec 2024 09:19:28 +0200") References: <20241220214351.57036-1-hong@topbug.net> <86y1098pvj.fsf@gnu.org> User-Agent: mu4e 1.12.8; emacs 29.4 Date: Sat, 21 Dec 2024 00:06:53 -0800 Message-ID: <87r0615ujm.fsf@topbug.net> MIME-Version: 1.0 Content-Type: text/plain X-ZohoMailClient: External X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 74999 Cc: 74999@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 2024-12-20 Fri 23:19 GMT-08, Eli Zaretskii wrote: >> From: Hong Xu >> Date: Fri, 20 Dec 2024 13:42:29 -0800 >> >> -Mode-specific keymaps are bound using the @code{define-key} function, >> +Mode-specific keymaps are bound using the @code{keymap-set} function, >> which takes a specific keymap as an argument, as well as the key and >> -the command. For example, my @file{.emacs} file contains the >> -following expression to bind the @code{texinfo-insert-@@group} command >> -to @kbd{C-c C-c g}: >> +the command. For example, the following expression binds the >> +@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}: >> + >> +@smallexample >> +@group >> +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group) >> +@end group >> +@end smallexample >> + >> +While you are encouraged to use @code{keymap-set}, you likely would >> +encounter @code{define-key} in various places. @code{define-key} is an >> +older function to create keymaps, and is now considered legacy. > > This should say that historically, Emacs used 'define-key', and > therefore you are likely to see 'define-key' in various places etc. > In addition "older function" is not really accurate: 'keymap-set' > calls 'define-key' internally, so 'define-key' will not disappear from > Emacs any time soon. We just prefer using 'keymap-set' in Lisp > programs because it is higher-level. So instead of saying "older > function", I think we should say "more low-level function". > > Also, please make sure to leave two spaces between sentences, per our > conventions. > >> The >> +above key map can be rewritten in @code{define-key} as: > > Not "key map", but "key binding". The example doesn't show a complete > key map, it only shows a single binding within a key map. Since this > is an introductory manual, we must be very accurate and clear in our > text, to avoid confusing newcomers to Lisp, who are probably confused > already to begin with... > I agree, please see my follow-up patch. -- Thanks, Hong From debbugs-submit-bounces@debbugs.gnu.org Mon Dec 23 15:42:54 2024 Received: (at 74999) by debbugs.gnu.org; 23 Dec 2024 20:42:54 +0000 Received: from localhost ([127.0.0.1]:58193 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tPpGP-0002bu-A5 for submit@debbugs.gnu.org; Mon, 23 Dec 2024 15:42:53 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21288) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tPpGM-0002bm-Nq for 74999@debbugs.gnu.org; Mon, 23 Dec 2024 15:42:51 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1734986558; cv=none; d=zohomail.com; s=zohoarc; b=aAYPLSVXiQNSQAeJ2KlX/3nMnYmJqhA9lf6c35+zh6y6t2cxN4d//MwNzDoMQV6FJzk7bsxFmsOalU8iogOYaft98b2qPevhPfslqwMI0gkXInUOjnks8++u/7scmcS2C2nGFJ9ZCkxOdXBeNwEDn3WlWsJp9Dss6PTTun7ALLg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1734986558; h=Content-Type:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:Subject:Subject:To:To:Message-Id:Reply-To:Cc; bh=PAbTvSscsgYWKUNXpObCCgdoBwQAF4P9Z5JtP5/JjUI=; b=TI2JdePMODKOW5N8MJH4+D0Ztbv8vH4aq8a854uqqnwum6KzhD2OWsHWhaIwa0Fjk9nHOZn47qoNV5mDXMJWsUm/eJ/gPTQhsnB0zRn54E+8jGyfeCT9ssfOBX046dz8FyB/bUonGmOSFOZ2UwZ7qw1zxoezNGba6erM8j6m60A= 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=1734986558; s=zoho; d=topbug.net; i=hong@topbug.net; h=From:From:To:To:Subject:Subject:In-Reply-To:Date:Date:Message-ID:MIME-Version:Content-Type:Message-Id:Reply-To:Cc; bh=PAbTvSscsgYWKUNXpObCCgdoBwQAF4P9Z5JtP5/JjUI=; b=E0kDeODMyl6UCivKTiUCtfpB6j1IldRC+tk24WcNvO+sYgRsigV/BpXXWJbotak1 Tfkn1n1B47P9v1bocmMOPQ1Rz5sRRG3Kn5R1Z9tG+LF0+cn2sq1LxgNzE8vokkkih1r mKvLusvWlLDQDcoIK2NJ/B4sliiSn94uqpQ7HMrc= Received: by mx.zohomail.com with SMTPS id 1734986555609455.9858013384576; Mon, 23 Dec 2024 12:42:35 -0800 (PST) From: Hong Xu To: 74999@debbugs.gnu.org, Eli Zaretskii Subject: Re: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro In-Reply-To: <20241221080552.259664-1-hong@topbug.net> (Hong Xu's message of "Sat, 21 Dec 2024 00:03:54 -0800") Date: Mon, 23 Dec 2024 12:42:34 -0800 Message-ID: <87a5cm1685.fsf@topbug.net> MIME-Version: 1.0 Content-Type: text/plain X-ZohoMailClient: External X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 74999 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 (-) References: <86y1098pvj.fsf@gnu.org> <20241221080552.259664-1-hong@topbug.net> User-Agent: mu4e 1.12.8; emacs 29.4 Date: Mon, 23 Dec 2024 12:42:29 -0800 On 2024-12-21 Sat 00:03 GMT-08, Hong Xu wrote: > * Since `define-key' is considered legacy and we encourage `keymap-set' > now. > --- > doc/lispintro/emacs-lisp-intro.texi | 25 ++++++++++++++++++------- > 1 file changed, 18 insertions(+), 7 deletions(-) > > <...> In case you missed this, are you still interested in reviewing this patch? -- Hong From debbugs-submit-bounces@debbugs.gnu.org Mon Dec 23 22:29:58 2024 Received: (at 74999) by debbugs.gnu.org; 24 Dec 2024 03:29:58 +0000 Received: from localhost ([127.0.0.1]:58864 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tPvcM-0004bS-3L for submit@debbugs.gnu.org; Mon, 23 Dec 2024 22:29:58 -0500 Received: from eggs.gnu.org ([209.51.188.92]:35496) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tPvcJ-0004b8-KV for 74999@debbugs.gnu.org; Mon, 23 Dec 2024 22:29:56 -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 1tPva7-0006BV-29; Mon, 23 Dec 2024 22:27:39 -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=xsBrhEwlY2Pey5Gv2/98I5/mNfn0Cp+FitxFBk3xWmk=; b=TBTl7zsJ2mcp KKx0eWQjwqVKc35F0P6awQNL55XfEjHImSNBoedYoaspbAJcLiNvElng95xUDO+ZuQqb059MBbv6O ie9cPulUnSTqDYv5BgAEXg/Pz33PqZEVU31lIMw7nCaFpRVFX8ot3EzZhMu5JKcxRV02pj/0wTkrJ EElLvV3NdgYpqr6jymdyC4n/mnZQjHdYYNKWcbp49E3yKwggjQfjcz8i+um6v6igwP8zxHW8Hx/qF BNJO1nxGtrcbqtM4Q71LwiOb2f4nDx0mzq6t+HRPVhW3xSx4WI1zB62si3bM9bRfD0KF71fflJcsN elc5RpmD2oMUv5qHZquARw==; Date: Tue, 24 Dec 2024 05:27:29 +0200 Message-Id: <86y1053gm6.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <87a5cm1685.fsf@topbug.net> (message from Hong Xu on Mon, 23 Dec 2024 12:42:34 -0800) Subject: Re: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro References: <87a5cm1685.fsf@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 74999 Cc: 74999@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: Mon, 23 Dec 2024 12:42:34 -0800 > > References: <86y1098pvj.fsf@gnu.org> <20241221080552.259664-1-hong@topbug.net> > User-Agent: mu4e 1.12.8; emacs 29.4 > Date: Mon, 23 Dec 2024 12:42:29 -0800 > > On 2024-12-21 Sat 00:03 GMT-08, Hong Xu wrote: > > > * Since `define-key' is considered legacy and we encourage `keymap-set' > > now. > > --- > > doc/lispintro/emacs-lisp-intro.texi | 25 ++++++++++++++++++------- > > 1 file changed, 18 insertions(+), 7 deletions(-) > > > > <...> > > In case you missed this, are you still interested in reviewing this patch? I didn't miss it. It's in my queue. From debbugs-submit-bounces@debbugs.gnu.org Thu Dec 26 03:20:39 2024 Received: (at 74999) by debbugs.gnu.org; 26 Dec 2024 08:20:39 +0000 Received: from localhost ([127.0.0.1]:39993 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tQj6k-0000Fr-MP for submit@debbugs.gnu.org; Thu, 26 Dec 2024 03:20:39 -0500 Received: from eggs.gnu.org ([209.51.188.92]:50750) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tQj6i-0000FT-Dj for 74999@debbugs.gnu.org; Thu, 26 Dec 2024 03:20:37 -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 1tQj6c-0000LI-1T; Thu, 26 Dec 2024 03:20:30 -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=C8VNq7YFNumwbIGN0yCrRct9kWx1chghIzbzhWbVE0U=; b=PRMIeaK022bO HxWqjK1WAB/Gqane1m2CpuSlUVV/O6BHWdgk94NFWRJGHk7xlknQka6HoZtUivKYeJfCqoqvMpqGb PC96U5cbXBB7FrUATGWQBKNjIpeWzL2GPAII2aKEyGr4fFaYWrTlj+3SOpcESTmLduoFgxjaCYMVm eEPxAmEPl1kDzndahwruKEuZ0GkNUTQuA3FwKIOyMNqmB8bFY7IUUq8q0OHJCReImlNE8dc0NZhEQ y+L4xo8V+7GvGoxmKdrVTMtz1dc3OY5FT0daU1NGLue5Bcs2ROj5EQbKzLweCi4VKHkPdBiTjuXk+ aiqq/N00lM+wBY9RNA21PQ==; Date: Thu, 26 Dec 2024 10:20:11 +0200 Message-Id: <86ed1uzwhw.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <20241221080552.259664-1-hong@topbug.net> (message from Hong Xu on Sat, 21 Dec 2024 00:03:54 -0800) Subject: Re: bug#74999: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro References: <86y1098pvj.fsf@gnu.org> <20241221080552.259664-1-hong@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 74999 Cc: 74999@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, 21 Dec 2024 00:03:54 -0800 > > * Since `define-key' is considered legacy and we encourage `keymap-set' > now. > --- > doc/lispintro/emacs-lisp-intro.texi | 25 ++++++++++++++++++------- > 1 file changed, 18 insertions(+), 7 deletions(-) Thanks. I tried to install this, but the git-commit hook rejected the commit because Subject line is too long: Line longer than 78 characters in commit message Commit aborted; please see the file CONTRIBUTE Please format the patch using "git format-patch", and please commit the patch locally before you do so (assuming you have the hooks in your local clone), to make sure these problems are corrected before you send the patch here. More generally, global-set-key, discussed earlier in this section, is also obsolete, and we nowadays prefer keymap-global-set instead. So, if we want to modernize this part of the Emacs Lisp Intro manual, I think we should replace all the key-binding examples and the surrounding text in the manual to use the new keymap-* functions. It makes little sense to replace only define-key and leave the rest as they were. Would you like to submit a patch that takes care of these issues in a more thorough manner? > +While you are encouraged to use @code{keymap-set}, you likely would > +encounter @code{define-key} in various places. Historically, keymaps > +are bound using a lower-level function, @code{define-key}, which > +is now considered legacy. These two sentences should be in reverse order: first tell that historically we used define-key, then say that the reader is encouraged to use keymap-set. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Thu Dec 26 16:48:25 2024 Received: (at 74999) by debbugs.gnu.org; 26 Dec 2024 21:48:25 +0000 Received: from localhost ([127.0.0.1]:42534 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tQviS-00044F-Ba for submit@debbugs.gnu.org; Thu, 26 Dec 2024 16:48:25 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21275) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tQviO-000445-Px for 74999@debbugs.gnu.org; Thu, 26 Dec 2024 16:48:22 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1735249697; cv=none; d=zohomail.com; s=zohoarc; b=Z9KFrNZql++wkTdOLa4AIgl1v0q8LrsHfvudCEyi7g4qOsrQ/bKZH/xwbrrLrWU7/VzkTQvF54dd7/Ny9TzB95b2uBBlClVdwjTidS39F3QKVqKABR5BBICSbkNNYs/R1ILBmiGejHrWIDB7jPdjFReM3F67zZDZvCSXUxyE1IY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1735249697; h=Content-Transfer-Encoding:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:Subject:To:To:Message-Id:Reply-To:Cc; bh=jshizdoncLPo96gIQGgQ2Hau08kduzxrHwXs65f1I3Y=; b=YlKzXsTnHazyR6+VZZq1pPL61qsbaAeVu9NTvVwIh1/52SoBXDRw1MdKqBM3kNbXwjKB4TedgrCiCrysyRJJdu0m3O5xLygyk4TFZWljYMraa6zS2TqXtpIJ6MPcB5BI5iWQzFnpXSDD+ZVbk+u1KXQEFDtuVoLsAeoMATB9fR0= 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=1735249697; s=zoho; d=topbug.net; i=hong@topbug.net; h=From:From:To:To:Subject:Subject:Date:Date:Message-ID:In-Reply-To:References:MIME-Version:Content-Transfer-Encoding:Message-Id:Reply-To:Cc; bh=jshizdoncLPo96gIQGgQ2Hau08kduzxrHwXs65f1I3Y=; b=fi5HtRUMqfWWJfhyHJoTnDzzzp/kYApVhEeBerqftJcxKIm3nkXaAiptjVJijl0O oQJojQRn3WWSl2p4LEdpr9k4kcvqLE6dHIKmdoNoHpEjaz217Li90vPcvzwCwSLh4l/ t6ry0SOG/hRRY4OsugOhGwhq/k8eXjyo5MweTDgs= Received: by mx.zohomail.com with SMTPS id 1735249695423525.5268683139931; Thu, 26 Dec 2024 13:48:15 -0800 (PST) From: Hong Xu To: 74999@debbugs.gnu.org Subject: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro Date: Thu, 26 Dec 2024 13:46:39 -0800 Message-ID: <20241226214814.52057-1-hong@topbug.net> X-Mailer: git-send-email 2.47.1 In-Reply-To: <86ed1uzwhw.fsf@gnu.org> References: <86ed1uzwhw.fsf@gnu.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-ZohoMailClient: External X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 74999 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 (-) * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since `global-set-key' and `define-key' are considered legacy, we encourage `keymap-global-set' and `keymap-set' now. --- doc/lispintro/emacs-lisp-intro.texi | 119 +++++++++++++++++++--------- 1 file changed, 81 insertions(+), 38 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 49916235fbf9..daffd6386133 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -13810,7 +13810,7 @@ Whitespace Bug If you wish, you can also install this key binding by evaluating it: @smallexample -(global-set-key "\C-c=" '@value{COUNT-WORDS}) +(keymap-global-set "C-c =" '@value{COUNT-WORDS}) @end smallexample To conduct the first test, set mark and point to the beginning and end @@ -14762,7 +14762,7 @@ count-words-in-defun Let's reuse @kbd{C-c =} as a convenient key binding: @smallexample -(global-set-key "\C-c=" 'count-words-defun) +(keymap-global-set "C-c =" 'count-words-defun) @end smallexample Now we can try out @code{count-words-defun}: install both @@ -17229,7 +17229,7 @@ Key Bindings @smallexample @group ;;; Compare windows -(global-set-key "\C-cw" 'compare-windows) +(keymap-global-set "C-c w" 'compare-windows) @end group @end smallexample @@ -17242,20 +17242,18 @@ Key Bindings This also shows how to set a key globally, for all modes. @cindex Setting a key globally -@cindex Global set key +@cindex Keymap global set @cindex Key setting globally -@findex global-set-key -The command is @code{global-set-key}. It is followed by the -key binding. In a @file{.emacs} file, the keybinding is written as -shown: @code{\C-c} stands for Control-C, which means to press the -control key and the @kbd{c} key at the same time. The @code{w} means -to press the @kbd{w} key. The key binding is surrounded by double -quotation marks. In documentation, you would write this as -@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as -@kbd{M-c}, rather than a @key{CTRL} key, you would write -@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , -Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for -details.) +@findex keymap-global-set +The key setting command is @code{keymap-global-set}. It is followed by +the key binding. In a @file{.emacs} file, the keybinding is written as +shown: @code{C-c} stands for Control-C, which means to press the control +key and the @kbd{c} key at the same time. The @code{w} means to press +the @kbd{w} key. The key binding is surrounded by double quotation +marks. (If you were binding a @key{META} key, rather than a @key{CTRL} +key, you would write @w{@code{M-c}} in your @file{.emacs} file. +@xref{Init Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU +Emacs Manual}, for details.) The command invoked by the keys is @code{compare-windows}. Note that @code{compare-windows} is preceded by a single-quote; otherwise, Emacs @@ -17284,7 +17282,7 @@ Key Bindings @group ;;; Key binding for 'occur' ; I use occur a lot, so let's bind it to a key: -(global-set-key "\C-co" 'occur) +(keymap-global-set "C-c o" 'occur) @end group @end smallexample @@ -17296,7 +17294,7 @@ Key Bindings Matching lines are shown in a buffer called @file{*Occur*}. That buffer serves as a menu to jump to occurrences. -@findex global-unset-key +@findex keymap-global-unset @cindex Unbinding key @cindex Key unbinding @need 1250 @@ -17306,7 +17304,7 @@ Key Bindings @smallexample @group ;;; Unbind 'C-x f' -(global-unset-key "\C-xf") +(keymap-global-unset "C-x f") @end group @end smallexample @@ -17324,7 +17322,7 @@ Key Bindings @smallexample @group ;;; Rebind 'C-x C-b' for 'buffer-menu' -(global-set-key "\C-x\C-b" 'buffer-menu) +(keymap-global-set "C-x C-b" 'buffer-menu) @end group @end smallexample @@ -17336,33 +17334,79 @@ Key Bindings command, which not only lists the buffers, but moves point into that window. +@subsection Legacy Global Key Binding Commands + +@findex global-set-key +@cindex Global set key +Historically, keys are bound globally using a lower-level function, +@code{global-set-key}, which is now considered legacy. While you are +encouraged to use @code{keymap-global-set}, you likely would encounter +@code{global-set-key} in various places. The first example can be +rewritten using @code{global-set-key} as: + +@smallexample +@group +(global-set-key "\C-cw" 'compare-windows) +@end group +@end smallexample + +It is very similar to @code{keymap-global-set}, with the keybinding +following a slightly different format. Control-C is represented by +@code{\C-c}, instead of @code{C-c}. There is no space between key +strokes, like @code{\C-c} and @code{w} in this example. Despite the +difference, in documentation, this is still written as @w{@kbd{C-c w}} +for readability. + +@findex global-unset-key +Historically, keys are unbound globally using a lower-function, +@code{global-unset-key}, which is now considered legacy. Its key +binding format follows that of @code{global-set-key}. The above key +unbinding example can be rewritten as: +@smallexample +@group +;;; Unbind 'C-x f' +(global-unset-key "\C-xf") +@end group +@end smallexample + @node Keymaps @section Keymaps @cindex Keymaps @cindex Rebinding keys Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the key binding for a single -command in all parts of Emacs, you are specifying the key binding in -@code{current-global-map}. +When you use @code{keymap-global-set} to set the key binding for a +single command in all parts of Emacs, you are specifying the key binding +in @code{current-global-map}. Specific modes, such as C mode or Text mode, have their own keymaps; the mode-specific keymaps override the global map that is shared by all buffers. -The @code{global-set-key} function binds, or rebinds, the global +The @code{keymap-global-set} function binds, or rebinds, the global keymap. For example, the following binds the key @kbd{C-x C-b} to the function @code{buffer-menu}: @smallexample -(global-set-key "\C-x\C-b" 'buffer-menu) +(keymap-global-set "C-x C-b" 'buffer-menu) @end smallexample -Mode-specific keymaps are bound using the @code{define-key} function, +Mode-specific keymaps are bound using the @code{keymap-set} function, which takes a specific keymap as an argument, as well as the key and -the command. For example, my @file{.emacs} file contains the -following expression to bind the @code{texinfo-insert-@@group} command -to @kbd{C-c C-c g}: +the command. For example, the following expression binds the +@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}: + +@smallexample +@group +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group) +@end group +@end smallexample + +Historically, keymaps are bound using a lower-level function, +@code{define-key}, which is now considered legacy. While you are +encouraged to use @code{keymap-set}, you likely would encounter +@code{define-key} in various places. The above key binding can be +rewritten using @code{define-key} as: @smallexample @group @@ -17396,9 +17440,9 @@ Keymaps write a function to insert a word; but I prefer key strokes consistent with other Texinfo mode key bindings.) -You will see numerous @code{define-key} expressions in -@file{loaddefs.el} as well as in the various mode libraries, such as -@file{cc-mode.el} and @file{lisp-mode.el}. +You will see numerous @code{keymap-set} and @code{define-key} +expressions in @file{loaddefs.el} as well as in the various mode +libraries, such as @file{cc-mode.el} and @file{lisp-mode.el}. @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp @@ -17440,13 +17484,12 @@ Loading Files @need 1250 To replace the key binding for the default -@code{split-window-vertically}, you must also unset that key and bind -the keys to @code{split-window-quietly}, like this: +@code{split-window-vertically}, you must bind the keys to +@code{split-window-quietly}, like this: @smallexample @group -(global-unset-key "\C-x2") -(global-set-key "\C-x2" 'split-window-quietly) +(keymap-global-set "C-x 2" 'split-window-quietly) @end group @end smallexample @@ -17608,7 +17651,7 @@ Simple Extension this: @smallexample -(global-set-key [f6] 'line-to-top-of-window) +(keymap-global-set "" 'line-to-top-of-window) @end smallexample For more information, see @ref{Init Rebinding, , Rebinding Keys in @@ -18791,7 +18834,7 @@ the-the @group ;; Bind 'the-the' to C-c \ -(global-set-key "\C-c\\" 'the-the) +(keymap-global-set "C-c \\" 'the-the) @end group @end smallexample -- 2.47.1 From debbugs-submit-bounces@debbugs.gnu.org Thu Dec 26 16:58:52 2024 Received: (at 74999) by debbugs.gnu.org; 26 Dec 2024 21:58:52 +0000 Received: from localhost ([127.0.0.1]:42545 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tQvsa-0004YF-1n for submit@debbugs.gnu.org; Thu, 26 Dec 2024 16:58:52 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21298) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tQvsT-0004Y3-VE for 74999@debbugs.gnu.org; Thu, 26 Dec 2024 16:58:50 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1735250317; cv=none; d=zohomail.com; s=zohoarc; b=j8Yw84fy4wTKXvGHjq8eDmvS9HAKOgh5RmxoDP9PMbXsnY5CrxlfolRNhS86bdBZKZM8xmTao7yw5uDvUp5lthUEuR/lfUTHRxKA01mxpDPKaoveelIRcDf2nERRnwsxqIZ8iF3xNQe7HJ2Y3rDx5GwVuGUU2tuAPnv35Mhr6aQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1735250317; 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=1nqMZdNxWnpsFFLUlb8KQE1cxMmLJL5sp0PVzdoGHqg=; b=QZRsUlu8KTqoXUtRgLH5gcsPV6WNesdyop+ER/VRrwrHtDLCWkO56geOd35FkoKvydO1RTrtxd+OiDYWzTUi+qmIHsE5Nk7C0Da3smuMQc1+iOtTOdTkegrYumQ0yq5OoCw3mw4P90RtPUXhWP2TbrSFTZaddOoC6tnCX04elXI= 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=1735250317; 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=1nqMZdNxWnpsFFLUlb8KQE1cxMmLJL5sp0PVzdoGHqg=; b=gG+0vmpbtC+HiaaUyQ72tTYFCjWBP5+KN5KsCDrlSD3uZtfR7dG1gW9pOfQYe9AF YfcbN3vhyvzBuZujvogn83T4ljmoRQtvuvLTcuaJmoxe4V0cHFuPNwwE712yv6knwrM iTjF/+NKMofRsJyYbtQoFBl1eMrJ7QkKA4iVpgPY= Received: by mx.zohomail.com with SMTPS id 1735250314677111.68920987576792; Thu, 26 Dec 2024 13:58:34 -0800 (PST) From: Hong Xu To: Eli Zaretskii Subject: Re: bug#74999: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro In-Reply-To: <86ed1uzwhw.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 26 Dec 2024 10:20:11 +0200") References: <86y1098pvj.fsf@gnu.org> <20241221080552.259664-1-hong@topbug.net> <86ed1uzwhw.fsf@gnu.org> User-Agent: mu4e 1.12.8; emacs 29.4 Date: Thu, 26 Dec 2024 13:58:33 -0800 Message-ID: <87msgip0mu.fsf@topbug.net> MIME-Version: 1.0 Content-Type: text/plain X-ZohoMailClient: External X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 74999 Cc: 74999@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 (-) Thanks for reviewing. Please see my followup patch. On 2024-12-26 Thu 00:20 GMT-08, Eli Zaretskii wrote: >> From: Hong Xu >> Date: Sat, 21 Dec 2024 00:03:54 -0800 >> >> * Since `define-key' is considered legacy and we encourage `keymap-set' >> now. >> --- >> doc/lispintro/emacs-lisp-intro.texi | 25 ++++++++++++++++++------- >> 1 file changed, 18 insertions(+), 7 deletions(-) > > Thanks. I tried to install this, but the git-commit hook rejected the > commit because Subject line is too long: > > Line longer than 78 characters in commit message > Commit aborted; please see the file CONTRIBUTE > > Please format the patch using "git format-patch", and please commit > the patch locally before you do so (assuming you have the hooks in > your local clone), to make sure these problems are corrected before > you send the patch here. I could apply these patches without line length complaints, and the hooks were in effect. An inspection into the patch file also shows no line is longer than 78 characters. Git is supposed to abandon the "[Patch vN]" prefix when applying the patch. > More generally, global-set-key, discussed earlier in this section, is > also obsolete, and we nowadays prefer keymap-global-set instead. So, > if we want to modernize this part of the Emacs Lisp Intro manual, I > think we should replace all the key-binding examples and the > surrounding text in the manual to use the new keymap-* functions. It > makes little sense to replace only define-key and leave the rest as > they were. > > Would you like to submit a patch that takes care of these issues in a > more thorough manner? Addressed. > >> +While you are encouraged to use @code{keymap-set}, you likely would >> +encounter @code{define-key} in various places. Historically, keymaps >> +are bound using a lower-level function, @code{define-key}, which >> +is now considered legacy. > > These two sentences should be in reverse order: first tell that > historically we used define-key, then say that the reader is > encouraged to use keymap-set. > Addressed. From debbugs-submit-bounces@debbugs.gnu.org Thu Dec 26 17:05:08 2024 Received: (at 74999) by debbugs.gnu.org; 26 Dec 2024 22:05:08 +0000 Received: from localhost ([127.0.0.1]:42572 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tQvyd-0004uv-St for submit@debbugs.gnu.org; Thu, 26 Dec 2024 17:05:08 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21251) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tQvyb-0004sv-TW for 74999@debbugs.gnu.org; Thu, 26 Dec 2024 17:05:06 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1735250704; cv=none; d=zohomail.com; s=zohoarc; b=aEChYaDNZAdpaCryCOCj0N9d3gGfmH90XqMWjnAfNcDqkHcSb59CaOqfYGOPKHBjnnccXbikp+m6orzVJm5ITS8qsp2dPVNhCVt7+eGKvuZzj/6q/RLxGM6V9RWca3mc9/DAt2EBmWH6cfn5WFDeZ6Qa6evsvr6qKjQ9MQtXEs8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1735250704; 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=98Ozd33O/0BQvM7XFt2/nZXZ/U6ACWvDDZ2v9mhDKcc=; b=AelldNrUYRFaR7uvEUdQ+WVI3uE2wyhcAGTvpl+5QENdtNzL9pXTck0hENS7ynkoZrDT0fiVqs5XLKN7yVI72o2569wo0LBlN2y6dNwDRgXRv/+DZEOlpNrNqEDFofgmvRNSAKe63hs7lDU3E8JIj5EPs76WDTu0NLHcIrPT6k4= 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=1735250704; 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=98Ozd33O/0BQvM7XFt2/nZXZ/U6ACWvDDZ2v9mhDKcc=; b=WAywRVR8gaC2G98EnVCjYk0iJNzb+otLoMfgwFD8Yi61NhJjkSdW8wWrqEwd3Y0w t1pLok6+m/b23KrPsMQhbwjXmEjmJNSSe6zYn+8+HcFKbJIVCxum5mF6gjE9yoGgA2o PSRcxPXaWBkDJLAYNkoW1xcRt8UUdqzBZnLoGUn8= Received: by mx.zohomail.com with SMTPS id 1735250701917910.776667288921; Thu, 26 Dec 2024 14:05:01 -0800 (PST) From: Hong Xu To: 74999@debbugs.gnu.org Subject: Re: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro In-Reply-To: <20241226214814.52057-1-hong@topbug.net> (Hong Xu's message of "Thu, 26 Dec 2024 13:46:39 -0800") References: <86ed1uzwhw.fsf@gnu.org> <20241226214814.52057-1-hong@topbug.net> User-Agent: mu4e 1.12.8; emacs 29.4 Date: Thu, 26 Dec 2024 14:05:01 -0800 Message-ID: <87h66qp0c2.fsf@topbug.net> MIME-Version: 1.0 Content-Type: text/plain X-ZohoMailClient: External X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 74999 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 2024-12-26 Thu 13:46 GMT-08, Hong Xu wrote: > * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since > `global-set-key' and `define-key' are considered legacy, we encourage > `keymap-global-set' and `keymap-set' now. > --- > <...> > > +@findex global-unset-key > +Historically, keys are unbound globally using a lower-function, > +@code{global-unset-key}, which is now considered legacy. Its key > +binding format follows that of @code{global-set-key}. The above key > +unbinding example can be rewritten as: > +@smallexample > +@group > +;;; Unbind 'C-x f' > +(global-unset-key "\C-xf") > +@end group > +@end smallexample > + I'm thinking about dropping this paragraph, because `global-unset-key' isn't commonly seen, and there's no point to over fill an introduction with less used functions. Please advice. -- Hong From debbugs-submit-bounces@debbugs.gnu.org Fri Dec 27 02:37:38 2024 Received: (at 74999) by debbugs.gnu.org; 27 Dec 2024 07:37:38 +0000 Received: from localhost ([127.0.0.1]:44525 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tR4ug-0000gW-CM for submit@debbugs.gnu.org; Fri, 27 Dec 2024 02:37:38 -0500 Received: from eggs.gnu.org ([209.51.188.92]:37796) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tR4ud-0000gH-Tw for 74999@debbugs.gnu.org; Fri, 27 Dec 2024 02:37: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 1tR4uY-0007vp-5V; Fri, 27 Dec 2024 02:37:30 -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=sRkEFSPbsOTNY3GFzltzm1fyB4wH/LW+2WDZ8N2mAHI=; b=Jpa2BIIZw4q8 8IxuXzFfJ8m0hga2QYU1ITl1OzLep38FJj7cp3PeI33egm+BlPzfGILvO5lqQLpX7wjqV2GS9jbRC jMQpGgrc83ijjiKcVewUo7kKZUAkxMucOFEym3cCHgOy38XuaoS4TsJPdfWnWE6uLoRKRJVeTT0na Jh5RKfuxq88rfj6WSUwTBIEzN8a0nYzji8NWz/xiZSOHAqTKDaFMgiMHWvOaeXF2EotGLha3vpji/ 24SRhIkG/+TfX1/AHCeUpRNV6VVeUaEVDIrfmtZlnyIQKfnDgoInGjmyw6oCp2StP+f6k7kbosSUq jfRJ2xKlwNFjW936pvhBRg==; Date: Fri, 27 Dec 2024 09:37:28 +0200 Message-Id: <86a5chy3t3.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <87msgip0mu.fsf@topbug.net> (message from Hong Xu on Thu, 26 Dec 2024 13:58:33 -0800) Subject: Re: bug#74999: [PATCH v3] Recommend `keymap-set' instead of `define-key' in emacs lisp intro References: <86y1098pvj.fsf@gnu.org> <20241221080552.259664-1-hong@topbug.net> <86ed1uzwhw.fsf@gnu.org> <87msgip0mu.fsf@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 74999 Cc: 74999@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: 74999@debbugs.gnu.org > Date: Thu, 26 Dec 2024 13:58:33 -0800 > > > Thanks. I tried to install this, but the git-commit hook rejected the > > commit because Subject line is too long: > > > > Line longer than 78 characters in commit message > > Commit aborted; please see the file CONTRIBUTE > > > > Please format the patch using "git format-patch", and please commit > > the patch locally before you do so (assuming you have the hooks in > > your local clone), to make sure these problems are corrected before > > you send the patch here. > > I could apply these patches without line length complaints, and the > hooks were in effect. An inspection into the patch file also shows no > line is longer than 78 characters. Git is supposed to abandon the > "[Patch vN]" prefix when applying the patch. I'm guessing the problem on my side is because you sent the patch as a complete email message, where the heading line is presumed to be taken from Subject. To avoid these problems, please in the future send the patches as attachments, to allow me to pass to "git am" only the actual patch, not any of the other email headers. From debbugs-submit-bounces@debbugs.gnu.org Fri Dec 27 02:44:49 2024 Received: (at 74999) by debbugs.gnu.org; 27 Dec 2024 07:44:49 +0000 Received: from localhost ([127.0.0.1]:44540 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tR51c-0000zl-Lj for submit@debbugs.gnu.org; Fri, 27 Dec 2024 02:44:48 -0500 Received: from eggs.gnu.org ([209.51.188.92]:56304) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tR51a-0000zW-DF for 74999@debbugs.gnu.org; Fri, 27 Dec 2024 02:44:47 -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 1tR51U-0008UQ-Hv; Fri, 27 Dec 2024 02:44:40 -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=7jzpQTEFjpTH/FnyzKwWgYY8dNaPEiR+emyWI2cQ2Dc=; b=LUbhiwwS0vlx VX1K/WX9uz8PTnZfSFLshvnZuLkyEoA0S35USb4kcEgp4lpMqItVVc7C1DGcM0TiQJWgxC1zBDvah DjuaObhL9G8vms5LE/iiVSSl3UZX2xBx+n0WyV8CVQbw5sqa5bHm9kGVz4MxvWD80GyqfEXOJqvWw d+AjW6QqWjkiSItYoiPEYIJ/CB1TokgoYIuggTehSIdPk79nXELvwvN83x6k/cgzysfefSl0YGqRj YdH9/rFb09uNduYauGlNPb6M3YBG+peQKSR70KAmgsBzjFk9JI+A9Jrcz3t0Wgga+6UgMfnXag25M Yg6HDBDfrKtzaL7ib2x5gQ==; Date: Fri, 27 Dec 2024 09:44:39 +0200 Message-Id: <868qs1y3h4.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <87h66qp0c2.fsf@topbug.net> (message from Hong Xu on Thu, 26 Dec 2024 14:05:01 -0800) Subject: Re: bug#74999: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro References: <86ed1uzwhw.fsf@gnu.org> <20241226214814.52057-1-hong@topbug.net> <87h66qp0c2.fsf@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 74999 Cc: 74999@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: Thu, 26 Dec 2024 14:05:01 -0800 > > On 2024-12-26 Thu 13:46 GMT-08, Hong Xu wrote: > > > * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since > > `global-set-key' and `define-key' are considered legacy, we encourage > > `keymap-global-set' and `keymap-set' now. > > --- > > <...> > > > > +@findex global-unset-key > > +Historically, keys are unbound globally using a lower-function, > > +@code{global-unset-key}, which is now considered legacy. Its key > > +binding format follows that of @code{global-set-key}. The above key > > +unbinding example can be rewritten as: > > +@smallexample > > +@group > > +;;; Unbind 'C-x f' > > +(global-unset-key "\C-xf") > > +@end group > > +@end smallexample > > + > > I'm thinking about dropping this paragraph, because `global-unset-key' > isn't commonly seen, and there's no point to over fill an introduction > with less used functions. Please advice. I wouldn't remove it. This manual is an extended tutorial of the Emacs Lisp language, so it doesn't necessarily include only the frequently-used functions. We must trust the author of this manual, who was a great expert in teaching Emacs Lisp, that his decision to include this function had a good reason. From debbugs-submit-bounces@debbugs.gnu.org Sat Dec 28 07:17:40 2024 Received: (at 74999) by debbugs.gnu.org; 28 Dec 2024 12:17:40 +0000 Received: from localhost ([127.0.0.1]:49640 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tRVlE-0001ng-8Z for submit@debbugs.gnu.org; Sat, 28 Dec 2024 07:17:40 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52354) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tRVlC-0001nQ-N8 for 74999@debbugs.gnu.org; Sat, 28 Dec 2024 07:17:39 -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 1tRVl7-0004EE-0i; Sat, 28 Dec 2024 07:17:33 -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=pb1kiBpZkaofQALA+g8Oy4FHYxQYJL+V4lHK4/oE2GY=; b=KWWaBcq0zAt/ 5UM0fLo5UrMdHnV5HoI0wGieVwalk7fkkeU8TJ+0AphY4mePSksMVrpztXc4eHquiHfKwnBwr6rZt sjw9ksbGJ5oJxct5B57xNf4p6FFM9z0ehSnBZX+Arqeq2Ah+YZunBy+4t/bPAhi4bevHy0CycEiaa 9I/YBFTgwI5CXA9iT4hAudUOobZTUf08Ol7TDA0Fvwsru8NC4kKsz/EJbJPhRaZF/It1oJXtzXBrR lf8AC1787rIaJ3u7N/jEy1ZDylzwelolzs8jMb8+MRITv1Wr2tjGSgBnVA4RMC4ikqUXLSivZqHi5 WK2PJ0QPRk3qhNTmNzOftA==; Date: Sat, 28 Dec 2024 14:17:28 +0200 Message-Id: <86seq8roh3.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <20241226214814.52057-1-hong@topbug.net> (message from Hong Xu on Thu, 26 Dec 2024 13:46:39 -0800) Subject: Re: bug#74999: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro References: <86ed1uzwhw.fsf@gnu.org> <20241226214814.52057-1-hong@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 74999 Cc: 74999@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: Thu, 26 Dec 2024 13:46:39 -0800 > > * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since > `global-set-key' and `define-key' are considered legacy, we encourage > `keymap-global-set' and `keymap-set' now. > --- > doc/lispintro/emacs-lisp-intro.texi | 119 +++++++++++++++++++--------- > 1 file changed, 81 insertions(+), 38 deletions(-) Thanks, I have a few minor comments: > @cindex Setting a key globally > -@cindex Global set key > +@cindex Keymap global set > @cindex Key setting globally > -@findex global-set-key Please add index entries for the new APIs, but do not remove the index entries for old ones. Readers could still need to look up the old interfaces via index search. > -@findex global-unset-key > +@findex keymap-global-unset Same here. > +@subsection Legacy Global Key Binding Commands > + > +@findex global-set-key > +@cindex Global set key > +Historically, keys are bound globally using a lower-level function, > +@code{global-set-key}, which is now considered legacy. While you are > +encouraged to use @code{keymap-global-set}, you likely would encounter > +@code{global-set-key} in various places. The first example can be > +rewritten using @code{global-set-key} as: > + > +@smallexample > +@group > +(global-set-key "\C-cw" 'compare-windows) > +@end group > +@end smallexample The text says "first example", but which example is that? There are no examples in this subsection. > +Historically, keys are unbound globally using a lower-function, > +@code{global-unset-key}, which is now considered legacy. Its key > +binding format follows that of @code{global-set-key}. The above key > +unbinding example can be rewritten as: Same here: "the above key unbinding example" refers to an example in a different subsection. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Sat Dec 28 14:56:21 2024 Received: (at 74999) by debbugs.gnu.org; 28 Dec 2024 19:56:21 +0000 Received: from localhost ([127.0.0.1]:52681 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tRcv6-0006Vx-6O for submit@debbugs.gnu.org; Sat, 28 Dec 2024 14:56:21 -0500 Received: from sender4-of-o52.zoho.com ([136.143.188.52]:21290) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tRcv3-0006Vl-Eo for 74999@debbugs.gnu.org; Sat, 28 Dec 2024 14:56:18 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1735415768; cv=none; d=zohomail.com; s=zohoarc; b=PdSXGxKUYWV+ldGKf2dc2/aBIeCiRlBkgwiLlJlAJ7sLkq7je4R/IeSWNgKrIrm+kMOCcKI7qutHBtG6JnVIwcVsILzTxtFVc3xbZiOfq/Esym0VaVtmh4PoojDhNde3M5WN/KPN4j/0YgU+e8PQPsFJlkCCvs2l2JwIdDZRloo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1735415768; 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=2KnAdHAVNoggD8sAlzcME4hYFMwcZp2CsElTd29AfvQ=; b=Li1PAqQ/mrOcJXy7FSDvN3aXJGGd6oI6VancREHff8sGb5MfSfmCWVJkRsW8tbCeZg0yiAXKDEKcMZE2dsEtlqqVzeIcZCr4lFwFOCuR7dDVmFCzTR71sLqpgR+pUOfE8lwfoXkSGe5K8BNR3unbz4sPY8bpZK6JkWh4allEuQQ= 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=1735415768; 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=2KnAdHAVNoggD8sAlzcME4hYFMwcZp2CsElTd29AfvQ=; b=WadrldxgBd5F5zOfOph82z0wachpwSdW84lezvv2r2k2PlpECpkcEEhuUYZzFK2F ioqjbcDN0/JY+kg7Waab4tTQ4nBJ3R9FADjyNRZNTvPXHFyHkukPzjn6HDQpmvSsB7O YR0JdiRxuczAidVNVLhdf+3q8r/VhIj5ZTgaJ+Yg= Received: by mx.zohomail.com with SMTPS id 1735415766127753.3098464106029; Sat, 28 Dec 2024 11:56:06 -0800 (PST) From: Hong Xu To: Eli Zaretskii Subject: Re: bug#74999: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro In-Reply-To: <86seq8roh3.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 28 Dec 2024 14:17:28 +0200") References: <86ed1uzwhw.fsf@gnu.org> <20241226214814.52057-1-hong@topbug.net> <86seq8roh3.fsf@gnu.org> User-Agent: mu4e 1.12.8; emacs 29.4 Date: Sat, 28 Dec 2024 11:56:05 -0800 Message-ID: <877c7jzine.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: 74999 Cc: 74999@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 2024-12-28 Sat 04:17 GMT-08, Eli Zaretskii wrote: >> From: Hong Xu >> Date: Thu, 26 Dec 2024 13:46:39 -0800 >> >> * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since >> `global-set-key' and `define-key' are considered legacy, we encourage >> `keymap-global-set' and `keymap-set' now. >> --- >> doc/lispintro/emacs-lisp-intro.texi | 119 +++++++++++++++++++--------- >> 1 file changed, 81 insertions(+), 38 deletions(-) > > Thanks, I have a few minor comments: > >> @cindex Setting a key globally >> -@cindex Global set key >> +@cindex Keymap global set >> @cindex Key setting globally >> -@findex global-set-key > > Please add index entries for the new APIs, but do not remove the index > entries for old ones. Readers could still need to look up the old > interfaces via index search. > >> -@findex global-unset-key >> +@findex keymap-global-unset > > Same here. I moved these two indices to the legacy subsection, which is now the place that describes these functions. > >> +@subsection Legacy Global Key Binding Commands >> + >> +@findex global-set-key >> +@cindex Global set key >> +Historically, keys are bound globally using a lower-level function, >> +@code{global-set-key}, which is now considered legacy. While you are >> +encouraged to use @code{keymap-global-set}, you likely would encounter >> +@code{global-set-key} in various places. The first example can be >> +rewritten using @code{global-set-key} as: >> + >> +@smallexample >> +@group >> +(global-set-key "\C-cw" 'compare-windows) >> +@end group >> +@end smallexample > > The text says "first example", but which example is that? There are > no examples in this subsection. > >> +Historically, keys are unbound globally using a lower-function, >> +@code{global-unset-key}, which is now considered legacy. Its key >> +binding format follows that of @code{global-set-key}. The above key >> +unbinding example can be rewritten as: > > Same here: "the above key unbinding example" refers to an example in a > different subsection. The updated patch now adds an "in this section" qualifier. Please see the attachment. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=v5-0001-Use-keymap-set-over-global-set-key-define-key-in-.patch >From b25a4cd7fedaec382b0d486493a1208276e618de Mon Sep 17 00:00:00 2001 From: Hong Xu Date: Thu, 19 Dec 2024 14:33:35 -0800 Subject: [PATCH v5] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since `global-set-key' and `define-key' are considered legacy, we encourage `keymap-global-set' and `keymap-set' now. --- doc/lispintro/emacs-lisp-intro.texi | 120 +++++++++++++++++++--------- 1 file changed, 82 insertions(+), 38 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 49916235fbf9..863e06346edc 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -13810,7 +13810,7 @@ Whitespace Bug If you wish, you can also install this key binding by evaluating it: @smallexample -(global-set-key "\C-c=" '@value{COUNT-WORDS}) +(keymap-global-set "C-c =" '@value{COUNT-WORDS}) @end smallexample To conduct the first test, set mark and point to the beginning and end @@ -14762,7 +14762,7 @@ count-words-in-defun Let's reuse @kbd{C-c =} as a convenient key binding: @smallexample -(global-set-key "\C-c=" 'count-words-defun) +(keymap-global-set "C-c =" 'count-words-defun) @end smallexample Now we can try out @code{count-words-defun}: install both @@ -17229,7 +17229,7 @@ Key Bindings @smallexample @group ;;; Compare windows -(global-set-key "\C-cw" 'compare-windows) +(keymap-global-set "C-c w" 'compare-windows) @end group @end smallexample @@ -17242,20 +17242,18 @@ Key Bindings This also shows how to set a key globally, for all modes. @cindex Setting a key globally -@cindex Global set key +@cindex Keymap global set @cindex Key setting globally -@findex global-set-key -The command is @code{global-set-key}. It is followed by the -key binding. In a @file{.emacs} file, the keybinding is written as -shown: @code{\C-c} stands for Control-C, which means to press the -control key and the @kbd{c} key at the same time. The @code{w} means -to press the @kbd{w} key. The key binding is surrounded by double -quotation marks. In documentation, you would write this as -@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as -@kbd{M-c}, rather than a @key{CTRL} key, you would write -@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , -Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for -details.) +@findex keymap-global-set +The key setting command is @code{keymap-global-set}. It is followed by +the key binding. In a @file{.emacs} file, the keybinding is written as +shown: @code{C-c} stands for Control-C, which means to press the control +key and the @kbd{c} key at the same time. The @code{w} means to press +the @kbd{w} key. The key binding is surrounded by double quotation +marks. (If you were binding a @key{META} key, rather than a @key{CTRL} +key, you would write @w{@code{M-c}} in your @file{.emacs} file. +@xref{Init Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU +Emacs Manual}, for details.) The command invoked by the keys is @code{compare-windows}. Note that @code{compare-windows} is preceded by a single-quote; otherwise, Emacs @@ -17284,7 +17282,7 @@ Key Bindings @group ;;; Key binding for 'occur' ; I use occur a lot, so let's bind it to a key: -(global-set-key "\C-co" 'occur) +(keymap-global-set "C-c o" 'occur) @end group @end smallexample @@ -17296,7 +17294,7 @@ Key Bindings Matching lines are shown in a buffer called @file{*Occur*}. That buffer serves as a menu to jump to occurrences. -@findex global-unset-key +@findex keymap-global-unset @cindex Unbinding key @cindex Key unbinding @need 1250 @@ -17306,7 +17304,7 @@ Key Bindings @smallexample @group ;;; Unbind 'C-x f' -(global-unset-key "\C-xf") +(keymap-global-unset "C-x f") @end group @end smallexample @@ -17324,7 +17322,7 @@ Key Bindings @smallexample @group ;;; Rebind 'C-x C-b' for 'buffer-menu' -(global-set-key "\C-x\C-b" 'buffer-menu) +(keymap-global-set "C-x C-b" 'buffer-menu) @end group @end smallexample @@ -17336,33 +17334,80 @@ Key Bindings command, which not only lists the buffers, but moves point into that window. +@subsection Legacy Global Key Binding Commands + +@findex global-set-key +@cindex Global set key +Historically, keys are bound globally using a lower-level function, +@code{global-set-key}, which is now considered legacy. While you are +encouraged to use @code{keymap-global-set}, you likely would encounter +@code{global-set-key} in various places. The first example in this +section can be rewritten using @code{global-set-key} as: + +@smallexample +@group +(global-set-key "\C-cw" 'compare-windows) +@end group +@end smallexample + +It is very similar to @code{keymap-global-set}, with the keybinding +following a slightly different format. Control-C is represented by +@code{\C-c}, instead of @code{C-c}. There is no space between key +strokes, like @code{\C-c} and @code{w} in this example. Despite the +difference, in documentation, this is still written as @w{@kbd{C-c w}} +for readability. + +@findex global-unset-key +Historically, keys are unbound globally using a lower-function, +@code{global-unset-key}, which is now considered legacy. Its key +binding format follows that of @code{global-set-key}. The key unbinding +example in this section can be rewritten as: + +@smallexample +@group +;;; Unbind 'C-x f' +(global-unset-key "\C-xf") +@end group +@end smallexample + @node Keymaps @section Keymaps @cindex Keymaps @cindex Rebinding keys Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the key binding for a single -command in all parts of Emacs, you are specifying the key binding in -@code{current-global-map}. +When you use @code{keymap-global-set} to set the key binding for a +single command in all parts of Emacs, you are specifying the key binding +in @code{current-global-map}. Specific modes, such as C mode or Text mode, have their own keymaps; the mode-specific keymaps override the global map that is shared by all buffers. -The @code{global-set-key} function binds, or rebinds, the global +The @code{keymap-global-set} function binds, or rebinds, the global keymap. For example, the following binds the key @kbd{C-x C-b} to the function @code{buffer-menu}: @smallexample -(global-set-key "\C-x\C-b" 'buffer-menu) +(keymap-global-set "C-x C-b" 'buffer-menu) @end smallexample -Mode-specific keymaps are bound using the @code{define-key} function, +Mode-specific keymaps are bound using the @code{keymap-set} function, which takes a specific keymap as an argument, as well as the key and -the command. For example, my @file{.emacs} file contains the -following expression to bind the @code{texinfo-insert-@@group} command -to @kbd{C-c C-c g}: +the command. For example, the following expression binds the +@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}: + +@smallexample +@group +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group) +@end group +@end smallexample + +Historically, keymaps are bound using a lower-level function, +@code{define-key}, which is now considered legacy. While you are +encouraged to use @code{keymap-set}, you likely would encounter +@code{define-key} in various places. The above key binding can be +rewritten using @code{define-key} as: @smallexample @group @@ -17396,9 +17441,9 @@ Keymaps write a function to insert a word; but I prefer key strokes consistent with other Texinfo mode key bindings.) -You will see numerous @code{define-key} expressions in -@file{loaddefs.el} as well as in the various mode libraries, such as -@file{cc-mode.el} and @file{lisp-mode.el}. +You will see numerous @code{keymap-set} and @code{define-key} +expressions in @file{loaddefs.el} as well as in the various mode +libraries, such as @file{cc-mode.el} and @file{lisp-mode.el}. @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp @@ -17440,13 +17485,12 @@ Loading Files @need 1250 To replace the key binding for the default -@code{split-window-vertically}, you must also unset that key and bind -the keys to @code{split-window-quietly}, like this: +@code{split-window-vertically}, you must bind the keys to +@code{split-window-quietly}, like this: @smallexample @group -(global-unset-key "\C-x2") -(global-set-key "\C-x2" 'split-window-quietly) +(keymap-global-set "C-x 2" 'split-window-quietly) @end group @end smallexample @@ -17608,7 +17652,7 @@ Simple Extension this: @smallexample -(global-set-key [f6] 'line-to-top-of-window) +(keymap-global-set "" 'line-to-top-of-window) @end smallexample For more information, see @ref{Init Rebinding, , Rebinding Keys in @@ -18791,7 +18835,7 @@ the-the @group ;; Bind 'the-the' to C-c \ -(global-set-key "\C-c\\" 'the-the) +(keymap-global-set "C-c \\" 'the-the) @end group @end smallexample -- 2.47.1 --=-=-= Content-Type: text/plain -- Hong --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 01 20:26:23 2025 Received: (at control) by debbugs.gnu.org; 2 Jan 2025 01:26:23 +0000 Received: from localhost ([127.0.0.1]:41153 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tT9yg-0000Vq-Ne for submit@debbugs.gnu.org; Wed, 01 Jan 2025 20:26:22 -0500 Received: from mail-ed1-x530.google.com ([2a00:1450:4864:20::530]:42012) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from ) id 1tT9ye-0000VR-Nb for control@debbugs.gnu.org; Wed, 01 Jan 2025 20:26:21 -0500 Received: by mail-ed1-x530.google.com with SMTP id 4fb4d7f45d1cf-5d41848901bso20961049a12.0 for ; Wed, 01 Jan 2025 17:26:20 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1735781175; x=1736385975; darn=debbugs.gnu.org; h=to:subject:message-id:date:mime-version:from:from:to:cc:subject :date:message-id:reply-to; bh=HbzEC3VsTB3NNibkUf33B+fyvoMli2pOdsysvM2Ga5Y=; b=gd2W4SPU4Xuo/kqyz+UhgBz7qYFtvqTGHyfKTGMh6UWGAfC3hQVwsMGYdYThaFfsyS QONwh3bPLUgdlT66lHF80n1uXKNVSMfaoG9tDI13xI5vER6+hURaUubPfgHvuWZRiW1t MdKi/Kfau84AxxoWhSa5ZI6xeOdbAjTzZOpuecikwPEwYgGb+FYUk63K+3bYLk7MSSlc pkEl7ZAFoF7/1aofhTRPvK30FGbQzMYs0D3LaHRSTt9MPKBmQ9GP0TZhzR4oXJwXZ/gD CSaWqiSmVdT7fhTFYGqbRDRb/L5aW7qOCPGgiYe8hg3uU9o/kv7G2XoxIkRM3STXgtgn LSIg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1735781175; x=1736385975; h=to:subject:message-id:date:mime-version:from:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=HbzEC3VsTB3NNibkUf33B+fyvoMli2pOdsysvM2Ga5Y=; b=MK68nTZ3MctNBqDsRaUUY09A/c6JD5N8Nh8Au2UmrIUfyHoMG7VMvK8l2Qekfo5vNY RuqZBJjFB4RwVld5rLy0gLahYCD+LijvLcVCQxlyG/+qNq6qWRtCu3mqBvXndboImmeq 7i+YOVxsKa6/v6UhaaPGKnF/a15npxNV9RkgMbqAqfvqHXWgB62iTHyIsr34zyT0Am7T cp+DJFio4HeMyvRA35By90t8lTUBomtjKIwUMZvtpBZooYKZi9TLfFsRFAuiyK/WUFtY xtbRN5IyAsMNz+hjB4OZMhe71gRBVadOXLuF7pvPm4p7eAexlDe+wEj+s0JYAHBPUIYw wH5A== X-Gm-Message-State: AOJu0YwTGvp1JmWOo2103DOWqdq+YrDBhlRY+r7487axkSlIwOf9bNAw wHyQkowh95rodO7oMdiHZJ6UZe+w+PaFR8hBsyg+KeMuRUe818zfpp5wgJb4rPdnscrRJEbzTZo k3J1eS1r99v63LS4b6DNjQTxZYDezTpMI X-Gm-Gg: ASbGnctb7ITlYoQ2sEfwOilWN7WmItlWeG5T8sn4HqYJKeCrHqimuM9w0Hd1xHxtWtk 4AmB5HN9fB/vxuHZ7FiVsgAHvcUDh5RWIeViuu6qT X-Google-Smtp-Source: AGHT+IEFkYrK1MWX5Gw6zf+0V0fGIPmIVXNhNhJYZ8b+BJeVh9bThDkM1kxarrZ5uG8ty3PHp7TMJkCC2bjfE0wPK8U= X-Received: by 2002:a05:6402:3495:b0:5d0:f6ed:4cd1 with SMTP id 4fb4d7f45d1cf-5d81e7509c9mr41707483a12.10.1735781174630; Wed, 01 Jan 2025 17:26:14 -0800 (PST) Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Wed, 1 Jan 2025 19:26:14 -0600 From: Stefan Kangas MIME-Version: 1.0 Date: Wed, 1 Jan 2025 19:26:14 -0600 Message-ID: Subject: control message for bug #74999 To: control@debbugs.gnu.org Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control 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 (-) severity 74999 wishlist quit From debbugs-submit-bounces@debbugs.gnu.org Sat Jan 04 07:34:45 2025 Received: (at 74999-done) by debbugs.gnu.org; 4 Jan 2025 12:34:45 +0000 Received: from localhost ([127.0.0.1]:53790 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tU3MZ-0005VI-UY for submit@debbugs.gnu.org; Sat, 04 Jan 2025 07:34:44 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:46524) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tU3MV-0005V1-RE for 74999-done@debbugs.gnu.org; Sat, 04 Jan 2025 07:34:41 -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 1tU3MQ-0002Ep-En; Sat, 04 Jan 2025 07:34:34 -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=ZP5N3hvt/4JGunWyuCfN01tjxMQLKlHe6PInNOLBBlo=; b=WvtX5Z9lSeAs 12eMOLl0I3pf4bYOgdJvTfiwzl8g8YH8D6NohGvAm/d0A66H36IibYpX1oeJKJa3ZhZxuiHp4ydwD yfPhWZ2HrZl5a8OfXqEaZJ8Yp0wPNX9yhWDuMztSM3VSt7d+FP1ASr/gQm31JElfC5yarcnxcmXlv Rmag02YayzQn3bALEssD7GAw65fAk0uE85ucp72kvR354yrMOwYhiVWRhZoVJ2d/u64GHlVYDr62k +q8fuyaoTsruy/5eg4yJMpmMeHtzYzqL7YuGriVn577/Ah/F0z0cDx1LXwIb/JlF32kVIn7CO8Jxf DkSTdUPw+L4l+ratFDFxyw==; Date: Sat, 04 Jan 2025 14:34:30 +0200 Message-Id: <861pxiep0p.fsf@gnu.org> From: Eli Zaretskii To: Hong Xu In-Reply-To: <877c7jzine.fsf@topbug.net> (message from Hong Xu on Sat, 28 Dec 2024 11:56:05 -0800) Subject: Re: bug#74999: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro References: <86ed1uzwhw.fsf@gnu.org> <20241226214814.52057-1-hong@topbug.net> <86seq8roh3.fsf@gnu.org> <877c7jzine.fsf@topbug.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 74999-done Cc: 74999-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: 74999@debbugs.gnu.org > Date: Sat, 28 Dec 2024 11:56:05 -0800 > > On 2024-12-28 Sat 04:17 GMT-08, Eli Zaretskii wrote: > > >> From: Hong Xu > >> Date: Thu, 26 Dec 2024 13:46:39 -0800 > >> > >> * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since > >> `global-set-key' and `define-key' are considered legacy, we encourage > >> `keymap-global-set' and `keymap-set' now. > >> --- > >> doc/lispintro/emacs-lisp-intro.texi | 119 +++++++++++++++++++--------- > >> 1 file changed, 81 insertions(+), 38 deletions(-) > > > > Thanks, I have a few minor comments: > > > >> @cindex Setting a key globally > >> -@cindex Global set key > >> +@cindex Keymap global set > >> @cindex Key setting globally > >> -@findex global-set-key > > > > Please add index entries for the new APIs, but do not remove the index > > entries for old ones. Readers could still need to look up the old > > interfaces via index search. > > > >> -@findex global-unset-key > >> +@findex keymap-global-unset > > > > Same here. > > I moved these two indices to the legacy subsection, which is now the > place that describes these functions. > > > > >> +@subsection Legacy Global Key Binding Commands > >> + > >> +@findex global-set-key > >> +@cindex Global set key > >> +Historically, keys are bound globally using a lower-level function, > >> +@code{global-set-key}, which is now considered legacy. While you are > >> +encouraged to use @code{keymap-global-set}, you likely would encounter > >> +@code{global-set-key} in various places. The first example can be > >> +rewritten using @code{global-set-key} as: > >> + > >> +@smallexample > >> +@group > >> +(global-set-key "\C-cw" 'compare-windows) > >> +@end group > >> +@end smallexample > > > > The text says "first example", but which example is that? There are > > no examples in this subsection. > > > >> +Historically, keys are unbound globally using a lower-function, > >> +@code{global-unset-key}, which is now considered legacy. Its key > >> +binding format follows that of @code{global-set-key}. The above key > >> +unbinding example can be rewritten as: > > > > Same here: "the above key unbinding example" refers to an example in a > > different subsection. > > The updated patch now adds an "in this section" qualifier. Please see > the attachment. Thanks, installed on the emacs-30 branch, and closing the bug. From unknown Sat Jun 21 05:14:21 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:19 +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