[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs/doc/lispref ChangeLog windows.texi
From: |
Martin Rudalics |
Subject: |
[Emacs-diffs] emacs/doc/lispref ChangeLog windows.texi |
Date: |
Sat, 09 May 2009 07:19:48 +0000 |
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
- [Emacs-diffs] emacs/doc/lispref ChangeLog windows.texi,
Martin Rudalics <=