bug#35487: Make visiting function from help-mode more customizable

bug#35487: Make visiting function from help-mode more customizable

[Tak Kunihiro]

* Message

I often want to visit function from help-mode in `this window' in
stead of `other window'.  To do so, I found that to revise
help-function in help-function-def works.

I propose to (1) move help-function described as lambda function out
of button definition and (2) make function to visit function from
help-mode customizable.

After the revision, I can visit function from help-mode in `this
windows' as shown below.

#+begin_src emacs-lisp
(define-key help-mode-map (kbd "f")
  (lambda ()
    (interactive)
    (let ((help-switch-buffer-function 'switch-to-buffer))
      (push-button))))
#+end_src

I attach commit log and patch.


* Commit log

Author: Tak Kunihiro <tkk@misasa.okayama-u.ac.jp>

    Make visiting function from help-mode more customizable
    
    * lisp/help-mode.el
    (define-button-type): Move definition of help-function out.
    (help-switch-buffer-function): Function to display buffer in help-mode.
    (help-find-function): Define help-function using a new variable
    `help-switch-buffer-function'.

* Patch

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 6cc3f0d4f7..4e01e73181 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -192,32 +192,39 @@ 'help-customize-face
 
 (define-button-type 'help-function-def
   :supertype 'help-xref
-  'help-function (lambda (fun &optional file type)
-                   (or file
-                       (setq file (find-lisp-object-file-name fun type)))
-                   (if (not file)
-                       (message "Unable to find defining file")
-                     (require 'find-func)
-                     (when (eq file 'C-source)
-                       (setq file
-                             (help-C-file-name (indirect-function fun) 'fun)))
-                     ;; Don't use find-function-noselect because it follows
-                     ;; aliases (which fails for built-in functions).
-                     (let* ((location
-                             (find-function-search-for-symbol fun type file))
-                            (position (cdr location)))
-                       (pop-to-buffer (car location))
-                       (run-hooks 'find-function-after-hook)
-                       (if position
-                           (progn
-                             ;; Widen the buffer if necessary to go to this position.
-                             (when (or (< position (point-min))
-                                       (> position (point-max)))
-                               (widen))
-                             (goto-char position))
-                         (message "Unable to find location in file")))))
+  'help-function 'help-find-function
   'help-echo (purecopy "mouse-2, RET: find function's definition"))
 
+(defvar help-switch-buffer-function 'pop-to-buffer
+  "Function to display buffer in help-mode.")
+
+(defun help-find-function (fun &optional file type)
+  "Find object shown in help-mode."
+  (or file
+      (setq file (find-lisp-object-file-name fun type)))
+  (if (not file)
+      (message "Unable to find defining file")
+    (require 'find-func)
+    (when (eq file 'C-source)
+      (setq file
+            (help-C-file-name (indirect-function fun) 'fun)))
+    ;; Don't use find-function-noselect because it follows
+    ;; aliases (which fails for built-in functions).
+    (let* ((location
+            (find-function-search-for-symbol fun type file))
+           (position (cdr location)))
+      ;; (pop-to-buffer (car location))
+      (funcall help-switch-buffer-function (car location))
+      (run-hooks 'find-function-after-hook)
+      (if position
+          (progn
+            ;; Widen the buffer if necessary to go to this position.
+            (when (or (< position (point-min))
+                      (> position (point-max)))
+              (widen))
+            (goto-char position))
+        (message "Unable to find location in file")))))
+
 (define-button-type 'help-function-cmacro ; FIXME: Obsolete since 24.4.
   :supertype 'help-xref
   'help-function (lambda (fun file)

bug#35487: Make visiting function from help-mode more customizable

[Juri Linkov]

> I often want to visit function from help-mode in `this window' in
> stead of `other window'.  To do so, I found that to revise
> help-function in help-function-def works.
>
> I propose to (1) move help-function described as lambda function out
> of button definition and (2) make function to visit function from
> help-mode customizable.
>
> After the revision, I can visit function from help-mode in `this
> windows' as shown below.

I have exactly the same problem.  Fortunately, we have a powerful
customization mechanism of display-buffer-alist to allow clicking
a link from the *Help* buffer to open source code in the same window:

#+begin_src emacs-lisp
(custom-set-variables
 '(display-buffer-alist
   '((display-buffer-condition-from-help display-buffer-same-window))))

(defun display-buffer-condition-from-help (_buffer-name _action)
  (string-match-p "\\`\\*\\(Help\\)\\*\\(\\|<[0-9]+>\\)\\'" (buffer-name (current-buffer))))
#+end_src

bug#35487: Make visiting function from help-mode more customizable

[Tak Kunihiro]

Juri Linkov <juri@linkov.net> writes:

>> I often want to visit function from help-mode in `this window' in
>> stead of `other window'.  To do so, I found that to revise
>> help-function in help-function-def works.
>>
>> I propose to (1) move help-function described as lambda function out
>> of button definition and (2) make function to visit function from
>> help-mode customizable.
>>
>> After the revision, I can visit function from help-mode in `this
>> windows' as shown below.
>
> I have exactly the same problem.  Fortunately, we have a powerful
> customization mechanism of display-buffer-alist to allow clicking
> a link from the *Help* buffer to open source code in the same window:
>
> #+begin_src emacs-lisp
> (custom-set-variables
>  '(display-buffer-alist
>    '((display-buffer-condition-from-help display-buffer-same-window))))
>
> (defun display-buffer-condition-from-help (_buffer-name _action)
>   (string-match-p "\\`\\*\\(Help\\)\\*\\(\\|<[0-9]+>\\)\\'" (buffer-name (current-buffer))))
> #+end_src

Thank you for the solution!  Now from *Help* buffer I can open source
code in the same window by mouse click.

As a side effect, `C-h f' opens *Help* buffer in the same window.  I
still want to open *Help* in other window (original behavior).  Do you
have idea to do so?

bug#35487: Make visiting function from help-mode more customizable

[martin rudalics]

 > As a side effect, `C-h f' opens *Help* buffer in the same window.  I
 > still want to open *Help* in other window (original behavior).  Do you
 > have idea to do so?

You could try with

(defun display-buffer-condition-from-help (_buffer-name _action)
   (string-match-p "\\`\\*\\(Help\\)\\*\\(\\|<[0-9]+>\\)\\'"
		  (buffer-name (window-buffer))))

martin

bug#35487: Make visiting function from help-mode more customizable

[Juri Linkov]

>> As a side effect, `C-h f' opens *Help* buffer in the same window.  I
>> still want to open *Help* in other window (original behavior).  Do you
>> have idea to do so?
>
> You could try with
>
> (defun display-buffer-condition-from-help (_buffer-name _action)
>   (string-match-p "\\`\\*\\(Help\\)\\*\\(\\|<[0-9]+>\\)\\'"
> 		  (buffer-name (window-buffer))))

I confirm this is more correct.

BTW, I observed one strange effect: after the *Help* buffer is displayed
on one window, the next time it's always displayed in the same window
where it was displayed previously:

0. emacs -Q
1. C-h f car RET
2. C-x o
3. C-h i
4. C-h f car RET
   is displayed in the same window, whereas
5. C-h f cdr RET
   is displayed in another window

bug#35487: Make visiting function from help-mode more customizable

[Tak Kunihiro]

I configured `f' in help-mode in following way based on comments
and now it works good.

Thank you Juri and Martin for the responses!

#+begin_src emacs-lisp
(define-key help-mode-map (kbd "f") 'push-button-display-buffer)

(defun push-button-display-buffer (&optional action)
  (interactive)
  (or action (setq action 'display-buffer-same-window))
  (let ((display-buffer-alist `((display-buffer-condition-from-help ,action))))
    (push-button)))

(defun display-buffer-condition-from-help (_buffer-name _action)
  (with-current-buffer (window-buffer)
    (eq major-mode 'help-mode)))
#+end_src

bug#35487: Make visiting function from help-mode more customizable

[Stefan Monnier]

> (define-key help-mode-map (kbd "f") 'push-button-display-buffer)
>
> (defun push-button-display-buffer (&optional action)
>   (interactive)
>   (or action (setq action 'display-buffer-same-window))
>   (let ((display-buffer-alist
>          `((display-buffer-condition-from-help ,action))))
>     (push-button)))
>
> (defun display-buffer-condition-from-help (_buffer-name _action)
>   (with-current-buffer (window-buffer)
>     (eq major-mode 'help-mode)))

I think the display-buffer-condition-from-help (which likely should
have a final "-p" in its name) is only needed you you want to add it to
the global value of display-buffer-alist.

In the above code, since you're using a specific binding in
help-mode-map, you presumably already know that (eq major-mode 'help-mode)
so you can just rebind display-buffer-overriding-action.

BTW, this is a case where you could use the same approach as used in the
`other-frame-window` package but using a prefix command which says "use
the same window for the next command".


        Stefan

bug#35487: Make visiting function from help-mode more customizable

[Tak Kunihiro]

>> (define-key help-mode-map (kbd "f") 'push-button-display-buffer)
>>
>> (defun push-button-display-buffer (&optional action)
>>   (interactive)
>>   (or action (setq action 'display-buffer-same-window))
>>   (let ((display-buffer-alist
>>          `((display-buffer-condition-from-help ,action))))
>>     (push-button)))
>>
>> (defun display-buffer-condition-from-help (_buffer-name _action)
>>   (with-current-buffer (window-buffer)
>>     (eq major-mode 'help-mode)))
>
> I think the display-buffer-condition-from-help (which likely should
> have a final "-p" in its name) is only needed you you want to add it to
> the global value of display-buffer-alist.
>
> In the above code, since you're using a specific binding in
> help-mode-map, you presumably already know that (eq major-mode 'help-mode)
> so you can just rebind display-buffer-overriding-action.

Thank you Stefan for the help!

I think that following will open the code in the same window.  I
wanted this for a long time...

#+begin_src emacs-lisp
(define-key help-mode-map (kbd "f") 'push-button-display-same-window)
(define-key help-mode-map (kbd "o") 'push-button)

(defun push-button-display-same-window ()
  (interactive)
  (let ((display-buffer-overriding-action '(display-buffer-same-window)))
    (push-button)))
#+end_src

bug#35487: Make visiting function from help-mode more customizable

[Juri Linkov]

> I configured `f' in help-mode in following way based on comments
> and now it works good.
>
> Thank you Juri and Martin for the responses!

You are welcome.  Since it works good, I'm closing this request.