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

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]

Package: Emacs
Version: 30.0.50


As `special-display-buffer-names` and friends are nearing the 10 years
of being declared obsolete, I noticed that I can't find any replacement
for the `same-frame` parameter in `display-buffer-alist`.

The patch below is just a "proof-of-concept" I tried to see if I could
get a similar behavior to the old `same-frame` with the new code.
I'm not sufficiently familiar with the set of `display-buffer-*`
functions to judge if it's a good approach overall.

I also noticed that `special-display-popup-frame` is only called from
`special-display-function` (which is declared obsolete since 24.3), so
maybe it should also be declared obsolete?


        Stefan


diff --git a/lisp/window.el b/lisp/window.el
index b6fe5996123..72cd9f5d85c 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6795,6 +6795,7 @@ special-display-popup-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 "??" "30.1"))
   (if (and args (symbolp (car args)))
       (apply (car args) buffer (cdr args))
     (let ((window (get-buffer-window buffer 0)))
@@ -8014,6 +8015,7 @@ display-buffer-pop-up-frame
 	 (fun pop-up-frame-function)
 	 frame window)
     (when (and fun
+	       (not (alist-get 'same-frame alist))
 	       ;; Make BUFFER current so `make-frame' will use it as the
 	       ;; new frame's buffer (Bug#15133).
 	       (with-current-buffer buffer

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

[martin rudalics]

 > As `special-display-buffer-names` and friends are nearing the 10 years
 > of being declared obsolete, I noticed that I can't find any replacement
 > for the `same-frame` parameter in `display-buffer-alist`.

IIRC 'same-frames' had no clear semantics.  As for the selected window,
use 'display-buffer-same-window'.  As for a new window on the selected
frame, use 'display-buffer-pop-up-window'.  As for any other window on
the selected frame, use either ‘display-buffer-use-some-window’ or
‘display-buffer-use-least-recent-window’ with a nil 'lru-frames' action
alist entry.

martin

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]

>> As `special-display-buffer-names` and friends are nearing the 10 years
>> of being declared obsolete, I noticed that I can't find any replacement
>> for the `same-frame` parameter in `display-buffer-alist`.
> IIRC 'same-frame' had no clear semantics.

In `special-display-*`?

Are you referring to whether it's OK to (re)use a window on another
frame if it shows the buffer already?

Other than this, I don't see what was not clear about its semantics.
And I can't see any reason why we couldn't clarify the semantics.

> As for a new window on the selected frame, use
> 'display-buffer-pop-up-window'.  As for any other window on the
> selected frame, use either ‘display-buffer-use-some-window’ or
> ‘display-buffer-use-least-recent-window’ with a nil 'lru-frames'
> action alist entry.

`same-frame` was not quite like any of those, it said "keep using the
default set of options in the same order of preferences, except that if
at all possible, skip those options which end up displaying the buffer
in another frame".


        Stefan

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

[martin rudalics]

 >>> As `special-display-buffer-names` and friends are nearing the 10 years
 >>> of being declared obsolete, I noticed that I can't find any replacement
 >>> for the `same-frame` parameter in `display-buffer-alist`.
 >> IIRC 'same-frame' had no clear semantics.
 >
 > In `special-display-*`?

All 'same-frame' did was to inhibit calling 'special-display-function'
via

	 (let* ((pop-up-frames nil) (pop-up-windows t)
		special-display-regexps special-display-buffer-names
		(window (display-buffer buffer)))

That never precluded using a window on another frame, contradicting the
very meaning of "same frame" and was always documented as

   "Otherwise, if they include (same-frame . t), the buffer is displayed
    in a new window in the currently selected frame."

which failed to say what happens if no new window could be created on
the selected frame.  So historically 'same-frame' was always tied to
'special-display-*' and had no effect when that was uncustomized.

 > Are you referring to whether it's OK to (re)use a window on another
 > frame if it shows the buffer already?

(Re)use any window on another frame.

 > Other than this, I don't see what was not clear about its semantics.
 > And I can't see any reason why we couldn't clarify the semantics.

The action alist is flat - whichever entry comes first is used even if
it is not pertinent to the action chosen.  If the action chosen is say
'display-buffer-in-previous-window', the frames to investigate are
currently specified by a 'reusable-frames' entry.  If no such entry is
present, we could check for a 'same-frame' entry.  But what should
'display-buffer' do when both entries are present with 'same-frame'
coming first?  And how would 'display-buffer-use-some-window' and
'display-buffer-use-least-recent-window' handle the similar case with a
'lru-frames' and a 'same-frame' entry both present?

Now if you want 'same-frame' to prevail in either of these cases, it
will not suffice to rewrite the corresponding pieces of code where
another frame would be chosen.  Any application that really needs a
window on another frame will then have to provide a (same-frame . nil)
entry.

If you want 'same-frame' to not prevail in these cases, you probably
mean that it should only inhibit popping up a new frame via
'display-buffer-pop-up-frame'.  Again applications that want to pop up a
new frame would then have to provide a (same-frame . nil) entry.

 >> As for a new window on the selected frame, use
 >> 'display-buffer-pop-up-window'.  As for any other window on the
 >> selected frame, use either ‘display-buffer-use-some-window’ or
 >> ‘display-buffer-use-least-recent-window’ with a nil 'lru-frames'
 >> action alist entry.
 >
 > `same-frame` was not quite like any of those, it said "keep using the
 > default set of options in the same order of preferences, except that if
 > at all possible, skip those options which end up displaying the buffer
 > in another frame".

The proof of this pudding is in clarifying the "if at all possible" and
explaining any new special behavior in the manual.

martin

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]

>> Are you referring to whether it's OK to (re)use a window on another
>> frame if it shows the buffer already?
> (Re)use any window on another frame.

Right, so it should probably have been called something like "no new
frame".

> The action alist is flat - whichever entry comes first is used even if
> it is not pertinent to the action chosen.  If the action chosen is say
> 'display-buffer-in-previous-window', the frames to investigate are
> currently specified by a 'reusable-frames' entry.  If no such entry is
> present, we could check for a 'same-frame' entry.  But what should
> 'display-buffer' do when both entries are present with 'same-frame'
> coming first?

I don't see a big problem here: we could choose `same-frame` to imply
that `reusable-frames` is nil, or we could choose to ignore
`same-frame`.  Since the code that adds `(same-frame . t)` could just as well
also add `(reusable-frames)`, the first choice is less flexible
than the second (tho it allows overriding a higher-precedence
`reusable-frames` setting), so I'd go with the first choice, which also
has the advantage of not requiring any code modification :-)

> And how would 'display-buffer-use-some-window' and
> 'display-buffer-use-least-recent-window' handle the similar case with a
> 'lru-frames' and a 'same-frame' entry both present?

Same reasoning here.

> If you want 'same-frame' to not prevail in these cases, you probably

I don't necessarily want a particular behavior.  I want to provide
a similar functionality, within the constraints of what we can define
and implement sanely.

So no, I don't necessarily want it to prevail over those other entries.

> mean that it should only inhibit popping up a new frame via
> 'display-buffer-pop-up-frame'.

That was my conclusion when I looked at the code (concretized in
my PoC patch).

Another approach is to provide a new action.
This could be a `display-buffer-same-frame` action which tries its best
to use the selected frame.
I suspect in many cases the actual intention of `same-frame` was to keep
the buffer nearby, so I suspect we could also replace `same-frame` with
a `display-buffer-nearby` action.

The advantage of an action is that we don't need to decide how existing
actions interact with it.

> Again applications that want to pop up a new frame would then have to
> provide a (same-frame . nil) entry.

That would seem fair game, IMO.

> The proof of this pudding is in clarifying the "if at all possible" and
> explaining any new special behavior in the manual.

I suspect the main exception would be minibuffer-only frames, but we
could get fancier if we feel like it (like when the selected frame can't
accommodate the `window-min-width` and `window-min-height`, or when we
set `inhibit-same-window` (or the selected window is dedicated) and the
frame's sole window can't be split).


        Stefan

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

[martin rudalics]

 > Right, so it should probably have been called something like "no new
 > frame".

We should prominently mention that in the manual then.  BTW creating a
new frame is always one last resort of 'display-buffer'.

 > I don't see a big problem here: we could choose `same-frame` to imply
 > that `reusable-frames` is nil, or we could choose to ignore
 > `same-frame`.  Since the code that adds `(same-frame . t)` could just as well
 > also add `(reusable-frames)`, the first choice is less flexible
 > than the second (tho it allows overriding a higher-precedence
 > `reusable-frames` setting), so I'd go with the first choice, which also
 > has the advantage of not requiring any code modification :-)

So a (same-frame . t) entry would simply auto-translate to a pair of
(reusable-frames . nil) (lru-frames . nil) entries?

 > I don't necessarily want a particular behavior.  I want to provide
 > a similar functionality, within the constraints of what we can define
 > and implement sanely.
 >
 > So no, I don't necessarily want it to prevail over those other entries.

With the conclusion above it would prevail.

 >> mean that it should only inhibit popping up a new frame via
 >> 'display-buffer-pop-up-frame'.
 >
 > That was my conclusion when I looked at the code (concretized in
 > my PoC patch).

OK.

 > Another approach is to provide a new action.
 > This could be a `display-buffer-same-frame` action which tries its best
 > to use the selected frame.
 > I suspect in many cases the actual intention of `same-frame` was to keep
 > the buffer nearby, so I suspect we could also replace `same-frame` with
 > a `display-buffer-nearby` action.
 >
 > The advantage of an action is that we don't need to decide how existing
 > actions interact with it.

We could add a 'display-buffer--same-frame-action' variable.

 >> Again applications that want to pop up a new frame would then have to
 >> provide a (same-frame . nil) entry.
 >
 > That would seem fair game, IMO.

It means a change in existing code.  Till now, applications were on the
safe side in this regard since they could always blame others for using
an obsolete feature.

 > I suspect the main exception would be minibuffer-only frames, but we
 > could get fancier if we feel like it (like when the selected frame can't
 > accommodate the `window-min-width` and `window-min-height`, or when we
 > set `inhibit-same-window` (or the selected window is dedicated) and the
 > frame's sole window can't be split).

Do you anywhere see 'display-buffer' choose a minibuffer-only frame?
I'm aware of the fact that the

(window--frame-usable-p (last-nonminibuffer-frame))

is broken when a minibuffer-only frame is the only frame left but so far
nobody complained ...

martin

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]

> BTW creating a new frame is always one last resort of 'display-buffer'.

That depends on the rest of the config, AFAIK.
I tried the patch I sent on some of my config and it did have an effect
(e.g. when I open `M-x calendar`, depending the `same-frame` I either
get one frame with *Calendar* and another with `diary` or I get
a single frame with both.  Both windows are dedicated).

>> I don't see a big problem here: we could choose `same-frame` to imply
>> that `reusable-frames` is nil, or we could choose to ignore
>> `same-frame`.  Since the code that adds `(same-frame . t)` could just as well
>> also add `(reusable-frames)`, the first choice is less flexible
>> than the second (tho it allows overriding a higher-precedence
>> `reusable-frames` setting), so I'd go with the first choice, which also
>> has the advantage of not requiring any code modification :-)
>
> So a (same-frame . t) entry would simply auto-translate to a pair of
> (reusable-frames . nil) (lru-frames . nil) entries?

[ Hmm... I'm curious how you interpreted what I wrote to reach
  that conclusion.  ]
No, I meant the opposite: the users who want to override
`reusable-frames` and `lru-frames` need to add all three

    (same-frame . t)
    (reusable-frames . nil)
    (lru-frames . nil)

>> Another approach is to provide a new action.
>> This could be a `display-buffer-same-frame` action which tries its best
>> to use the selected frame.
>> I suspect in many cases the actual intention of `same-frame` was to keep
>> the buffer nearby, so I suspect we could also replace `same-frame` with
>> a `display-buffer-nearby` action.
>>
>> The advantage of an action is that we don't need to decide how existing
>> actions interact with it.
>
> We could add a 'display-buffer--same-frame-action' variable.

I don't really know what that suggestion means.
The `--` suggests it'd be some internal detail of `window.el` whereas
I thought we're discussing the externally visible API and semantics.

>>> Again applications that want to pop up a new frame would then have to
>>> provide a (same-frame . nil) entry.
>> That would seem fair game, IMO.
> It means a change in existing code.  Till now, applications were on the
> safe side in this regard since they could always blame others for using
> an obsolete feature.

I don't see why you think it'd require any change in existing code: the
ones who set `same-frame` get what they ask for.

>> I suspect the main exception would be minibuffer-only frames, but we
>> could get fancier if we feel like it (like when the selected frame can't
>> accommodate the `window-min-width` and `window-min-height`, or when we
>> set `inhibit-same-window` (or the selected window is dedicated) and the
>> frame's sole window can't be split).
>
> Do you anywhere see 'display-buffer' choose a minibuffer-only frame?

I'm not talking about `display-buffer` choosing a minibuffer-only frame.
I'm saying that when the selected-frame is a minibuffer-only frame, it's OK
to ignore the `same-frame` request.


        Stefan

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

[martin rudalics]

 > That depends on the rest of the config, AFAIK.
 > I tried the patch I sent on some of my config and it did have an effect
 > (e.g. when I open `M-x calendar`, depending the `same-frame` I either
 > get one frame with *Calendar* and another with `diary` or I get
 > a single frame with both.  Both windows are dedicated).

Neither of these deal with 'reusable-frames' or 'lru-frames'.

 >> So a (same-frame . t) entry would simply auto-translate to a pair of
 >> (reusable-frames . nil) (lru-frames . nil) entries?
 >
 > [ Hmm... I'm curious how you interpreted what I wrote to reach
 >    that conclusion.  ]
 > No, I meant the opposite: the users who want to override
 > `reusable-frames` and `lru-frames` need to add all three
 >
 >      (same-frame . t)
 >      (reusable-frames . nil)
 >      (lru-frames . nil)

Suppose an application calls ‘display-buffer’ with a non-nil
'same-frame' alist entry.  If we want an existing action function to
obey that entry and we do not want to rewrite that function, we could
have 'display-buffer' add a (reusable-frames . nil) (lru-frames . nil)
pair to the alist.

 >> We could add a 'display-buffer--same-frame-action' variable.
 >
 > I don't really know what that suggestion means.
 > The `--` suggests it'd be some internal detail of `window.el` whereas
 > I thought we're discussing the externally visible API and semantics.

It could do what I meant above - translate 'same-frame' internally.

 > I don't see why you think it'd require any change in existing code: the
 > ones who set `same-frame` get what they ask for.

You already would change the existing 'display-buffer-pop-up-frame'.  If
you think that change is sufficient, I will obviously stop thinking.

 > I'm not talking about `display-buffer` choosing a minibuffer-only frame.
 > I'm saying that when the selected-frame is a minibuffer-only frame, it's OK
 > to ignore the `same-frame` request.

When the selected frame is a minibuffer-only frame, 'display-buffer'
usually tries to think of 'last-nonminibuffer-frame' as the selected
frame.  So probably 'same-frame' should do the same.  But all I can do
is to hint at inconsistencies in your proposal.

martin

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]

>>> So a (same-frame . t) entry would simply auto-translate to a pair of
>>> (reusable-frames . nil) (lru-frames . nil) entries?
>>
>> [ Hmm... I'm curious how you interpreted what I wrote to reach
>>    that conclusion.  ]
>> No, I meant the opposite: the users who want to override
>> `reusable-frames` and `lru-frames` need to add all three
>>
>>      (same-frame . t)
>>      (reusable-frames . nil)
>>      (lru-frames . nil)
>
> Suppose an application calls ‘display-buffer’ with a non-nil
> 'same-frame' alist entry.  If we want an existing action function to
> obey that entry and we do not want to rewrite that function, we could
> have 'display-buffer' add a (reusable-frames . nil) (lru-frames . nil)
> pair to the alist.

We could, but we could also define the semantics of `same-frame` to have
no effect on frame re-use (it would actually be closer to the current
semantics).  If so, it'd be best to find another name for it along the
lines of "no-new-frame".

>>> We could add a 'display-buffer--same-frame-action' variable.
>> I don't really know what that suggestion means.
>> The `--` suggests it'd be some internal detail of `window.el` whereas
>> I thought we're discussing the externally visible API and semantics.
> It could do what I meant above - translate 'same-frame' internally.

What is "it"?  `display-buffer--same-frame-action`?
Without knowing where you'd use such a variable, it's hard for me to
guess what you mean by that.

>> I don't see why you think it'd require any change in existing code: the
>> ones who set `same-frame` get what they ask for.
> You already would change the existing 'display-buffer-pop-up-frame'.
> If you think that change is sufficient, I will obviously stop thinking.

I suspect it might be sufficient, but it would deserve a better name so
users don't get the wrong impression that it will affect reuse on
other frames.

So you think the patch I sent is actually more-or-less acceptable
(modulo documentation and finding a better name)?

>> I'm not talking about `display-buffer` choosing a minibuffer-only frame.
>> I'm saying that when the selected-frame is a minibuffer-only frame, it's OK
>> to ignore the `same-frame` request.
> When the selected frame is a minibuffer-only frame, 'display-buffer'
> usually tries to think of 'last-nonminibuffer-frame' as the selected
> frame.  So probably 'same-frame' should do the same.

Sounds like this is compatible to my suggestion that it's OK to ignore
`same-frame` when the selected frame is a minibuffer-only frame.

> But all I can do is to hint at inconsistencies in your proposal.

Not sure what's the inconsistency there.


        Stefan

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

[martin rudalics]

 > We could, but we could also define the semantics of `same-frame` to have
 > no effect on frame re-use (it would actually be closer to the current
 > semantics).  If so, it'd be best to find another name for it along the
 > lines of "no-new-frame".

Agreed.  'inhibit-pop-up-frame' or 'inhibit-new-frame' would be more in
accordance with 'inhibit-same-window' and 'inhibit-switch-frame'.

 >>>> We could add a 'display-buffer--same-frame-action' variable.
 >>> I don't really know what that suggestion means.
 >>> The `--` suggests it'd be some internal detail of `window.el` whereas
 >>> I thought we're discussing the externally visible API and semantics.
 >> It could do what I meant above - translate 'same-frame' internally.
 >
 > What is "it"?  `display-buffer--same-frame-action`?
 > Without knowing where you'd use such a variable, it's hard for me to
 > guess what you mean by that.

It would be similar to 'display-buffer--same-window-action' and
'display-buffer--other-frame-action' and could be used in the same way.
But I'm not familiar with these variables and the customization types
that use them (IIRC either you or Chong invented them).

 > I suspect it might be sufficient, but it would deserve a better name so
 > users don't get the wrong impression that it will affect reuse on
 > other frames.
 >
 > So you think the patch I sent is actually more-or-less acceptable
 > (modulo documentation and finding a better name)?

Yes.

 >> When the selected frame is a minibuffer-only frame, 'display-buffer'
 >> usually tries to think of 'last-nonminibuffer-frame' as the selected
 >> frame.  So probably 'same-frame' should do the same.
 >
 > Sounds like this is compatible to my suggestion that it's OK to ignore
 > `same-frame` when the selected frame is a minibuffer-only frame.
 >
 >> But all I can do is to hint at inconsistencies in your proposal.
 >
 > Not sure what's the inconsistency there.

If OT1H 'same-frame' is ignored when the selected frame is a
minibuffer-only frame (so a new frame gets popped up instead) and OTOH
the remaining action functions do use the last non-minibuffer frame in
such case, then the behavior of 'display-buffer' is inconsistent in my
regard.

martin

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]

>> We could, but we could also define the semantics of `same-frame` to have
>> no effect on frame re-use (it would actually be closer to the current
>> semantics).  If so, it'd be best to find another name for it along the
>> lines of "no-new-frame".
> Agreed.  'inhibit-pop-up-frame' or 'inhibit-new-frame' would be more in
> accordance with 'inhibit-same-window' and 'inhibit-switch-frame'.

I like `inhibit-new-frame`, thanks.

>>>>> We could add a 'display-buffer--same-frame-action' variable.
>>>> I don't really know what that suggestion means.
>>>> The `--` suggests it'd be some internal detail of `window.el` whereas
>>>> I thought we're discussing the externally visible API and semantics.
>>> It could do what I meant above - translate 'same-frame' internally.
>> What is "it"?  `display-buffer--same-frame-action`?
>> Without knowing where you'd use such a variable, it's hard for me to
>> guess what you mean by that.
> It would be similar to 'display-buffer--same-window-action' and
> 'display-buffer--other-frame-action' and could be used in the same way.

These are just implementation details of `switch-to-buffer-other-frame`,
`display-buffer-other-frame`, `pop-to-buffer-same-window`, ...

So, it would still require the introduction of something like
`display-buffer-same-frame` to make use of it.

> But I'm not familiar with these variables

I guess only Chong is familiar with them, then 🙁

> and the customization types that use them (IIRC either you or Chong
> invented them).

The customization type is not used for them (they are internal
variables, not user-facing nor Customizable).

>> So you think the patch I sent is actually more-or-less acceptable
>> (modulo documentation and finding a better name)?
> Yes.

OK, I'll try and get it into an acceptable shape, then.

> If OT1H 'same-frame' is ignored when the selected frame is a
> minibuffer-only frame (so a new frame gets popped up instead) and OTOH
> the remaining action functions do use the last non-minibuffer frame in
> such case, then the behavior of 'display-buffer' is inconsistent in my
> regard.

Ah, yes, I see.
IIUC, the "inhibit-new-frame" semantics seems less susceptible to this
problem then the "same-frame", no?


        Stefan

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

[martin rudalics]

 >> and the customization types that use them (IIRC either you or Chong
 >> invented them).
 >
 > The customization type is not used for them (they are internal
 > variables, not user-facing nor Customizable).

I meant their use in, for example,

(defcustom display-comint-buffer-action display-buffer--same-window-action

 >> If OT1H 'same-frame' is ignored when the selected frame is a
 >> minibuffer-only frame (so a new frame gets popped up instead) and OTOH
 >> the remaining action functions do use the last non-minibuffer frame in
 >> such case, then the behavior of 'display-buffer' is inconsistent in my
 >> regard.
 >
 > Ah, yes, I see.
 > IIUC, the "inhibit-new-frame" semantics seems less susceptible to this
 > problem then the "same-frame", no?

When I type M-x to invoke a custom function for displaying a buffer, I'd
probably want 'inhibit-new-frame' to do what it advertises regardless of
whether I'm in a stand-alone minibuffer frame or in a normal minibuffer
window.  But we could add a separate value for 'inhibit-new-frame' like
'may-use-last-nonminibuffer-frame' to regulate that.

martin

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]

[-- Attachment #1: Type: text/plain, Size: 1804 bytes --]

>>> If OT1H 'same-frame' is ignored when the selected frame is a
>>> minibuffer-only frame (so a new frame gets popped up instead) and OTOH
>>> the remaining action functions do use the last non-minibuffer frame in
>>> such case, then the behavior of 'display-buffer' is inconsistent in my
>>> regard.
>> Ah, yes, I see.
>> IIUC, the "inhibit-new-frame" semantics seems less susceptible to this
>> problem then the "same-frame", no?
> When I type M-x to invoke a custom function for displaying a buffer, I'd
> probably want 'inhibit-new-frame' to do what it advertises regardless of
> whether I'm in a stand-alone minibuffer frame or in a normal minibuffer
> window.

Indeed, but the difference between "same frame" and "inhibit new frame"
is that the meaning of "same frame" depends on the `selected-frame`
whereas "inhibit new frame" doesn't, so I think we're OK.

Here's a first candidate patch.

I introduced a new function `display-buffer--pop-up-frame` so as to
ignore `inhibit-new-frame` as a last resort.

I also modified `display-buffer--other-frame-action` to use
`display-buffer--pop-up-frame`, because it seems this is used only(?) in
response to an explicit user request where the user does expect a new
frame (like `C-x 5 b`) and so it seems to make sense to override even an
`inhibit-new-frame` coming from `display-buffer-alist`.


        Stefan


PS: Am I the only one who finds it confusing how some functions
named `display-buffer-<foo>` are meant to be used from the ACTIONs
(i.e. from within `display-buffer`) while others are implemented on top
of `display-buffer` (and thus should not be used within ACTIONS)?
Could we try and find a clear naming convention to distinguish the two,
or am I even more confused than I thought and several of those functions
can be used either way?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: inhibit-new-frame.patch --]
[-- Type: text/x-diff, Size: 4335 bytes --]

diff --git a/lisp/window.el b/lisp/window.el
index 0c5ccf167dc..34027c58cae 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6860,6 +6860,7 @@ special-display-popup-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)))
@@ -7627,7 +7628,7 @@ display-buffer-fallback-action
      display-buffer-in-previous-window
      display-buffer-use-some-window
      ;; If all else fails, pop up a new frame.
-     display-buffer-pop-up-frame))
+     display-buffer--pop-up-frame))
   "Default fallback action for `display-buffer'.
 This is the action used by `display-buffer' if no other actions
 have been specified, for example, by the user options
@@ -7657,7 +7658,7 @@ display-buffer--same-window-action
 
 (defvar display-buffer--other-frame-action
   '((display-buffer-reuse-window
-     display-buffer-pop-up-frame)
+     display-buffer--pop-up-frame)
     (reusable-frames . 0)
     (inhibit-same-window . t))
   "A `display-buffer' action for displaying in another frame.
@@ -7735,6 +7736,8 @@ display-buffer
     Note that a window manager may still raise a new frame and
     give it focus, effectively overriding the value specified
     here.
+ `inhibit-new-frame' -- A non-nil value forces the use of an
+    existing frame to display the buffer.
  `reusable-frames' -- The value specifies the set of frames to
     search for a window that already displays the buffer.
     Possible values are nil (the selected frame), t (any live
@@ -7828,12 +7831,12 @@ display-buffer
                           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"))
@@ -8090,10 +8093,16 @@ display-buffer--special-action
                          (funcall special-display-function
                                   buffer (if (listp pars) pars)))))))))
 
+(defun display-buffer--pop-up-frame (buffer alist)
+  "Like `display-buffer--pop-up-frame' but ignores `inhibit-new-frame'.
+Used only in exceptional cases."
+  (display-buffer-pop-up-frame buffer `((inhibit-new-frame . nil) ,@alist)))
+
 (defun display-buffer-pop-up-frame (buffer alist)
   "Display BUFFER in a new frame.
 This works by calling `pop-up-frame-function'.  If successful,
 return the window used; otherwise return nil.
+Do nothing if ALIST's `inhibit-new-frame' is non-nil.
 
 ALIST is an association list of action symbols and values.  See
 Info node `(elisp) Buffer Display Action Alists' for details of
@@ -8107,15 +8116,16 @@ display-buffer-pop-up-frame
 node `(elisp) Buffer Display Action Functions'.  It should be
 called only by `display-buffer' or a function directly or
 indirectly called by the latter."
-  (let* ((params (cdr (assq 'pop-up-frame-parameters alist)))
-	 (pop-up-frame-alist (append params pop-up-frame-alist))
-	 (fun pop-up-frame-function)
+  (let* ((fun pop-up-frame-function)
 	 frame window)
     (when (and fun
+	       (not (alist-get 'inhibit-new-frame alist))
 	       ;; Make BUFFER current so `make-frame' will use it as the
 	       ;; new frame's buffer (Bug#15133).
 	       (with-current-buffer buffer
-		 (setq frame (funcall fun)))
+		 (let* ((params (cdr (assq 'pop-up-frame-parameters alist)))
+		        (pop-up-frame-alist (append params pop-up-frame-alist)))
+		   (setq frame (funcall fun))))
 	       (setq window (frame-selected-window frame)))
       (prog1 (window--display-buffer buffer window 'frame alist)
 	(unless (cdr (assq 'inhibit-switch-frame alist))

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

[martin rudalics]

 > Here's a first candidate patch.
 >
 > I introduced a new function `display-buffer--pop-up-frame` so as to
 > ignore `inhibit-new-frame` as a last resort.

Good idea.

 > I also modified `display-buffer--other-frame-action` to use
 > `display-buffer--pop-up-frame`, because it seems this is used only(?) in
 > response to an explicit user request where the user does expect a new
 > frame (like `C-x 5 b`) and so it seems to make sense to override even an
 > `inhibit-new-frame` coming from `display-buffer-alist`.

 >  (defvar display-buffer--other-frame-action
 >    '((display-buffer-reuse-window
 > -     display-buffer-pop-up-frame)
 > +     display-buffer--pop-up-frame)
 >      (reusable-frames . 0)
 >      (inhibit-same-window . t))

This one is messy anyway but I never tried to tinker with it.  After
all, "0" means to probe any frame around _including_ the selected one.
It probably should call 'display-buffer-use-some-frame' and maybe also
'display-buffer-use-least-recent-window' with a suitable 'lru-frames'
entry.  Just that our FRAMES argument nomenclature does not allow to
exclude the selected frame from the list of frames to probe or return.

 > +(defun display-buffer--pop-up-frame (buffer alist)
 > +  "Like `display-buffer--pop-up-frame' but ignores `inhibit-new-frame'.

This seems to have an extra "-".

 > PS: Am I the only one who finds it confusing how some functions
 > named `display-buffer-<foo>` are meant to be used from the ACTIONs
 > (i.e. from within `display-buffer`) while others are implemented on top
 > of `display-buffer` (and thus should not be used within ACTIONS)?
 > Could we try and find a clear naming convention to distinguish the two,
 > or am I even more confused than I thought and several of those functions
 > can be used either way?

Do you mean 'display-buffer-override-next-command' and
'display-buffer-record-window'?  As for the latter, the reason was that
applications might want to call this in their code for recording the
window used so it's not meant to be strictly window.el internal.  If you
mean something else, please give one or two examples of such confusing
functions.

martin

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]

>> +(defun display-buffer--pop-up-frame (buffer alist)
>> +  "Like `display-buffer--pop-up-frame' but ignores `inhibit-new-frame'.
> This seems to have an extra "-".

Indeed, thanks.

>> PS: Am I the only one who finds it confusing how some functions
>> named `display-buffer-<foo>` are meant to be used from the ACTIONs
>> (i.e. from within `display-buffer`) while others are implemented on top
>> of `display-buffer` (and thus should not be used within ACTIONS)?
>> Could we try and find a clear naming convention to distinguish the two,
>> or am I even more confused than I thought and several of those functions
>> can be used either way?
>
> Do you mean 'display-buffer-override-next-command' and
> 'display-buffer-record-window'?

I mostly noticed `display-buffer-other-frame` whose name (to me)
suggests it can be used in an ACTION.  The two you cite could be
considered as colliding, but since their name doesn't suggest they're
going to "display a buffer", they didn't bother me.

Hmm... after looking a bit more maybe it's not that bad, since the
calling convention can be used to distinguish them
(e.g. `display-buffer-other-frame` doesn't take an ALIST after the
BUFFER).


        Stefan

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]

[-- Attachment #1: Type: text/plain, Size: 302 bytes --]

BTW, I just noticed another way to attack the problem, which is to add
a `pop-up-frames` argument which works just like the variable but takes
precedence over it, as in the PoC patch below (a real patch would
adjust other places where we use that variable, among other things).

WDYT?


        Stefan

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: same-frame.patch --]
[-- Type: text/x-diff, Size: 691 bytes --]

diff --git a/lisp/window.el b/lisp/window.el
index 0c5ccf167dc..2b8c6483fe5 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -8180,9 +8181,11 @@ display-buffer--maybe-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)
+  (let* ((override (assq 'pop-up-frames alist))
+         (pop-up (if override (cdr override) pop-up-frames)))
+  (and (if (eq pop-up 'graphic-only)
 	   (display-graphic-p)
-	 pop-up-frames)
+	 pop-up)
        (display-buffer-pop-up-frame buffer alist)))
 
 (defun display-buffer--maybe-pop-up-window (buffer alist)

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

[martin rudalics]

 > BTW, I just noticed another way to attack the problem, which is to add
 > a `pop-up-frames` argument which works just like the variable but takes
 > precedence over it, as in the PoC patch below (a real patch would
 > adjust other places where we use that variable, among other things).
 >
 > WDYT?

Then we should probably use 'pop-up-windows' instead of
'inhibit-same-window'.  'display-buffer' resembles a Cervantesque
struggle of consistency with history.

martin

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]

>> BTW, I just noticed another way to attack the problem, which is to add
>> a `pop-up-frames` argument which works just like the variable but takes
>> precedence over it, as in the PoC patch below (a real patch would
>> adjust other places where we use that variable, among other things).
>> WDYT?
> Then we should probably use 'pop-up-windows' instead of
> 'inhibit-same-window'.

Hmm... I don't think it would quite work, because `pop-up-windows`
only controls creation of new windows, whereas `inhibit-same-window`
has an effect in more cases.

> 'display-buffer' resembles a Cervantesque struggle of consistency
> with history.

Indeed.  But I'm not sure how that translates into a practical choice
between `pop-up-frames` and `inhibit-new-frame`.

I'm leaning towards `pop-up-frames` right now because it avoids
introducing a new notion.  Admittedly, the notion it reuses
(i.e. `pop-up-frames`) is not the cleanest around, but
`inhibit-new-frame` isn't super clean either.

Can someone help me choose between those two bad choices?


        Stefan

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]

[-- Attachment #1: Type: text/plain, Size: 344 bytes --]

> I'm leaning towards `pop-up-frames` right now because it avoids
> introducing a new notion.  Admittedly, the notion it reuses
> (i.e. `pop-up-frames`) is not the cleanest around, but
> `inhibit-new-frame` isn't super clean either.
>
> Can someone help me choose between those two bad choices?

FWIW, here's my current patch.


        Stefan

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: pop-up-frames.patch --]
[-- Type: text/x-diff, Size: 3940 bytes --]

diff --git a/lisp/window.el b/lisp/window.el
index fbdcd611068..58e77745280 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6862,6 +6862,7 @@ special-display-popup-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 @@ special-display-popup-frame
        ;; 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 @@ pop-up-frames
 	  (const :tag "Always" t))
   :group 'windows)
 
+(defun window--pop-up-frames (&optional alist)
+ (let* ((override (assq 'pop-up-frames alist))
+        (pop-up (if override (cdr overriding) 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
@@ -7830,12 +7837,12 @@ display-buffer
                           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 +7985,7 @@ display-buffer-reuse-window
 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 +8039,7 @@ display-buffer-reuse-mode-window
   (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 +8185,7 @@ display-buffer--maybe-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 +8549,7 @@ display-buffer-in-previous-window
 	  (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))))

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

[martin rudalics]

 > FWIW, here's my current patch.

Before pushing it, please try to fix the corresponding sections in the
Elisp manual.  It will be non-trivial to avoid confusions with the old
'pop-up-frames' option.

martin

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]

[-- Attachment #1: Type: text/plain, Size: 217 bytes --]

> Before pushing it, please try to fix the corresponding sections in the
> Elisp manual.  It will be non-trivial to avoid confusions with the old
> 'pop-up-frames' option.

How 'bout the patch below?


        Stefan

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: pop-up-frames.patch --]
[-- Type: text/x-diff, Size: 5824 bytes --]

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 22c1b307252..7649013fce4 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3433,9 +3433,13 @@ Choosing Window Options
 @end defopt
 
 @defopt pop-up-frames
-If the value of this variable is non-@code{nil}, that means
-@code{display-buffer} may display buffers by making new frames.  The
-default is @code{nil}.
+If the value of this parameter is non-@code{nil}, that means
+@code{display-buffer} may display buffers by making new frames.
+It can be specified in two ways: via the @code{pop-up-frames}
+variable and via a @code{pop-up-frames} entry in
+@code{display-buffer}'s @var{alist},
+where the entry in the alist takes precedence over the variable.
+The default is @code{nil}.
 
 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
diff --git a/etc/NEWS b/etc/NEWS
index 60391cfb22e..060d1a2fe5c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1289,6 +1289,10 @@ values.
 \f
 * 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..93c8ad7fad9 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6862,6 +6862,7 @@ special-display-popup-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 @@ special-display-popup-frame
        ;; 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 @@ pop-up-frames
 	  (const :tag "Always" t))
   :group 'windows)
 
+(defun window--pop-up-frames (alist)
+ (let* ((override (assq 'pop-up-frames alist))
+        (pop-up (if override (cdr overriding) 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 @@ display-buffer
     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 @@ display-buffer
                           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 @@ display-buffer-reuse-window
 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 @@ display-buffer-reuse-mode-window
   (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 @@ display-buffer--maybe-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 @@ display-buffer-in-previous-window
 	  (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))))

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

[Drew Adams]

+** 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.

Please don't do that.  This is a user option,
_not_ just a variable.  (And yes, it should
continue to be supported, forever, regardless
of the fact that it's been "deprecated".)

`display-buffer' shouldn't override the user's
choice for the behavior.

From my point of view it's OK for a given
command to override a user option, but only
if the command's doc tells users that it does
that.

And a command can do that just by binding the
option to nil.  Please don't let a parameter
to `display-buffer' override this handy, simple
user option.

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]

Hi Drew,

I have no idea what you're talking about.  Please double check
that you actually understand what the patch is doing (and take the
`Subject:` of this bug report as a good hint for the intended use),
and then clarify your argument.

For example, `pop-up-frames` is not deprecated.


        Stefan


Drew Adams [2023-12-09 22:40:00] wrote:

> +** 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.
>
> Please don't do that.  This is a user option,
> _not_ just a variable.  (And yes, it should
> continue to be supported, forever, regardless
> of the fact that it's been "deprecated".)
>
> `display-buffer' shouldn't override the user's
> choice for the behavior.
>
> From my point of view it's OK for a given
> command to override a user option, but only
> if the command's doc tells users that it does
> that.
>
> And a command can do that just by binding the
> option to nil.  Please don't let a parameter
> to `display-buffer' override this handy, simple
> user option.

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

[Drew Adams]

> I have no idea what you're talking about.  Please double check
> that you actually understand what the patch is doing (and take the
> `Subject:` of this bug report as a good hint for the intended use),
> and then clarify your argument.

I did look at the patch, and I understood that.
The only thing I objected to is having the value
of that user option be overridden by passing a
different value of the eponymous `display-buffer'
parameter.

> For example, `pop-up-frames` is not deprecated.

Yes, I know that.  I didn't say it is.  I only
mentioned, in parens, that I hope it remains
undeprecated.

To be clear, it's _good_ for `display-buffer' to
be able to do what `pop-up-frames' does.  Most
use cases would (I guess?) also be covered by
just binding the option.  I just don't think it's
great for such a work-horse function to override
an option value.

If the doc about the parameter made clear what's
involved (i.e., say that it overrides the option
etc.), and counseled against overriding an option
without letting users know that that's happening
(e.g. in the doc string of a command that uses
`display-buffer' this way), then that's probably
OK.

IOW, let's please refer to it as a user "option",
not just a "variable", and remind users of the
parameter that it's not very kosher to override
the behavior of an option without also letting
users know explicitly that that's happening.

If a user of a command knows that it overrides
an option then, well, using that command is a
choice.  And they can likely define their own
command that doesn't do so.  Can they do that
just by binding `pop-up-frames'?  (No, right?)

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

[Eli Zaretskii]

> Cc: "67249@debbugs.gnu.org" <67249@debbugs.gnu.org>
> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 9 Dec 2023 22:40:00 +0000
> 
> +** 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.
> 
> Please don't do that.  This is a user option,
> _not_ just a variable.  (And yes, it should
> continue to be supported, forever, regardless
> of the fact that it's been "deprecated".)
> 
> `display-buffer' shouldn't override the user's
> choice for the behavior.

There's nothing wrong with having parameters and user options by the
same name that affect the same functionality, but indeed usually the
user option overrides the parameter, not the other way around.  See,
for example, the cursor-type option and frame parameter.

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]

> There's nothing wrong with having parameters and user options by the
> same name that affect the same functionality, but indeed usually the
> user option overrides the parameter, not the other way around.  See,
> for example, the cursor-type option and frame parameter.

Usually the rule we follow is to obey the most specific setting.
In your example, we obey the (potentially buffer-local) variable in
preference to the frame-local parameter.

In my patch the choice is between the global variable (I've never seen
it set buffer-locally and I don't think the code would handle it "right"
if set buffer-locally) and the buffer/operation-specific parameter.

Also, contrary to the current situation where code let-binds the
variable to "impose" its choice over that of the user (which is hard to
undo/override), when code sets it via the new alist entry the user gets
a chance to override this override via `display-buffer-alist`.

The `display-buffer` action system is complex, but it is designed
specifically so as to allow the user to stay in control.


        Stefan

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

[Drew Adams]

> > +** 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.
> >
> > Please don't do that.  This is a user option,
> > _not_ just a variable.  (And yes, it should
> > continue to be supported, forever, regardless
> > of the fact that it's been "deprecated".)
> >
> > `display-buffer' shouldn't override the user's
> > choice for the behavior.
> 
> There's nothing wrong with having parameters and user options by the
> same name that affect the same functionality, but indeed usually the
> user option overrides the parameter, not the other way around.  See,
> for example, the cursor-type option and frame parameter.

Exactly.

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

[Eli Zaretskii]

> Cc: 67249@debbugs.gnu.org
> Date: Sat, 09 Dec 2023 17:29:06 -0500
> From:  Stefan Monnier via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
>  @defopt pop-up-frames
> -If the value of this variable is non-@code{nil}, that means
> -@code{display-buffer} may display buffers by making new frames.  The
> -default is @code{nil}.
> +If the value of this parameter is non-@code{nil}, that means
> +@code{display-buffer} may display buffers by making new frames.
> +It can be specified in two ways: via the @code{pop-up-frames}
> +variable and via a @code{pop-up-frames} entry in
> +@code{display-buffer}'s @var{alist},
> +where the entry in the alist takes precedence over the variable.
> +The default is @code{nil}.

pop-up-frames described here is a user option, so saying "the value of
this parameter" is wrong.  My suggestion is to leave the current text
alone, and add after it something like

  An entry by the same name in @code{display-buffer}'s @var{alist}
  takes precedence over the variable.

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]

> pop-up-frames described here is a user option, so saying "the value of
> this parameter" is wrong.  My suggestion is to leave the current text
> alone, and add after it something like
>
>   An entry by the same name in @code{display-buffer}'s @var{alist}
>   takes precedence over the variable.

Thanks.  The doc change is now as below.


        Stefan


diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 22c1b307252..5f5e5d143aa 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
+This 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

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

[martin rudalics via Bug reports for GNU Emacs, the Swiss army knife of text editors]

 > +@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.

 > +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)))

martin

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]

>> +@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
 

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]

Pushed, thanks,


        Stefan

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

[martin rudalics]

 >> Do you mean 'display-buffer-override-next-command' and
 >> 'display-buffer-record-window'?
 >
 > I mostly noticed `display-buffer-other-frame` whose name (to me)
 > suggests it can be used in an ACTION.  The two you cite could be
 > considered as colliding, but since their name doesn't suggest they're
 > going to "display a buffer", they didn't bother me.
 >
 > Hmm... after looking a bit more maybe it's not that bad, since the
 > calling convention can be used to distinguish them
 > (e.g. `display-buffer-other-frame` doesn't take an ALIST after the
 > BUFFER).

'display-buffer-other-frame' was in files.el so C-x 5 C-o could be bound
to it - mainly as counterpart to C-x 4 C-o, I suppose.  It would be more
consistent to have two functions say 'show-buffer-other-window' and
'show-buffer-other-frame' we could bind to C-x 4 C-b and C-x 5 C-b and
assign them appropriate action functions but I'm not sure whether people
would like it.

martin

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]

> 'display-buffer-other-frame' was in files.el so C-x 5 C-o could be bound
> to it - mainly as counterpart to C-x 4 C-o, I suppose.  It would be more
> consistent to have two functions say 'show-buffer-other-window' and
> 'show-buffer-other-frame' we could bind to C-x 4 C-b and C-x 5 C-b and
> assign them appropriate action functions but I'm not sure whether people
> would like it.

Right, it seems it's just a "historical accident" and we should just
live with it.


        Stefan