master cc58626f643: * lisp/help-fns.el (describe-mode-outline): New user option (bug#64684).

[Juri Linkov]

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

    * lisp/help-fns.el (describe-mode-outline): New user option (bug#64684).
    
    (describe-mode, describe-mode--minor-modes): Use 'describe-mode-outline'.
    
    * lisp/help-mode.el (help-setup-xref): After disabling outline-minor-mode
    also kill all outline-related local variables.  So that they won't affect
    the output of other help commands in the same help buffer.
---
 etc/NEWS          |  4 +++
 lisp/help-fns.el  | 97 ++++++++++++++++++++++++++++++++++++++-----------------
 lisp/help-mode.el | 12 ++++++-
 3 files changed, 83 insertions(+), 30 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 7b248c3fe78..13b41feccbc 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -130,6 +130,10 @@ the signature) the automatically inferred function type as 
well.
 This user option controls outline visibility in the output buffer of
 'describe-bindings' when 'describe-bindings-outline' is non-nil.
 
+---
+*** 'C-h m' ('describe-mode') uses outlining by default.
+Set 'describe-mode-outline' to nil to get back the old behavior.
+
 ** Outline Mode
 
 +++
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 1ba848c107d..15d87f9925c 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -2133,6 +2133,12 @@ keymap value."
     (when used-gentemp
       (makunbound keymap))))
 
+(defcustom describe-mode-outline t
+  "Non-nil enables outlines in the output buffer of `describe-mode'."
+  :type 'boolean
+  :group 'help
+  :version "30.1")
+
 ;;;###autoload
 (defun describe-mode (&optional buffer)
   "Display documentation of current major mode and minor modes.
@@ -2145,7 +2151,10 @@ variable \(listed in `minor-mode-alist') must also be a 
function
 whose documentation describes the minor mode.
 
 If called from Lisp with a non-nil BUFFER argument, display
-documentation for the major and minor modes of that buffer."
+documentation for the major and minor modes of that buffer.
+
+When `describe-mode-outline' is non-nil, Outline minor mode
+is enabled in the Help buffer."
   (interactive "@")
   (unless buffer
     (setq buffer (current-buffer)))
@@ -2159,13 +2168,20 @@ documentation for the major and minor modes of that 
buffer."
       (with-current-buffer (help-buffer)
         ;; Add the local minor modes at the start.
         (when local-minors
-          (insert (format "Minor mode%s enabled in this buffer:"
-                          (if (length> local-minors 1)
-                              "s" "")))
+          (unless describe-mode-outline
+            (insert (format "Minor mode%s enabled in this buffer:"
+                            (if (length> local-minors 1)
+                                "s" ""))))
           (describe-mode--minor-modes local-minors))
 
         ;; Document the major mode.
         (let ((major (buffer-local-value 'major-mode buffer)))
+          (when describe-mode-outline
+            (goto-char (point-min))
+            (put-text-property
+             (point) (progn (insert (format "Major mode %S" major)) (point))
+             'outline-level 1)
+            (insert "\n\n"))
           (insert "The major mode is "
                   (buttonize
                    (propertize (format-mode-line
@@ -2189,36 +2205,56 @@ documentation for the major and minor modes of that 
buffer."
 
           ;; Insert the global minor modes after the major mode.
           (when global-minor-modes
-            (insert (format "Global minor mode%s enabled:"
-                            (if (length> global-minor-modes 1)
-                                "s" "")))
-            (describe-mode--minor-modes global-minor-modes)
-            (when (re-search-forward "^\f")
-              (beginning-of-line)
-              (ensure-empty-lines 1)))
+            (unless describe-mode-outline
+              (insert (format "Global minor mode%s enabled:"
+                              (if (length> global-minor-modes 1)
+                                  "s" ""))))
+            (describe-mode--minor-modes global-minor-modes t)
+            (unless describe-mode-outline
+              (when (re-search-forward "^\f")
+                (beginning-of-line)
+                (ensure-empty-lines 1))))
+
+          (when describe-mode-outline
+            (setq-local outline-search-function #'outline-search-level)
+            (setq-local outline-level (lambda () 1))
+            (setq-local outline-minor-mode-cycle t
+                        outline-minor-mode-highlight t
+                        outline-minor-mode-use-buttons 'insert)
+            (outline-minor-mode 1))
+
           ;; For the sake of IELM and maybe others
           nil)))))
 
-(defun describe-mode--minor-modes (modes)
+(defun describe-mode--minor-modes (modes &optional global)
   (dolist (mode (seq-sort #'string< modes))
     (let ((pretty-minor-mode
            (capitalize
             (replace-regexp-in-string
              "\\(\\(-minor\\)?-mode\\)?\\'" ""
              (symbol-name mode)))))
-      (insert
-       " "
-       (buttonize
-        pretty-minor-mode
-        (lambda (mode)
-          (goto-char (point-min))
-          (text-property-search-forward
-           'help-minor-mode mode t)
-          (beginning-of-line))
-        mode))
+      (if (not describe-mode-outline)
+          (insert
+           " "
+           (buttonize
+            pretty-minor-mode
+            (lambda (mode)
+              (goto-char (point-min))
+              (text-property-search-forward
+               'help-minor-mode mode t)
+              (beginning-of-line))
+            mode))
+        (goto-char (point-max))
+        (put-text-property
+         (point) (progn (insert (if global "Global" "Local")
+                                (format " minor mode %S" mode))
+                        (point))
+         'outline-level 1)
+        (insert "\n\n"))
       (save-excursion
-       (goto-char (point-max))
-       (insert "\n\n\f\n")
+       (unless describe-mode-outline
+          (goto-char (point-max))
+         (insert "\n\n\f\n"))
        ;; Document the minor modes fully.
         (insert (buttonize
                  (propertize pretty-minor-mode 'help-minor-mode mode)
@@ -2232,11 +2268,14 @@ documentation for the major and minor modes of that 
buffer."
                            (format "indicator%s"
                                    indicator)))))
        (insert (or (help-split-fundoc (documentation mode) nil 'doc)
-                   "No docstring")))))
-  (forward-line -1)
-  (fill-paragraph nil)
-  (forward-paragraph 1)
-  (ensure-empty-lines 1))
+                   "No docstring"))
+        (when describe-mode-outline
+          (insert "\n\n")))))
+  (unless describe-mode-outline
+    (forward-line -1)
+    (fill-paragraph nil)
+    (forward-paragraph 1)
+    (ensure-empty-lines 1)))
 
 (defun help-fns--list-local-commands ()
   (let ((functions nil))
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 9c405efeee5..f9ec8a5cc2b 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -501,7 +501,17 @@ restore it properly when going back."
     ;; Disable `outline-minor-mode' in a reused Help buffer
     ;; created by `describe-bindings' that enables this mode.
     (when (bound-and-true-p outline-minor-mode)
-      (outline-minor-mode -1))
+      (outline-minor-mode -1)
+      (mapc #'kill-local-variable
+            '(outline-search-function
+              outline-regexp
+              outline-heading-end-regexp
+              outline-level
+              outline-minor-mode-cycle
+              outline-minor-mode-highlight
+              outline-minor-mode-use-buttons
+              outline-default-state
+              outline-default-rules)))
     (when help-xref-stack-item
       (push (cons (point) help-xref-stack-item) help-xref-stack)
       (setq help-xref-forward-stack nil))