[Emacs-diffs] /srv/bzr/emacs/trunk r106326: * doc/lispref/windows.texi (Resizing Windows): Simplify introduction.

[Chong Yidong]

------------------------------------------------------------
revno: 106326
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Tue 2011-11-08 23:34:21 +0800
message:
  * 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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/windows.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-11-08 07:43:30 +0000
+++ b/doc/lispref/ChangeLog     2011-11-08 15:34:21 +0000
@@ -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  <address@hidden>
 

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2011-11-08 07:43:30 +0000
+++ b/doc/lispref/windows.texi  2011-11-08 15:34:21 +0000
@@ -274,7 +274,7 @@
 @defun window-combined-p &optional window horizontal
 This function returns a address@hidden 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 address@hidden, this
 means to return address@hidden if and only if @var{window} is part of
@@ -542,138 +542,74 @@
 @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
address@hidden address@hidden means to return @var{delta} if
address@hidden 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 address@hidden lines or columns.  If @var{window} cannot be
-shrunk by address@hidden 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
address@hidden 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 address@hidden, 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} address@hidden 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} address@hidden means don't
-check whether @var{window} itself and its child windows can be resized.
+changed vertically by @var{delta} lines.  If the optional argument
address@hidden is address@hidden, it instead returns @var{delta} if
address@hidden 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
address@hidden is non-zero, a return value of 0 means that the window
+cannot be resized.
+
+Normally, the variables @code{window-min-height} and
address@hidden specify the smallest allowable window size.
address@hidden Window,, Deleting and Rearranging Windows, emacs, The GNU
+Emacs Manual}.  However, if the optional argument @var{ignore} is
address@hidden, this function ignores @code{window-min-height} and
address@hidden, 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 address@hidden, this function
+considers a resize operation that does not alter the window parent of
address@hidden, only its siblings.  If the optional argument
address@hidden is address@hidden, it does not attempt to check whether
address@hidden 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:
-
 @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 address@hidden lines.
-
-Optional argument @var{horizontal} address@hidden means to resize
address@hidden 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
address@hidden columns.
-
-Optional argument @var{ignore} has the same meaning as for the function
address@hidden 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
address@hidden described below should be used.
+This function resizes @var{window} by @var{delta} increments.  If
address@hidden 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
address@hidden means to shrink it.
+
+If @var{window} is @code{nil}, it defaults to the selected window.  If
+the window cannot be resized as demanded, an error is signaled.
+
+The optional argument @var{ignore} has the same meaning as for the
+function @code{window-resizable} above.
+
+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
address@hidden, below.
 @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
address@hidden
-
address@hidden 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 address@hidden,
-it makes the selected window wider by @var{delta} columns.  If
address@hidden is negative, it shrinks the selected window by address@hidden
-lines or columns.  The return value is @code{nil}.
address@hidden deffn
-
address@hidden 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.
address@hidden deffn
-
address@hidden 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 address@hidden,
-it makes the selected window narrower by @var{delta} columns.  If
address@hidden is negative, it enlarges the selected window by address@hidden
-lines or columns.  The return value is @code{nil}.
address@hidden deffn
-
address@hidden 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.
address@hidden deffn
-
-The following function is useful for moving the line dividing two
address@hidden The commands enlarge-window, enlarge-window-horizontally,
address@hidden shrink-window, and shrink-window-horizontally are documented in 
the
address@hidden Emacs manual.  They are not preferred for calling from Lisp.
+
+  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 @@
 @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 address@hidden, @code{split-window} tries to resize
 all windows that are part of the same combination as the old window to
@@ -1488,11 +1424,11 @@
 @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 @@
 @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 address@hidden
 
 The argument @var{action} can also have a address@hidden, non-list
 value.  This has the special meaning that the buffer should be
@@ -2159,7 +2095,7 @@
 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
address@hidden has a non-nil @code{inhibit-same-window} entry.
address@hidden has a address@hidden @code{inhibit-same-window} entry.
 @end defun
 
 @defun display-buffer-reuse-window buffer alist