Allow reusing the *Help* window with `i'/`s/ commands

* doc/emacs/help.texi (Help): Document it.

* lisp/help-mode.el (help-function-def--button-function): Use it.
* lisp/help-mode.el (help-goto-info): Use it.

* lisp/help.el (help-window-select): Mention it.
(help-window-keep-selected): New user option (bug#9054).

* lisp/info-look.el (info-lookup-symbol):
(info-lookup): Allow keeping the same window.

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 3c8f90da1021f6b188c647e472def87a917be98d..11ee9dc2b2fbbdc3e4308557fc121049d58bfc35 100644 (file)
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -34,6 +34,14 @@ is unconditionally selected by help commands, and if its value is
 @code{other}, the help window is selected only if there are more than
 two windows on the selected frame.
 
+@vindex help-window-keep-selected
+  Conversely, many commands in the @samp{*Help*} buffer will pop up a
+new window to display the results.  For instance, clicking on the link
+to show the source code, or using the @key{i} command to display the
+manual entry, will (by default) pop up a new window.  If
+@code{help-window-keep-selected} is changed to non-@code{nil}, the
+window displaying the @samp{*Help*} buffer will be reused instead.
+
 @cindex searching documentation efficiently
 @cindex looking for a subject in documentation
   If you are looking for a certain feature, but don't know what it is

diff --git a/etc/NEWS b/etc/NEWS
index 882748d8c7f301ac8bc60217b4a2b5c6b893ab1a..5e7baab109601ab1d0cd340a886690588d20df59 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -443,6 +443,11 @@ command also works for non-Emoji characters.)
 
 ** Help
 
++++
+*** New user option 'help-window-keep-selected'.
+If non-nil, commands to show the info manual and the source will reuse
+the same window the *Help* buffer is shown in.
+
 ---
 *** Commands like 'C-h f' have changed how they describe menu bindings.
 For instance, previously a command might be described as having the

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index cb87035281adbb1e98a9e7e32a4ef87776798894..c725c0f1a15df60bc09eb1ae4da6b73da93862ae 100644 (file)
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -268,7 +268,9 @@ The format is (FUNCTION ARGS...).")
     (let* ((location
             (find-function-search-for-symbol fun type file))
            (position (cdr location)))
-      (pop-to-buffer (car location))
+      (if help-window-keep-selected
+          (pop-to-buffer-same-window (car location))
+        (pop-to-buffer (car location)))
       (run-hooks 'find-function-after-hook)
       (if position
           (progn
@@ -819,7 +821,8 @@ The help buffers are divided into \"pages\" by the ^L character."
   (unless help-mode--current-data
     (error "No symbol to look up in the current buffer"))
   (info-lookup-symbol (plist-get help-mode--current-data :symbol)
-                      'emacs-lisp-mode))
+                      'emacs-lisp-mode
+                      help-window-keep-selected))
 
 (defun help-goto-lispref-info ()
   "View the Emacs Lisp manual *info* node of the current help item."

diff --git a/lisp/help.el b/lisp/help.el
index 2d08ceb86c75608ca58efde9a4e0d5eb6f3cc4b2..fe999de63824a9b2fc1d3622a5351d6dc1d4916f 100644 (file)
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1802,13 +1802,25 @@ the help window appears on another frame, it may get selected and
 its frame get input focus even if this option is nil.
 
 This option has effect if and only if the help window was created
-by `with-help-window'."
+by `with-help-window'.
+
+Also see `help-window-keep-selected'."
   :type '(choice (const :tag "never (nil)" nil)
                 (const :tag "other" other)
                 (const :tag "always (t)" t))
   :group 'help
   :version "23.1")
 
+(defcustom help-window-keep-selected nil
+  "If non-nil, navigation commands in the *Help* buffer will reuse the window.
+If nil, many commands in the *Help* buffer, like \\<help-mode-map>\\[help-view-source] and \\[help-goto-info], will
+pop to a different window to display the results.
+
+Also see `help-window-select'."
+  :type 'boolean
+  :group 'help
+  :version "29.1")
+
 (define-obsolete-variable-alias 'help-enable-auto-load
   'help-enable-autoload "27.1")
 

diff --git a/lisp/info-look.el b/lisp/info-look.el
index aa07c3f5e70a589c891b982e90ffc12763dc6455..6c8ef091a087f75573a774f2d0e58cc82a343d02 100644 (file)
--- a/lisp/info-look.el
+++ b/lisp/info-look.el
@@ -280,7 +280,7 @@ system."
 
 ;;;###autoload (put 'info-lookup-symbol 'info-file "emacs")
 ;;;###autoload
-(defun info-lookup-symbol (symbol &optional mode)
+(defun info-lookup-symbol (symbol &optional mode same-window)
   "Look up and display documentation of SYMBOL in the relevant Info manual.
 SYMBOL should be an identifier: a function or method, a macro, a variable,
 a data type, a class, etc.
@@ -293,10 +293,13 @@ MODE is the major mode whose Info manuals to search for the documentation
 of SYMBOL.  It defaults to the current buffer's `major-mode'; if that
 mode doesn't have any Info manuals known to Emacs, the command will
 prompt for MODE to use, with completion.  With prefix arg, the command
-always prompts for MODE."
+always prompts for MODE.
+
+Is SAME-WINDOW, try to reuse the current window instead of
+popping up a new one."
   (interactive
    (info-lookup-interactive-arguments 'symbol current-prefix-arg))
-  (info-lookup 'symbol symbol mode))
+  (info-lookup 'symbol symbol mode same-window))
 
 ;;;###autoload (put 'info-lookup-file 'info-file "emacs")
 ;;;###autoload
@@ -388,7 +391,7 @@ If optional argument QUERY is non-nil, query for the help mode."
         spec
       mode)))
 
-(defun info-lookup (topic item mode)
+(defun info-lookup (topic item mode &optional same-window)
   "Display the documentation of TOPIC whose name is ITEM, using MODE's manuals.
 TOPIC should be any known symbol of a help topic type, such as `file'
 or `symbol'.  See the documentation of HELP-TOPIC in the doc
@@ -397,7 +400,10 @@ ITEM is the item whose documentation to search: file name if
 TOPIC is `file', a symbol if TOPIC is `symbol', etc.
 MODE is the `major-mode' whose Info manuals to search for documentation
 of ITEM; if it's nil, the function uses `info-lookup-file-name-alist'
-and the current buffer's file name to guess the mode.."
+and the current buffer's file name to guess the mode.
+
+If SAME-WINDOW, reuse the current window.  If nil, pop to a
+different window."
   (or mode (setq mode (info-lookup-select-mode)))
   (setq mode (info-lookup--item-to-mode item mode))
   (if-let ((info (info-lookup->mode-value topic mode)))
@@ -423,19 +429,21 @@ and the current buffer's file name to guess the mode.."
       (if (not info-lookup-other-window-flag)
          (info)
        (save-window-excursion (info))
-       (let* ((info-window (get-buffer-window "*info*" t))
-              (info-frame (and info-window (window-frame info-window))))
-         (if (and info-frame
-                  (not (eq info-frame (selected-frame)))
-                  (display-multi-frame-p)
-                  (memq info-frame (frames-on-display-list)))
-             ;; *info* is visible in another frame on same display.
-             ;; Raise that frame and select the window.
-             (progn
-               (select-window info-window)
-               (raise-frame info-frame))
-           ;; In any other case, switch to *info* in another window.
-           (switch-to-buffer-other-window "*info*")))))
+        (if same-window
+            (pop-to-buffer-same-window "*info*")
+         (let* ((info-window (get-buffer-window "*info*" t))
+                (info-frame (and info-window (window-frame info-window))))
+           (if (and info-frame
+                    (not (eq info-frame (selected-frame)))
+                    (display-multi-frame-p)
+                    (memq info-frame (frames-on-display-list)))
+               ;; *info* is visible in another frame on same display.
+               ;; Raise that frame and select the window.
+               (progn
+                 (select-window info-window)
+                 (raise-frame info-frame))
+             ;; In any other case, switch to *info* another window.
+             (switch-to-buffer-other-window "*info*"))))))
     (while (and (not found) modes)
       (setq doc-spec (info-lookup->doc-spec topic (car modes)))
       (while (and (not found) doc-spec)