master 3eb421bda38 1/2: (display-buffer): New `pop-up-frames` action alist entry

[Stefan Monnier]

branch: master
commit 3eb421bda38981dbb08c3342833b1c7156156469
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    (display-buffer): New `pop-up-frames` action alist entry
    
    Allow overriding the `pop-up-frames` variable from `display-buffer-alist`
    so as to provide a worthy replacement for the old `same-frame`
    parameter of `special-display-*` (bug#67249).
    
    * lisp/window.el (special-display-popup-frame): Declare obsolete;
    that was apparently forgotten back when `special-display-*` variables
    were declared obsolete.
    Use the new `pop-up-frames` action alist entry instead of the variable.
    (display-buffer): Document new alist entry.
    (window--pop-up-frames): New function.
    (display-buffer--maybe-pop-up-frame, display-buffer-in-previous-window)
    (display-buffer-reuse-window, display-buffer-reuse-mode-window): Use it.
    
    * doc/lispref/windows.texi (Choosing Window Options): Mention that
    `pop-up-frames` is also an action alist entry.
    (Buffer Display Action Alists): Add `pop-up-frames` entry.
---
 doc/lispref/windows.texi | 19 ++++++++++++++-----
 etc/NEWS                 |  4 ++++
 lisp/window.el           | 33 +++++++++++++++++----------------
 3 files changed, 35 insertions(+), 21 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 22c1b307252..b11f6d4f3ab 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3268,6 +3268,15 @@ The value specifies an alist of frame parameters to give 
a new frame,
 if one is created.  @code{display-buffer-pop-up-frame} is its one and
 only addressee.
 
+@vindex pop-up-frames@r{, a buffer display action alist entry}
+@item pop-up-frames
+The value controls whether @code{display-buffer} may display buffers
+by making new frames.  It has the same meaning as the
+@code{pop-up-frames} variable and takes precedence over it when present.
+Its main intended purpose is to override a non-nil value of the
+variable for particular buffers which the user prefers to keep
+in the selected frame.
+
 @vindex parent-frame@r{, a buffer display action alist entry}
 @item parent-frame
 The value specifies the parent frame to be used when the buffer is
@@ -3441,6 +3450,9 @@ A non-@code{nil} value also means that when 
@code{display-buffer} is
 looking for a window already displaying @var{buffer-or-name}, it can
 search any visible or iconified frame, not just the selected frame.
 
+An entry by the same name in @code{display-buffer}'s @var{alist}
+takes precedence over the variable.
+
 This variable is provided mainly for backward compatibility.  It is
 obeyed by @code{display-buffer} via a special mechanism in
 @code{display-buffer-fallback-action}, which calls the action function
@@ -3512,15 +3524,12 @@ functions it should try instead as, for example:
 
 @item pop-up-frames
 @vindex pop-up-frames@r{, replacement for}
-Instead of customizing this variable to @code{t}, customize
+Instead of customizing this variable to @code{t}, you can customize
 @code{display-buffer-base-action}, for example, as follows:
 
 @example
 @group
-(setopt
- display-buffer-base-action
- '((display-buffer-reuse-window display-buffer-pop-up-frame)
-   (reusable-frames . 0)))
+(setopt display-buffer-base-action '(nil (pop-up-frames . t)))
 @end group
 @end example
 
diff --git a/etc/NEWS b/etc/NEWS
index 60391cfb22e..060d1a2fe5c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1289,6 +1289,10 @@ values.
 
 * Lisp Changes in Emacs 30.1
 
+** New 'pop-up-frames' action alist entry for 'display-buffer'.
+This has the same effect as the variable of the same name and takes
+precedence over the variable when present.
+
 ** New function 'merge-ordered-lists'.
 Mostly used internally to do a kind of topological sort of
 inheritance hierarchies.
diff --git a/lisp/window.el b/lisp/window.el
index fbdcd611068..40070a4d929 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6862,6 +6862,7 @@ BUFFER in a window of the selected frame.
 If ARGS is a list whose car is a symbol, use (car ARGS) as a
 function to do the work.  Pass it BUFFER as first argument, and
 pass the elements of (cdr ARGS) as the remaining arguments."
+  (declare (obsolete display-buffer-pop-up-frame "30.1"))
   (if (and args (symbolp (car args)))
       (apply (car args) buffer (cdr args))
     (let ((window (get-buffer-window buffer 0)))
@@ -6881,9 +6882,8 @@ pass the elements of (cdr ARGS) as the remaining 
arguments."
        ;; Stay on the same frame if requested.
        (when (or (cdr (assq 'same-frame args)) (cdr (assq 'same-window args)))
         (let* ((pop-up-windows t)
-               pop-up-frames
                special-display-buffer-names special-display-regexps)
-          (display-buffer buffer)))
+          (display-buffer buffer '((pop-up-frames . nil)))))
        ;; If no window yet, make one in a new frame.
        (let* ((frame
               (with-current-buffer buffer
@@ -6996,6 +6996,13 @@ Emacs Lisp manual for an example."
          (const :tag "Always" t))
   :group 'windows)
 
+(defun window--pop-up-frames (alist)
+ (let* ((override (assq 'pop-up-frames alist))
+        (pop-up (if override (cdr override) pop-up-frames)))
+   (if (eq pop-up 'graphic-only)
+       (display-graphic-p)
+     pop-up)))
+
 (defcustom display-buffer-reuse-frames nil
   "Non-nil means `display-buffer' should reuse frames.
 If the buffer in question is already displayed in a frame, raise
@@ -7742,6 +7749,8 @@ Action alist entries are:
     Possible values are nil (the selected frame), t (any live
     frame), visible (any visible frame), 0 (any visible or
     iconified frame) or an existing live frame.
+ `pop-up-frames' -- Same effect as the eponymous variable.
+    Takes precedence over the variable.
  `pop-up-frame-parameters' -- The value specifies an alist of
     frame parameters to give a new frame, if one is created.
  `window-height' -- The value specifies the desired height of the
@@ -7830,12 +7839,12 @@ specified by the ACTION argument."
                           user-action special-action action extra-action
                           display-buffer-base-action
                           display-buffer-fallback-action))
-           (functions (apply 'append
+           (functions (apply #'append
                              (mapcar (lambda (x)
                                        (setq x (car x))
                                        (if (functionp x) (list x) x))
                                      actions)))
-           (alist (apply 'append (mapcar 'cdr actions)))
+           (alist (apply #'append (mapcar #'cdr actions)))
            window)
       (unless (buffer-live-p buffer)
         (error "Invalid buffer"))
@@ -7978,9 +7987,7 @@ called only by `display-buffer' or a function directly or
 indirectly called by the latter."
   (let* ((alist-entry (assq 'reusable-frames alist))
         (frames (cond (alist-entry (cdr alist-entry))
-                      ((if (eq pop-up-frames 'graphic-only)
-                           (display-graphic-p)
-                         pop-up-frames)
+                      ((window--pop-up-frames alist)
                        0)
                       (display-buffer-reuse-frames 0)
                       (t (last-nonminibuffer-frame))))
@@ -8034,9 +8041,7 @@ indirectly called by the latter."
   (let* ((alist-entry (assq 'reusable-frames alist))
          (alist-mode-entry (assq 'mode alist))
         (frames (cond (alist-entry (cdr alist-entry))
-                      ((if (eq pop-up-frames 'graphic-only)
-                           (display-graphic-p)
-                         pop-up-frames)
+                      ((window--pop-up-frames alist)
                        0)
                       (display-buffer-reuse-frames 0)
                       (t (last-nonminibuffer-frame))))
@@ -8182,9 +8187,7 @@ text-only terminal), try with 
`display-buffer-pop-up-frame'.
 ALIST is an association list of action symbols and values.  See
 Info node `(elisp) Buffer Display Action Alists' for details of
 such alists."
-  (and (if (eq pop-up-frames 'graphic-only)
-          (display-graphic-p)
-        pop-up-frames)
+  (and (window--pop-up-frames alist)
        (display-buffer-pop-up-frame buffer alist)))
 
 (defun display-buffer--maybe-pop-up-window (buffer alist)
@@ -8548,9 +8551,7 @@ indirectly called by the latter."
          (cdr (assq 'inhibit-same-window alist)))
         (frames (cond
                  (alist-entry (cdr alist-entry))
-                 ((if (eq pop-up-frames 'graphic-only)
-                      (display-graphic-p)
-                    pop-up-frames)
+                 ((window--pop-up-frames alist)
                   0)
                  (display-buffer-reuse-frames 0)
                  (t (last-nonminibuffer-frame))))