* doc/lispref/windows.texi (Resizing Windows): Simplify introduction.

Don't document enlarge-window, shrink-window, enlarge-window-horizontally,
and shrink-window-horizontally; they are no longer preferred for calling
from Lisp, and are already documented in the Emacs manual.

2 files changed, 74 insertions, 134 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 47214596c1a..7a1e34de159 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -4,6 +4,10 @@
         window-text-height.  Remove window-min-height and window-min-width
         discussion, referring instead to Emacs manual.
         (Splitting Windows, Resizing Windows): Add xref to Emacs manual.
+        (Resizing Windows): Simplify introduction.  Don't document
+        enlarge-window, shrink-window, enlarge-window-horizontally, and
+        shrink-window-horizontally; they are no longer preferred for
+        calling from Lisp, and are already documented in the Emacs manual.
 
 2011-11-07  Glenn Morris  <rgm@gnu.org>
 
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 2bb30dd4cbc..46ed4476036 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -274,7 +274,7 @@ the leftmost child window for a horizontal combination.  If
 @defun window-combined-p &optional window horizontal
 This function returns a non-@code{nil} value if and only if
 @var{window} is part of a vertical combination.  If @var{window} is
-omitted or nil, it defaults to the selected one.
+omitted or @code{nil}, it defaults to the selected one.
 
 If the optional argument @var{horizontal} is non-@code{nil}, this
 means to return non-@code{nil} if and only if @var{window} is part of
@@ -542,138 +542,74 @@ function @code{window-resizable}.  @xref{Resizing Windows}.
 @cindex changing window size
 @cindex window size, changing
 
-Emacs does not permit overlapping windows or gaps between windows, so
-changing the size of a window always affects at least one other window.
-When a frame contains just one window, that window can be resized only
-by resizing the window's frame.  The functions described below are
-therefore meaningful only in the context of a frame containing at least
-two windows.  The size of the corresponding frame never changes when
-invoking a function described in this section.
-
-   The routines changing window sizes always operate in one dimension at
-a time.  This means that windows can be resized only either vertically
-or horizontally.  If a window shall be resized in both dimensions, it
-must be resized in one dimension first and in the other dimension
-afterwards.  If the second resize operation fails, the frame might end
-up in an unsatisfactory state.  To avoid such states, it might be useful
-to save the current window configuration (@pxref{Window Configurations})
-before attempting the first resize operation and restore the saved
-configuration in case the second resize operation fails.
-
-   Functions that resize windows are supposed to obey restrictions
-imposed by window minimum sizes and fixed-size windows, see @ref{Window
-Sizes}.  In order to determine whether resizing a specific window is
-possible in the first place, the following function can be used:
+  This section describes functions for resizing a window without
+changing the size of its frame.  Because live windows do not overlap,
+these functions are meaningful only on frames that contain two or more
+windows: resizing a window also changes the size of a neighboring
+window.  If there is just one window on a frame, its size cannot be
+changed except by resizing the frame (@pxref{Size and Position}).
+
+  Except where noted, these functions also accept internal windows as
+arguments.  Resizing an internal window causes its child windows to be
+resized to fit the same space.
 
 @defun window-resizable window delta &optional horizontal ignore side noup nodown
 This function returns @var{delta} if the size of @var{window} can be
-changed vertically by @var{delta} lines.  Optional argument
-@var{horizontal} non-@code{nil} means to return @var{delta} if
-@var{window} can be resized horizontally by @var{delta} columns.  A
-return value of zero means that @var{window} is not resizable.
-
-If @var{delta} is a positive number, this means that @var{window} shall
-be enlarged by @var{delta} lines or columns.  If @var{window} cannot be
-enlarged by @var{delta} lines or columns, this function returns the
-maximum value in the range from 0 to @var{delta} by which @var{window}
-can be enlarged.
-
-If @var{delta} is a negative number, this means that @var{window} shall
-be shrunk by -@var{delta} lines or columns.  If @var{window} cannot be
-shrunk by -@var{delta} lines or columns, this function returns the
-minimum value in the range from @var{delta} to 0 that can be used for
-shrinking @var{window}.
-
-Normally, the customizable variables @code{window-min-height} and
-@code{window-min-width} specify the smallest allowable size of a
-window.  @xref{Change Window,,Deleting and Rearranging Windows,
-emacs, The GNU Emacs Manual}.  If resizing would result in making any
-window smaller than this, this function usually signals an error.
-However, if the optional argument @var{ignore} is non-@code{nil}, this
-function ignores @code{window-min-height} and @code{window-min-width},
-as well as @code{window-size-fixed}.  In that case, the minimum-height
-window consists of a header (if any), a mode line, plus a text area
-one line tall; the minimum-width window consists of any fringes,
-margins and scroll bar, plus a text area two columns wide.
-
-If @var{ignore} denotes a window, this means to ignore restrictions for
-that window only.  If @var{ignore} equals the constant @code{safe}, this
-means a live window may get as small as one line or two columns.
-
-Optional argument @var{noup} non-@code{nil} means don't go up in the
-window tree but try to steal or distribute the space needed for the
-resize operation among the other windows within @var{window}'s
-combination.  Optional argument @var{nodown} non-@code{nil} means don't
-check whether @var{window} itself and its child windows can be resized.
-@end defun
-
-The function @code{window-resizable} does not change any window sizes.
-The following function does:
+changed vertically by @var{delta} lines.  If the optional argument
+@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
+@var{window} can be resized horizontally by @var{delta} columns.  It
+does not actually change the window size.
+
+If @var{window} is @code{nil}, it defaults to the selected window.
+
+A positive value of @var{delta} enlarges the window by that number of
+lines or columns; a negative value of @var{delta} shrinks it.  If
+@var{delta} is non-zero, a return value of 0 means that the window
+cannot be resized.
+
+Normally, the variables @code{window-min-height} and
+@code{window-min-width} specify the smallest allowable window size.
+@xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU
+Emacs Manual}.  However, if the optional argument @var{ignore} is
+non-@code{nil}, this function ignores @code{window-min-height} and
+@code{window-min-width}, as well as @code{window-size-fixed}.
+Instead, it considers the minimum-height window to be one consisting
+of a header (if any), a mode line, plus a text area one line tall; and
+a minimum-width window as one consisting of fringes, margins, and
+scroll bar (if any), plus a text area two columns wide.
+
+If the optional argument @var{noup} is non-@code{nil}, this function
+considers a resize operation that does not alter the window parent of
+@var{window}, only its siblings.  If the optional argument
+@var{nodown} is non-@code{nil}, it does not attempt to check whether
+@var{window} itself and its child windows can be resized.
+@end defun
 
 @defun window-resize window delta &optional horizontal ignore
-This function resizes @var{window} vertically by @var{delta} lines.  The
-argument @var{window} can denote an arbitrary window and defaults to the
-selected one.  An attempt to resize the root window of a frame will
-raise an error.
-
-Second argument @var{delta} a positive number means @var{window} shall
-be enlarged by @var{delta} lines.  If @var{delta} is negative, that
-means @var{window} shall be shrunk by -@var{delta} lines.
-
-Optional argument @var{horizontal} non-@code{nil} means to resize
-@var{window} horizontally by @var{delta} columns.  In this case a
-positive @var{delta} means enlarge @var{window} by @var{delta} columns.
-A negative @var{delta} means @var{window} shall be shrunk by
--@var{delta} columns.
-
-Optional argument @var{ignore} has the same meaning as for the function
-@code{window-resizable} above.
-
-This function can simultaneously move two edges of WINDOW.  Exactly
-which edges of @var{window} are moved and which other windows are
-resized along with @var{window} is determined by the splits and nest
-status of the involved windows (@pxref{Splitting Windows}).  If only the
-low (right) edge of @var{window} shall be moved, the function
-@code{adjust-window-trailing-edge} described below should be used.
-@end defun
-
-The next four commands are simple interfaces to @code{window-resize}.
-They always operate on the selected window, never delete any window, and
-always raise an error when resizing would violate a restriction imposed
-by @code{window-min-height}, @code{window-min-width}, or
-@code{window-size-fixed}.
-
-@deffn Command enlarge-window delta &optional horizontal
-This function makes the selected window @var{delta} lines taller.
-Interactively, if no argument is given, it makes the selected window one
-line taller.  If optional argument @var{horizontal} is non-@code{nil},
-it makes the selected window wider by @var{delta} columns.  If
-@var{delta} is negative, it shrinks the selected window by -@var{delta}
-lines or columns.  The return value is @code{nil}.
-@end deffn
+This function resizes @var{window} by @var{delta} increments.  If
+@var{horizontal} is @code{nil}, it changes the height by @var{delta}
+lines; otherwise, it changes the width by @var{delta} columns.  A
+positive @var{delta} means to enlarge the window, and a negative
+@var{delta} means to shrink it.
 
-@deffn Command enlarge-window-horizontally delta
-This function makes the selected window @var{delta} columns wider.
-Interactively, if no argument is given, it makes the selected window one
-column wider.
-@end deffn
+If @var{window} is @code{nil}, it defaults to the selected window.  If
+the window cannot be resized as demanded, an error is signaled.
 
-@deffn Command shrink-window delta &optional horizontal
-This function makes the selected window @var{delta} lines smaller.
-Interactively, if no argument is given, it makes the selected window one
-line smaller.  If optional argument @var{horizontal} is non-@code{nil},
-it makes the selected window narrower by @var{delta} columns.  If
-@var{delta} is negative, it enlarges the selected window by -@var{delta}
-lines or columns.  The return value is @code{nil}.
-@end deffn
+The optional argument @var{ignore} has the same meaning as for the
+function @code{window-resizable} above.
 
-@deffn Command shrink-window-horizontally delta
-This function makes the selected window @var{delta} columns narrower.
-Interactively, if no argument is given, it makes the selected window one
-column narrower.
-@end deffn
+The choice of which window edge this function alters depends on the
+splitting and nesting status of the involved windows; in some cases,
+it may alter both edges.  @xref{Splitting Windows}.  To resize by
+moving only the bottom or right edge of a window, use the function
+@code{adjust-window-trailing-edge}, below.
+@end defun
+
+@c The commands enlarge-window, enlarge-window-horizontally,
+@c shrink-window, and shrink-window-horizontally are documented in the
+@c Emacs manual.  They are not preferred for calling from Lisp.
 
-The following function is useful for moving the line dividing two
+  The following function is useful for moving the line dividing two
 windows.
 
 @defun adjust-window-trailing-edge window delta &optional horizontal
@@ -1101,9 +1037,9 @@ configuration.
 @code{split-window}.
 
 @defopt window-splits
-If this variable is nil, the function @code{split-window} can split a
-window if and only if that window's screen estate is sufficiently large
-to accommodate both--itself and the new window.
+If this variable is @code{nil}, the function @code{split-window} can
+split a window if and only if that window's screen estate is
+sufficiently large to accommodate both--itself and the new window.
 
 If this variable is non-@code{nil}, @code{split-window} tries to resize
 all windows that are part of the same combination as the old window to
@@ -1488,11 +1424,11 @@ function, it calls that function with @var{window} as its sole argument.
 @end deffn
 
 @deffn Command delete-windows-on &optional buffer-or-name frame
-This function deletes all windows showing @var{buffer-or-name} and
-returns nil.  If there are no windows showing @var{buffer-or-name}, it
-does nothing.  The optional argument @var{buffer-or-name} may be a
-buffer or the name of an existing buffer and defaults to the current
-buffer.  Invoking this command on a minibuffer signals an error.
+This function deletes all windows showing @var{buffer-or-name}.  If
+there are no windows showing @var{buffer-or-name}, it does nothing.
+The optional argument @var{buffer-or-name} may be a buffer or the name
+of an existing buffer and defaults to the current buffer.  Invoking
+this command on a minibuffer signals an error.
 
 The function @code{delete-windows-on} operates by calling
 @code{delete-window} for each window showing @var{buffer-or-name}.  If a
@@ -2108,7 +2044,7 @@ The constant @code{display-buffer-fallback-action}.
 @noindent
 Each action function is called in turn, passing the buffer as the
 first argument and the combined action alist as the second argument,
-until one of the functions returns non-nil.
+until one of the functions returns non-@code{nil}.
 
 The argument @var{action} can also have a non-@code{nil}, non-list
 value.  This has the special meaning that the buffer should be
@@ -2159,7 +2095,7 @@ returns the window if it succeeds, and @code{nil} if it fails.
 This function tries to display @var{buffer} in the selected window.
 It fails if the selected window is a minibuffer window or is dedicated
 to another buffer (@pxref{Dedicated Windows}).  It also fails if
-@var{alist} has a non-nil @code{inhibit-same-window} entry.
+@var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
 @end defun
 
 @defun display-buffer-reuse-window buffer alist