bug#67249: 30.0.50; `same-frame` equivalent for `display-buffer-alist`

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

>> +@vindex pop-up-frames{, a buffer display action alist entry}
>> +@item pop-up-frames
>> +This value controls whether @code{display-buffer} may display buffers
> I don't think that "value" is correct here.

I changed "This value" to "The value", since that's the term used for
the other alist entries in this section.

>> +by making new frames.  It has the same meaning as the
>
> Also you probably might want to recommend using an alist entry here:
>
> ‘pop-up-frames’
>      Instead of customizing this variable to ‘t’, customize
>      ‘display-buffer-base-action’, for example, as follows:
>
>           (setopt
>            display-buffer-base-action
>            '((display-buffer-reuse-window display-buffer-pop-up-frame)
>              (reusable-frames . 0)))

Indeed, thanks,


        Stefan


diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 22c1b307252..48893e22511 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3268,6 +3268,15 @@ Buffer Display Action Alists
 if one is created.  @code{display-buffer-pop-up-frame} is its one and
 only addressee.
 
+@vindex pop-up-frames{, 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 @@ Choosing Window Options
 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 @@ Choosing Window Options
 
 @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