master e0ebce5: * lisp/help.el (describe-bindings-outline): New defcustom (bug#45147).

[Juri Linkov]

branch: master
commit e0ebce5ce2ba76779a5a74dcffba60b83cf9df2f
Author: Juri Linkov <juri@linkov.net>
Commit: Juri Linkov <juri@linkov.net>

    * lisp/help.el (describe-bindings-outline): New defcustom (bug#45147).
    
    (describe-bindings): Use describe-bindings-outline.
    (describe-bindings-internal): Remove function obsolete since 24.4.
---
 etc/NEWS     |  5 +++++
 lisp/help.el | 43 ++++++++++++++++++++++++++-----------------
 2 files changed, 31 insertions(+), 17 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 0bdb79e..693d0c0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1053,6 +1053,11 @@ commands and is globally bound to `C-h x'.
 *** New command 'describe-keymap' describes keybindings in a keymap.
 
 ---
+*** New user option 'describe-bindings-outline'.
+It enables outlines in the output buffer of `describe-bindings' that
+can provide a better overview in a long list of available bindings.
+
+---
 *** New keybinding 'C-h R' prompts for a manual to display and displays it.
 
 +++
diff --git a/lisp/help.el b/lisp/help.el
index babaf4a..1bb1b30 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -561,6 +561,12 @@ To record all your input, use `open-dribble-file'."
               'font-lock-face 'help-key-binding
               'face 'help-key-binding))
 
+(defcustom describe-bindings-outline nil
+  "Non-nil enables outlines in the output buffer of `describe-bindings'."
+  :type 'boolean
+  :group 'help
+  :version "28.1")
+
 (defun describe-bindings (&optional prefix buffer)
   "Display a buffer showing a list of all defined keys, and their definitions.
 The keys are displayed in order of precedence.
@@ -578,23 +584,26 @@ or a buffer name."
     ;; Be aware that `describe-buffer-bindings' puts its output into
     ;; the current buffer.
     (with-current-buffer (help-buffer)
-      (describe-buffer-bindings buffer prefix))))
-
-(defun describe-bindings-internal (&optional menus prefix)
-  "Show a list of all defined keys, and their definitions.
-We put that list in a buffer, and display the buffer.
-
-The optional argument MENUS, if non-nil, says to mention menu bindings.
-\(Ordinarily these are omitted from the output.)
-The optional argument PREFIX, if non-nil, should be a key sequence;
-then we display only bindings that start with that prefix."
-  (declare (obsolete describe-buffer-bindings "24.4"))
-  (let ((buf (current-buffer)))
-    (with-help-window (help-buffer)
-      ;; Be aware that `describe-buffer-bindings' puts its output into
-      ;; the current buffer.
-      (with-current-buffer (help-buffer)
-       (describe-buffer-bindings buf prefix menus)))))
+      (describe-buffer-bindings buffer prefix)
+
+      (when describe-bindings-outline
+        (setq-local outline-regexp ".*:$")
+        (setq-local outline-heading-end-regexp ":\n")
+        (setq-local outline-level (lambda () 1))
+        (setq-local outline-minor-mode-cycle t
+                    outline-minor-mode-highlight t)
+        (outline-minor-mode 1)
+        (save-excursion
+          (let ((inhibit-read-only t))
+            (goto-char (point-min))
+            (insert (substitute-command-keys
+                     (concat "\\<outline-mode-cycle-map>Type "
+                             "\\[outline-cycle] or \\[outline-cycle-buffer] "
+                             "on headings to cycle their visibility.\n\n")))
+            ;; Hide the longest body
+            (when (and (re-search-forward "Key translations" nil t)
+                       (fboundp 'outline-cycle))
+              (outline-cycle))))))))
 
 (defun where-is (definition &optional insert)
   "Print message listing key sequences that invoke the command DEFINITION.