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#68929: [PATCH] Copy which-key from GNU ELPA into core Date: Thu, 15 Feb 2024 10:29:03 +0200 Message-ID: <86r0hew2pc.fsf@gnu.org> References: <871q9rvqbi.fsf@jeremybryant.net> <86wmrj148c.fsf@gnu.org> <87ttmkrlc5.fsf@jeremybryant.net> <86fry3xzae.fsf@gnu.org> <87zfwar3qd.fsf@jeremybryant.net> <87wmraptwj.fsf@jeremybryant.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="21591"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 68929@debbugs.gnu.org, justin@burkett.cc, monnier@iro.umontreal.ca To: Jeremy Bryant Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Feb 15 09:29:56 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 1raX7z-0005P5-Ut for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 15 Feb 2024 09:29:56 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1raX7p-0001SA-Dp; Thu, 15 Feb 2024 03:29:45 -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 1raX7o-0001S0-5T for bug-gnu-emacs@gnu.org; Thu, 15 Feb 2024 03:29:44 -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 1raX7n-00059J-TU for bug-gnu-emacs@gnu.org; Thu, 15 Feb 2024 03:29:43 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1raX85-0000Pf-VJ for bug-gnu-emacs@gnu.org; Thu, 15 Feb 2024 03:30: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: Thu, 15 Feb 2024 08:30:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 68929 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 68929-submit@debbugs.gnu.org id=B68929.17079857751534 (code B ref 68929); Thu, 15 Feb 2024 08:30:01 +0000 Original-Received: (at 68929) by debbugs.gnu.org; 15 Feb 2024 08:29:35 +0000 Original-Received: from localhost ([127.0.0.1]:53939 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1raX7e-0000Og-Ib for submit@debbugs.gnu.org; Thu, 15 Feb 2024 03:29:35 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:39038) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1raX7b-0000OT-KA for 68929@debbugs.gnu.org; Thu, 15 Feb 2024 03:29:32 -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 1raX7C-00050v-Qx; Thu, 15 Feb 2024 03:29:06 -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=MkUFEq8I9T1srNZJMmNz5vmTdCXbY6GhXXnH2o+Qz+8=; b=aGP0aV6pLWVF M2ARpR5i38S2q5946benKGa7qRDv93HE7xZiPtxxB5u5bsU6imJlu5t3AihE9h0DWdRWvhgwyI9AJ ds58u//Ql/IwOXtMt/Fed18qLRgJodbluIdSW8t9Y1cqA195wYcM2eoF85kDSZzclcL9iN4vNZe7O amvnUkrMlTLriX5oXuUxnwK6YqY5NiaG0nb6Ttz9ItAcBDwMZaUH9Eli1EtXBiC1tBZeyst9fGgyO 9CEv8cEWZDgTHQWRm+AfuViBuw4W5u4jRUanj0ly86xPnswj3maaP++0JXaL/EgNOd/P1LwPQWbku +j3AMpiiL4z2FyBKZOLxIA==; In-Reply-To: <87wmraptwj.fsf@jeremybryant.net> (message from Jeremy Bryant on Sun, 11 Feb 2024 21:32:44 +0000) 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:280048 Archived-At: > From: Jeremy Bryant > Cc: Eli Zaretskii , 68929@debbugs.gnu.org, justin@burkett.cc, > monnier@iro.umontreal.ca, bug-gnu-emacs@gnu.org > Date: Sun, 11 Feb 2024 21:32:44 +0000 > > > Eli Zaretskii writes: > > > >> Will the section be very long? How long? > >> > >> If it's not very long, I think the right place is in "Key Help", > >> perhaps as a separate subsection below it. Also, I think which-key > >> should be briefly mentioned in "Display Custom", where echo-keystrokes > >> is described. > >> > >> If the section about which-key you envision is supposed to be long and > >> detailed, perhaps it would be better to have a separate manual with > >> all that stuff, whereas the Emacs user manual should have only a short > >> description of the main features, and a cross-reference to the > >> separate manual. > > > > I would propose to make a new section short enough to belong in the main > > Emacs manual, as which-key's "keymay discovery" perspective should be > > easier to find. > > > > I can volunteer to write a draft and confer with Justin, the actual > > author, for completeness. > > Attached are a proposed patch for the Emacs manual, intentionally very > short. > Feedback welcome on any aspects. LGTM, thanks. Some minor comments below. > * doc/emacs/display.texi (Display Custom): brief mention > * doc/emacs/help.texi (Key Help): reference node above The descriptions of the changes in these entries should be complete sentences: begin with a capital letter and end with a period. > --- a/doc/emacs/display.texi > +++ b/doc/emacs/display.texi > @@ -2215,7 +2215,8 @@ Display Custom > default), the multi-character key sequence echo shown according to > @code{echo-keystrokes} will include a short help text about keys which > will invoke @code{describe-prefix-bindings} (@pxref{Misc Help}) to show > -the list of commands for the prefix you already typed. > +the list of commands for the prefix you already typed. For a related > +help facility (@pxref{which-key}). The parentheses here don't look right. It is better to say For a related help facility, see @ref{which-key}. > +@node which-key It is better to use @anchor which-key Then you don't need the @subsection at all. > + @command{M-x which-key} is a global minor mode which helps in @command is for shell commands. Here you show something the user types, so the right markup is @kbd.