From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: JD Smith Newsgroups: gmane.emacs.bugs Subject: bug#68236: [PATCH] help.el: allow help-quick to use local commands/quick-sections Date: Fri, 5 Jan 2024 12:00:32 -0500 Message-ID: References: <1B0F351A-C393-4C1B-B883-814F2C33E802@gmail.com> <83a5ply2ca.fsf@gnu.org> <721ABC11-E691-43F9-9034-F375240C2E20@gmail.com> <83sf3dw699.fsf@gnu.org> <4CB34A88-87DE-4347-A886-4BF8D4998E67@gmail.com> <835y08w4v1.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3774.300.61.1.2\)) Content-Type: multipart/alternative; boundary="Apple-Mail=_E7F07FC7-5300-4430-9253-F145EF9BB797" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="26385"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 68236@debbugs.gnu.org, Stefan Kangas To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Jan 05 18:02:02 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 1rLna5-0006b9-DU for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 05 Jan 2024 18:02:01 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rLnZ9-0003cQ-Bq; Fri, 05 Jan 2024 12:01:03 -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 1rLnZ4-0003bH-Hq for bug-gnu-emacs@gnu.org; Fri, 05 Jan 2024 12:00:58 -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 1rLnZ4-00078m-9H for bug-gnu-emacs@gnu.org; Fri, 05 Jan 2024 12:00:58 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rLnZ8-0000ht-AG for bug-gnu-emacs@gnu.org; Fri, 05 Jan 2024 12:01:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: JD Smith Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 05 Jan 2024 17:01:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 68236 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 68236-submit@debbugs.gnu.org id=B68236.17044740602535 (code B ref 68236); Fri, 05 Jan 2024 17:01:02 +0000 Original-Received: (at 68236) by debbugs.gnu.org; 5 Jan 2024 17:01:00 +0000 Original-Received: from localhost ([127.0.0.1]:57755 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rLnZ5-0000e2-ED for submit@debbugs.gnu.org; Fri, 05 Jan 2024 12:01:00 -0500 Original-Received: from mail-qk1-x72c.google.com ([2607:f8b0:4864:20::72c]:42257) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rLnZ1-0000Ov-Cs for 68236@debbugs.gnu.org; Fri, 05 Jan 2024 12:00:58 -0500 Original-Received: by mail-qk1-x72c.google.com with SMTP id af79cd13be357-78104f6f692so57426985a.1 for <68236@debbugs.gnu.org>; Fri, 05 Jan 2024 09:00:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1704474045; x=1705078845; darn=debbugs.gnu.org; h=references:to:cc:in-reply-to:date:subject:mime-version:message-id :from:from:to:cc:subject:date:message-id:reply-to; bh=//3rDSWoXosCOamgu6gWPDrQXqSZO5Rv/4XKBn50nSI=; b=LBRJ5WsfJzeW21WMdAjXPYaBAIAaxS+c2wbw8imSGGTnOAzdRHP4IDHRLnz5r3Te5a 2Nlci7FJBTpMC+y8Q7aKRmpCtBJRdlt7C+D7FExVPd5NMVTbBLyrri31Fw2PjuGXiUid jy7UjLtyGNsuGtIdPnNKPw0KeBbmUjz0v+0Yx1iGmuT9XgDwXK+zUGGO1tjbgHyxkdDm MVm6PZXdw1vY+B9UytUw/1N2oB+GX50NcL/iKk/Odq2EqCjmM2ynXDnJqJbIAQhu4Kok 2sLxhvGY5c2apldpdnGuDfHKoXntfOwsh4H7+XZccABeOt8qhxv0aMGQttT3AR3LAufv 9riw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704474045; x=1705078845; h=references:to:cc:in-reply-to:date:subject:mime-version:message-id :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=//3rDSWoXosCOamgu6gWPDrQXqSZO5Rv/4XKBn50nSI=; b=gV8a88WssXcduPW8bMyjgdO3CPUGcgguV3a3cVxKnd6H/wZ2ZZdw9Fkm92vFF024Jc 4Bbgtk3hoSIa7Nv0gsddN3ew/ziqoDZKP64vzUqTUlBSalPEr9Jm9rKqu7BD/GIaMw6W G2nVjY+l9SyciBzro0PIpR05/KxwsRNQCqhAka6/4bqsuN9UGphfup9Fo1M6+d+MKdzi kgTgneguXg7P79Lf4DYGrQtPqRt6pQnNK6lUnQeX6Gt739RVUwG6C8czjP/iFAAtASxf aBkLslExUPCh1eeS4BMGq+C+EQUgbEOIGnBWCjrNxdXxMAMBTy2mSPhUREq9wYIf3dNr bypQ== X-Gm-Message-State: AOJu0Yxa/7shtA1YVOAhIHkF9F5GrsxjMpLpeN5oPu7Jcy7eMvMGrWaf 47OWGWif9RWsaIA6pc20SW0= X-Google-Smtp-Source: AGHT+IFB4f/06NVNyECAmw89cay+tDjBlL6vhgjH6aR0/y0WgREwmPwROKSz8RYY8fSYDdkH/zqtvQ== X-Received: by 2002:a05:620a:468f:b0:783:bf8:7f82 with SMTP id bq15-20020a05620a468f00b007830bf87f82mr1284037qkb.70.1704474044811; Fri, 05 Jan 2024 09:00:44 -0800 (PST) Original-Received: from smtpclient.apple (cm-24-53-187-34.buckeyecom.net. [24.53.187.34]) by smtp.gmail.com with ESMTPSA id c27-20020a05620a11bb00b007816cf21f7asm711852qkk.76.2024.01.05.09.00.43 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Fri, 05 Jan 2024 09:00:43 -0800 (PST) In-Reply-To: <835y08w4v1.fsf@gnu.org> X-Mailer: Apple Mail (2.3774.300.61.1.2) 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:277402 Archived-At: --Apple-Mail=_E7F07FC7-5300-4430-9253-F145EF9BB797 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 > On Jan 5, 2024, at 3:40=E2=80=AFAM, Eli Zaretskii = wrote: >=20 >> From: JD Smith >> Date: Thu, 4 Jan 2024 20:28:27 -0500 >> Cc: 68236@debbugs.gnu.org >>=20 >>> On Jan 4, 2024, at 8:57=E2=80=AFAM, Eli Zaretskii = wrote: >>>=20 >>> If we are going to expose help-quick-sections as a defcustom, then I >>> don't understand why we need to change the code at all. Is the idea >>> that sections will depend on the current buffer? If so, then we = just >>> need to add an element to the list members which will store the >>> major-mode for which the member is relevant. >>>=20 >>> Or what am I missing? >>=20 >> Right now the code does >>=20 >> (with-current-buffer (get-buffer-create "*Quick Help*") >>=20 >> right away, then checks `where-is-internal' for each listed command = in `help-quick-sections'. So only global bindings (and bindings = available in help-mode) are accessible for display. My patch simply = delays switching to *Quick Help* buffer, so that binding information can = be gathered from the local buffer from which quick help was summoned. = Note that help-quick omits any bindings that are nil, as well as any = empty sections. So adding sections to the defcustom that do not apply = (=3Dhave no bindings) in some buffer is not a problem. =20 >=20 > Your proposal has the disadvantage that the user must switch to a > buffer under some major mode to see the entries for that mode in the > quick-help window. It could be an annoyance; e.g., consider a user > who wants to see this while in a *Help* buffer. And I don't think > being in the buffer under the major mode is the only way of getting > mode-specific bindings; for example, where-is-internal can accept a > KEYMAP argument, which will be used to find key bindings. The current disadvantage is related, but much worse than this: you = currently cannot configure quick help to show any bindings other than = global and help-mode bindings. It might be nice to see e.g. = org-bindings from anywhere, but to me it=E2=80=99s an advantage to show = =E2=80=9Cquick help for this mode=E2=80=9D. > Or maybe we should have a separate command for cheat sheets specific > to a major mode. The window we pop up cannot be too large, so if the > user only wants a quick help for the current mode, she might consider > global bindings an annoying waste of screen estate. =20 I=E2=80=99d probably disable most of the global bindings, since I = already know those. But some are useful (e.g. I often forget the = project bindings). =20 > Moreover, the > current quick help shows "popular commands", which are likely to be > already known to some users, whereas when the user works in a major > mode that is new to the user, one is likely to be in the need of the > cheat sheet for that one mode. (Yes, we do already have "C-h b", but > the output of that could be overwhelming: for example in an Org buffer > I get almost 1400 lines in the *Help* buffer showing the Org-specific > bindings.) Agree, this is a real problem for discoverability. Also command names = are not always informative enough to find what you are actually looking = for (org is terrible for this). > IOW, if we want to consider mode-specific quick help, we should > perhaps discuss more about the goals before we consider code tricks to > implement it. I do like this idea. Perhaps mode authors could add a =E2=80=9Cstarter = pack=E2=80=9D of this information themselves, if they are suitably = admonished to keep this information brief, high level, and with clear = few-word command descriptions. Perhaps adding a =E2=80=98help-quick = property to the mode command symbol? =20 One guiding principle I suggest: users in the end should be able to = decide what quick help they need; what=E2=80=99s memorable for some may = be frequently forgotten for others.=20 --Apple-Mail=_E7F07FC7-5300-4430-9253-F145EF9BB797 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=utf-8

On Jan 5, 2024, at 3:40=E2=80=AFAM, Eli Zaretskii = <eliz@gnu.org> wrote:

From: JD Smith = <jdtsmith@gmail.com>
Date: Thu, 4 Jan 2024 20:28:27 = -0500
Cc: 68236@debbugs.gnu.org

On = Jan 4, 2024, at 8:57=E2=80=AFAM, Eli Zaretskii <eliz@gnu.org> = wrote:

If we are going to expose help-quick-sections as a = defcustom, then I
don't understand why we need to change the code at = all.  Is the idea
that sections will depend on the current = buffer?  If so, then we just
need to add an element to the list = members which will store the
major-mode for which the member is = relevant.

Or what am I missing?

Right now the = code does

 (with-current-buffer (get-buffer-create "*Quick = Help*")

right away, then checks `where-is-internal' for each = listed command in `help-quick-sections'.  So only global bindings = (and bindings available in help-mode) are accessible for display. =  My patch simply delays switching to *Quick Help* buffer, so that = binding information can be gathered from the local buffer from which = quick help was summoned.  Note that help-quick omits any bindings = that are nil, as well as any empty sections.  So adding sections to = the defcustom that do not apply (=3Dhave no bindings) in some buffer is = not a problem.  

Your = proposal has the disadvantage that the user must switch to a
buffer under some major mode to see the = entries for that mode in the
quick-help window.  It could be an annoyance; e.g., = consider a user
who = wants to see this while in a *Help* buffer.  And I don't = think
being in the buffer = under the major mode is the only way of getting
mode-specific bindings; for example, = where-is-internal can accept a
KEYMAP = argument, which will be used to find key bindings.

The current disadvantage = is related, but much worse than this: you currently cannot configure = quick help to show any bindings other than global and = help-mode bindings.  It might be nice to see e.g. org-bindings from = anywhere, but to me it=E2=80=99s an advantage to show =E2=80=9Cquic= k help for this mode=E2=80=9D.

Or = maybe we should have a separate command for cheat sheets = specific
to a major mode. =  The window we pop up cannot be too large, so if the
user only wants a quick help for the = current mode, she might consider
global = bindings an annoying waste of screen estate. =  

I=E2=80=99d probably = disable most of the global bindings, since I already know those. =  But some are useful (e.g. I often forget the project = bindings).  

Moreover, the
current = quick help shows "popular commands", which are likely to be
already known to some users, whereas when = the user works in a major
mode = that is new to the user, one is likely to be in the need of = the
cheat sheet for that one = mode.  (Yes, we do already have "C-h b", but
the output of that could be overwhelming: = for example in an Org buffer
I get = almost 1400 lines in the *Help* buffer showing the = Org-specific
bindings.)

Agree, this is a real = problem for discoverability.  Also command names are not always = informative enough to find what you are actually looking for (org is = terrible for this).

IOW, if we want to consider mode-specific = quick help, we should
perhaps = discuss more about the goals before we consider code tricks to
implement it.

I do like = this idea.  Perhaps mode authors could add a =E2=80=9Cstarter = pack=E2=80=9D of this information themselves, if they are suitably = admonished to keep this information brief, high level, and with clear = few-word command descriptions.  Perhaps adding a =E2=80=98help-quick = property to the mode command symbol?  

One = guiding principle I suggest: users in the end should be able to decide = what quick help they need; what=E2=80=99s memorable for some may be = frequently forgotten for others. 

= --Apple-Mail=_E7F07FC7-5300-4430-9253-F145EF9BB797--