[Emacs-diffs] /srv/bzr/emacs/trunk r106038: Describe frame-auto-hide-function and related issues.

[martin rudalics]

------------------------------------------------------------
revno: 106038
committer: martin rudalics <address@hidden>
branch nick: trunk
timestamp: Sun 2011-10-09 14:26:29 +0200
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/buffers.texi
  doc/lispref/windows.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-10-08 20:53:06 +0000
+++ b/doc/lispref/ChangeLog     2011-10-09 12:26:29 +0000
@@ -1,3 +1,12 @@
+2011-10-09  Martin Rudalics  <address@hidden>
+
+       * 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  <address@hidden>
 
        * symbols.texi (Other Plists): Markup fix.  (Bug#9702)

=== modified file 'doc/lispref/buffers.texi'
--- a/doc/lispref/buffers.texi  2011-09-24 22:49:32 +0000
+++ b/doc/lispref/buffers.texi  2011-10-09 12:26:29 +0000
@@ -884,23 +884,28 @@
 @code{other-buffer} to return.  The argument can be either a buffer
 itself or the name of one.
 
address@hidden 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)}.
+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 buffer is displayed in the
-selected window, this switches to some other buffer (obtained using
address@hidden) 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
+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
address@hidden (@pxref{Quitting Windows}) will deal
+with the window.  If the window is not dedicated to its buffer, it calls
address@hidden (@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
address@hidden  @xref{Buffers and Windows}.
address@hidden, @xref{Buffers and Windows}.
 @end deffn
 
 @deffn Command unbury-buffer

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2011-10-01 22:16:24 +0000
+++ b/doc/lispref/windows.texi  2011-10-09 12:26:29 +0000
@@ -2076,16 +2076,17 @@
 all windows displaying it.  For each such window, it choose another
 buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
 
address@hidden 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 @@
 @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
address@hidden (@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
address@hidden (@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 @@
 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
address@hidden 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}.
address@hidden 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
address@hidden, 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 @@
 (@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.
+
address@hidden 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,
address@hidden 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.
address@hidden defopt
+
 
 @node Window Point
 @section Windows and Point

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-10-08 19:17:34 +0000
+++ b/etc/NEWS  2011-10-09 12:26:29 +0000
@@ -1106,6 +1106,11 @@
 The behavior of `quit-window' has been changed in order to restore the
 state before the last buffer display operation in that window.
 
++++
+*** The new option `frame-auto-hide-function' lets you choose between
+iconfying or deleting a frame when burying a buffer shown in a dedicated
+frame or quitting a window showing a buffer in a frame of its own.
+
 ** Completion
 
 *** New variable completion-extra-properties used to specify extra properties