bug#7865: Bug in display-buffer-reuse-frames [was Re: bug#7865: 24.0.50; doc of display-buffer-reuse-frames]

[Drew Adams]

> > This option is used in only `display-buffer', in a test that is
> > essentially (or pop-up-frames display-buffer-reuse-frames ...)
> >
> > That means that this option has no effect if `pop-up-frames' is
> > non-nil.
> 
> I think this is actually a bug.  Doing `C-x b' with non-nil
> display-buffer-reuse-frames should make Emacs raise another frame if
> it;s already displaying the desired buffer---regardless of 
> the value of pop-up-frames.

No, it should not.  That would flagrantly contradict the intention of
`pop-up-frames', as well as its longstanding and documented behavior.

> Currently, if display-buffer-reuse-frames and pop-up-frames 
> are both t, `C-x b' instead displays the buffer in the
> existing frame.  So `pop-up-frames' has changed the behavior,
> even though it's not doing any "popping up" in this case.

No, no, no.  There is no bug other than the doc bug I filed.

You say that `pop-up-frames' has changed the behavior?  On the contrary, if you
were to make the change you suggest then `display-buffer-reuse-frames' would be
changing the behavior specified (and realized since Day One) by `pop-up-frames'
- and that would be the case regardless of the value of
`display-buffer-reuse-frames'!

`pop-up-frames' should not be affected by `display-buffer-reuse-frames':
`pop-up-frames' is already specifying the reuse of frames.

>From  (elisp) Choosing Window: "[`pop-up-frames'] specifies whether
`display-buffer' should make new frames."  Likewise, the first line of its doc
string: "Whether `display-buffer' should make a separate frame."

That's exactly what `pop-up-frames' does: specify when to reuse a frame vs make
a new frame.  `display-buffer-reuse-frames' was created later to do something
similar but without ever creating a new frame.

`pop-up-frames' has been around a lot longer than `display-buffer-reuse-frames',
so it cannot be said to change the behavior of the latter.  The definition of
`pop-up-frames' is clear about reusing frames.  Again, from (elisp) Choosing
Window:

"If [`pop-up-frames'] is non-`nil', `display-buffer' looks
for a window already displaying BUFFER-OR-NAME on any visible
or iconified frame.  If it finds such a window, it makes that
window's frame visible and raises it if necessary, and returns
the window.  Otherwise it makes a new frame..."

Please reread the whole bug report.  In particular: "`pop-up-frames' determines
the behavior even if `display-buffer-reuse-frames' is non-nil - its description
should come first."

The behavior of `pop-up-frames' is correct (and longstanding).  The behavior of
`display-buffer-reuse-frames' is correct also.  In particular, it is correct
that it _has no effect_ if `pop-up-frames' is non-nil.  What needs fixing is the
doc (only).

(And it is not too kosher to simply change the subject line and thus "reuse"
(hijack) the bug number.)