From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 4 Jan 2024 08:17:30 +0000 (+0200)
Subject: Provide decent documentation for 'help-quick'
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a2a6619b282;p=emacs.git

Provide decent documentation for 'help-quick'

* lisp/help.el (help-quick, help-quick-toggle): Doc fix.

* doc/emacs/help.texi (Help Summary, Misc Help): Document
'help-quick-toggle'.
---

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 68299c057d7..1330717b758 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -115,6 +115,9 @@ Display a list of commands whose names match @var{topics}
 Display all active key bindings; minor mode bindings first, then those
 of the major mode, then global bindings (@code{describe-bindings}).
 @xref{Misc Help}.
+@item C-h C-q
+Toggle display of a window showing popular commands and their key
+bindings.  @xref{Misc Help}.
 @item C-h c @var{key}
 Show the name of the command that the key sequence @var{key} is bound
 to (@code{describe-key-briefly}).  Here @kbd{c} stands for
@@ -700,6 +703,18 @@ displays the contents of the syntax table, with explanations of each
 character's syntax (@pxref{Syntax Tables,, Syntax Tables, elisp, The
 Emacs Lisp Reference Manual}).
 
+@kindex C-h C-q
+@findex help-quick-toggle
+@findex help-quick
+@cindex cheat sheet of popular Emacs commands
+  @kbd{C-h C-q} (@code{help-quick-toggle}) toggles on and off the
+display of a buffer showing the most popular Emacs commands and their
+respective key bindings (a.k.a.@: ``cheat sheet'').  The contents of
+that buffer are created by the command @code{help-quick}.  Each key
+binding shown in this buffer is a button: click on it with
+@kbd{mouse-1} or @kbd{mouse-2} to show the documentation of the
+command bound to that key sequence.
+
 @findex describe-prefix-bindings
   You can get a list of subcommands for a particular prefix key by
 typing @kbd{C-h}, @kbd{?}, or @key{F1}
diff --git a/lisp/help.el b/lisp/help.el
index fe80dd3a72d..accd01e56f5 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -171,7 +171,10 @@ buffer.")
 
 ;; Inspired by a mg fork (https://github.com/troglobit/mg)
 (defun help-quick ()
-  "Display a quick-help buffer."
+  "Display a quick-help buffer showing popular commands and their bindings.
+The window showing quick-help can be toggled using \\[help-quick-toggle].
+You can click on a key binding shown in the quick-help buffer to display
+the documentation of the command bound to that key sequence."
   (interactive)
   (with-current-buffer (get-buffer-create "*Quick Help*")
     (let ((inhibit-read-only t) (padding 2) blocks)
@@ -244,10 +247,14 @@ buffer.")
       ;; ... and shrink it immediately.
       (fit-window-to-buffer))
     (message
-     (substitute-command-keys "Toggle the quick help buffer using \\[help-quick-toggle]."))))
+     (substitute-command-keys "Toggle display of quick-help buffer using \\[help-quick-toggle]."))))
 
 (defun help-quick-toggle ()
-  "Toggle the quick-help window."
+  "Toggle display of a window showing popular commands and their bindings.
+This toggles on and off the display of the quick-help buffer, which shows
+popular commands and their bindings as produced by `help-quick'.
+You can click on a key binding shown in the quick-help buffer to display
+the documentation of the command bound to that key sequence."
   (interactive)
   (if (and-let* ((window (get-buffer-window "*Quick Help*")))
         (quit-window t window))