Describe frame-auto-hide-function and related issues.

* buffers.texi (The Buffer List): Describe how bury-buffer deals
with the selected window.
* windows.texi (Buffers and Windows): Reformulate text on how
replace-buffer-in-windows deals with a window.
(Quitting Windows): Describe how quit-window deals with a
standalone frame.  Describe new option frame-auto-hide-function.

3 files changed, 76 insertions, 33 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index adc15cfc373..f822b4bebdf 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,12 @@
+2011-10-09  Martin Rudalics  <rudalics@gmx.at>
+
+        * buffers.texi (The Buffer List): Describe how bury-buffer deals
+        with the selected window.
+        * windows.texi (Buffers and Windows): Reformulate text on how
+        replace-buffer-in-windows deals with a window.
+        (Quitting Windows): Describe how quit-window deals with a
+        standalone frame.  Describe new option frame-auto-hide-function.
+
 2011-10-08  Glenn Morris  <rgm@gnu.org>
 
         * symbols.texi (Other Plists): Markup fix.  (Bug#9702)
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index ce1a8b0fb4e..816d0f9faa8 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -884,23 +884,28 @@ This buffer therefore becomes the least desirable candidate for
 @code{other-buffer} to return.  The argument can be either a buffer
 itself or the name of one.
 
-@code{bury-buffer} operates on each frame's @code{buffer-list} parameter
-as well as the fundamental buffer list; therefore, the buffer that you
-bury will come last in the value of @code{(buffer-list @var{frame})} and
-in the value of @code{(buffer-list)}.
-
-If @var{buffer-or-name} is @code{nil} or omitted, this means to bury
-the current buffer.  In addition, if the buffer is displayed in the
-selected window, this switches to some other buffer (obtained using
-@code{other-buffer}) in the selected window.  @xref{Switching
-Buffers}.  But if the selected window is dedicated to its buffer, it
-deletes that window if there are other windows left on its frame.
-Otherwise, if the selected window is the only window on its frame, it
-iconifies that frame.  If @var{buffer-or-name} is displayed in some
+This functions operates on each frame's @code{buffer-list} parameter as
+well as the fundamental buffer list; therefore, the buffer that you bury
+will come last in the value of @code{(buffer-list @var{frame})} and in
+the value of @code{(buffer-list)}.  In addition, it also puts the buffer
+at the end of the list of buffer of the selected window (@pxref{Window
+History}) provided it is shown in that window.
+
+If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
+current buffer.  In addition, if the current buffer is displayed in the
+selected window, this makes sure that the window is either deleted or
+another buffer is shown in it.  More precisely, if the window is
+dedicated (@pxref{Dedicated Windows}) and there are other windows on its
+frame, the window is deleted.  If the window is both dedicated and the
+only window on its frame's terminal, the function specified by
+@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal
+with the window.  If the window is not dedicated to its buffer, it calls
+@code{switch-to-prev-buffer} (@pxref{Window History}) to show another
+buffer in that window.  If @var{buffer-or-name} is displayed in some
 other window, it remains displayed there.
 
 To replace a buffer in all the windows that display it, use
-@code{replace-buffer-in-windows}.  @xref{Buffers and Windows}.
+@code{replace-buffer-in-windows}, @xref{Buffers and Windows}.
 @end deffn
 
 @deffn Command unbury-buffer
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index bffea19210c..41ccbaafd49 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2076,16 +2076,17 @@ This command replaces @var{buffer-or-name} with some other buffer, in
 all windows displaying it.  For each such window, it choose another
 buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
 
-@var{buffer-or-name} may be a buffer, or the name of an existing
-buffer; it defaults to the current buffer.
+The argument @var{buffer-or-name} may be a buffer, or the name of an
+existing buffer; it defaults to the current buffer.
 
 If a window displaying @var{buffer-or-name} is dedicated
-(@pxref{Dedicated Windows}), has never displayed any other buffers and
-is not the only window on its frame, that window is deleted.  If that
-window is the only window on its frame and there are other frames on the
-frame's terminal, that frame is deleted too; otherwise, the buffer
-provided by the function @code{switch-to-prev-buffer} (@pxref{Window
-History}) is displayed instead.
+(@pxref{Dedicated Windows}) and is not the only window on its frame,
+that window is deleted.  If that window is the only window on its frame
+and there are other frames on the frame's terminal, that frame is dealt
+with by the function spcecified by @code{frame-auto-hide-function}
+(@pxref{Quitting Windows}).  Otherwise, the buffer provided by the
+function @code{switch-to-prev-buffer} (@pxref{Window History}) is
+displayed in the window instead.
 @end deffn
 
 
@@ -2784,14 +2785,14 @@ non-@code{nil} value.
 @section Quitting Windows
 
 When you want to get rid of a window used for displaying a buffer you
-can use the function @code{delete-window} (@pxref{Deleting Windows}) to
-remove that window from its frame.  If the buffer has been shown on a
-separate frame, you might want to call @code{delete-frame}
-(@pxref{Deleting Frames}) instead.  If, on the other hand, a window has
-been reused for displaying the buffer, you might prefer showing the
-buffer previously shown in that window by calling the function
-@code{switch-to-prev-buffer} (@pxref{Window History}).  Finally, you
-might want to either bury (@pxref{The Buffer List}) or kill
+can call @code{delete-window} or @code{delete-windows-on}
+(@pxref{Deleting Windows}) to remove that window from its frame.  If the
+buffer is shown on a separate frame, you might want to call
+@code{delete-frame} (@pxref{Deleting Frames}) instead.  If, on the other
+hand, a window has been reused for displaying the buffer, you might
+prefer showing the buffer previously shown in that window by calling the
+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
@@ -2807,9 +2808,12 @@ 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 other frames still
-exist, delete the frame together with @var{window}.  If, however, there
-are no other frames left, display some other buffer in @var{window}.
+@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
@@ -2831,6 +2835,31 @@ stored in @var{window}'s @code{quit-restore} window parameter
 (@pxref{Window Parameters}) and resets that parameter to @code{nil}
 after it's done.
 
+The following option specifies how to deal with a frame containing just
+one window that shall be either quit or whose buffer shall be buried.
+
+@defopt frame-auto-hide-function
+The function specified by this option is called to automatically hide
+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 shall be buried.  It is also called by @code{quit-window} (see
+above) when the frame of the window that shall be quit has been
+specially created for displaying that window's buffer and the buffer
+shall be buried.
+
+The default is to call @code{iconify-frame} (@pxref{Visibility of
+Frames}).  Alternatively, you may either specify @code{delete-frame}
+(@pxref{Deleting Frames}) to remove the frame from its display,
+@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's at least one other frame on the terminal of the frame it's
+supposed to handle and that frame contains only one live window.
+@end defopt
+
 
 @node Window Point
 @section Windows and Point