Doc changes related to displaying buffers and quitting windows.

[bpt/emacs.git] / doc / lispref / windows.texi

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 75d4a9b..2fbb59c 100644 (file)
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3,8 +3,7 @@
 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.

-@setfilename ../../info/windows
-@node Windows, Frames, Buffers, Top
+@node Windows

 @chapter Windows
 
 This chapter describes the functions and variables related to Emacs
 @chapter Windows
 
 This chapter describes the functions and variables related to Emacs


@@ -77,30 +76,35 @@ within the area of the frame.  When a window is created, resized, or
 deleted, the change in window space is taken from or given to the
 adjacent windows, so that the total area of the frame is unchanged.
 
 deleted, the change in window space is taken from or given to the
 adjacent windows, so that the total area of the frame is unchanged.
 

-@cindex live windows
-@cindex internal windows
-  A @dfn{live window} is one that is actually displaying a buffer in a
-frame.  Such a window can be @dfn{deleted}, i.e. removed from the
-frame (@pxref{Deleting Windows}); then it is no longer live, but the
-Lisp object representing it might be still referenced from other Lisp
-objects.  A deleted window may be brought back to life by restoring a
-saved window configuration (@pxref{Window Configurations}).
-

 @defun windowp object
 This function returns @code{t} if @var{object} is a window (whether or
 @defun windowp object
 This function returns @code{t} if @var{object} is a window (whether or

-not it is live).  Otherwise, it returns @code{nil}.
+not it displays a buffer).  Otherwise, it returns @code{nil}.

 @end defun
 
 @end defun
 

+@cindex live windows
+A @dfn{live window} is one that is actually displaying a buffer in a
+frame.
+

 @defun window-live-p object
 This function returns @code{t} if @var{object} is a live window and
 @code{nil} otherwise.  A live window is one that displays a buffer.
 @end defun
 
 @defun window-live-p object
 This function returns @code{t} if @var{object} is a live window and
 @code{nil} otherwise.  A live window is one that displays a buffer.
 @end defun
 

-  The windows in each frame are organized into a @dfn{window tree}.
-@xref{Windows and Frames}.  The leaf nodes of each window tree are
-live windows---the ones actually displaying buffers.  The internal
-nodes of the window tree are internal windows, which are not live.
-You can distinguish internal windows from deleted windows with
+@cindex internal windows
+The windows in each frame are organized into a @dfn{window tree}.
+@xref{Windows and Frames}.  The leaf nodes of each window tree are live
+windows---the ones actually displaying buffers.  The internal nodes of
+the window tree are @dfn{internal windows}, which are not live.
+
+@cindex valid windows
+   A @dfn{valid window} is one that is either live or internal.  A valid
+window can be @dfn{deleted}, i.e. removed from its frame
+(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
+object representing it might be still referenced from other Lisp
+objects.  A deleted window may be made valid again by restoring a saved
+window configuration (@pxref{Window Configurations}).
+
+   You can distinguish valid windows from deleted windows with

 @code{window-valid-p}.
 
 @defun window-valid-p object
 @code{window-valid-p}.
 
 @defun window-valid-p object


@@ -1130,16 +1134,15 @@ are the opposite of what they are in those other functions.
 
 @defun select-window window &optional norecord
 This function makes @var{window} the selected window, as well as the
 
 @defun select-window window &optional norecord
 This function makes @var{window} the selected window, as well as the

-window selected within its frame (@pxref{Basic Windows}).
-@var{window} must be a live window.  Unless @var{window} already is the
-selected window, its buffer becomes the current buffer (@pxref{Buffers
-and Windows}).  The return value is @var{window}.
+window selected within its frame (@pxref{Basic Windows}).  @var{window}
+must be a live window.  This function makes also @var{window}'s buffer
+current (@pxref{Buffers and Windows}).  The return value is
+@var{window}.

 
 

-By default, this function also moves @var{window}'s selected buffer to
-the front of the buffer list (@pxref{The Buffer List}), and makes
-@var{window} the most recently selected window.  However, if the
-optional argument @var{norecord} is non-@code{nil}, these additional
-actions are omitted.
+By default, this function also moves @var{window}'s buffer to the front
+of the buffer list (@pxref{The Buffer List}), and makes @var{window} the
+most recently selected window.  However, if the optional argument
+@var{norecord} is non-@code{nil}, these additional actions are omitted.

 @end defun
 
 @cindex most recently selected windows
 @end defun
 
 @cindex most recently selected windows


@@ -1319,31 +1322,37 @@ meaning as for @code{next-window}.
 criterion, without selecting it:
 
 @cindex least recently used window
 criterion, without selecting it:
 
 @cindex least recently used window

-@defun get-lru-window &optional all-frames dedicated
+@defun get-lru-window &optional all-frames dedicated not-selected

 This function returns a live window which is heuristically the ``least
 recently used'' window.  The optional argument @var{all-frames} has
 the same meaning as in @code{next-window}.
 
 If any full-width windows are present, only those windows are
 This function returns a live window which is heuristically the ``least
 recently used'' window.  The optional argument @var{all-frames} has
 the same meaning as in @code{next-window}.
 
 If any full-width windows are present, only those windows are

-considered.  The selected window is never returned, unless it is the
-only candidate.  A minibuffer window is never a candidate.  A
-dedicated window (@pxref{Dedicated Windows}) is never a candidate
-unless the optional argument @var{dedicated} is non-@code{nil}.
+considered.  A minibuffer window is never a candidate.  A dedicated
+window (@pxref{Dedicated Windows}) is never a candidate unless the
+optional argument @var{dedicated} is non-@code{nil}.  The selected
+window is never returned, unless it is the only candidate.  However, if
+the optional argument @var{not-selected} is non-@code{nil}, this
+function returns @code{nil} in that case.

 @end defun
 
 @cindex largest window
 @end defun
 
 @cindex largest window

-@defun get-largest-window &optional all-frames dedicated
+@defun get-largest-window &optional all-frames dedicated not-selected

 This function returns the window with the largest area (height times
 This function returns the window with the largest area (height times

-width).  A minibuffer window is never a candidate.  A dedicated window
+width).  The optional argument @var{all-frames} specifies the windows to
+search, and has the same meaning as in @code{next-window}.
+
+A minibuffer window is never a candidate.  A dedicated window

 (@pxref{Dedicated Windows}) is never a candidate unless the optional
 (@pxref{Dedicated Windows}) is never a candidate unless the optional

-argument @var{dedicated} is non-@code{nil}.
+argument @var{dedicated} is non-@code{nil}.  The selected window is not
+a candidate if the optional argument @var{not-selected} is
+non-@code{nil}.  If the optional argument @var{not-selected} is
+non-@code{nil} and the selected window is the only candidate, this
+function returns @code{nil}.

 
 If there are two candidate windows of the same size, this function
 prefers the one that comes first in the cyclic ordering of windows,
 starting from the selected window.
 
 If there are two candidate windows of the same size, this function
 prefers the one that comes first in the cyclic ordering of windows,
 starting from the selected window.

-
-The optional argument @var{all-frames} specifies the windows to
-search, and has the same meaning as in @code{next-window}.

 @end defun
 
 @cindex window that satisfies a predicate
 @end defun
 
 @cindex window that satisfies a predicate


@@ -1361,6 +1370,26 @@ windows to search, and have the same meanings as in
 @code{next-window}.
 @end defun
 
 @code{next-window}.
 @end defun
 

+@cindex window in direction
+@defun window-in-direction direction &optional window ignore
+This function returns the nearest window in direction @var{direction} as
+seen from the position of @code{window-point} in window @var{window}.
+The argument @var{direction} must be one of @code{above}, @code{below},
+@code{left} or @code{right}.  The optional argument @var{window} must
+denote a live window and defaults to the selected one.
+
+This function does not return a window whose @code{no-other-window}
+parameter is non-@code{nil}.  If the nearest window's
+@code{no-other-window} parameter is non-@code{nil}, this function tries
+to find another window in the indicated direction whose
+@code{no-other-window} parameter is @code{nil}.  If the optional
+argument @var{ignore} is non-@code{nil}, a window may be returned even
+if its @code{no-other-window} parameter is non-@code{nil}.
+
+If it doesn't find a suitable window, this function returns @code{nil}.
+@end defun
+
+

 @node Buffers and Windows
 @section Buffers and Windows
 @cindex examining windows
 @node Buffers and Windows
 @section Buffers and Windows
 @cindex examining windows


@@ -1400,7 +1429,7 @@ When writing an application, you should normally use the higher-level
 functions described in @ref{Switching Buffers}, instead of calling
 @code{set-window-buffer} directly.
 
 functions described in @ref{Switching Buffers}, instead of calling
 @code{set-window-buffer} directly.
 

-This function runs @code{window-scroll-functions}, followed by
+This runs @code{window-scroll-functions}, followed by

 @code{window-configuration-change-hook}.  @xref{Window Hooks}.
 @end defun
 
 @code{window-configuration-change-hook}.  @xref{Window Hooks}.
 @end defun
 


@@ -1494,12 +1523,10 @@ to make a buffer current to modify it in Lisp, use
 @code{set-buffer}.  @xref{Current Buffer}.
 
 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
 @code{set-buffer}.  @xref{Current Buffer}.
 
 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window

-This function displays @var{buffer-or-name} in the selected window,
-and makes it the current buffer.  (In contrast, @code{set-buffer}
-makes the buffer current but does not display it; @pxref{Current
-Buffer}).  It is often used interactively (as the binding of @kbd{C-x
-b}), as well as in Lisp programs.  The return value is the buffer
-switched to.
+This command attempts to display @var{buffer-or-name} in the selected
+window, and makes it the current buffer.  It is often used
+interactively (as the binding of @kbd{C-x b}), as well as in Lisp
+programs.  The return value is the buffer switched to.

 
 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
 returned by @code{other-buffer} (@pxref{The Buffer List}).  If
 
 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
 returned by @code{other-buffer} (@pxref{The Buffer List}).  If


@@ -1508,20 +1535,41 @@ buffer, this function creates a new buffer with that name; the new
 buffer's major mode is determined by the variable @code{major-mode}
 (@pxref{Major Modes}).
 
 buffer's major mode is determined by the variable @code{major-mode}
 (@pxref{Major Modes}).
 

-Normally the specified buffer is put at the front of the buffer
+Normally, the specified buffer is put at the front of the buffer

 list---both the global buffer list and the selected frame's buffer
 list (@pxref{The Buffer List}).  However, this is not done if the
 optional argument @var{norecord} is non-@code{nil}.
 
 list---both the global buffer list and the selected frame's buffer
 list (@pxref{The Buffer List}).  However, this is not done if the
 optional argument @var{norecord} is non-@code{nil}.
 

-If this function is unable to display the buffer in the selected
-window---usually because the selected window is a minibuffer window or
-is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then
-it normally tries to display the buffer in some other window, in the
-manner of @code{pop-to-buffer} (see below).  However, if the optional
-argument @var{force-same-window} is non-@code{nil}, it signals an error
+Sometimes, @code{switch-to-buffer} may be unable to display the buffer
+in the selected window.  This happens if the selected window is a
+minibuffer window, or if the selected window is strongly dedicated to
+its buffer (@pxref{Dedicated Windows}).  In that case, the command
+normally tries to display the buffer in some other window, by invoking
+@code{pop-to-buffer} (see below).  However, if the optional argument
+@var{force-same-window} is non-@code{nil}, it signals an error

 instead.
 @end deffn
 
 instead.
 @end deffn
 

+By default, @code{switch-to-buffer} sets @code{window-point} of the
+window used to the buffer's position of @code{point}.  This behavior can
+be tuned using the following option.
+
+@defopt switch-to-buffer-preserve-window-point
+If this variable is @code{nil}, @code{switch-to-buffer} displays the
+buffer specified by @var{buffer-or-name} at the position of that
+buffer's @code{point}.  If this variable is @code{already-displayed}, it
+tries to display the buffer at its previous position in the selected
+window, provided the buffer is currently displayed in some other window
+on any visible or iconified frame.  If this variable is @code{t},
+@code{switch-to-buffer} unconditionally tries to display the buffer at
+its previous position in the selected window.
+
+This variable is ignored if the buffer is already displayed in the
+selected window or never appeared in it before, or if
+@code{switch-to-buffer} calls @code{pop-to-buffer} to display the
+buffer.
+@end defopt
+

 The next two functions are similar to @code{switch-to-buffer}, except
 for the described features.
 
 The next two functions are similar to @code{switch-to-buffer}, except
 for the described features.
 


@@ -1634,11 +1682,6 @@ The variable @code{display-buffer-overriding-action}.
 @item
 The user option @code{display-buffer-alist}.
 
 @item
 The user option @code{display-buffer-alist}.
 

-@item
-A special action for handling @code{special-display-buffer-names} and
-@code{special-display-regexps}, if either of those variables is
-non-@code{nil}.  @xref{Choosing Window Options}.
-

 @item
 The @var{action} argument.
 
 @item
 The @var{action} argument.
 


@@ -1730,8 +1773,7 @@ A frame means consider windows on that frame only.
 @end itemize
 
 If @var{alist} contains no @code{reusable-frames} entry, this function
 @end itemize
 
 If @var{alist} contains no @code{reusable-frames} entry, this function

-normally searches just the selected frame; however, if either the
-variable @code{display-buffer-reuse-frames} or the variable
+normally searches just the selected frame; however, if the variable

 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
 current terminal.  @xref{Choosing Window Options}.
 
 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
 current terminal.  @xref{Choosing Window Options}.
 


@@ -1753,9 +1795,51 @@ It actually performs the split by calling the function specified in
 @code{split-window-preferred-function} (@pxref{Choosing Window
 Options}).
 
 @code{split-window-preferred-function} (@pxref{Choosing Window
 Options}).
 

-It can fail if no window splitting can be performed for some reason
-(e.g. if there is just one frame and it has an @code{unsplittable}
-frame parameter; @pxref{Buffer Parameters}).
+The size of the new window can be adjusted by supplying
+@code{window-height} and @code{window-width} entries in @var{alist}.  To
+adjust the window's height, use an entry whose @sc{car} is
+@code{window-height} and whose @sc{cdr} is one of:
+
+@itemize @bullet
+@item
+@code{nil} means to leave the height of the new window alone.
+
+@item
+A number specifies the desired height of the new window.  An integer
+number specifies the number of lines of the window.  A floating point
+number gives the fraction of the window's height with respect to the
+height of the frame's root window.
+
+@item
+If the @sc{cdr} specifies a function, that function is called with one
+argument - the new window.  The function is supposed to adjust the
+height of the window; its return value is ignored.  Suitable functions
+are @code{shrink-window-if-larger-than-buffer} and
+@code{fit-window-to-buffer}, see @ref{Resizing Windows}.
+@end itemize
+
+To adjust the window's width, use an entry whose @sc{car} is
+@code{window-width} and whose @sc{cdr} is one of:
+
+@itemize @bullet
+@item
+@code{nil} means to leave the width of the new window alone.
+
+@item
+A number specifies the desired width of the new window.  An integer
+number specifies the number of columns of the window.  A floating point
+number gives the fraction of the window's width with respect to the
+width of the frame's root window.
+
+@item
+If the @sc{cdr} specifies a function, that function is called with one
+argument - the new window.  The function is supposed to adjust the width
+of the window; its return value is ignored.
+@end itemize
+
+This function can fail if no window splitting can be performed for some
+reason (e.g. if there is just one frame and it has an
+@code{unsplittable} frame parameter; @pxref{Buffer Parameters}).

 @end defun
 
 @defun display-buffer-use-some-window buffer alist
 @end defun
 
 @defun display-buffer-use-some-window buffer alist


@@ -1764,6 +1848,26 @@ window and displaying the buffer in that window.  It can fail if all
 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
 @end defun
 
 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
 @end defun
 

+@defun display-buffer-below-selected buffer alist
+This function tries to display @var{buffer} in a window below the
+selected window.  This means to either split the selected window or
+reuse the window below the selected one.
+@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}
+@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 as with
+@code{display-buffer-reuse-window}.
+
+If @var{alist} has a @code{previous-window} entry, the window
+specified by that entry will override any other window found by the
+methods above, even if that window never showed @var{buffer} before.
+@end defun
+
+

 @node Choosing Window Options
 @section Additional Options for Displaying Buffers
 
 @node Choosing Window Options
 @section Additional Options for Displaying Buffers
 


@@ -1771,14 +1875,6 @@ The behavior of the standard display actions of @code{display-buffer}
 (@pxref{Choosing Window}) can be modified by a variety of user
 options.
 
 (@pxref{Choosing Window}) can be modified by a variety of user
 options.
 

-@defopt display-buffer-reuse-frames
-If the value of this variable is non-@code{nil}, @code{display-buffer}
-may search all frames on the current terminal when looking for a
-window already displaying the specified buffer.  The default is
-@code{nil}.  This variable is consulted by the action function
-@code{display-buffer-reuse-window} (@pxref{Display Action Functions}).
-@end defopt
-

 @defopt pop-up-windows
 If the value of this variable is non-@code{nil}, @code{display-buffer}
 is allowed to split an existing window to make a new window for
 @defopt pop-up-windows
 If the value of this variable is non-@code{nil}, @code{display-buffer}
 is allowed to split an existing window to make a new window for


@@ -1876,91 +1972,6 @@ Parameters}), which is used by the default function in
 @code{nil}.
 @end defopt
 
 @code{nil}.
 @end defopt
 

-@defopt special-display-buffer-names
-A list of buffer names identifying buffers that should be displayed
-specially.  If the name of @var{buffer-or-name} is in this list,
-@code{display-buffer} handles the buffer specially.  By default, special
-display means to give the buffer a dedicated frame.
-
-If an element is a list, instead of a string, then the @sc{car} of that
-list is the buffer name, and the rest of that list says how to create
-the frame.  There are two possibilities for the rest of that list (its
-@sc{cdr}): It can be an alist, specifying frame parameters, or it can
-contain a function and arguments to give to it.  (The function's first
-argument is always the buffer to be displayed; the arguments from the
-list come after that.)
-
-For example:
-
-@example
-(("myfile" (minibuffer) (menu-bar-lines . 0)))
-@end example
-
-@noindent
-specifies to display a buffer named @samp{myfile} in a dedicated frame
-with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
-
-The list of frame parameters can also use the phony frame parameters
-@code{same-frame} and @code{same-window}.  If the specified frame
-parameters include @code{(same-window . @var{value})} and @var{value}
-is non-@code{nil}, that means to display the buffer in the current
-selected window.  Otherwise, if they include @code{(same-frame .
-@var{value})} and @var{value} is non-@code{nil}, that means to display
-the buffer in a new window in the currently selected frame.
-@end defopt
-
-@defopt special-display-regexps
-A list of regular expressions specifying buffers that should be
-displayed specially.  If the buffer's name matches any of the regular
-expressions in this list, @code{display-buffer} handles the buffer
-specially.  By default, special display means to give the buffer a
-dedicated frame.
-
-If an element is a list, instead of a string, then the @sc{car} of the
-list is the regular expression, and the rest of the list says how to
-create the frame.  See @code{special-display-buffer-names} above.
-@end defopt
-
-@defun special-display-p buffer-name
-This function returns non-@code{nil} if displaying a buffer
-named @var{buffer-name} with @code{display-buffer} would
-create a special frame.  The value is @code{t} if it would
-use the default frame parameters, or else the specified list
-of frame parameters.
-@end defun
-
-@defopt special-display-function
-This variable holds the function to call to display a buffer specially.
-It receives the buffer as an argument, and should return the window in
-which it is displayed.  The default value of this variable is
-@code{special-display-popup-frame}, see below.
-@end defopt
-
-@defun special-display-popup-frame buffer &optional args
-This function tries to make @var{buffer} visible in a frame of its own.
-If @var{buffer} is already displayed in some window, it makes that
-window's frame visible and raises it.  Otherwise, it creates a frame
-that is dedicated to @var{buffer}.  The return value is the window used
-to display @var{buffer}.
-
-If @var{args} is an alist, it specifies frame parameters for the new
-frame.  If @var{args} is a list whose @sc{car} is a symbol, then
-@code{(car @var{args})} is a function to actually create and
-set up the frame; it is called with @var{buffer} as first argument, and
-@code{(cdr @var{args})} as additional arguments.
-
-This function always uses an existing window displaying @var{buffer},
-whether or not it is in a frame of its own; but if you set up the above
-variables in your init file, before @var{buffer} was created, then
-presumably the window was previously made by this function.
-@end defun
-
-@defopt special-display-frame-alist
-@anchor{Definition of special-display-frame-alist}
-This variable holds frame parameters for
-@code{special-display-popup-frame} to use when it creates a frame.
-@end defopt
-

 @defopt same-window-buffer-names
 A list of buffer names for buffers that should be displayed in the
 selected window.  If a buffer's name is in this list,
 @defopt same-window-buffer-names
 A list of buffer names for buffers that should be displayed in the
 selected window.  If a buffer's name is in this list,


@@ -1981,19 +1992,6 @@ named @var{buffer-name} with @code{display-buffer} would
 put it in the selected window.
 @end defun
 
 put it in the selected window.
 @end defun
 

-@c Emacs 19 feature
-@defopt display-buffer-function
-This variable is the most flexible way to customize the behavior of
-@code{display-buffer}.  If it is non-@code{nil}, it should be a function
-that @code{display-buffer} calls to do the work.  The function should
-accept two arguments, the first two arguments that @code{display-buffer}
-received.  It should choose or create a window, display the specified
-buffer in it, and then return the window.
-
-This variable takes precedence over all the other options described
-above.
-@end defopt
-

 @node Window History
 @section Window History
 @cindex window history
 @node Window History
 @section Window History
 @cindex window history


@@ -2170,45 +2168,77 @@ function @code{switch-to-prev-buffer} (@pxref{Window History}).
 Finally, you might want to either bury (@pxref{The Buffer List}) or kill
 (@pxref{Killing Buffers}) the window's buffer.
 
 Finally, you might want to either bury (@pxref{The Buffer List}) or kill
 (@pxref{Killing Buffers}) the window's buffer.
 

-   The following function uses information on how the window for
-displaying the buffer was obtained in the first place, thus attempting to
-automate the above decisions for you.
+   The following command uses information on how the window for
+displaying the buffer was obtained in the first place, thus attempting
+to automate the above decisions for you.

 
 @deffn Command quit-window &optional kill window
 This command quits @var{window} and buries its buffer.  The argument
 @var{window} must be a live window and defaults to the selected one.
 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
 
 @deffn Command quit-window &optional kill window
 This command quits @var{window} and buries its buffer.  The argument
 @var{window} must be a live window and defaults to the selected one.
 With prefix argument @var{kill} non-@code{nil}, it kills the buffer

-instead of burying it.
-
-Quitting @var{window} means to proceed as follows: If @var{window} was
-created specially for displaying its current buffer, delete @var{window}
-provided its frame contains at least one other live window.  If
-@var{window} is the only window on its frame and there are other frames
-on the frame's terminal, the value of @var{kill} determines how to
-proceed with the window.  If @var{kill} is @code{nil}, the fate of the
-frame is determined by calling @code{frame-auto-hide-function} (see
-below) with that frame as sole argument.  If @var{kill} is
-non-@code{nil}, the frame is deleted unconditionally.
-
-If @var{window} was reused for displaying its buffer, this command tries
-to display the buffer previously shown in it.  It also tries to restore
-the window start (@pxref{Window Start and End}) and point (@pxref{Window
-Point}) positions of the previously shown buffer.  If, in addition, the
-current buffer was temporarily resized, this command will also try to
-restore the original height of @var{window}.
-
-The three cases described so far require that the buffer shown in
-@var{window} is still the buffer displayed by the last buffer display
-function for this window.  If another buffer has been shown in the
-meantime, or the buffer previously shown no longer exists, this command
-calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some
-other buffer instead.
+instead of burying it.  It calls the function @code{quit-restore-window}
+described next to deal with the window and its buffer.

 @end deffn
 
 @end deffn
 

-The function @code{quit-window} bases its decisions on information
-stored in @var{window}'s @code{quit-restore} window parameter
-(@pxref{Window Parameters}), and resets that parameter to @code{nil}
-after it's done.
+@defun quit-restore-window &optional window bury-or-kill
+This function tries to restore the state of @var{window} that existed
+before its buffer was displayed in it.  The optional argument
+@var{window} must be a live window and defaults to the selected one.
+
+If @var{window} was created specially for displaying its buffer, this
+function deletes @var{window} provided its frame contains at least one
+other live window.  If @var{window} is the only window on its frame and
+there are other frames on the frame's terminal, the value of the
+optional argument @var{bury-or-kill} determines how to proceed with the
+window.  If @var{bury-or-kill} equals @code{kill}, the frame is deleted
+unconditionally.  Otherwise, the fate of the frame is determined by
+calling @code{frame-auto-hide-function} (see below) with that frame as
+sole argument.
+
+Otherwise, this function tries to redisplay the buffer previously shown
+in @var{window}.  It also tries to restore the window start
+(@pxref{Window Start and End}) and point (@pxref{Window Point})
+positions of the previously shown buffer.  If, in addition,
+@var{window}'s buffer was temporarily resized, this function will also
+try to restore the original height of @var{window}.
+
+The cases described so far require that the buffer shown in @var{window}
+is still the buffer displayed by the last buffer display function for
+this window.  If another buffer has been shown in the meantime, or the
+buffer previously shown no longer exists, this function calls
+@code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
+buffer instead.
+
+The optional argument @var{bury-or-kill} specifes how to deal with
+@var{window}'s buffer.  The following values are handled:
+
+@table @code
+@item nil
+This means to not deal with the buffer in any particular way.  As a
+consequence, if @var{window} is not deleted, invoking
+@code{switch-to-prev-buffer} will usually show the buffer again.
+
+@item append
+This means that if @var{window} is not deleted, its buffer is moved to
+the end of @var{window}'s list of previous buffers, so it's less likely
+that a future invocation of @code{switch-to-prev-buffer} will switch to
+it.  Also, it moves the buffer to the end of the frame's buffer list.
+
+@item bury
+This means that if @var{window} is not deleted, its buffer is removed
+from @var{window}'s list of previous buffers.  Also, it moves the buffer
+to the end of the frame's buffer list.  This value provides the most
+reliable remedy to not have @code{switch-to-prev-buffer} switch to this
+buffer again without killing the buffer.
+
+@item kill
+This means to kill @var{window}'s buffer.
+@end table
+
+@code{quit-restore-window} bases its decisions on information stored in
+@var{window}'s @code{quit-restore} window parameter (@pxref{Window
+Parameters}), and resets that parameter to @code{nil} after it's done.
+@end defun

 
 The following option specifies how to deal with a frame containing just
 one window that should be either quit, or whose buffer should be buried.
 
 The following option specifies how to deal with a frame containing just
 one window that should be either quit, or whose buffer should be buried.


@@ -2219,10 +2249,9 @@ frames.  This function is called with one argument---a frame.
 
 The function specified here is called by @code{bury-buffer} (@pxref{The
 Buffer List}) when the selected window is dedicated and shows the buffer
 
 The function specified here is called by @code{bury-buffer} (@pxref{The
 Buffer List}) when the selected window is dedicated and shows the buffer

-that should be buried.  It is also called by @code{quit-window} (see
-above) when the frame of the window that should be quit has been
-specially created for displaying that window's buffer and the buffer
-should be buried.
+to bury.  It is also called by @code{quit-restore-window} (see above)
+when the frame of the window to quit has been specially created for
+displaying that window's buffer and the buffer is not killed.

 
 The default is to call @code{iconify-frame} (@pxref{Visibility of
 Frames}).  Alternatively, you may specify either @code{delete-frame}
 
 The default is to call @code{iconify-frame} (@pxref{Visibility of
 Frames}).  Alternatively, you may specify either @code{delete-frame}


@@ -2230,9 +2259,9 @@ Frames}).  Alternatively, you may specify either @code{delete-frame}
 @code{ignore} to leave the frame unchanged, or any other function that
 can take a frame as its sole argument.
 
 @code{ignore} to leave the frame unchanged, or any other function that
 can take a frame as its sole argument.
 

-Note that the function specified by this option is called if and only if
-there is at least one other frame on the terminal of the frame it's
-supposed to handle, and that frame contains only one live window.
+Note that the function specified by this option is called only if the
+specified frame contains just one live window and there is at least one
+other frame on the same terminal.

 @end defopt
 
 
 @end defopt
 
 


@@ -2277,19 +2306,18 @@ For a nonselected window, this is the value point would have (in that
 window's buffer) if that window were selected.  The default for
 @var{window} is the selected window.
 
 window's buffer) if that window were selected.  The default for
 @var{window} is the selected window.
 

-When @var{window} is the selected window and its buffer is also the
-current buffer, the value returned is the same as point in that buffer.
-Strictly speaking, it would be more correct to return the ``top-level''
-value of point, outside of any @code{save-excursion} forms.  But that
-value is hard to find.
+When @var{window} is the selected window, the value returned is the
+value of point in that window's buffer.  Strictly speaking, it would be
+more correct to return the ``top-level'' value of point, outside of any
+@code{save-excursion} forms.  But that value is hard to find.

 @end defun
 
 @defun set-window-point window position
 This function positions point in @var{window} at position
 @var{position} in @var{window}'s buffer.  It returns @var{position}.
 
 @end defun
 
 @defun set-window-point window position
 This function positions point in @var{window} at position
 @var{position} in @var{window}'s buffer.  It returns @var{position}.
 

-If @var{window} is selected, and its buffer is current,
-this simply does @code{goto-char}.
+If @var{window} is selected, this simply does @code{goto-char} in
+@var{window}'s buffer.

 @end defun
 
 @defvar window-point-insertion-type
 @end defun
 
 @defvar window-point-insertion-type


@@ -3156,42 +3184,21 @@ as @code{save-window-excursion}:
 @end defun
 
 @defmac save-window-excursion forms@dots{}
 @end defun
 
 @defmac save-window-excursion forms@dots{}

-This special form records the window configuration, executes @var{forms}
-in sequence, then restores the earlier window configuration.  The window
-configuration includes, for each window, the value of point and the
-portion of the buffer that is visible.  It also includes the choice of
-selected window.  However, it does not include the value of point in
-the current buffer; use @code{save-excursion} also, if you wish to
-preserve that.
-
-Don't use this construct when @code{save-selected-window} is sufficient.
-
-Exit from @code{save-window-excursion} always triggers execution of
-@code{window-size-change-functions}.  (It doesn't know how to tell
-whether the restored configuration actually differs from the one in
-effect at the end of the @var{forms}.)
-
-The return value is the value of the final form in @var{forms}.
-For example:
-
-@example
-@group
-(split-window)
-     @result{} #<window 25 on control.texi>
-@end group
-@group
-(setq w (selected-window))
-     @result{} #<window 19 on control.texi>
-@end group
-@group
-(save-window-excursion
-  (delete-other-windows w)
-  (switch-to-buffer "foo")
-  'do-something)
-     @result{} do-something
-     ;; @r{The screen is now split again.}
-@end group
-@end example
+This macro records the window configuration of the selected frame,
+executes @var{forms} in sequence, then restores the earlier window
+configuration.  The return value is the value of the final form in
+@var{forms}.
+
+Most Lisp code should not use this macro; @code{save-selected-window}
+is typically sufficient.  In particular, this macro cannot reliably
+prevent the code in @var{forms} from opening new windows, because new
+windows might be opened in other frames (@pxref{Choosing Window}), and
+@code{save-window-excursion} only saves and restores the window
+configuration on the current frame.
+
+Do not use this macro in @code{window-size-change-functions}; exiting
+the macro triggers execution of @code{window-size-change-functions},
+leading to an endless loop.

 @end defmac
 
 @defun window-configuration-p object
 @end defmac
 
 @defun window-configuration-p object


@@ -3229,8 +3236,8 @@ frame into the root window of that very frame only).
 
 @defun window-state-get &optional window writable
 This function returns the state of @var{window} as a Lisp object.  The
 
 @defun window-state-get &optional window writable
 This function returns the state of @var{window} as a Lisp object.  The

-argument @var{window} can be any window and defaults to the root window
-of the selected frame.
+argument @var{window} must be a valid window and defaults to the root
+window of the selected frame.

 
 If the optional argument @var{writable} is non-@code{nil}, this means to
 not use markers for sampling positions like @code{window-point} or
 
 If the optional argument @var{writable} is non-@code{nil}, this means to
 not use markers for sampling positions like @code{window-point} or


@@ -3373,10 +3380,28 @@ from.  It is installed by @code{window-state-get} (@pxref{Window
 Configurations}).
 
 @item @code{quit-restore}
 Configurations}).
 
 @item @code{quit-restore}

-This parameter specifies what to do with a window when the buffer it
-shows is not needed any more.  It is installed by the buffer display
-functions (@pxref{Choosing Window}), and consulted by the function
-@code{quit-window} (@pxref{Quitting Windows}).
+This parameter is installed by the buffer display functions
+(@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
+(@pxref{Quitting Windows}).  It contains four elements:
+
+The first element is one of the symbols @code{window} - meaning that the
+window has been specially created by @code{display-buffer}, @code{frame}
+- a separate frame has been created, @code{same} - the window has
+displayed the same buffer before, or @code{other} - the window showed
+another buffer before.
+
+The second element is either one of the symbols @code{window} or
+@code{frame}, or a list whose elements are the buffer shown in the
+window before, that buffer's window start and window point positions,
+and the window's height at that time.
+
+The third element is the window selected at the time the parameter was
+created.  The function @code{quit-restore-window} tries to reselect that
+window when it deletes the window passed to it as argument.
+
+The fourth element is the buffer whose display caused the creation of
+this parameter.  @code{quit-restore-window} deletes the specified window
+only if it still shows that buffer.

 @end table
 
 There are additional parameters @code{window-atom} and @code{window-side};
 @end table
 
 There are additional parameters @code{window-atom} and @code{window-side};


@@ -3427,11 +3452,11 @@ Creating or deleting windows counts as a size change, and therefore
 causes these functions to be called.  Changing the frame size also
 counts, because it changes the sizes of the existing windows.
 
 causes these functions to be called.  Changing the frame size also
 counts, because it changes the sizes of the existing windows.
 

-It is not a good idea to use @code{save-window-excursion} (@pxref{Window
-Configurations}) in these functions, because that always counts as a
-size change, and it would cause these functions to be called over and
-over.  In most cases, @code{save-selected-window} (@pxref{Selecting
-Windows}) is what you need here.
+You may use @code{save-selected-window} in these functions
+(@pxref{Selecting Windows}).  However, do not use
+@code{save-window-excursion} (@pxref{Window Configurations}); exiting
+that macro counts as a size change, which would cause these functions
+to be called over and over.

 @end defvar
 
 @defvar window-configuration-change-hook
 @end defvar
 
 @defvar window-configuration-change-hook