The display-buffer command (as well as commands that call it
internally) chooses a window to display by following the steps given
below. See Choosing a Window for Display in The Emacs Lisp Reference Manual, for details about how to alter this
sequence of steps.
First, check if the buffer should be displayed in the selected window
regardless of other considerations. You can tell Emacs to do this by
adding the desired buffer’s name to the list
same-window-buffer-names, or adding a matching regular
expression to the list same-window-regexps. By default, these
variables are nil, so this step is skipped.
Otherwise, if the buffer is already displayed in an existing window,
reuse that window. Normally, only windows on the selected frame
are considered, but windows on other frames are also reusable if you
change pop-up-frames (see below) to t.
Otherwise, optionally create a new frame and display the buffer there.
By default, this step is skipped. To enable it, change the variable
pop-up-frames to a non-nil value. The special value
graphic-only means to do this only on graphical displays.
Otherwise, try to create a new window by splitting a window on the
selected frame, and display the buffer in that new window.
The split can be either vertical or horizontal, depending on the
variables split-height-threshold and
split-width-threshold. These variables should have integer
values. If split-height-threshold is smaller than the chosen
window’s height, the split puts the new window below. Otherwise, if
split-width-threshold is smaller than the window’s width, the
split puts the new window on the right. If neither condition holds,
Emacs tries to split so that the new window is below—but only if the
window was not split before (to avoid excessive splitting).
Otherwise, display the buffer in a window previously showing it.
Normally, only windows on the selected frame are considered, but if
pop-up-frames is non-nil the window may be also on another
Otherwise, display the buffer in an existing window on the selected
If all the above methods fail for whatever reason, create a new frame
and display the buffer there.
A more advanced and flexible way to customize the behavior of
display-buffer is by using the option display-buffer-alist
mentioned in the next section.