[Emacs-diffs] emacs/doc/lispref ChangeLog windows.texi

[Martin Rudalics]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Martin Rudalics <m061211>       09/05/09 07:19:48

Modified files:
        doc/lispref    : ChangeLog windows.texi 

Log message:
        (Choosing Window): Describe split-window-sensibly
        and rewrite section on window splitting accordingly.
        (Textual Scrolling): Replace `...' by @code{...}.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/ChangeLog?cvsroot=emacs&r1=1.268&r2=1.269
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/windows.texi?cvsroot=emacs&r1=1.28&r2=1.29

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/ChangeLog,v
retrieving revision 1.268
retrieving revision 1.269
diff -u -b -r1.268 -r1.269
--- ChangeLog   4 May 2009 23:25:38 -0000       1.268
+++ ChangeLog   9 May 2009 07:19:47 -0000       1.269
@@ -1,3 +1,9 @@
+2009-05-09  Martin Rudalics  <address@hidden>
+
+       * windows.texi (Choosing Window): Describe split-window-sensibly
+       and rewrite section on window splitting accordingly.
+       (Textual Scrolling): Replace `...' by @code{...}.
+
 2009-05-04  Chong Yidong  <address@hidden>
 
        * hooks.texi (Standard Hooks): Add abbrev-expand-functions.

Index: windows.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/windows.texi,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -b -r1.28 -r1.29
--- windows.texi        7 May 2009 18:55:54 -0000       1.28
+++ windows.texi        9 May 2009 07:19:48 -0000       1.29
@@ -956,63 +956,84 @@
 
 @defopt pop-up-windows
 This variable specifies whether @code{display-buffer} is allowed to
-split (@pxref{Splitting Windows}) an existing window .  If it is
address@hidden, @code{display-buffer} tries to split the largest
-or least recently used window on the selected frame.  (If the selected
-frame is a minibuffer-only frame, it tries to split a window on
-another frame instead.)  If @code{pop-up-windows} is @code{nil} or the
+split (@pxref{Splitting Windows}) an existing window.  If this variable
+is address@hidden, @code{display-buffer} tries to split the largest or
+least recently used window on the selected frame.  (If the selected
+frame is a minibuffer-only frame, @code{display-buffer} tries to split a
+window on another frame instead.)  If this variable is @code{nil} or the
 variable @code{pop-up-frames} (see below) is address@hidden,
 @code{display-buffer} does not split any window.
 @end defopt
 
 @defvar split-window-preferred-function
-This variable specifies how to split a window.  Its value, if
address@hidden, should be a function of one argument, which is a
-window.  If this variable specifies a function, @code{display-buffer}
-will call it with one or more candidate windows when it looks for a
-window to split.  If the argument window fits, the function is
-expected to split it and return a new window.  If the function returns
address@hidden, the argument window will not be split.
-
-If the value of this variable is @code{nil}, @code{display-buffer}
-uses the two variables described next to decide whether and which
-window to split.
+This variable must specify a function with one argument, which is a
+window.  The @code{display-buffer} routines will call this function with
+one or more candidate windows when they look for a window to split.  The
+function is expected to split that window and return the new window.  If
+the function returns @code{nil}, this means that the argument window
+cannot (or shall not) be split.
+
+The default value of @code{split-window-preferred-function} is the
+function @code{split-window-sensibly} described below.  When you
+customize this option, bear in mind that the @code{display-buffer}
+routines may call your function up to two times when trying to split a
+window.  The argument of the first call is the largest window on the
+chosen frame (as returned by @code{get-largest-window}).  If that call
+fails to return a live window, your function is called a second time
+with the least recently used window on that frame (as returned by
address@hidden).
+
+The function assigned to this option may also try to split any other
+window instead of the argument window.  Note that the window selected at
+the time @code{display-buffer} was invoked is still selected when your
+function is called.  Hence, you can split the selected window (instead
+of the largest or least recently used one) by simply ignoring the window
+argument in the body of your function.  You can even choose to not split
+any window as long as the return value of your function specifies a live
+window or nil, but you are not encouraged to do so unconditionally.  If
+you want @code{display-buffer} to never split any windows, set
address@hidden to @code{nil}.
 @end defvar
 
address@hidden split-window-sensibly
+This function takes a window as argument and tries to split that window
+in a suitable way.  The two variables described next are useful for
+tuning the behavior of this function.
address@hidden defun
+
 @defopt split-height-threshold
-This variable specifies whether @code{display-buffer} may split a window
-vertically, provided there are multiple windows.  If the value is a
-number, @code{display-buffer} splits a window only if it has at least
-this many lines.  If no window is tall enough, or if the value of this
-variable is @code{nil}, @code{display-buffer} tries to split some window
-horizontally, subject to restrictions of @code{split-width-threshold}
-(see below).  If splitting horizontally is impossible too,
address@hidden splits a window vertically only if it's the only
-window on its frame and not the minibuffer window, and only if
address@hidden is address@hidden
-
-A window whose height is fixed (@pxref{Resizing Windows}) cannot be
-split vertically by @code{display-buffer}.  Also, @code{display-buffer}
-splits a window vertically only if it can accommodate two windows that
-are both at least `window-min-height' lines tall.  Moreover, if the
-window that shall be split has a mode line, the window must be at least
-four lines tall in order to make sure that the new window can have a
-mode line as well.  If the original window doesn't have a mode line, a
-height of two lines suffices.
+This variable specifies whether @code{split-window-sensibly} may split
+its argument window vertically.  If this variable is set to an integer,
address@hidden splits the window only if it has at least
+this many lines.  If the value of this variable is @code{nil},
address@hidden tries to split the window horizontally,
+subject to restrictions of @code{split-width-threshold} (see below).  If
+splitting horizontally fails too, @code{split-window-sensibly} will try
+to split the window vertically disregarding the value of this variable.
+
address@hidden does not split a window vertically whose
+height is fixed (@pxref{Resizing Windows}).  Moreover, it splits a
+window vertically only if the space taken up by that window can
+accommodate two windows one above the other that are both at least
address@hidden lines tall.  Finally, if the window that shall
+be split has a mode line, @code{split-window-sensibly} makes sure that
+the new window can accomodate a mode line as well.
 @end defopt
 
 @defopt split-width-threshold
-This variable specifies whether @code{display-buffer} may split a window
-horizontally.  If the value is a number, @code{display-buffer} may split
-a window if it has at least this many columns.  If the value of this
-variable is @code{nil}, @code{display-buffer} will not split any windows
-horizontally.  (It still might split some window vertically, though, see
+This variable specifies whether @code{split-window-sensibly} may split
+its argument window horizontally.  If this variable is set to an
+integer, @code{split-window-sensibly} splits the window only if it has
+at least this many columns.  If the value of this variable is
address@hidden, @code{split-window-sensibly} will not split the window
+horizontally.  (It still might split the window vertically, though, see
 above.)
 
-A window whose width is fixed (@pxref{Resizing Windows}) cannot be split
-horizontally by @code{display-buffer}.  Also, @code{display-buffer}
-splits a window horizontally only if it can accommodate two windows that
-are both at least `window-min-width' columns wide.
address@hidden does not split a window horizontally if
+that window's width is fixed (@pxref{Resizing Windows}).  Also, it
+splits a window horizontally only if the space that window takes up can
+accommodate two windows side by side that are both at least
address@hidden columns wide.
 @end defopt
 
 @defopt even-window-heights
@@ -1535,9 +1556,9 @@
 
   If the window contains a row which is taller than the height of the
 window (for example in the presence of a large image), the scroll
-functions will adjust the window vscroll to scroll the partially
-visible row.  To disable this feature, Lisp code may bind the variable
-`auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}).
+functions will adjust the window vscroll to scroll the partially visible
+row.  To disable this feature, Lisp code may bind the variable
address@hidden to @code{nil} (@pxref{Vertical Scrolling}).
 
 @deffn Command scroll-up &optional count
 This function scrolls the text in the selected window upward