changeset 98835:4c36d8b3b766

(Choosing Window, Deleting Windows) (Displaying Buffers): Expand documentation of dedicated windows.

--- a/doc/lispref/windows.texi	Sat Oct 18 18:06:19 2008 +0000
+++ b/doc/lispref/windows.texi	Sat Oct 18 18:07:09 2008 +0000
@@ -400,7 +400,9 @@
 space.  If all windows in some frame are showing @var{buffer-or-name}
 (including the case where there is only one window), then the frame
 winds up with a single window showing another buffer chosen with
-@code{other-buffer}.  @xref{The Buffer List}.
+@code{other-buffer}.  @xref{The Buffer List}.  If, however, that window
+is dedicated and there are other frames left, the window's frame is
+deleted.
 
 The argument @var{frame} controls which frames to operate on.  This
 function does not use it in quite the same way as the other functions
@@ -893,12 +895,18 @@
 @end defun
 
 @deffn Command replace-buffer-in-windows buffer-or-name
-This function replaces @var{buffer-or-name} with some other buffer in all
-windows displaying it.  It chooses the other buffer with
+This function replaces @var{buffer-or-name} with some other buffer in
+all windows displaying it.  It chooses the other buffer with
 @code{other-buffer}.  In the usual applications of this function, you
 don't care which other buffer is used; you just want to make sure that
 @var{buffer-or-name} is no longer displayed.
 
+If a window displaying @var{buffer-or-name} is dedicated and the window
+is not the only window on its frame, that window is deleted.  If the
+window is the only window on its frame and there are other frames left,
+the window's frame is deleted too.  If there are no other frames left,
+some other buffer is displayed in that window.
+
 This function returns @code{nil}.
 @end deffn
 
@@ -1178,9 +1186,19 @@
 @cindex dedicated window
 A window can be marked as ``dedicated'' to its buffer.  Then
 @code{display-buffer} will not try to use that window to display any
-other buffer.
-
-@defun window-dedicated-p window
+other buffer.  @code{set-window-buffer} will throw an error when asked
+to display another buffer in it.  Both, @code{get-lru-window} and
+@code{get-largest-window} do not consider dedicated windows as
+candidates when their @var{dedicated} argument is non-@code{nil}.
+
+When @code{delete-windows-on} deletes a dedicated window and that window
+is the only window on its frame, it will delete that frame as well when
+there are other frames left.  @code{replace-buffer-in-windows} deletes
+any dedicated window showing its buffer argument.  When such a window is
+the only window on its frame, that frame is deleted too when there are
+other frames left.
+
+@defun window-dedicated-p &optional window
 This function returns non-@code{nil} if @var{window} is marked as
 dedicated; otherwise @code{nil}.
 @end defun