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#69786: [PATCH] docs: mention the keymap to add keybindings to for term-mode Date: Thu, 14 Mar 2024 09:33:38 +0200 Message-ID: <86sf0tb73h.fsf@gnu.org> References: <844975c2f1ed019fb6be836643e118ed850e0605.camel@yandex.ru> <86ttl9bdp2.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="29994"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 69786@debbugs.gnu.org To: Konstantin Kharlamov Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Mar 14 08:35:03 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 1rkfcE-0007Y2-O0 for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 14 Mar 2024 08:35:02 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rkfbg-0003IX-M7; Thu, 14 Mar 2024 03:34:28 -0400 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 1rkfbe-0003IP-Qt for bug-gnu-emacs@gnu.org; Thu, 14 Mar 2024 03:34:26 -0400 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 1rkfbe-0003OI-IZ for bug-gnu-emacs@gnu.org; Thu, 14 Mar 2024 03:34:26 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rkfcD-000655-SP for bug-gnu-emacs@gnu.org; Thu, 14 Mar 2024 03:35:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 14 Mar 2024 07:35:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 69786 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 69786-submit@debbugs.gnu.org id=B69786.171040166523305 (code B ref 69786); Thu, 14 Mar 2024 07:35:01 +0000 Original-Received: (at 69786) by debbugs.gnu.org; 14 Mar 2024 07:34:25 +0000 Original-Received: from localhost ([127.0.0.1]:48095 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rkfbc-00063p-Q9 for submit@debbugs.gnu.org; Thu, 14 Mar 2024 03:34:25 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:37310) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rkfba-00063b-V3 for 69786@debbugs.gnu.org; Thu, 14 Mar 2024 03:34:23 -0400 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 1rkfav-0003G2-KL; Thu, 14 Mar 2024 03:33:41 -0400 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=q1fL8fKBVufHrWSxrTnfCYOP0aWKX/cRWcfWfb9cbRY=; b=Y6Hb8FB13LyH 1Ak1RNaT+vmxNpWhSzWdTZBnnOi+FxeO2yC5BEkO7ojRKcJEEgwDAYq8oOmq9FK45rhA4KuCNByE2 6av/EJdlGq0zzmvyWneYfagaam+BDvzAWyb5mZFrYR81Ti4IKz3PyN26ryodAT3hu5XEI6gfpLGXp 6qM0XODieDn09LsYCBaM6O1kwRFOBhIJ/qGEYm8NLve43ycp9B9iLWJFo9RsBpaAx21t9W7KjXIsm RmvWVq65Nw0sYOFwEIan2YtqvmJSYusecgOKe7YgMR+MLpEDfq2nHrSmHsmmu4bdZC7EIls4Cmlhu h1M14+1b1otiUC/9ag2E9w==; In-Reply-To: (message from Konstantin Kharlamov on Thu, 14 Mar 2024 10:20:22 +0300) 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:281585 Archived-At: > From: Konstantin Kharlamov > Cc: 69786@debbugs.gnu.org > Date: Thu, 14 Mar 2024 10:20:22 +0300 > > On Thu, 2024-03-14 at 07:11 +0200, Eli Zaretskii wrote: > > > It is completely non-intuitive (and I also for some reason didn't > > > get > > > the answer on emacs.stackexchange for the same problem when I was > > > trying to google it), so let's document that nuisance. > > > > Thanks, but the Emacs user manual is not the right place for this > > kind > > of information. > > Why not? Because this is information on the level of customization via Lisp programming, not the level of _using_ Emacs. One can use a mode without having any idea how its map is called. > > Instead, this should be mentioned in the doc string > > of term-mode. > > As a long-time Emacs user, I'd have never looked at major mode > documentation. That's because you'd expect it describe what the mode > is for, however typically if you start using a major mode, you already > know that. As a matter of fact, the mode name alone is often enough to > describe its purpose. If you ignore doc strings in Emacs, you are making a mistake, IMO. I believe many/most users do consult the doc strings, and I urge you to teach yourself to look there, not just in the manuals. The manuals don't (and cannot) cover all the public variables and functions, whereas the doc strings can and do. > I see that major mode docs may sometimes also describe keybindings I wasn't talking about the key bindings, I was talking about the specific quirk of this mode: that it has several distinct keymaps instead of just one. This is somewhat unusual, and thus deserves to be called out in the doc string of the mode, since the maps belong to the mode. (Each of the maps has its own doc string that explains its purpose, but that is not enough because those doc strings are not easily discoverable. Mentioning the maps in the doc string of the mode will close the gap.)