[Emacs-diffs] /srv/bzr/emacs/trunk r110700: Reformulate description of windows basics. Describe changes in window ordering.

[martin rudalics]

------------------------------------------------------------
revno: 110700
committer: martin rudalics <address@hidden>
branch nick: trunk
timestamp: Sun 2012-10-28 13:56:15 +0100
message:
  Reformulate description of windows basics.  Describe changes in window 
ordering.
  
  * windows.texi (Basic Windows): Reformulate description of live,
  internal and valid windows.
  (Cyclic Window Ordering): Describe new argument of
  get-lru-window and get-largest-window.  Add description of
  window-in-direction.
modified:
  doc/lispref/ChangeLog
  doc/lispref/windows.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-10-27 22:42:07 +0000
+++ b/doc/lispref/ChangeLog     2012-10-28 12:56:15 +0000
@@ -1,3 +1,11 @@
+2012-10-28  Martin Rudalics  <address@hidden>
+
+       * windows.texi (Basic Windows): Reformulate description of live,
+       internal and valid windows.
+       (Cyclic Window Ordering): Describe new argument of
+       get-lru-window and get-largest-window.  Add description of
+       window-in-direction.
+
 2012-10-27  Glenn Morris  <address@hidden>
 
        * variables.texi (Generalized Variables): New section,

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2012-10-27 05:03:52 +0000
+++ b/doc/lispref/windows.texi  2012-10-28 12:56:15 +0000
@@ -76,30 +76,35 @@
 deleted, the change in window space is taken from or given to the
 adjacent windows, so that the total area of the frame is unchanged.
 
address@hidden live windows
address@hidden internal windows
-  A @dfn{live window} is one that is actually displaying a buffer in a
-frame.  Such a window can be @dfn{deleted}, i.e. removed from the
-frame (@pxref{Deleting Windows}); then it is no longer live, but the
-Lisp object representing it might be still referenced from other Lisp
-objects.  A deleted window may be brought back to life by restoring a
-saved window configuration (@pxref{Window Configurations}).
-
 @defun windowp object
 This function returns @code{t} if @var{object} is a window (whether or
-not it is live).  Otherwise, it returns @code{nil}.
+not it displays a buffer).  Otherwise, it returns @code{nil}.
 @end defun
 
address@hidden live windows
+A @dfn{live window} is one that is actually displaying a buffer in a
+frame.
+
 @defun window-live-p object
 This function returns @code{t} if @var{object} is a live window and
 @code{nil} otherwise.  A live window is one that displays a buffer.
 @end defun
 
-  The windows in each frame are organized into a @dfn{window tree}.
address@hidden and Frames}.  The leaf nodes of each window tree are
-live windows---the ones actually displaying buffers.  The internal
-nodes of the window tree are internal windows, which are not live.
-You can distinguish internal windows from deleted windows with
address@hidden internal windows
+The windows in each frame are organized into a @dfn{window tree}.
address@hidden and Frames}.  The leaf nodes of each window tree are live
+windows---the ones actually displaying buffers.  The internal nodes of
+the window tree are @dfn{internal windows}, which are not live.
+
address@hidden valid windows
+   A @dfn{valid window} is one that is either live or internal.  A valid
+window can be @dfn{deleted}, i.e. removed from its frame
+(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
+object representing it might be still referenced from other Lisp
+objects.  A deleted window may be made valid again by restoring a saved
+window configuration (@pxref{Window Configurations}).
+
+   You can distinguish valid windows from deleted windows with
 @code{window-valid-p}.
 
 @defun window-valid-p object
@@ -1317,31 +1322,37 @@
 criterion, without selecting it:
 
 @cindex least recently used window
address@hidden get-lru-window &optional all-frames dedicated
address@hidden get-lru-window &optional all-frames dedicated not-selected
 This function returns a live window which is heuristically the ``least
 recently used'' window.  The optional argument @var{all-frames} has
 the same meaning as in @code{next-window}.
 
 If any full-width windows are present, only those windows are
-considered.  The selected window is never returned, unless it is the
-only candidate.  A minibuffer window is never a candidate.  A
-dedicated window (@pxref{Dedicated Windows}) is never a candidate
-unless the optional argument @var{dedicated} is address@hidden
+considered.  A minibuffer window is never a candidate.  A dedicated
+window (@pxref{Dedicated Windows}) is never a candidate unless the
+optional argument @var{dedicated} is address@hidden  The selected
+window is never returned, unless it is the only candidate.  However, if
+the optional argument @var{not-selected} is address@hidden, this
+function returns @code{nil} in that case.
 @end defun
 
 @cindex largest window
address@hidden get-largest-window &optional all-frames dedicated
address@hidden get-largest-window &optional all-frames dedicated not-selected
 This function returns the window with the largest area (height times
-width).  A minibuffer window is never a candidate.  A dedicated window
+width).  The optional argument @var{all-frames} specifies the windows to
+search, and has the same meaning as in @code{next-window}.
+
+A minibuffer window is never a candidate.  A dedicated window
 (@pxref{Dedicated Windows}) is never a candidate unless the optional
-argument @var{dedicated} is address@hidden
+argument @var{dedicated} is address@hidden  The selected window is not
+a candidate if the optional argument @var{not-selected} is
address@hidden  If the optional argument @var{not-selected} is
address@hidden and the selected window is the only candidate, this
+function returns @code{nil}.
 
 If there are two candidate windows of the same size, this function
 prefers the one that comes first in the cyclic ordering of windows,
 starting from the selected window.
-
-The optional argument @var{all-frames} specifies the windows to
-search, and has the same meaning as in @code{next-window}.
 @end defun
 
 @cindex window that satisfies a predicate
@@ -1359,6 +1370,26 @@
 @code{next-window}.
 @end defun
 
address@hidden window in direction
address@hidden 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},
address@hidden 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 address@hidden  If the nearest window's
address@hidden parameter is address@hidden, this function tries
+to find another window in the indicated direction whose
address@hidden parameter is @code{nil}.  If the optional
+argument @var{ignore} is address@hidden, a window may be returned even
+if its @code{no-other-window} parameter is address@hidden
+
+If it doesn't find a suitable window, this function returns @code{nil}.
address@hidden defun
+
+
 @node Buffers and Windows
 @section Buffers and Windows
 @cindex examining windows