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 v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro Date: Sat, 21 Dec 2024 09:19:28 +0200 Message-ID: <86y1098pvj.fsf@gnu.org> References: <20241220214351.57036-1-hong@topbug.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="21427"; 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 21 08:20:15 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 1tOtmX-0005PR-Uu for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 21 Dec 2024 08:20:14 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tOtmO-00089W-VX; Sat, 21 Dec 2024 02:20: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 1tOtmM-00086v-Ol for bug-gnu-emacs@gnu.org; Sat, 21 Dec 2024 02:20:02 -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 1tOtmM-0003UQ-Eq for bug-gnu-emacs@gnu.org; Sat, 21 Dec 2024 02:20: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=ervWYEXn6hMJKBS2r309M/lZ7s8bK5gpBeXNYfiGT+Y=; b=RG3NrpA22Avz5v6y5O7v489akp3oGLgDiyKGeAkqBGssrGXgPUuMviUxcs5Fe8T4yUePDOGL/B2m9P0IcZd1mLE00kK/k/iEKfgf/kIP+/hsC6Kbkbxt+Rdze1MGG+Sfek4umSNnNske55H/CtTCbFqG0X17eNkbBiwEkvw2ayTpW+adY/+JLWf4qhK/CFW7btA5A9bU3kL7Xvse4G4cgJMdfDldVkSWQg2HQINY/Ih54jAIcmFSqormFbl2LzoDnLGeaVudDfmrZ2sBw1PY2Mnj/zcAV5WFQWwESIConGkdihGRbbfxRSHhm0/3N21G0pSVDOo1AI+yYKXl3tMSiw==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tOtmM-000100-0y for bug-gnu-emacs@gnu.org; Sat, 21 Dec 2024 02:20:02 -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, 21 Dec 2024 07:20: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.17347655793797 (code B ref 74999); Sat, 21 Dec 2024 07:20:01 +0000 Original-Received: (at 74999) by debbugs.gnu.org; 21 Dec 2024 07:19:39 +0000 Original-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 Original-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 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 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==; In-Reply-To: <20241220214351.57036-1-hong@topbug.net> (message from Hong Xu on Fri, 20 Dec 2024 13:42:29 -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:297490 Archived-At: > 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.