Does display-buffer display the buffer or not?

Does display-buffer display the buffer or not?

[Lennart Borgman]

The doc string for displayb buffer begins like this:

  Make buffer BUFFER-OR-NAME appear in some window but don't select it.
  BUFFER-OR-NAME must be a buffer or the name of an existing
  buffer.  Return the window chosen to display BUFFER-OR-NAME or
  nil if no such window is found.

I do not understand the last sentence. Could it happen that the buffer
is not displayed? In that case, should not that be an error?

Re: Does display-buffer display the buffer or not?

[Tassilo Horn]

Lennart Borgman <lennart.borgman@gmail.com> writes:

Hi Lennart,

> The doc string for displayb buffer begins like this:
>
>   Make buffer BUFFER-OR-NAME appear in some window but don't select it.
>   BUFFER-OR-NAME must be a buffer or the name of an existing
>   buffer.  Return the window chosen to display BUFFER-OR-NAME or
>   nil if no such window is found.
>
> I do not understand the last sentence. Could it happen that the buffer
> is not displayed? In that case, should not that be an error?

My first idea was that when you say NOT-THIS-WINDOW (t) and the current
FRAME (nil), but the current frame has only one window and is only of
minimal size, so no split can be done, then it must return nil and do
nothing.  Unfortunately, testing that situation with

  (display-buffer "*info*" t nil)

pops up a completely new frame showing *info*.  Reading the docs a bit
further, there is

,----[ C-h f display-buffer RET ]
| [...]
| 
| nil - consider windows on the selected frame (actually the
| last non-minibuffer frame) only.  If, however, either
| `display-buffer-reuse-frames' or `pop-up-frames' is non-nil
| (non-nil and not graphic-only on a text-only terminal),
| consider all visible or iconified frames.
`----

Unfortunately, both `display-buffer-reuse-frames' and `pop-up-frames'
are nil, here.

I do think that creating a new frame is appropriate in the situation
above, but the docs should make that clear.  Currently, they don't match
the implemented behavior.

Bye,
Tassilo

Re: Does display-buffer display the buffer or not?

[martin rudalics]

 > My first idea was that when you say NOT-THIS-WINDOW (t) and the current
 > FRAME (nil), but the current frame has only one window and is only of
 > minimal size, so no split can be done, then it must return nil and do
 > nothing.  Unfortunately, testing that situation with
 >
 >   (display-buffer "*info*" t nil)
 >
 > pops up a completely new frame showing *info*.  Reading the docs a bit
 > further, there is
 >
 > ,----[ C-h f display-buffer RET ]
 > | [...]
 > |
 > | nil - consider windows on the selected frame (actually the
 > | last non-minibuffer frame) only.  If, however, either
 > | `display-buffer-reuse-frames' or `pop-up-frames' is non-nil
 > | (non-nil and not graphic-only on a text-only terminal),
 > | consider all visible or iconified frames.
 > `----
 >
 > Unfortunately, both `display-buffer-reuse-frames' and `pop-up-frames'
 > are nil, here.
 >
 > I do think that creating a new frame is appropriate in the situation
 > above, but the docs should make that clear.  Currently, they don't match
 > the implemented behavior.

The Elisp manual says

       If all options described above fail to produce a suitable window,
    `display-buffer' tries to reuse an existing window.  As a last resort,
    it will try to display BUFFER-OR-NAME on a separate frame.  In that
    case, the value of `pop-up-frames' is disregarded.

I never investigated whether this occurs in practice and what happens,
for example, on non-graphic displays.  It's just a fallback method and
I'm not sure whether it's worth mentioning in the doc-string.

martin

Re: Does display-buffer display the buffer or not?

[Tassilo Horn]

martin rudalics <rudalics@gmx.at> writes:

Hi Martin,

>> My first idea was that when you say NOT-THIS-WINDOW (t) and the
>> current FRAME (nil), but the current frame has only one window and is
>> only of minimal size, so no split can be done, then it must return
>> nil and do nothing.  Unfortunately, testing that situation with
>>
>>   (display-buffer "*info*" t nil)
>>
>> pops up a completely new frame showing *info*.  Reading the docs a bit
>> further, there is
>>
>> ,----[ C-h f display-buffer RET ]
>> | [...]
>> |
>> | nil - consider windows on the selected frame (actually the
>> | last non-minibuffer frame) only.  If, however, either
>> | `display-buffer-reuse-frames' or `pop-up-frames' is non-nil
>> | (non-nil and not graphic-only on a text-only terminal),
>> | consider all visible or iconified frames.
>> `----
>>
>> Unfortunately, both `display-buffer-reuse-frames' and `pop-up-frames'
>> are nil, here.
>>
>> I do think that creating a new frame is appropriate in the situation
>> above, but the docs should make that clear.  Currently, they don't match
>> the implemented behavior.
>
> The Elisp manual says
>
>       If all options described above fail to produce a suitable window,
>    `display-buffer' tries to reuse an existing window.  As a last resort,
>    it will try to display BUFFER-OR-NAME on a separate frame.  In that
>    case, the value of `pop-up-frames' is disregarded.

Ok, I see.

> I never investigated whether this occurs in practice and what happens,
> for example, on non-graphic displays.

In ttys it also creates a new frame with that buffer.  You cannot see
that there is a new frame, except that you have to to C-x 5 0 twice to
return to the command line (when tty frame was created by emacsclient)
or to get the message that one cannot delete the only frame (with emacs
-nw -Q), and

  (frames-on-display-list)

returns 2 frames.

Hm, is it sensible to have multiple frames on one tty?  You can only see
one at a time anyway...

> It's just a fallback method and I'm not sure whether it's worth
> mentioning in the doc-string.

Yes, IMO, it is.  And the "nil if no such window is found" should be
removed.  The fallback ensures that a window will always be found,
right?

With the current spelling, I read the docs like "the function caller
should check that the return-value of display-buffer is nil, and if it
is, act appropriately by creating a new frame, for example."

Bye,
Tassilo

Re: Does display-buffer display the buffer or not?

[martin rudalics]

 > Hm, is it sensible to have multiple frames on one tty?  You can only see
 > one at a time anyway...

That's what graphic-only for `pop-up-frames' is used for.  But this
option is ignored in the fallback case (unless `pop-up-frame-function'
wants to check it).

 >> It's just a fallback method and I'm not sure whether it's worth
 >> mentioning in the doc-string.
 >
 > Yes, IMO, it is.  And the "nil if no such window is found" should be
 > removed.  The fallback ensures that a window will always be found,
 > right?

As I explained elsewhere you can make `pop-up-frame-function' do
something silly, so the frame is not created in the worst case.  Hence,
I would have to say that `pop-up-frame-function' has to behave
reasonably in that case.  And I would have to enlist the windows
`display-buffer' tries to reuse before trying to pop up a new frame and
maybe some other things I never tried to understand.

 > With the current spelling, I read the docs like "the function caller
 > should check that the return-value of display-buffer is nil, and if it
 > is, act appropriately by creating a new frame, for example."

That's a correct conclusion, indeed.  The "creating a new frame" part
would then have to sidestep `pop-up-frame-function', obviously.

martin

Re: Does display-buffer display the buffer or not?

[Lennart Borgman]

On Fri, Dec 24, 2010 at 12:13 PM, martin rudalics <rudalics@gmx.at> wrote:
>
>> With the current spelling, I read the docs like "the function caller
>> should check that the return-value of display-buffer is nil, and if it
>> is, act appropriately by creating a new frame, for example."
>
> That's a correct conclusion, indeed.  The "creating a new frame" part
> would then have to sidestep `pop-up-frame-function', obviously.

So the average programmers is supposed to know how to handle this, but
those writing for example the routines that shows a backtrace when
there is an error are not.

Why is the average programmer better at avoiding looping here?

Re: Does display-buffer display the buffer or not?

[martin rudalics]

 >> That's a correct conclusion, indeed.  The "creating a new frame" part
 >> would then have to sidestep `pop-up-frame-function', obviously.
 >
 > So the average programmers is supposed to know how to handle this, but
 > those writing for example the routines that shows a backtrace when
 > there is an error are not.
 >
 > Why is the average programmer better at avoiding looping here?

Emacs doesn't pop up the *Backtrace* buffer by default so the "average"
user is not affected.  And the average user is not supposed to customize
`pop-up-frame-function' either.  I intended this as a hint for people
writing, for example, a silly `pop-up-frame-function' so they can find
the cuplrit easier.  And, obviously, if a function is allowed to return
nil, the doc-string of the function should say so.

martin

Re: Does display-buffer display the buffer or not?

[Lennart Borgman]

On Fri, Dec 24, 2010 at 12:49 PM, martin rudalics <rudalics@gmx.at> wrote:
>>> That's a correct conclusion, indeed.  The "creating a new frame" part
>>> would then have to sidestep `pop-up-frame-function', obviously.
>>
>> So the average programmers is supposed to know how to handle this, but
>> those writing for example the routines that shows a backtrace when
>> there is an error are not.
>>
>> Why is the average programmer better at avoiding looping here?
>
> Emacs doesn't pop up the *Backtrace* buffer by default so the "average"
> user is not affected.  And the average user is not supposed to customize
> `pop-up-frame-function' either.  I intended this as a hint for people
> writing, for example, a silly `pop-up-frame-function' so they can find
> the cuplrit easier.  And, obviously, if a function is allowed to return
> nil, the doc-string of the function should say so.

And why is it better not to give an error then?

Re: Does display-buffer display the buffer or not?

[martin rudalics]

 >>> Why is the average programmer better at avoiding looping here?
 >> Emacs doesn't pop up the *Backtrace* buffer by default so the "average"
 >> user is not affected.  And the average user is not supposed to customize
 >> `pop-up-frame-function' either.  I intended this as a hint for people
 >> writing, for example, a silly `pop-up-frame-function' so they can find
 >> the cuplrit easier.  And, obviously, if a function is allowed to return
 >> nil, the doc-string of the function should say so.
 >
 > And why is it better not to give an error then?

I don't know whether it's better.  Maybe because, as I tried to explain
earlier, the error handler would call `display-buffer' and fail the same
way.

martin

Re: Does display-buffer display the buffer or not?

[Lennart Borgman]

On Fri, Dec 24, 2010 at 3:41 PM, martin rudalics <rudalics@gmx.at> wrote:
>>>> Why is the average programmer better at avoiding looping here?
>>> Emacs doesn't pop up the *Backtrace* buffer by default so the "average"
>>> user is not affected.  And the average user is not supposed to customize
>>> `pop-up-frame-function' either.  I intended this as a hint for people
>>> writing, for example, a silly `pop-up-frame-function' so they can find
>>> the cuplrit easier.  And, obviously, if a function is allowed to return
>>> nil, the doc-string of the function should say so.
>>
>> And why is it better not to give an error then?
>
> I don't know whether it's better.  Maybe because, as I tried to explain
> earlier, the error handler would call `display-buffer' and fail the same
> way.

And in response to that I said that then it is left to every
programmer using display-buffer to handle this very uncommon cases
instead.

Re: Does display-buffer display the buffer or not?

[martin rudalics]

 > I don't know whether it's better.  Maybe because, as I tried to explain
 > > earlier, the error handler would call `display-buffer' and fail the same
 > > way.
 >
 > And in response to that I said that then it is left to every
 > programmer using display-buffer to handle this very uncommon cases
 > instead.

I never disputed that.  But what you said earlier was that

 > So the average programmers is supposed to know how to handle this, but
 > those writing for example the routines that shows a backtrace when
 > there is an error are not.
 >
 > Why is the average programmer better at avoiding looping here?

and I tried to explain that the average programmer usually doesn't mess
things up in a way that the "very uncommon case" really occurs.  So in
practice the "very uncommon case" usually occurs only when a non-average
programmer fails at writing a good `pop-up-frame-function'.  In that
case, however, signalling an error wouldn't help her much since that
might call the same `pop-up-frame-function' again.

martin

Re: Does display-buffer display the buffer or not?

[Eli Zaretskii]

> From: Tassilo Horn <tassilo@member.fsf.org>
> Date: Fri, 24 Dec 2010 11:22:41 +0100
> Cc: Lennart Borgman <lennart.borgman@gmail.com>,
> 	Emacs-Devel devel <emacs-devel@gnu.org>
> 
> > I never investigated whether this occurs in practice and what happens,
> > for example, on non-graphic displays.
> 
> In ttys it also creates a new frame with that buffer.  You cannot see
> that there is a new frame

You should be able to see that, by looking at the far left edge of the
mode line: there, to the left of the buffer name, you will see the
frame name, which is normally F1, F2, etc.  When a new frame is
displayed, you get Fn with n one more than the last one you saw.
Usually, you will see F2 where before that you saw F1.

> Hm, is it sensible to have multiple frames on one tty?  You can only see
> one at a time anyway...

You don't use Emacs on a TTY too much, do you? ;-)

Of course, it's sensible.  Emacs still maintains separate faces,
separate buffer lists, etc. for each frame, even though only one is
visible at a time.  So you could use each frame for a separate related
groups of tasks, e.g. develop code in one, read email in another, etc.
We have set-frame-name and select-frame-by-name to make this kind of
workflow easier, btw.

Re: Does display-buffer display the buffer or not?

[Tassilo Horn]

Eli Zaretskii <eliz@gnu.org> writes:

Hi Eli,

>> In ttys it also creates a new frame with that buffer.  You cannot see
>> that there is a new frame
>
> You should be able to see that, by looking at the far left edge of the
> mode line: there, to the left of the buffer name, you will see the
> frame name, which is normally F1, F2, etc.  When a new frame is
> displayed, you get Fn with n one more than the last one you saw.
> Usually, you will see F2 where before that you saw F1.

Oh, indeed.  I didn't notice that.

>> Hm, is it sensible to have multiple frames on one tty?  You can only
>> see one at a time anyway...
>
> You don't use Emacs on a TTY too much, do you? ;-)

Not really.

> Of course, it's sensible.  Emacs still maintains separate faces,
> separate buffer lists, etc. for each frame, even though only one is
> visible at a time.  So you could use each frame for a separate related
> groups of tasks, e.g. develop code in one, read email in another, etc.

I think, I don't get it.  I mean, except their order, all entries in
(buffer-list) are shared by all emacs frames of the same emacs instance.
So how would I create a frame dedicated to email, one to coding, and so
forth?

Bye,
Tassilo

Re: Does display-buffer display the buffer or not?

[martin rudalics]

 > I think, I don't get it.  I mean, except their order, all entries in
 > (buffer-list) are shared by all emacs frames of the same emacs instance.
 > So how would I create a frame dedicated to email, one to coding, and so
 > forth?

By customizing `special-display-buffer-names' and/or
`special-display-regexps'.

martin

Re: Does display-buffer display the buffer or not?

[Eli Zaretskii]

> Date: Fri, 24 Dec 2010 16:04:09 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: Eli Zaretskii <eliz@gnu.org>, lennart.borgman@gmail.com, 
>  emacs-devel@gnu.org
> 
>  > I think, I don't get it.  I mean, except their order, all entries in
>  > (buffer-list) are shared by all emacs frames of the same emacs instance.
>  > So how would I create a frame dedicated to email, one to coding, and so
>  > forth?
> 
> By customizing `special-display-buffer-names' and/or
> `special-display-regexps'.

You don't even need that, for many use-cases: Emacs does TRT
automatically, e.g. "C-x b" will first suggest buffers which were
displayed in the current frame.  For more complex jobs, yes, these
customizations will do the rest.

Re: Does display-buffer display the buffer or not?

[martin rudalics]

 >   Make buffer BUFFER-OR-NAME appear in some window but don't select it.
 >   BUFFER-OR-NAME must be a buffer or the name of an existing
 >   buffer.  Return the window chosen to display BUFFER-OR-NAME or
 >   nil if no such window is found.
 >
 > I do not understand the last sentence. Could it happen that the buffer
 > is not displayed?

It could happen but it's very unlikely.

 > In that case, should not that be an error?

Not really since this might try to display the *Backtrace* buffer :-(

martin

Re: Does display-buffer display the buffer or not?

[Lennart Borgman]

On Fri, Dec 24, 2010 at 10:31 AM, martin rudalics <rudalics@gmx.at> wrote:
>>   Make buffer BUFFER-OR-NAME appear in some window but don't select it.
>>   BUFFER-OR-NAME must be a buffer or the name of an existing
>>   buffer.  Return the window chosen to display BUFFER-OR-NAME or
>>   nil if no such window is found.
>>
>> I do not understand the last sentence. Could it happen that the buffer
>> is not displayed?
>
> It could happen but it's very unlikely.
>
>> In that case, should not that be an error?
>
> Not really since this might try to display the *Backtrace* buffer :-(

:-(

Does not the error routines do all they can to survive situations like
that? What happens otherwise for example if an error occurs because
the buffer was not displayed?

Re: Does display-buffer display the buffer or not?

[martin rudalics]

 > Does not the error routines do all they can to survive situations like
 > that? What happens otherwise for example if an error occurs because
 > the buffer was not displayed?

To produce such a case you would probably have to make all frames
unsplittable, all windows dedicated, and set `pop-up-frame-function' to
something like `ignore'.  Then look what happens ;-)

martin