This section describes functions for creating a new window by
@dfn{splitting} an existing one.
-@deffn Command split-window &optional window size side
+@defun split-window &optional window size side
This function creates a new live window next to the window
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
to the selected window. That window is ``split'', and reduced in
lieu of the usual action of @code{split-window}. Otherwise, this
function obeys the @code{window-atom} or @code{window-side} window
parameter, if any. @xref{Window Parameters}.
-@end deffn
+@end defun
As an example, here is a sequence of @code{split-window} calls that
yields the window configuration discussed in @ref{Windows and Frames}.
@cindex window combination limit
@defun set-window-combination-limit window limit
-This functions sets the @dfn{combination limit} of the window
+This function sets the @dfn{combination limit} of the window
@var{window} to @var{limit}. This value can be retrieved via the
function @code{window-combination-limit}. See below for its effects;
note that it is only meaningful for internal windows. The
@defun set-frame-selected-window frame window &optional norecord
This function makes @var{window} the window selected within the frame
-@var{frame}. @var{frame} should be a live frame; if omitted or
-@code{nil}, it defaults to the selected frame. @var{window} should be
-a live window; if omitted or @code{nil}, it defaults to the selected
-window.
+@var{frame}. @var{frame} should be a live frame; if @code{nil}, it
+defaults to the selected frame. @var{window} should be a live window;
+if @code{nil}, it defaults to the selected window.
If @var{frame} is the selected frame, this makes @var{window} the
selected window.
@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-@code{nil}.
+until one of the functions returns non-@code{nil}. The caller can
+pass @code{(allow-no-window . t)} as an element of the action alist to
+indicate its readiness to handle the case of not displaying the
+buffer in a window.
The argument @var{action} can also have a non-@code{nil}, non-list
value. This has the special meaning that the buffer should be
A frame means consider windows on that frame only.
@end itemize
+Note that these meanings differ slightly from those of the
+@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
+Ordering}).
+
If @var{alist} contains no @code{reusable-frames} entry, this function
normally searches just the selected frame; however, if the variable
@code{pop-up-frames} is non-@code{nil}, it searches all frames on the
Each list element has the form @code{(@var{buffer} @var{window-start}
@var{window-pos})}, where @var{buffer} is a buffer previously shown in
-the window, @var{window-start} is the window start position when that
-buffer was last shown, and @var{window-pos} is the point position when
+the window, @var{window-start} is the window start position
+(@pxref{Window Start and End}) when that buffer was last shown, and
+@var{window-pos} is the point position (@pxref{Window Point}) when
that buffer was last shown in @var{window}.
The list is ordered so that earlier elements correspond to more
@defopt switch-to-visible-buffer
If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
@code{switch-to-next-buffer} may switch to a buffer that is already
-visible on the same frame, provided the buffer was shown in the relevant
-window before. If it is @code{nil}, @code{switch-to-prev-buffer} and
-@code{switch-to-next-buffer} always try to avoid switching to a buffer
-that is already visible in another window on the same frame.
+visible on the same frame, provided the buffer was shown in the
+relevant window before. If it is @code{nil},
+@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always
+try to avoid switching to a buffer that is already visible in another
+window on the same frame. The default is @code{t}.
@end defopt
@code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
called when a buffer gets killed, deletes the window in case (1) and
behaves like @code{delete-windows-on} otherwise.
+@c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
When @code{bury-buffer} (@pxref{The Buffer List}) operates on the
selected window (which shows the buffer that shall be buried), it
@node Window Start and End
@section The Window Start and End Positions
@cindex window start position
+@cindex display-start position
Each window maintains a marker used to keep track of a buffer position
that specifies where in the buffer display should start. This position
Here is how you can determine whether a given position @var{position}
is off the screen due to horizontal scrolling:
+@c FIXME: Maybe hscroll-on-screen-p is a better name?
@example
@group
(defun hscroll-on-screen (window position)