From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Konstantin Kharlamov Newsgroups: gmane.emacs.bugs Subject: bug#69786: [PATCH] docs: mention the keymap to add keybindings to for term-mode Date: Thu, 14 Mar 2024 10:53:50 +0300 Message-ID: <4f76012b122ae8334689a6b124ffb671a72f1454.camel@yandex.ru> References: <844975c2f1ed019fb6be836643e118ed850e0605.camel@yandex.ru> <86ttl9bdp2.fsf@gnu.org> <86sf0tb73h.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="12129"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Evolution 3.50.4 Cc: 69786@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Mar 14 08:55:44 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 1rkfwF-00032x-Vu for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 14 Mar 2024 08:55:43 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rkfw6-0007pa-B5; Thu, 14 Mar 2024 03:55:34 -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 1rkfw3-0007kK-8T for bug-gnu-emacs@gnu.org; Thu, 14 Mar 2024 03:55:31 -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 1rkfvy-0007Zh-Rl for bug-gnu-emacs@gnu.org; Thu, 14 Mar 2024 03:55:30 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rkfwY-0006xO-B6 for bug-gnu-emacs@gnu.org; Thu, 14 Mar 2024 03:56:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Konstantin Kharlamov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 14 Mar 2024 07:56:02 +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.171040290326616 (code B ref 69786); Thu, 14 Mar 2024 07:56:02 +0000 Original-Received: (at 69786) by debbugs.gnu.org; 14 Mar 2024 07:55:03 +0000 Original-Received: from localhost ([127.0.0.1]:48195 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rkfva-0006vE-FY for submit@debbugs.gnu.org; Thu, 14 Mar 2024 03:55:02 -0400 Original-Received: from forward500a.mail.yandex.net ([178.154.239.80]:53382) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rkfvY-0006ui-6O for 69786@debbugs.gnu.org; Thu, 14 Mar 2024 03:55:00 -0400 Original-Received: from mail-nwsmtp-smtp-production-main-18.vla.yp-c.yandex.net (mail-nwsmtp-smtp-production-main-18.vla.yp-c.yandex.net [IPv6:2a02:6b8:c0d:3621:0:640:20a5:0]) by forward500a.mail.yandex.net (Yandex) with ESMTPS id 38BB4618FB; Thu, 14 Mar 2024 10:53:51 +0300 (MSK) Original-Received: by mail-nwsmtp-smtp-production-main-18.vla.yp-c.yandex.net (smtp/Yandex) with ESMTPSA id orieaeRLjGk0-FGMvvJ3l; Thu, 14 Mar 2024 10:53:50 +0300 X-Yandex-Fwd: 1 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yandex.ru; s=mail; t=1710402831; bh=x6RHZGcnz4HaMcHfeKLcZmMvIPzAMfhn2EPPE6PNAkc=; h=References:Date:In-Reply-To:Cc:To:From:Subject:Message-ID; b=plXG4R2vsZ/X2mw6KnX6zuJvZeQFdk5/W6hCJlMBDhYvQsLhh8IsiQteqRM3UqdX2 aB6IV4th6SOoJ8kwNmHpnTqpbGMq0f6lrMPIRFOMr2M88oh7ZnDD1JY95LDD7UAG7I mjQ6BzbPxORQZGxZeuVkn6EVcEy39wgBiY/yLBFY= Authentication-Results: mail-nwsmtp-smtp-production-main-18.vla.yp-c.yandex.net; dkim=pass header.i=@yandex.ru In-Reply-To: <86sf0tb73h.fsf@gnu.org> 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:281589 Archived-At: On Thu, 2024-03-14 at 09:33 +0200, Eli Zaretskii wrote: >=20 > If you ignore doc strings in Emacs, you are making a mistake, IMO.=C2=A0 = 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.=C2=A0 The manuals > don't (and cannot) cover all the public variables and functions, > whereas the doc strings can and do. I don't "ignore doc strings in Emacs", that is impossible to do because you have to consult at least function docs to customize, fix problems, etc =F0=9F=98=8A Instead I ignore specifically major mode documentation an= d I'd be surprised if too many other people read it. You see, documentation should be intuitive. A user asks a question "how to do X", the answer intuitively should be "search docs for X". If you ask "why my customizations to term-mode-map do not work?", the answer would be "look at term-mode-map docs, perhaps it mentions something". Similarly, by intuition, if I ask myself "what docs do I expect the `term-mode` to have", I'd reply "General information about the mode, i.e. that it launches a terminal and maybe a reference to shell and eshell alternatives". I'd not expect my problem with the not working keybindings to be mentioned in term-mode doc-string (even if it is actually there). > > I see that major mode docs may sometimes also describe keybindings >=20 > 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.=C2=A0 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.=C2=A0 (Each of the maps has its own doc string that explains it= s > purpose, but that is not enough because those doc strings are not > easily discoverable.=C2=A0 Mentioning the maps in the doc string of the > mode will close the gap.) Okay then, I'll add docs to the `term-mode` if you think it might be useful for someone and (re: the other email) to `term-mode-map` and `term-raw-map` variables =F0=9F=98=8A