Doc changes related to displaying buffers and quitting windows.

* window.el (switch-to-visible-buffer)
(switch-to-buffer-preserve-window-point): Fix doc-strings.

* windows.texi (Switching Buffers): Document option
switch-to-buffer-preserve-window-point.
(Display Action Functions): Document window-height and
window-width alist entries.
(Display Action Functions): Document
display-buffer-below-selected and
display-buffer-in-previous-window.
(Quitting Windows): Document quit-restore-window.  Rewrite
section.
(Window Configurations): In window-state-get mention that
argument window must be valid.
(Window Parameters): Document quit-restore window parameter
(Bug#12158).

5 files changed, 215 insertions, 59 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index da3cc91a675..fa996191ac4 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,19 @@
+2012-11-03  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Switching Buffers): Document option
+        switch-to-buffer-preserve-window-point.
+        (Display Action Functions): Document window-height and
+        window-width alist entries.
+        (Display Action Functions): Document
+        display-buffer-below-selected and
+        display-buffer-in-previous-window.
+        (Quitting Windows): Document quit-restore-window.  Rewrite
+        section.
+        (Window Configurations): In window-state-get mention that
+        argument window must be valid.
+        (Window Parameters): Document quit-restore window parameter
+        (Bug#12158).
+
 2012-10-31  Glenn Morris  <rgm@gnu.org>
 
         * control.texi (Catch and Throw): Add xref to cl.texi.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index d0e149eb165..2fbb59cd1dd 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1550,6 +1550,26 @@ normally tries to display the buffer in some other window, by invoking
 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.
 
@@ -1775,9 +1795,51 @@ It actually performs the split by calling the function specified in
 @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
@@ -1786,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
 
+@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
 
@@ -2086,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.
 
-   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
-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
 
-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.
@@ -2135,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
-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}
@@ -2146,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.
 
-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
 
 
@@ -3123,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
-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
@@ -3267,10 +3380,28 @@ from.  It is installed by @code{window-state-get} (@pxref{Window
 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};
diff --git a/etc/NEWS b/etc/NEWS
index 31a4909f8d9..9ece829217f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -818,7 +818,7 @@ to work out which code is doing something.
 recursive invocations.
 
 ** Window changes
-
++++
 *** The functions get-lru-window, get-mru-window and get-largest-window
 now accept a third argument to avoid choosing the selected window.
 
@@ -831,9 +831,12 @@ reused.
 
 *** New function `fit-frame-to-buffer' and new options
 `fit-frame-to-buffer' and `fit-frame-to-buffer-bottom-margin'.
-
++++
+*** New option switch-to-buffer-preserve-window-point to restore a
+window's point when switching buffers.
++++
 *** New display action functions `display-buffer-below-selected',
-`display-buffer-at-bottom' and `display-buffer-in-previous-window'.
+and `display-buffer-in-previous-window'.
 
 *** New display action alist entry `inhibit-switch-frame', if non-nil,
 tells display action functions to avoid changing which frame is
@@ -841,10 +844,10 @@ selected.
 
 *** New display action alist entry `pop-up-frame-parameters', if
 non-nil, specifies frame parameters to give any newly-created frame.
-
++++
 *** New display action alist entry `previous-window', if non-nil,
 specifies window to reuse in `display-buffer-in-previous-window'.
-
++++
 *** New display action alist entries `window-height' and `window-width'
 to specify size of new window created by `display-buffer'.
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index ab73a61d9e6..1b560651abb 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+2012-11-03  Martin Rudalics  <rudalics@gmx.at>
+
+        * window.el (switch-to-visible-buffer)
+        (switch-to-buffer-preserve-window-point): Fix doc-strings.
+
 2012-11-01  Stephen Berman  <stephen.berman@gmx.net>
 
         * play/gomoku.el (gomoku-display-statistics): Update mode line
diff --git a/lisp/window.el b/lisp/window.el
index 10f75d44d69..be6ddf8ab9e 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -3091,10 +3091,11 @@ before was current this also makes BUFFER the current buffer."
   "If non-nil, allow switching to an already visible buffer.
 If this variable is non-nil, `switch-to-prev-buffer' and
 `switch-to-next-buffer' may switch to an already visible buffer
-provided the buffer was shown in the argument window before.  If
-this variable is nil, `switch-to-prev-buffer' and
-`switch-to-next-buffer' always try to avoid switching to a buffer
-that is already visible in another window on the same frame."
+provided the buffer was shown before in the window specified as
+argument to those functions.  If this variable is nil,
+`switch-to-prev-buffer' and `switch-to-next-buffer' always try to
+avoid switching to a buffer that is already visible in another
+window on the same frame."
   :type 'boolean
   :version "24.1"
   :group 'windows)
@@ -5855,8 +5856,8 @@ window on any visible or iconified frame.  If this is t, it
 unconditionally tries to display the buffer at its previous
 position in the selected window.
 
-This variable is ignored if the the buffer is already displayed
-in the selected window or never appeared in it before, or if
+This variable is ignored if the buffer is already displayed in
+the selected window or never appeared in it before, or if
 `switch-to-buffer' calls `pop-to-buffer' to display the buffer."
   :type '(choice
           (const :tag "Never" nil)