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

[martin rudalics <rudalics@gmx.at>]

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