branch: externals/perl-doc
commit 8641934da5d611885a54c98c5d11e430d26a4109
Author: Harald Jörg <h...@posteo.de>
Commit: Harald Jörg <h...@posteo.de>
Feature: New user option perl-doc-window
Controls whether new Perl documentation is displayed
by splitting the current window (default), using the whole
window, using a new frame each time or use a dedicated
frame for perl-doc-mode buffers. Requested by
https://github.com/HaraldJoerg/emacs-perl-doc/issues/3.
---
ChangeLog | 30 ++++++++++++++++++++++++++++++
perl-doc.el | 42 +++++++++++++++++++++++++++++++++++++-----
2 files changed, 67 insertions(+), 5 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index c62b079877..4db88b1fa4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,33 @@
+2025-06-04 Harald Jörg <h...@posteo.de>
+
+ Trial version:
+
+ * perl-doc.el: New user option 'perl-doc-window'
+ to control where perl-doc will display Perl documentation.
+ Requested in https://github.com/HaraldJoerg/emacs-perl-doc/issues/3.
+
+2023-08-05 Harald Jörg <h...@posteo.de>
+
+ Version 0.81:
+
+ * perl-doc.el (perl-doc--index-available-p): New function to
+ indicate whether we can run imenu.
+ * perl-doc.el (perl-doc--render-pod): Delete run of
+ `perl-doc--process-region'
+ (perl-doc): Make completion work in Emacs 27/28 (Fixes #2)
+ Recognize atan2 as a function (Fixes #1)
+ (perl-doc--speedbar-view-source): New function to view POD sources
+ from the speedbar menu
+ (perl-doc-speedbar-menu-items): Add menu items to view POD and its
+ source to the speedbar context menu
+ (perl-doc--insert-file-button): Don't show a "+" for modules if
+ imenu isn't available
+ * (perl-doc-speedbar-view-pod): Fix an error
+ discovered by relint
+
+ * test/perl-doc-tests.el (perl-doc-test-process-links): Test one
+ more edge case from open.pm
+
2022-09-29 Harald Jörg <h...@posteo.de>
* perl-doc.el (perl-doc-with-L-grammar): Allow the vertical bar in
diff --git a/perl-doc.el b/perl-doc.el
index 0e45b1b553..359cbe7dbb 100644
--- a/perl-doc.el
+++ b/perl-doc.el
@@ -112,6 +112,23 @@ be used by the Perl interpreter."
:group 'perl-doc
:type '(repeat directory))
+(defcustom perl-doc-window 'default
+ "Where `perl-doc' displays Perl documentation.
+same-window -- use the current window
+frame -- use a new frame
+same-frame -- reuse a frame already showing Perl documentation
+default -- use the default selection of `pop-to-buffer'.
+Any other value behaves like 'default'.
+With the default setting, `perl-doc' can be customized to any desired
+behavior by using the user options `display-buffer-alist' and
+`display-buffer-base-action'."
+ :group 'perl-doc
+ :type '(radio
+ (const default)
+ (const same-window)
+ (const same-frame)
+ (const frame)))
+
(defvar perl-doc--debug nil
"If non-nil, unrecognized POD links are reported to the message buffer.
This is only relevant for developers, not for users.")
@@ -541,8 +558,23 @@ function or a variable."
(setq-local perl-doc-window-width
(window-body-width (selected-window) t))))
;; Eventually, show the buffer and store current variables
- (or noselect
- (pop-to-buffer perldoc-buffer))))
+ (or noselect
+ (cond
+ ((equal perl-doc-window 'same-window)
+ (pop-to-buffer-same-window perldoc-buffer))
+ ((equal perl-doc-window 'frame)
+ (pop-to-buffer perldoc-buffer
+ '((display-buffer-reuse-window
+ display-buffer-pop-up-frame)
+ (reusable-frames . visible))))
+ ((equal perl-doc-window 'same-frame)
+ (pop-to-buffer perldoc-buffer
+ '((display-buffer-reuse-window
+ display-buffer-reuse-mode-window
+ display-buffer-pop-up-frame)
+ (mode . perl-doc-mode)
+ (reusable-frames . 0))))
+ (t (pop-to-buffer perldoc-buffer))))))
;;;###autoload
(defun perl-doc (word &optional section)
@@ -596,7 +628,7 @@ This retrieves the corresponding section from the perlfunc
page.
No completion is done (yet). Sorry."
(interactive "MFunction name: ")
(perl-doc--common topic 'perl-function))
-
+
;;;###autoload
(defun perl-doc-variable (topic)
"Get Perl documentation for a builtin function WORD.
@@ -604,7 +636,7 @@ This retrieves the corresponding section from the perlfunc
page.
No completion is done (yet). Sorry."
(interactive "MVariable name: ")
(perl-doc--common topic 'perl-variable))
-
+
;;;###autoload
(defun perl-doc-file (file)
"Run `perl-doc' on FILE.
@@ -1189,7 +1221,7 @@ already there, nil otherwise."
(pcase topic
((pred perl-doc--language-documentation-p)
"0:<.> Perl Language")
- ((pred perl-doc--module-documentation-p)
+ ((pred perl-doc--module-documentation-p)
"0:<.> Modules")
((pred perl-doc--old-delta-p)
"0:<.> Old perldeltas")))
