mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-26 07:33:47 +00:00
Code Issues Releases Activity

Improve recent changes in documentation of window handling

Browse Source 
* doc/lispref/windows.texi (Displaying Buffers)
(Choosing Window, Buffer Display Action Functions)
(Buffer Display Action Alists, Choosing Window Options)
(Precedence of Action Functions, The Zen of Buffer Display):
Fix wording, punctuation, and markup.  Remove redundant
cross-references.

* doc/emacs/windows.texi (Window Choice, Temporary Displays):
Fix wording and punctuation.
This commit is contained in:
Eli Zaretskii 2018-11-04 19:08:00 +02:00
parent c04b48c088
commit 6937c35d32
2 changed files with 162 additions and 176 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
doc/emacs/windows.texi
View File

@ -386,9 +386,10 @@ to alter this sequence of steps.
@itemize
@item
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 a regular expression matching the buffer's name together with a
If the buffer should be displayed in the selected window regardless of
other considerations, reuse the selected window. By default, this
step is skipped, but you can tell Emacs not to skip it by adding a
regular expression matching the buffer's name together with a
reference to the @code{display-buffer-same-window} action function
(@pxref{Buffer Display Action Functions,,Action Functions for Buffer
Display, elisp, The Emacs Lisp Reference Manual}) to the option
@ -405,17 +406,16 @@ selected window write:
@end group
@end example
By default, @code{display-buffer-alist} is @code{nil}, so this step is
skipped.
By default, @code{display-buffer-alist} is @code{nil}.
@item
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 a
corresponding @code{reusable-frames} action alist entry (@pxref{Buffer
Display Action Alists,,Action Alists for Buffer Display, elisp, The
Emacs Lisp Reference Manual}) is used (see the next step for an
example of how to do that).
considered, but windows on other frames are also reusable if you use
the corresponding @code{reusable-frames} action alist entry
(@pxref{Buffer Display Action Alists,,Action Alists for Buffer
Display, elisp, The Emacs Lisp Reference Manual}). See the
next step for an example of how to do that.
@item
Otherwise, optionally create a new frame and display the buffer there.
@ -434,7 +434,7 @@ Lisp Reference Manual}) as follows:
@end example
This customization will also try to make the preceding step search for
a reusable window on all visible of iconified frames
a reusable window on all visible or iconified frames.
@item
Otherwise, try to create a new window by splitting a window on the
@ -475,22 +475,21 @@ and display the buffer there.
Some buffers are shown in windows for perusal rather than for editing.
Help commands (@pxref{Help}) typically use a buffer called @file{*Help*}
for that purpose, minibuffer completion (@pxref{Completion}) uses a
buffer called @file{*Completions*} instead. Such buffers are usually
buffer called @file{*Completions*}, etc. Such buffers are usually
displayed only for a short period of time.
Normally, Emacs chooses the window for such temporary displays via
@code{display-buffer} as described in the previous subsection. The
@code{display-buffer}, as described in the previous subsection. The
@file{*Completions*} buffer, on the other hand, is normally displayed
in a window at the bottom of the selected frame, regardless of the
number of windows already shown on that frame.
If you prefer Emacs to display a temporary buffer in a different
fashion, we recommend customizing the variable
@code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window
for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}).
For example, to display @file{*Completions*} always below the selected
window, use the following form in your initialization file
(@pxref{Init File}):
fashion, customize the variable @code{display-buffer-alist}
(@pxref{Choosing Window,,Choosing a Window for Displaying a Buffer,
elisp, The Emacs Lisp Reference Manual}) appropriately. For example,
to display @file{*Completions*} always below the selected window, use
the following form in your initialization file (@pxref{Init File}):
@example
@group
@ -504,10 +503,10 @@ window, use the following form in your initialization file
The @file{*Completions*} buffer is also special in the sense that
Emacs usually tries to make its window just as large as necessary to
display all of its contents. To resize windows showing other
temporary displays like, for example, the @file{*Help*} buffer
accordingly, turn on the minor mode (@pxref{Minor Modes})
@code{temp-buffer-resize-mode} (@pxref{Temporary Displays,,Temporary
Displays, elisp, The Emacs Lisp Reference Manual}).
temporary displays, like, for example, the @file{*Help*} buffer, turn
on the minor mode (@pxref{Minor Modes}) @code{temp-buffer-resize-mode}
(@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
Reference Manual}).
@vindex temp-buffer-max-height
@vindex temp-buffer-max-width
@ -515,7 +514,7 @@ Displays, elisp, The Emacs Lisp Reference Manual}).
can be controlled by customizing the options
@code{temp-buffer-max-height} and @code{temp-buffer-max-width}
(@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
Reference Manual}) and cannot exceed the size of the containing frame.
Reference Manual}), and cannot exceed the size of the containing frame.
@node Window Convenience

291
doc/lispref/windows.texi
View File

@ -2338,20 +2338,19 @@ Window}).
@code{display-buffer} delegates the task of finding a suitable
window to so-called action functions (@pxref{Buffer Display Action
Functions}). Before, @code{display-buffer} compiles a so-called
action alist---a special association list action functions can use to
fine-tune their behavior--- and passes that alist on to each action
Functions}). First, @code{display-buffer} compiles a so-called action
alist---a special association list that action functions can use to
fine-tune their behavior. Then it passes that alist on to each action
function it calls (@pxref{Buffer Display Action Alists}).
The behavior of @code{display-buffer} is highly customizable. To
understand how customizations are put into practice, readers may want
to study examples illustrating the precedence acquired by
@code{display-buffer} for calling action functions (@pxref{Precedence
of Action Functions}). To avoid that Lisp programs calling
@code{display-buffer} come into conflict with users customizing its
behavior, it may make sense to follow a number of guidelines which are
sketched in the final part of this section (@pxref{The Zen of Buffer
Display}).
understand how customizations are used in practice, you may wish to
study examples illustrating the order of precedence which
@code{display-buffer} uses to call action functions (@pxref{Precedence
of Action Functions}). To avoid conflicts between Lisp programs
calling @code{display-buffer} and user customizations of its behavior,
it may make sense to follow a number of guidelines which are sketched
in the final part of this section (@pxref{The Zen of Buffer Display}).
@menu
* Choosing Window:: How to choose a window for displaying a buffer.
@ -2379,12 +2378,12 @@ Buffers}).
@cindex display action
This command performs several complex steps to find a window to
display in. These steps are described by means of @dfn{display
actions}, which have the form @code{(@var{function} . @var{alist})}.
Here, @var{function} is either a function or a list of functions,
which we refer to as ``action functions'' (@pxref{Buffer Display
Action Functions}); @var{alist} is an association list, which we refer
to as ``action alist'' (@pxref{Buffer Display Action Alists}). See
@ref{The Zen of Buffer Display}, for samples of display actions.
actions}, which have the form @code{(@var{functions} . @var{alist})}.
Here, @var{functions} is either a single function or a list of
functions, referred to as ``action functions'' (@pxref{Buffer Display
Action Functions}); and @var{alist} is an association list, referred
to as ``action alist'' (@pxref{Buffer Display Action Alists}).
@xref{The Zen of Buffer Display}, for samples of display actions.
An action function accepts two arguments: the buffer to display and
an action alist. It attempts to display the buffer in some window,
@ -2400,14 +2399,14 @@ value.
This command makes @var{buffer-or-name} appear in some window, without
selecting the window or making the buffer current. The argument
@var{buffer-or-name} must be a buffer or the name of an existing
buffer. The return value is the window chosen to display the buffer.
It is @code{nil} if no suitable window was found.
buffer. The return value is the window chosen to display the buffer,
or @code{nil} if no suitable window was found.
The optional argument @var{action}, if non-@code{nil}, should normally
be a display action (described above). @code{display-buffer} builds a
list of action functions and an action alist, by consolidating display
actions from the following sources (in order of their precedence,
highest ranking first):
from highest to lowest):
@itemize
@item
@ -2439,7 +2438,7 @@ may be called multiple times during one call of @code{display-buffer}.
@code{display-buffer} calls the action functions specified by this
list in turn, passing the buffer as the first argument and the
combined action alist as the second argument, until one of the
functions returns non-@code{nil}. See @ref{Precedence of Action
functions returns non-@code{nil}. @xref{Precedence of Action
Functions}, for examples how display actions specified by different
sources are processed by @code{display-buffer}.
@ -2466,8 +2465,8 @@ should always supply a list value.
The optional argument @var{frame}, if non-@code{nil}, specifies which
frames to check when deciding whether the buffer is already displayed.
It is equivalent to adding an element @code{(reusable-frames
. @var{frame})} to the action alist of @var{action} (@pxref{Buffer
It is equivalent to adding an element @w{@code{(reusable-frames
. @var{frame})}} to the action alist of @var{action} (@pxref{Buffer
Display Action Alists}). The @var{frame} argument is provided for
compatibility reasons, Lisp programs should not use it.
@end deffn
@ -2475,16 +2474,16 @@ compatibility reasons, Lisp programs should not use it.
@defvar display-buffer-overriding-action
The value of this variable should be a display action, which is
treated with the highest priority by @code{display-buffer}. The
default value is empty, i.e., @code{(nil . nil)}.
default value is an empty display action, i.e., @w{@code{(nil . nil)}}.
@end defvar
@defopt display-buffer-alist
The value of this option is an alist mapping conditions to display
actions. Each condition may be either a regular expression matching a
buffer name or a function that takes two arguments: a buffer name and
the @var{action} argument passed to @code{display-buffer}. If the
name of the buffer passed to @code{display-buffer} either matches a
regular expression in this alist or the function specified by a
the @var{action} argument passed to @code{display-buffer}. If either
the name of the buffer passed to @code{display-buffer} matches a
regular expression in this alist, or the function specified by a
condition returns non-@code{nil}, then @code{display-buffer} uses the
corresponding display action to display the buffer.
@end defopt
@ -2519,8 +2518,7 @@ and @code{nil} if they fail.
This function tries to display @var{buffer} in the selected window.
It fails if the selected window is a minibuffer window or is dedicated
to another buffer (@pxref{Dedicated Windows}). It also fails if
@var{alist} has a non-@code{nil} @code{inhibit-same-window} entry
(@pxref{Buffer Display Action Alists}).
@var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
@end defun
@defun display-buffer-reuse-window buffer alist
@ -2530,15 +2528,13 @@ is already displaying it.
If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
the selected window is not eligible for reuse. The set of frames to
search for a window already displaying @var{buffer} can be specified
with the help of a @code{reusable-frames} action alist entry
(@pxref{Buffer Display Action Alists}). If @var{alist} contains no
@code{reusable-frames} entry, this function searches just the selected
frame.
with the help of the @code{reusable-frames} action alist entry. If
@var{alist} contains no @code{reusable-frames} entry, this function
searches just the selected frame.
If this function chooses a window on another frame, it makes that
frame visible and, unless @var{alist} contains an
@code{inhibit-switch-frame} entry (@pxref{Buffer Display Action
Alists}), raises that frame if necessary.
@code{inhibit-switch-frame} entry, raises that frame if necessary.
@end defun
@defun display-buffer-reuse-mode-window buffer alist
@ -2553,8 +2549,8 @@ whose mode derives from one of the modes specified thusly.
The behavior is also controlled by @var{alist} entries for
@code{inhibit-same-window}, @code{reusable-frames} and
@code{inhibit-switch-frame} (@pxref{Buffer Display Action Alists}) as
is done in the function @code{display-buffer-reuse-window}.
@code{inhibit-switch-frame}, like @code{display-buffer-reuse-window}
does.
@end defun
@defun display-buffer-pop-up-window buffer alist
@ -2565,27 +2561,25 @@ It actually performs the split by calling the function specified by
Options}).
The size of the new window can be adjusted by supplying
@code{window-height} and @code{window-width} entries in @var{alist}
(@pxref{Buffer Display Action Alists}). If @var{alist} contains a
@code{preserve-size} entry, Emacs will also try to preserve the size
of the new window during future resize operations (@pxref{Preserving
Window Sizes}).
@code{window-height} and @code{window-width} entries in @var{alist}.
If @var{alist} contains a @code{preserve-size} entry, Emacs will also
try to preserve the size of the new window during future resize
operations (@pxref{Preserving Window Sizes}).
This function fails if no window can be split. More often than not
This function fails if no window can be split. More often than not,
this happens because no window is large enough to allow splitting.
Setting @code{split-height-threshold} or @code{split-width-threshold}
(@pxref{Choosing Window Options}) to lower values may help in this
regard. Spliting also fails when the selected frame has an
@code{unsplittable} frame parameter; @pxref{Buffer Parameters}.
to lower values may help in this regard. Spliting also fails when the
selected frame has an @code{unsplittable} frame parameter;
@pxref{Buffer Parameters}.
@end defun
@defun display-buffer-in-previous-window buffer alist
This function tries to display @var{buffer} in a window previously
showing it. If @var{alist} has a non-@code{nil}
This function tries to display @var{buffer} in a window where it was
previously displayed. If @var{alist} has a non-@code{nil}
@code{inhibit-same-window} entry, the selected window is not eligible
for reuse. If @var{alist} contains a @code{reusable-frames} entry,
its value determines which frames to search for a suitable window
(@pxref{Buffer Display Action Alists}).
its value determines which frames to search for a suitable window.
If @var{alist} has a @code{previous-window} entry and the window
specified by that entry is live and not dedicated to another buffer,
@ -2596,7 +2590,7 @@ before.
@defun display-buffer-use-some-window buffer alist
This function tries to display @var{buffer} by choosing an existing
window and displaying the buffer in that window. It can fail if all
windows are dedicated to another buffer (@pxref{Dedicated Windows}).
windows are dedicated to other buffers (@pxref{Dedicated Windows}).
@end defun
@defun display-buffer-below-selected buffer alist
@ -2605,13 +2599,13 @@ selected window. If there is a window below the selected one and that
window already displays @var{buffer}, it reuses that window.
If there is no such window, this function tries to create a new window
by splitting the selected one and display @var{buffer} there. It will
by splitting the selected one, and displays @var{buffer} there. It will
also try to adjust that window's size provided @var{alist} contains a
suitable @code{window-height} or @code{window-width} entry, see above.
If splitting the selected window fails and there is a non-dedicated
window below the selected one showing some other buffer, it tries to
use that window for showing @var{buffer}.
window below the selected one showing some other buffer, this function
tries to use that window for showing @var{buffer}.
@end defun
@defun display-buffer-at-bottom buffer alist
@ -2634,19 +2628,19 @@ the newly created frame's parameters.
@defun display-buffer-in-child-frame buffer alist
This function tries to display @var{buffer} in a child frame
(@pxref{Child Frames}) of the selected frame, either reusing an existing
child frame or by making a new one. If @var{alist} has a non-@code{nil}
@code{child-frame-parameters} entry, the corresponding value is an alist
of frame parameters to give the new frame. A @code{parent-frame}
parameter specifying the selected frame is provided by default. If the
child frame should be or become the child of another frame, a
corresponding entry must be added to @var{alist}.
(@pxref{Child Frames}) of the selected frame, either reusing an
existing child frame or by making a new one. If @var{alist} has a
non-@code{nil} @code{child-frame-parameters} entry, the corresponding
value is an alist of frame parameters to give the new frame. A
@code{parent-frame} parameter specifying the selected frame is
provided by default. If the child frame should become the child of
another frame, a corresponding entry must be added to @var{alist}.
The appearance of child frames is largely dependent on the parameters
provided via @var{alist}. It is advisable to use at least ratios to
specify the size (@pxref{Size Parameters}) and the position
(@pxref{Position Parameters}) of the child frame and to add a
@code{keep-ratio} parameter (@pxref{Frame Interaction Parameters}) in
(@pxref{Position Parameters}) of the child frame, and to add a
@code{keep-ratio} parameter (@pxref{Frame Interaction Parameters}), in
order to make sure that the child frame remains visible. For other
parameters that should be considered see @ref{Child Frames}.
@end defun
@ -2658,8 +2652,7 @@ frame).
If this function chooses a window on another frame, it makes that
frame visible and, unless @var{alist} contains an
@code{inhibit-switch-frame} entry (@pxref{Buffer Display Action
Alists}), raises that frame if necessary.
@code{inhibit-switch-frame} entry, raises that frame if necessary.
If @var{alist} has a non-@code{nil} @code{frame-predicate} entry, its
value is a function taking one argument (a frame), returning
@ -2690,7 +2683,7 @@ non-@code{nil} @code{allow-no-window} entry, it is also able to handle
a @code{nil} return value.
@end defun
Two action functions are described in their proper
Two other action functions are described in their proper
sections---@code{display-buffer-in-side-window} (@pxref{Displaying
Buffers in Side Windows}) and @code{display-buffer-in-atom-window}
(@pxref{Atomic Windows}).
@ -2710,18 +2703,19 @@ and passes that entire list on to any action function it calls.
By design, action functions are free in their interpretation of
action alist entries. In fact, some entries like
@code{allow-no-window} or @code{previous-window} have a meaning only
for one or a few action functions and are ignored by the rest. Other
for one or a few action functions, and are ignored by the rest. Other
entries, like @code{inhibit-same-window} or @code{window-parameters},
are supposed to be respected by most action functions including those
are supposed to be respected by most action functions, including those
provided by application programs and external packages.
In the previous subsection we have described in detail how
individual action functions interpret the action alist entries they
care about. Here we give a reference list of all known action alist
entries according to their symbols, together with their values and
action functions that recognize them. Throughout this list, the terms
``buffer'' will refer to the buffer @code{display-buffer} is supposed
to display and ``value'' to the entry's value.
action functions (@pxref{Buffer Display Action Functions}) that
recognize them. Throughout this list, the terms ``buffer'' will refer
to the buffer @code{display-buffer} is supposed to display, and
``value'' refers to the entry's value.
@table @code
@vindex inhibit-same-window@r{, a buffer display action alist entry}
@ -2733,25 +2727,23 @@ must not be used for displaying the buffer. All action functions that
@vindex previous-window@r{, a buffer display action alist entry}
@item previous-window
The value must specify a window that may have displayed the buffer
previously. @code{display-buffer-in-previous-window} (@pxref{Buffer
Display Action Functions}) will give preference to such a window
provided it is still live and not dedicated to another buffer.
previously. @code{display-buffer-in-previous-window} will give
preference to such a window provided it is still live and not
dedicated to another buffer.
@vindex mode@r{, a buffer display action alist entry}
@item mode
The value is either a major mode or a list of major modes.
@code{display-buffer-reuse-mode-window} (@pxref{Buffer Display Action
Functions}) may reuse a window whenever the value specified by this
entry matches the major mode of that window's buffer. Other action
functions ignore such entries.
@code{display-buffer-reuse-mode-window} may reuse a window whenever
the value specified by this entry matches the major mode of that
window's buffer. Other action functions ignore such entries.
@vindex frame-predicate@r{, a buffer display action alist entry}
@item frame-predicate
The value must be a function taking one argument (a frame), supposed
to return non-@code{nil} if that frame is a candidate for displaying
the buffer. This entry is used by
@code{display-buffer-use-some-frame} (@pxref{Buffer Display Action
Functions}).
@code{display-buffer-use-some-frame}.
@vindex reusable-frames@r{, a buffer display action alist entry}
@item reusable-frames
@ -2777,9 +2769,9 @@ Note that the meaning of @code{nil} differs slightly from that of the
@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
Ordering}).
A major client of this is @code{display-buffer-reuse-window}
(@pxref{Buffer Display Action Functions}) but all other action
functions that try to reuse a window are affected as well.
A major client of this is @code{display-buffer-reuse-window}, but all
other action functions that try to reuse a window are affected as
well.
@vindex inhibit-switch-frame@r{, a buffer display action alist entry}
@item inhibit-switch-frame
@ -2787,9 +2779,9 @@ A non-@code{nil} value prevents another frame from being raised or
selected, if the window chosen by @code{display-buffer} is displayed
there. Primarily affected by this are
@code{display-buffer-use-some-frame} and
@code{display-buffer-reuse-window} (@pxref{Buffer Display Action
Functions}). @code{display-buffer-pop-up-frame} should be affected as
well but there is no guarantee that the window manager will comply.
@code{display-buffer-reuse-window}.
@code{display-buffer-pop-up-frame} should be affected as well, but
there is no guarantee that the window manager will comply.
@vindex window-parameters@r{, a buffer display action alist entry}
@item window-parameters
@ -2800,7 +2792,7 @@ entry.
@vindex window-height@r{, a buffer display action alist entry}
@item window-height
The value specifies whether and how to adjust the height of the chosen
window and can be provided as follows:
window, and can have the following values:
@itemize @bullet
@item
@ -2825,8 +2817,8 @@ All action functions that choose a window should process this entry.
@vindex window-width@r{, a buffer display action alist entry}
@item window-width
This entry is similar to the @code{window-height} entry described
before but can be used to adjust the chosen window's width instead.
The value can be one of the following:
before, but used to adjust the chosen window's width instead. The
value can be one of the following:
@itemize @bullet
@item
@ -2852,28 +2844,26 @@ If non-@code{nil} such an entry tells Emacs to preserve the size of
the window chosen (@pxref{Preserving Window Sizes}). The value should
be either @code{(t . nil)} to preserve the width of the window,
@code{(nil . t)} to preserve its height or @code{(t . t)} to preserve
both, its width and its height. All action functions that choose a
both its width and its height. All action functions that choose a
window should process this entry.
@vindex pop-up-frame-parameters@r{, a buffer display action alist entry}
@item pop-up-frame-parameters
The value specifies an alist of frame parameters to give a new frame,
if one is created. @code{display-buffer-pop-up-frame} (@pxref{Buffer
Display Action Functions}) is its one and only addressee.
if one is created. @code{display-buffer-pop-up-frame} is its one and
only addressee.
@vindex parent-frame@r{, a buffer display action alist entry}
@item parent-frame
The value specifies the parent frame to be used when the buffer is
displayed on a child frame. This entry is used by
@code{display-buffer-in-child-frame} (@pxref{Buffer Display Action
Functions}) only.
displayed on a child frame. This entry is used only by
@code{display-buffer-in-child-frame}.
@vindex child-frame-parameters@r{, a buffer display action alist entry}
@item child-frame-parameters
The value specifies an alist of frame parameters used when the buffer
is displayed on a child frame. This entry is used by
@code{display-buffer-in-child-frame} (@pxref{Buffer Display Action
Functions}) only.
The value specifies an alist of frame parameters to use when the buffer
is displayed on a child frame. This entry is used only by
@code{display-buffer-in-child-frame}.
@vindex side@r{, a buffer display action alist entry}
@item side
@ -2889,27 +2879,25 @@ Windows}).
@vindex slot@r{, a buffer display action alist entry}
@item slot
If non-@code{nil}, the value specifies the slot of the side window
supposed to display the buffer. This entry is used by
@code{display-buffer-in-side-window} only (@pxref{Displaying Buffers
in Side Windows}).
supposed to display the buffer. This entry is used only by
@code{display-buffer-in-side-window}.
@vindex window@r{, a buffer display action alist entry}
@item window
The value specifies a window that is in some way related to the window
chosen by @code{display-buffer}. This entry is currently used by
@code{display-buffer-in-atom-window} to indicate the window on whose
side the new window shall be created (@pxref{Atomic Windows}).
side the new window shall be created.
@vindex allow-no-window@r{, a buffer display action alist entry}
@item allow-no-window
If the value is non-@code{nil}, @code{display-buffer} does not
necessarily have to display the buffer and the caller is prepared to
accept that. This entry is not intended for user customizations since
there is no guarantee that an arbitrary caller of
accept that. This entry is not intended for user customizations,
since there is no guarantee that an arbitrary caller of
@code{display-buffer} will be able to handle the case that no window
will display the buffer. @code{display-buffer-no-window}
(@pxref{Buffer Display Action Functions}) is the only action function
that cares about this entry.
will display the buffer. @code{display-buffer-no-window} is the only
action function that cares about this entry.
@end table
@ -2937,16 +2925,16 @@ user may specify directly in @code{display-buffer-alist} etc.
This variable specifies a function for splitting a window, in order to
make a new window for displaying a buffer. It is used by the
@code{display-buffer-pop-up-window} action function to actually split
the window (@pxref{Buffer Display Action Functions}).
the window.
The value must be a function that takes one argument, a window, and
return either a new window (which will be used to display the desired
returns either a new window (which will be used to display the desired
buffer) or @code{nil} (which means the splitting failed). The default
value is @code{split-window-sensibly}, which is documented next.
@end defopt
@defun split-window-sensibly &optional window
This function tries to split @var{window}, and return the newly created
This function tries to split @var{window} and return the newly created
window. If @var{window} cannot be split, it returns @code{nil}. If
@var{window} is omitted or @code{nil}, it defaults to the selected
window.
@ -2957,7 +2945,7 @@ placing the new window below, subject to the restriction imposed by
@code{split-height-threshold} (see below), in addition to any other
restrictions. If that fails, it tries to split by placing the new
window to the right, subject to @code{split-width-threshold} (see
below). If that fails, and the window is the only window on its
below). If that also fails, and the window is the only window on its
frame, this function again tries to split and place the new window
below, disregarding @code{split-height-threshold}. If this fails as
well, this function gives up and returns @code{nil}.
@ -2981,7 +2969,7 @@ that means not to split this way.
@defopt even-window-sizes
This variable, if non-@code{nil}, causes @code{display-buffer} to even
window sizes whenever it reuses an existing window and that window is
window sizes whenever it reuses an existing window, and that window is
adjacent to the selected one.
If its value is @code{width-only}, sizes are evened only if the reused
@ -3016,8 +3004,7 @@ directly in @code{display-buffer-alist} etc.
@defopt pop-up-frame-function
This variable specifies a function for creating a new frame, in order
to make a new window for displaying a buffer. It is used by the
@code{display-buffer-pop-up-frame} action function (@pxref{Buffer
Display Action Functions}).
@code{display-buffer-pop-up-frame} action function.
The value should be a function that takes no arguments and returns a
frame, or @code{nil} if no frame could be created. The default value
@ -3032,9 +3019,8 @@ Parameters}), which is used by the function specified by
@code{nil}.
This option is provided for backward compatibility only. Note, that
when @code{display-buffer-pop-up-frame} (@pxref{Buffer Display Action
Functions}) calls the function specified by
@code{pop-up-frame-function}, it prepends the value of all
when @code{display-buffer-pop-up-frame} calls the function specified
by @code{pop-up-frame-function}, it prepends the value of all
@code{pop-up-frame-parameters} action alist entries to
@code{pop-up-frame-alist} so that the values specified by the action
alist entry effectively override any corresponding values of
@ -3111,6 +3097,7 @@ specifying the action function @code{display-buffer-same-window}.
@subsection Precedence of Action Functions
@cindex precedence of buffer display action functions
@cindex execution order of buffer display action functions
@cindex buffer display action functions, precedence
From the past subsections we already know that @code{display-buffer}
must be supplied with a number of display actions (@pxref{Choosing
@ -3132,7 +3119,7 @@ Consider the following form:
@noindent
Evaluating this form in the buffer @file{*scratch*} of an uncustomized
Emacs session will usually fail to reuse a window that shows
@file{*foo*} already but succeed in popping up a new window.
@file{*foo*} already, but succeed in popping up a new window.
Evaluating the same form again will now not cause any visible
changes---@code{display-buffer} reused the window already showing
@file{*foo*} because that action was applicable and had the highest
@ -3157,13 +3144,13 @@ already shown @file{*foo*} previously and was therefore chosen instead
of some other window.
So far we have only observed the default behavior in an uncustomized
Emacs session. To see how this behavior can be customized let's
Emacs session. To see how this behavior can be customized, let's
consider the option @code{display-buffer-base-action}. It provides a
very coarse customization which conceptually affects the display of
@emph{any} buffer. It can be used to supplement the actions supplied
by @code{display-buffer-fallback-action} by reordering them or by
adding actions that are not present there but fit more closely the
user's editing practice. It can be, however, also used to change the
user's editing practice. However, it can also be used to change the
default behavior in a more profound way.
Let's consider a user who, as a rule, prefers to display buffers on
@ -3179,7 +3166,7 @@ another frame. Such a user might provide the following customization:
@end example
@noindent
This setting will cause@code{display-buffer} to first try to find a
This setting will cause @code{display-buffer} to first try to find a
window showing the buffer on a visible or iconified frame and, if no
such frame exists, pop up a new frame. You can observe this behavior
on a graphical system by typing @w{@kbd{C-x 1}} in the window showing
@ -3191,8 +3178,8 @@ the new frame (usually raising the frame and giving it focus too).
Only if creating a new frame fails, @code{display-buffer} will
apply the actions supplied by @code{display-buffer-fallback-action}
which means to again try to reuse a window, pop up a new window and so
on. A trivial way to make frame creation fail is supplied by the
which means to again try reusing a window, popping up a new window and
so on. A trivial way to make frame creation fail is supplied by the
following form:
@example
@ -3213,7 +3200,7 @@ tried there anyway. However, that would fail because due to the
precedence of @code{display-buffer-base-action} over
@code{display-buffer-fallback-action}, at that time
@code{display-buffer-pop-up-frame} would have already won the race.
In fact
In fact, this:
@example
@group
@ -3231,13 +3218,13 @@ which is probably not what our user wants.
default behavior of @code{display-buffer}. Let us now see how
@emph{applications} can change the course of @code{display-buffer}.
The canonical way to do that is to use the @var{action} argument of
@code{display-buffer} or a function that calls it like, for example,
@code{display-buffer} or a function that calls it, like, for example,
@code{pop-to-buffer} (@pxref{Switching Buffers}).
Suppose an application wants to display @file{*foo*} preferably
below the selected window (to immediately attract the attention of the
user to the new window) or, if that fails, in a window at the bottom
of the frame. It could do that with a call like
of the frame. It could do that with a call like this:
@example
@group
@ -3250,8 +3237,8 @@ of the frame. It could do that with a call like
@noindent
In order to see how this new, modified form works, delete any frame
showing @file{*foo*}, type @w{@kbd{C-x 1}} followed by @w{@kbd{C-x 2}} in the
window showing @file{*scratch*} and subsequently evaluate that form.
@code{display-buffer} should split the upper window and show
window showing @file{*scratch*}, and subsequently evaluate that form.
@code{display-buffer} should split the upper window, and show
@file{*foo*} in the new window. Alternatively, if after @w{@kbd{C-x 2}}
you had typed @w{@kbd{C-x o}}, @code{display-buffer} would have split the
window at the bottom instead.
@ -3269,7 +3256,7 @@ by the @var{action} argument try to reuse such a window first.
By setting the @var{action} argument, an application effectively
overrules any customization of @code{display-buffer-base-action}. Our
user can now either accept the choice of the application or redouble
user can now either accept the choice of the application, or redouble
by customizing the option @code{display-buffer-alist} as follows:
@example
@ -3320,9 +3307,9 @@ preferred way regardless of whether the display is also guided by an
We can, however, reasonably conclude that customizing
@code{display-buffer-alist} differs from customizing
@code{display-buffer-base-action} in two major aspects: It is stronger
@code{display-buffer-base-action} in two major aspects: it is stronger
because it overrides the @var{action} argument of
@code{display-buffer}. And it allows to explicitly specify the
@code{display-buffer}, and it allows to explicitly specify the
affected buffers. In fact, displaying other buffers is not affected
in any way by a customization for @file{*foo*}. For example,
@ -3382,7 +3369,7 @@ explaining who added this and the subsequent elements) is:
@end example
@noindent
Note that among the internal functions listed here
Note that among the internal functions listed here,
@code{display-buffer--maybe-same-window} is effectively ignored while
@code{display-buffer--maybe-pop-up-frame-or-window} actually runs
@code{display-buffer-pop-up-window}.
@ -3398,7 +3385,7 @@ The action alist passed in each function call is:
@noindent
which shows that we have used the second specification of
@code{display-buffer-alist} above overriding the specification
@code{display-buffer-alist} above, overriding the specification
supplied by @code{display-buffer-base-action}. Suppose our user had
written that as
@ -3432,7 +3419,7 @@ regard, the application would have to specify an appropriate
@noindent
This last example shows that while the precedence order of action
functions is fixed as described in @ref{Choosing Window}, an action
functions is fixed, as described in @ref{Choosing Window}, an action
alist entry specified by a display action ranked lower in that order
can affect the execution of a higher ranked display action.
@ -3468,13 +3455,13 @@ layouts.
back on a split & delete windows metaphor is not a good idea either.
Buffer display functions give Lisp programs and users a framework to
reconcile their different needs; no comparable framework exists for
splitting and deleting windows. They also allow to at least partially
restore the layout of a frame when removing a buffer from it later
(@pxref{Quitting Windows}).
splitting and deleting windows. Buffer display functions also allow
to at least partially restore the layout of a frame when removing a
buffer from it later (@pxref{Quitting Windows}).
Below we will give a number of guidelines to redeem the frustration
mentioned above and thus to avoid that buffers literally get lost in
between the windows of a frame.
mentioned above and thus to avoid literally losing buffers in-between
the windows of a frame.
@table @asis
@item Write display actions without stress
@ -3499,7 +3486,7 @@ also the last example of the preceding subsection.
@end example
@noindent
on the other hand specifies one action function and an empty action
on the other hand, specifies one action function and an empty action
alist. To combine the effects of the above two specifications one
would write the form
@ -3588,7 +3575,7 @@ Options}). This was one major reason for redesigning
@code{display-buffer}---to provide a clear framework specifying what
users and applications should be allowed to do.
Lisp Programs must be prepared that a user's customizations may
Lisp programs must be prepared that user customizations may
cause buffers to get displayed in an unexpected way. They should
never assume in their subsequent behavior, that the buffer has been
shown precisely the way they asked for in the @var{action} argument of
@ -3597,11 +3584,11 @@ shown precisely the way they asked for in the @var{action} argument of
Users should not pose too many and too severe restrictions on how
arbitrary buffers get displayed. Otherwise, they will risk to lose
the characteristics of showing a buffer for a certain purpose.
Suppose an lisp program has been written to compare different versions
Suppose a Lisp program has been written to compare different versions
of a buffer in two windows side-by-side. If the customization of
@code{display-buffer-alist} prescribes that any such buffer should be
always shown in or below the selected window, the lisp program will
have a hard time to set up the desired window configuration via
always shown in or below the selected window, the program will have a
hard time to set up the desired window configuration via
@code{display-buffer}.
To specify a preference for showing an arbitrary buffer, users
@ -3611,7 +3598,7 @@ in the previous subsection. @code{display-buffer-alist} should be
reserved for displaying specific buffers in a specific way.
@item Consider reusing a window that already shows the buffer
Generally, it's always a good idea for users and lisp program
Generally, it's always a good idea for users and Lisp
programmers to be prepared for the case that a window already shows
the buffer in question and to reuse that window. In the preceding
subsection we have shown that failing to do so properly may cause
@ -3655,19 +3642,19 @@ configurations.
To produce a window configuration displaying multiple buffers (or
different views of one and the same buffer) in one and the same
display cycle, lisp program programmers will unavoidably have to write
display cycle, Lisp programmers will unavoidably have to write
their own action functions. A few tricks listed below might help in
this regard.
@itemize @bullet
@item
Making windows atomic (@pxref{Atomic Windows}) avoids that an
existing window composition gets broken when popping up a new window.
Making windows atomic (@pxref{Atomic Windows}) avoids breaking an
existing window composition when popping up a new window.
The new window will pop up outside the composition instead.
@item
Temporarily dedicating windows to their buffers (@pxref{Dedicated
Windows}) avoids that a window gets used for displaying a different
Windows}) avoids using a window for displaying a different
buffer. A non-dedicated window will be used instead.
@item
@ -3679,8 +3666,8 @@ the same combination can be shrunk instead, though.
@item
Side windows (@pxref{Side Windows}) can be used for displaying
specific buffers always in a window at the same position of a frame.
This permits to group buffers that do not compete for being shown at
the same time on a frame and show any such buffer in the same window
This permits grouping buffers that do not compete for being shown at
the same time on a frame and showing any such buffer in the same window
without disrupting the display of other buffers.
@item