From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#74999: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro Date: Sat, 28 Dec 2024 14:17:28 +0200 Message-ID: <86seq8roh3.fsf@gnu.org> References: <86ed1uzwhw.fsf@gnu.org> <20241226214814.52057-1-hong@topbug.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17992"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 74999@debbugs.gnu.org To: Hong Xu Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Dec 28 13:18:30 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tRVm2-0004XW-2y for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 28 Dec 2024 13:18:30 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tRVld-0001We-8g; Sat, 28 Dec 2024 07:18:05 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tRVla-0001WL-S6 for bug-gnu-emacs@gnu.org; Sat, 28 Dec 2024 07:18:03 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tRVla-0004Hx-Ab for bug-gnu-emacs@gnu.org; Sat, 28 Dec 2024 07:18:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=References:In-Reply-To:From:Date:To:Subject; bh=pb1kiBpZkaofQALA+g8Oy4FHYxQYJL+V4lHK4/oE2GY=; b=GpU4GuZrqwYs7ViazQ0poNIvOoMbyfmaNBbaOTzPbzU+4BX3t9hl8DWMdPZGepVo7Cm64dKocqP0IMkbO10SwMfSkjDjKf7kYAQ9dluXg+fr2lZ+T54tREkMktXpb4J1U7CIHlEgWn+XHjHa4sh1m4+okK+AN1ECX8gP1JNk/hqCrZbIK2ZL9bBKYoFnjjtkDenBLPv9Zp2WjgclKgifh9tCbbedcke2ejFdffVY0S10ICs2IPDWuMC1gKs7ncnvYArA5nArwUK2QarCwbR2zSCmneSdw3RJ/KukJfZ5kL70rfeh6vBJgmJ+lWwR0pk31me2kyCAGwF2e8csrpEARA==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tRVlZ-0001oM-Up for bug-gnu-emacs@gnu.org; Sat, 28 Dec 2024 07:18:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 28 Dec 2024 12:18:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 74999 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 74999-submit@debbugs.gnu.org id=B74999.17353882606929 (code B ref 74999); Sat, 28 Dec 2024 12:18:01 +0000 Original-Received: (at 74999) by debbugs.gnu.org; 28 Dec 2024 12:17:40 +0000 Original-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 Original-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 Original-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==; In-Reply-To: <20241226214814.52057-1-hong@topbug.net> (message from Hong Xu on Thu, 26 Dec 2024 13:46:39 -0800) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:297894 Archived-At: > 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.