bug#7865: 24.0.50; doc of display-buffer-reuse-frames

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.
This should be made clear wherever `display-buffer-reuse-frames' is
documented.  (Alternatively, make it clear in one place and
cross-reference that place from the others.)
 
These are the places it is documented:
 
1. Elisp manual, node `Displaying Buffers'
2. Elisp manual, node `Choosing Window'
3. Emacs manual, node `Select Buffer
4. Doc string
 
Only in #1 is this made clear: "If either of the variables
`display-buffer-reuse-frames' or `pop-up-frames' is non-`nil'...".
(Although "option" would be better than "variable" here - and
throughout.)
 
Each of the other spots describes the option without mentioning this.
Either add this info to #2 and #3 or reduce/remove their descriptions of
the option and just cross-reference to the full description in #1 that
does mention this.
 
In any case, the doc string should mention it.
 
Finally, the description of this option in #3 just ends with this: "If
there is no such window or `display-buffer-reuse-frames' is `nil', the
behavior of `display-buffer' is determined by the variables described
next."
 
There follow descriptions of 15 other user options!  Does that sentence
mean all 15 or just the first two, which are followed by the description
of a function?  `pop-up-frames' is one of the 15, but it appears after
the function description, as the 6th option after
`display-buffer-reuse-frames'.  And of course `pop-up-frame' determines
the behavior even if `display-buffer-reuse-frames' is non-nil - its
description should come first.
 
Just remove that last sentence, please - it is confusing and doesn't say
anything.  If you want, replace it with a sentence saying only that when
it is nil it has no effect on the buffer display (other things come into
play to govern the behavior).
 
 
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-01-17 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

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

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

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

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.

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

[martin rudalics]

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

If `display-buffer-reuse-frames' is non-nil, Emacs currently uses an
arbitrary window on _any_ frame provided the window shows the buffer,
regardless of the value of `pop-up-frames'.  It has been this way ever
since `display-buffer-reuse-frames' was introduced.

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

I suppose you mean "if `display-buffer-reuse-frames' is nil and
`pop-up-frames' is t" in the first sentence above.  In that case I'd
agree.  But I think Stefan wants it the current way because he doesn't
care much about `display-buffer-reuse-frames' and he's using these
options for popping up dedicated frames to show some buffer in such a
frame and nowhere else.  In his particular use case the present behavior
makes perfect sense because it DTRT even if he asks for displaying the
buffer when its frame _is_ currently selected.

To make `display-buffer-reuse-frames' work as you describe we'd have to
make the `get-buffer-window' routines understand as ALL-FRAMES argument
a value of say 'other, meaning to "not return a window on the selected
frame".  Or, we can sort out these windows manually - you might want to
have a look at the routine `display-buffer-reuse-window' in my branch to
see how it's done there.

martin

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

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

[Stefan Monnier]

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

> I suppose you mean "if `display-buffer-reuse-frames' is nil and
> `pop-up-frames' is t" in the first sentence above.  In that case I'd
> agree.

I'm confused here.  Which case are we talking about, which behavior is
not desired, and which alternative behavior would you(plural) prefer?


        Stefan

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

[martin rudalics]

 >> I suppose you mean "if `display-buffer-reuse-frames' is nil and
 >> `pop-up-frames' is t" in the first sentence above.  In that case I'd
 >> agree.
 >
 > I'm confused here.  Which case are we talking about, which behavior is
 > not desired, and which alternative behavior would you(plural) prefer?

When a buffer is already displayed, `display-buffer-reuse-frames' is nil
and `pop-up-frames' is non-nil, `display-buffer' reuses a window.  So if
you set the default of `display-buffer-reuse-frames' to t as someone
proposed, customizing `display-buffer-reuse-frames' will have no effect
when `pop-up-frames' is non-nil.  I don't know whether this is desired
or not and I don't care about the alternatives because `pop-up-frames'
is nil here.

I guess that `display-buffer-reuse-frames' was invented for something
like the following use case:

- The user has `pop-up-frames' nil.

- An application binds `pop-up-frames' to non-nil and pops up a buffer
   in a new frame.

- The user returns to her old frame and eventually does something like
   `pop-to-buffer' on that buffer which should get her to the new frame.

This means that setting `display-buffer-reuse-frames' to t makes sense
iff `pop-up-frames' is nil and the scenario I described above does not
apply, usually.  It's still confusing in my opinion, though.

martin

bug#7865: 24.0.50; doc of display-buffer-reuse-frames

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> Each of the other spots describes the option without mentioning this.
> Either add this info to #2 and #3 or reduce/remove their descriptions of
> the option and just cross-reference to the full description in #1 that
> does mention this.

Closing, since display-buffer-reuse-frames has been obsoleted.

bug#7865: 24.0.50; doc of display-buffer-reuse-frames

[Drew Adams]

> > Each of the other spots describes the option without 
> > mentioning this.  Either add this info to #2 and #3 or
> > reduce/remove their descriptions of the option and just
> > cross-reference to the full description in #1 that
> > does mention this.
> 
> Closing, since display-buffer-reuse-frames has been obsoleted.

Deprecation is not the same as desupport.  As long as this is supported the doc
should be correct regarding it.

And the bug description points out several interrelated doc problems. These
should be corrected, not simply waved away as irrelevant.