Correct and reword recent changes to window.texi.

* windows.texi (Basic Windows): Fix typo.
(Windows and Frames): Fix example.  Move description of
window-in-direction here.
(Recombining Windows): Fix example.
(Buffers and Windows): Fix description of
replace-buffer-in-windows.
(Switching Buffers): Reword.
(Display Action Functions): Minor adjustments.
(Choosing Window Options): Minor fixes.
(Window History): Minor rewording.
(Dedicated Windows): Correct and reword part describing how
dedicatedness affects functions removing buffers or windows.
* buffers.texi (The Buffer List): Fix description of
bury-buffer.

3 files changed, 165 insertions, 139 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 23da5634889..adb52dc7f2b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,20 @@
+2012-11-23  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Basic Windows): Fix typo.
+        (Windows and Frames): Fix example.  Move description of
+        window-in-direction here.
+        (Recombining Windows): Fix example.
+        (Buffers and Windows): Fix description of
+        replace-buffer-in-windows.
+        (Switching Buffers): Reword.
+        (Display Action Functions): Minor adjustments.
+        (Choosing Window Options): Minor fixes.
+        (Window History): Minor rewording.
+        (Dedicated Windows): Correct and reword part describing how
+        dedicatedness affects functions removing buffers or windows.
+        * buffers.texi (The Buffer List): Fix description of
+        bury-buffer.
+
 2012-11-23  Chong Yidong  <cyd@gnu.org>
 
         * modes.texi (%-Constructs): Fix statement about mode construct
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 4a556895de7..6462788b34e 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -886,7 +886,7 @@ 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.
 
-This functions operates on each frame's @code{buffer-list} parameter as
+This function 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
@@ -896,15 +896,15 @@ 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.
+another buffer is shown in it.  More precisely, if the selected window
+is dedicated (@pxref{Dedicated Windows}) and there are other windows on
+its frame, the window is deleted.  If it is the only window on its frame
+and that frame is not the only frame on its terminal, the frame is
+``dismissed'' by calling the function specified by
+@code{frame-auto-hide-function} (@pxref{Quitting Windows}).  Otherwise,
+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}.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 46b31ef0d9f..224c4736c92 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -51,9 +51,9 @@ is displayed in windows.
 @section Basic Concepts of Emacs Windows
 @cindex window
 
-A @dfn{window} is a area of the screen that is used to display a
-buffer (@pxref{Buffers}).  In Emacs Lisp, windows are represented by a
-special Lisp object type.
+A @dfn{window} is an area of the screen that is used to display a buffer
+(@pxref{Buffers}).  In Emacs Lisp, windows are represented by a special
+Lisp object type.
 
 @cindex multiple windows
   Windows are grouped into frames (@pxref{Frames}).  Each frame
@@ -247,12 +247,12 @@ following example:
 @end smallexample
 
 @noindent
-The root window of this frame is an internal window, @code{W1}.  Its
+The root window of this frame is an internal window, @var{W1}.  Its
 child windows form a horizontal combination, consisting of the live
-window @code{W2} and the internal window @code{W3}.  The child windows
-of @code{W3} form a vertical combination, consisting of the live
-windows @code{W4} and @code{W5}.  Hence, the live windows in this
-window tree are @code{W2} @code{W4}, and @code{W5}.
+window @var{W2} and the internal window @var{W3}.  The child windows
+of @var{W3} form a vertical combination, consisting of the live
+windows @var{W4} and @var{W5}.  Hence, the live windows in this
+window tree are @var{W2} @var{W4}, and @var{W5}.
 
   The following functions can be used to retrieve a child window of an
 internal window, and the siblings of a child window.
@@ -308,8 +308,8 @@ The functions @code{window-next-sibling} and
 and previous window, respectively, in the cyclic ordering of windows
 (@pxref{Cyclic Window Ordering}).
 
-  You can use the following functions to find the first live window on
-a frame, and to retrieve the entire window tree of a frame:
+  You can use the following functions to find the first live window on a
+frame and the window nearest to a given window.
 
 @defun frame-first-window &optional frame-or-window
 This function returns the live window at the upper left corner of the
@@ -318,9 +318,32 @@ frame specified by @var{frame-or-window}.  The argument
 to the selected frame.  If @var{frame-or-window} specifies a window,
 this function returns the first window on that window's frame.  Under
 the assumption that the frame from our canonical example is selected
-@code{(frame-first-window)} returns @code{W2}.
+@code{(frame-first-window)} returns @var{W2}.
 @end defun
 
+@cindex window in direction
+@defun window-in-direction direction &optional window ignore
+This function returns the nearest live 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} (@pxref{Window Parameters}).  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
+
+The following function allows to retrieve the entire window tree of a
+frame:
+
 @defun window-tree &optional frame
 This function returns a list representing the window tree for frame
 @var{frame}.  If @var{frame} is omitted or @code{nil}, it defaults to
@@ -925,9 +948,9 @@ are the opposite of what they are in those other functions.
 @node Recombining Windows
 @section Recombining Windows
 
-When deleting the last sibling of a window @code{W}, its parent window
-is deleted too, with @code{W} replacing it in the window tree.  This
-means that @code{W} must be recombined with its parent's siblings to
+When deleting the last sibling of a window @var{W}, its parent window
+is deleted too, with @var{W} replacing it in the window tree.  This
+means that @var{W} must be recombined with its parent's siblings to
 form a new window combination (@pxref{Windows and Frames}).  In some
 occasions, deleting a live window may even entail the deletion of two
 internal windows.
@@ -952,20 +975,20 @@ internal windows.
 @end smallexample
 
 @noindent
-Deleting @code{W5} in this configuration normally causes the deletion of
-@code{W3} and @code{W4}.  The remaining live windows @code{W2},
-@code{W6} and @code{W7} are recombined to form a new horizontal
-combination with parent @code{W1}.
+Deleting @var{W5} in this configuration normally causes the deletion of
+@var{W3} and @var{W4}.  The remaining live windows @var{W2},
+@var{W6} and @var{W7} are recombined to form a new horizontal
+combination with parent @var{W1}.
 
    Sometimes, however, it makes sense to not delete a parent window like
-@code{W4}.  In particular, a parent window should not be removed when it
+@var{W4}.  In particular, a parent window should not be removed when it
 was used to preserve a combination embedded in a combination of the same
 type.  Such embeddings make sense to assure that when you split a window
 and subsequently delete the new window, Emacs reestablishes the layout
 of the associated frame as it existed before the splitting.
 
-   Consider a scenario starting with two live windows @code{W2} and
-@code{W3} and their parent @code{W1}.
+   Consider a scenario starting with two live windows @var{W2} and
+@var{W3} and their parent @var{W1}.
 
 @smallexample
 @group
@@ -988,7 +1011,7 @@ of the associated frame as it existed before the splitting.
 @end smallexample
 
 @noindent
-Split @code{W2} to make a new window @code{W4} as follows.
+Split @var{W2} to make a new window @var{W4} as follows.
 
 @smallexample
 @group
@@ -1013,8 +1036,8 @@ Split @code{W2} to make a new window @code{W4} as follows.
 @noindent
 Now, when enlarging a window vertically, Emacs tries to obtain the
 corresponding space from its lower sibling, provided such a window
-exists.  In our scenario, enlarging @code{W4} will steal space from
-@code{W3}.
+exists.  In our scenario, enlarging @var{W4} will steal space from
+@var{W3}.
 
 @smallexample
 @group
@@ -1037,8 +1060,8 @@ exists.  In our scenario, enlarging @code{W4} will steal space from
 @end smallexample
 
 @noindent
-Deleting @code{W4} will now give its entire space to @code{W2},
-including the space earlier stolen from @code{W3}.
+Deleting @var{W4} will now give its entire space to @var{W2},
+including the space earlier stolen from @var{W3}.
 
 @smallexample
 @group
@@ -1061,12 +1084,12 @@ including the space earlier stolen from @code{W3}.
 @end smallexample
 
 @noindent
-This can be counterintutive, in particular if @code{W4} were used for
+This can be counterintutive, in particular if @var{W4} were used for
 displaying a buffer only temporarily (@pxref{Temporary Displays}), and
 you want to continue working with the initial layout.
 
 The behavior can be fixed by making a new parent window when splitting
-@code{W2}.  The variable described next allows to do that.
+@var{W2}.  The variable described next allows to do that.
 
 @defopt window-combination-limit
 This variable controls whether splitting a window shall make a new
@@ -1108,7 +1131,7 @@ internal window.  This affects how the window tree is rearranged when
 the child windows are deleted (see below).
 @end defopt
 
-  If @code{window-combination-limit} is @code{t}, splitting @code{W2} in
+  If @code{window-combination-limit} is @code{t}, splitting @var{W2} in
 the initial configuration of our scenario would have produced this:
 
 @smallexample
@@ -1132,12 +1155,12 @@ the initial configuration of our scenario would have produced this:
 @end smallexample
 
 @noindent
-A new internal window @code{W5} has been created; its children are
-@code{W2} and the new live window @code{W4}.  Now, @code{W2} is the only
-sibling of @code{W4}, so enlarging @code{W4} will try to shrink
-@code{W2}, leaving @code{W3} unaffected.  Observe that @code{W5}
+A new internal window @var{W5} has been created; its children are
+@var{W2} and the new live window @var{W4}.  Now, @var{W2} is the only
+sibling of @var{W4}, so enlarging @var{W4} will try to shrink
+@var{W2}, leaving @var{W3} unaffected.  Observe that @var{W5}
 represents a vertical combination of two windows embedded in the
-vertical combination @code{W1}.
+vertical combination @var{W1}.
 
 @cindex window combination limit
 @defun set-window-combination-limit window limit
@@ -1162,9 +1185,9 @@ windows of @var{window} are never automatically recombined with its
 siblings.
 
 If, in the configuration shown at the beginning of this section, the
-combination limit of @code{W4} (the parent window of @code{W6} and
-@code{W7}) is @code{t}, deleting @code{W5} will not implicitly delete
-@code{W4} too.
+combination limit of @var{W4} (the parent window of @var{W6} and
+@var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete
+@var{W4} too.
 @end defun
 
 Alternatively, the problems sketched above can be avoided by always
@@ -1215,7 +1238,7 @@ the following frame layout.
 
 @noindent
 If @code{window-combination-resize} is @code{nil}, splitting window
-@code{W3} leaves the size of @code{W2} unchanged:
+@var{W3} leaves the size of @var{W2} unchanged:
 
 @smallexample
 @group
@@ -1238,7 +1261,7 @@ If @code{window-combination-resize} is @code{nil}, splitting window
 @end smallexample
 
 @noindent
-If @code{window-combination-resize} is @code{t}, splitting @code{W3}
+If @code{window-combination-resize} is @code{t}, splitting @var{W3}
 instead leaves all three live windows with approximately the same
 height:
 
@@ -1263,7 +1286,7 @@ height:
 @end smallexample
 
 @noindent
-Deleting any of the live windows @code{W2}, @code{W3} or @code{W4} will
+Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will
 distribute its space proportionally among the two remaining live
 windows.
 
@@ -1510,25 +1533,6 @@ windows to search, and have the same meanings as in
 @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
@@ -1631,28 +1635,30 @@ behave exactly like in @code{get-buffer-window}.
 
 @deffn Command replace-buffer-in-windows &optional buffer-or-name
 This command replaces @var{buffer-or-name} with some other buffer, in
-all windows displaying it.  @var{buffer-or-name} should be a buffer,
-or the name of an existing buffer; if omitted or @code{nil}, it
-defaults to the current buffer.
+all windows displaying it.  @var{buffer-or-name} should be a buffer, or
+the name of an existing buffer; if omitted or @code{nil}, it defaults to
+the current buffer.
 
 The replacement buffer in each window is chosen via
 @code{switch-to-prev-buffer} (@pxref{Window History}).  Any dedicated
-window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated
-Windows}), unless it is the only window on its frame---if it is the
-only window, and that frame is not the only frame on its terminal, the
-frame is ``dismissed'' by calling the function specified by
-@code{frame-auto-hide-function} (@pxref{Quitting Windows}).  If the
-dedicated window is the only window on the only frame on its terminal,
-the buffer is replaced anyway.
+window displaying @var{buffer-or-name} is deleted if possible
+(@pxref{Dedicated Windows}).  If such a window is the only window on its
+frame and there are other frames on the same terminal, the frame is
+deleted as well.  If the dedicated window is the only window on the only
+frame on its terminal, the buffer is replaced anyway.
 @end deffn
 
+
 @node Switching Buffers
 @section Switching to a Buffer in a Window
 @cindex switching to a buffer
 @cindex displaying a buffer
 
-  This section describes high-level functions for switching to a
-specified buffer in some window.
+This section describes high-level functions for switching to a specified
+buffer in some window.  In general, ``switching to a buffer'' means to
+(1) show the buffer in some window, (2) make that window the selected
+window (and its frame the selected frame), and (3) make the buffer the
+current buffer.
 
   Do @emph{not} use these functions to make a buffer temporarily
 current just so a Lisp program can access or modify it.  They have
@@ -1664,9 +1670,9 @@ to make a buffer current to modify it in Lisp, use
 
 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
 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.
+window and make 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
@@ -1690,9 +1696,8 @@ 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.
+By default, @code{switch-to-buffer} shows the buffer at its 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
@@ -1710,13 +1715,13 @@ selected window or never appeared in it before, or if
 buffer.
 @end defopt
 
-The next two functions are similar to @code{switch-to-buffer}, except
-for the described features.
+The next two commands are similar to @code{switch-to-buffer}, except for
+the described features.
 
 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
-This function makes the buffer specified by @var{buffer-or-name}
-current and displays it in some window other than the selected window.
-It uses the function @code{pop-to-buffer} internally (see below).
+This function displays the buffer specified by @var{buffer-or-name} in
+some window other than the selected window.  It uses the function
+@code{pop-to-buffer} internally (see below).
 
 If the selected window already displays the specified buffer, it
 continues to do so, but another window is nonetheless found to display
@@ -1727,9 +1732,9 @@ meanings as in @code{switch-to-buffer}.
 @end deffn
 
 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
-This function makes the buffer specified by @var{buffer-or-name}
-current and displays it, usually in a new frame.  It uses the function
-@code{pop-to-buffer} (see below).
+This function displays the buffer specified by @var{buffer-or-name} in a
+new frame.  It uses the function @code{pop-to-buffer} internally (see
+below).
 
 If the specified buffer is already displayed in another window, in any
 frame on the current terminal, this switches to that window instead of
@@ -1987,8 +1992,8 @@ 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}).
+reason (e.g. if the selected frame has an @code{unsplittable} frame
+parameter; @pxref{Buffer Parameters}).
 @end defun
 
 @defun display-buffer-below-selected buffer alist
@@ -2035,14 +2040,15 @@ example.
 
 @noindent
 Evaluating the form above will cause @code{display-buffer} to proceed as
-follows: If `*foo*' already appears on a visible or iconified frame, it
-will reuse its window.  Otherwise, it will try to pop up a new window
-or, if that is impossible, a new frame.  If all these steps fail, it
-will proceed using whatever @code{display-buffer-base-action} and
+follows: If a buffer called *foo* already appears on a visible or
+iconified frame, it will reuse its window.  Otherwise, it will try to
+pop up a new window or, if that is impossible, a new frame and show the
+buffer there.  If all these steps fail, it will proceed using whatever
+@code{display-buffer-base-action} and
 @code{display-buffer-fallback-action} prescribe.
 
    Furthermore, @code{display-buffer} will try to adjust a reused window
-(provided `*foo*' was put by @code{display-buffer} there before) or a
+(provided *foo* was put by @code{display-buffer} there before) or a
 popped-up window as follows: If the window is part of a vertical
 combination, it will set its height to ten lines.  Note that if, instead
 of the number ``10'', we specified the function
@@ -2077,10 +2083,10 @@ and @code{split-width-threshold} (@pxref{Choosing Window Options}).
 @end example
 
 @noindent
-Evaluating this form will cause @code{display-buffer} to first try
-reusing a window showing @code{*foo*} on the selected frame.
-If no such window exists, it will try to split the selected window or,
-if that is impossible, use the window below the selected window.
+This form will have @code{display-buffer} first try reusing a window
+that shows *foo* on the selected frame.  If there's no such window, it
+will try to split the selected window or, if that is impossible, use the
+window below the selected window.
 
    If there's no window below the selected one, or the window below the
 selected one is dedicated to its buffer, @code{display-buffer} will
@@ -2119,8 +2125,8 @@ make a new window for displaying a buffer.  It is used by the
 the window (@pxref{Display Action Functions}).
 
 The default value is @code{split-window-sensibly}, which is documented
-below.  The value must be a function that takes one argument, a
-window, and return either a new window (which is used to display the
+below.  The value must be a function that takes one argument, a window,
+and return either a new window (which will be used to display the
 desired buffer) or @code{nil} (which means the splitting failed).
 @end defopt
 
@@ -2198,15 +2204,15 @@ Parameters}), which is used by the default function in
 @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,
-@code{display-buffer} handles the buffer by switching to it in the
-selected window.
+@code{display-buffer} handles the buffer by showing it in the selected
+window.
 @end defopt
 
 @defopt same-window-regexps
 A list of regular expressions that specify buffers that should be
 displayed in the selected window.  If the buffer's name matches any of
 the regular expressions in this list, @code{display-buffer} handles the
-buffer by switching to it in the selected window.
+buffer by showing it in the selected window.
 @end defopt
 
 @defun same-window-p buffer-name
@@ -2219,22 +2225,23 @@ put it in the selected window.
 @section Window History
 @cindex window history
 
-Each window remembers the buffers it has previously displayed, and the order
-in which these buffers were removed from it.  This history is used,
-for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and
-Windows}).  This list is automatically maintained by Emacs, but you can
-use the following functions to explicitly inspect or alter it:
+Each window remembers in a list the buffers it has previously displayed,
+and the order in which these buffers were removed from it.  This history
+is used, for example, by @code{replace-buffer-in-windows}
+(@pxref{Buffers and Windows}).  The list is automatically maintained by
+Emacs, but you can use the following functions to explicitly inspect or
+alter it:
 
 @defun window-prev-buffers &optional window
 This function returns a list specifying the previous contents of
-@var{window}, which should be a live window and defaults to the
-selected window.
+@var{window}.  The optional argument @var{window} should be a live
+window and defaults to the selected one.
 
 Each list element has the form @code{(@var{buffer} @var{window-start}
 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
 the window, @var{window-start} is the window start position when that
 buffer was last shown, and @var{window-pos} is the point position when
-that buffer was last shown.
+that buffer was last shown in @var{window}.
 
 The list is ordered so that earlier elements correspond to more
 recently-shown buffers, and the first element usually corresponds to the
@@ -2331,29 +2338,31 @@ Functions for displaying a buffer can be told to not use specific
 windows by marking these windows as @dfn{dedicated} to their buffers.
 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
 window for displaying another buffer in it.  @code{get-lru-window} and
-@code{get-largest-window} (@pxref{Selecting Windows}) do not consider
-dedicated windows as candidates when their @var{dedicated} argument is
-non-@code{nil}.  The behavior of @code{set-window-buffer}
+@code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not
+consider dedicated windows as candidates when their @var{dedicated}
+argument is non-@code{nil}.  The behavior of @code{set-window-buffer}
 (@pxref{Buffers and Windows}) with respect to dedicated windows is
 slightly different, see below.
 
-When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
-delete a dedicated window and that window is the only window on its
-frame, it deletes the window's frame too, provided there are other
-frames left.  @code{replace-buffer-in-windows} (@pxref{Switching
-Buffers}) tries to delete all dedicated windows showing its buffer
-argument.  When such a window is the only window on its frame, that
-frame is deleted, provided there are other frames left.  If there are
-no more frames left, some other buffer is displayed in the window, and
-the window is marked as non-dedicated.
-
-When you kill a buffer (@pxref{Killing Buffers}) displayed in a
-dedicated window, any such window usually gets deleted too, since
-@code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
-up windows.  Burying a buffer (@pxref{The Buffer List}) deletes the
-selected window if it is dedicated to that buffer.  If, however, that
-window is the only window on its frame, @code{bury-buffer} displays
-another buffer in it and iconifies the frame.
+   Functions supposed to remove a buffer from a window or a window from
+a frame can behave specially when a window they operate on is dedicated.
+We will distinguish three basic cases, namely where (1) the window is
+not the only window on its frame, (2) the window is the only window on
+its frame but there are other frames on the same terminal left, and (3)
+the window is the only window on the only frame on the same terminal.
+
+   In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
+handles case (2) by deleting the associated frame and case (3) by
+showing another buffer in that frame's only window.  The function
+@code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
+called when a buffer gets killed, deletes the window in case (1) and
+behaves like @code{delete-windows-on} otherwise.
+
+   When @code{bury-buffer} (@pxref{The Buffer List}) operates on the
+selected window (which shows the buffer that shall be buried), it
+handles case (2) by calling @code{frame-auto-hide-function}
+(@pxref{Quitting Windows}) to deal with the selected frame.  The other
+two cases are handled as with @code{replace-buffer-in-windows}.
 
 @defun window-dedicated-p &optional window
 This function returns non-@code{nil} if @var{window} is dedicated to its