comparison doc/lispref/windows.texi @ 99474:ecad25300f20

Fix usage of `see @ref'.

99473:867b00482e8f

  A @dfn{window} in Emacs is the physical area of the screen in which a
buffer is displayed.  The term is also used to refer to a Lisp object that
represents that screen area in Emacs Lisp.  It should be
clear from the context which is meant.

  Emacs groups windows into frames, see @ref{Frames}.  A frame
represents an area of screen available for Emacs to use.  Each frame
always contains at least one window, but you can subdivide it
vertically or horizontally into multiple, nonoverlapping Emacs
windows.

window, but the other windows have ``non-selected'' cursors, normally
less visible.  (@xref{Cursor Parameters}, for customizing this.)  At
any time, one frame is the selected frame; and the window selected
within that frame is @dfn{the selected window}.  The selected window's
buffer is usually the current buffer (except when @code{set-buffer} has
been used), see @ref{Current Buffer}.

  For practical purposes, a window exists only while it is displayed in
a frame.  Once removed from the frame, the window is effectively deleted
and should not be used, @emph{even though there may still be references
to it} from other Lisp objects, see @ref{Deleting Windows}.  Restoring a
saved window configuration is the only way for a window no longer on the
screen to come back to life, see @ref{Window Configurations}.

@cindex multiple windows
  Users create multiple windows so they can look at several buffers at
once.  Lisp libraries use multiple windows for a variety of reasons, but
most often to display related information.  In Rmail, for example, you

The value of the argument @var{minibuf} specifies whether the minibuffer
is included in the window order.  Normally, when @var{minibuf} is
@code{nil}, the minibuffer is included only if it is currently
``active''; this matches the behavior of @kbd{C-x o}.  (The minibuffer
window is active while the minibuffer is in use, see @ref{Minibuffers}.)

If @var{minibuf} is @code{t}, the cyclic ordering includes the
minibuffer window even if it is not active.  If @var{minibuf} is neither
@code{t} nor @code{nil}, the minibuffer window is not included even if
it is active.

If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a
buffer using @code{other-buffer}.  If @var{buffer-or-name} is a string
that does not identify an existing buffer, then a new buffer by that
name is created.  The major mode for the new buffer is set according to
the variable @code{default-major-mode}, see @ref{Auto Major Mode}.

When @code{enable-recursive-minibuffers} is non-@code{nil} and the
selected window is either the minibuffer window or is dedicated to its
buffer (@pxref{Dedicated Windows}), @code{switch-to-buffer} calls
@code{pop-to-buffer} (see below) to display the buffer in some other

@deffn Command pop-to-buffer buffer-or-name &optional other-window norecord
This command makes @var{buffer-or-name} the current buffer and switches
to it in some window, preferably not the window previously selected.
The ``popped-to'' window becomes the selected window.  Its frame is
given the X server's focus, if possible, see @ref{Input Focus}.  The return
value is the buffer that was switched to.

If @var{buffer-or-name} is @code{nil}, that means to choose some other
buffer, but you don't specify which.  If @var{buffer-or-name} is a
string that does not name an existing buffer, a buffer by that name is

full-width and/or full-height windows.  If @var{window-or-frame}
specifies a frame, it balances all windows on that frame.  If
@var{window-or-frame} specifies a window, it balances this window and
its ``siblings'' only.  Think of a sibling as the other (original or
new) window with respect to the present one, involved in the process of
splitting, see @ref{Splitting Windows}.  Since a sibling may have been
split again, a window can have more than one sibling.
@end deffn

@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame

buffers are scrolled, and their values of point and the mark; also their
fringes, margins, and scroll bar settings.  It also includes the value
of @code{minibuffer-scroll-window}.  As a special exception, the window
configuration does not record the value of point in the selected window
for the current buffer.  Also, the window configuration does not record
the values of window parameters, see @ref{Window Parameters}.

  You can bring back an entire frame layout by restoring a previously
saved window configuration.  If you want to record the layout of all
frames instead of just one, use a frame configuration instead of a
window configuration, see @ref{Frame Configurations}.

@defun current-window-configuration &optional frame
This function returns a new object representing @var{frame}'s current
window configuration.  @var{frame} defaults to the selected frame.
@end defun

99474:ecad25300f20

  A @dfn{window} in Emacs is the physical area of the screen in which a
buffer is displayed.  The term is also used to refer to a Lisp object that
represents that screen area in Emacs Lisp.  It should be
clear from the context which is meant.

  Emacs groups windows into frames; see @ref{Frames}.  A frame
represents an area of screen available for Emacs to use.  Each frame
always contains at least one window, but you can subdivide it
vertically or horizontally into multiple, nonoverlapping Emacs
windows.

window, but the other windows have ``non-selected'' cursors, normally
less visible.  (@xref{Cursor Parameters}, for customizing this.)  At
any time, one frame is the selected frame; and the window selected
within that frame is @dfn{the selected window}.  The selected window's
buffer is usually the current buffer (except when @code{set-buffer} has
been used); see @ref{Current Buffer}.

  For practical purposes, a window exists only while it is displayed in
a frame.  Once removed from the frame, the window is effectively deleted
and should not be used, @emph{even though there may still be references
to it} from other Lisp objects; see @ref{Deleting Windows}.  Restoring a
saved window configuration is the only way for a window no longer on the
screen to come back to life; see @ref{Window Configurations}.

@cindex multiple windows
  Users create multiple windows so they can look at several buffers at
once.  Lisp libraries use multiple windows for a variety of reasons, but
most often to display related information.  In Rmail, for example, you

The value of the argument @var{minibuf} specifies whether the minibuffer
is included in the window order.  Normally, when @var{minibuf} is
@code{nil}, the minibuffer is included only if it is currently
``active''; this matches the behavior of @kbd{C-x o}.  (The minibuffer
window is active while the minibuffer is in use; see @ref{Minibuffers}.)

If @var{minibuf} is @code{t}, the cyclic ordering includes the
minibuffer window even if it is not active.  If @var{minibuf} is neither
@code{t} nor @code{nil}, the minibuffer window is not included even if
it is active.

If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a
buffer using @code{other-buffer}.  If @var{buffer-or-name} is a string
that does not identify an existing buffer, then a new buffer by that
name is created.  The major mode for the new buffer is set according to
the variable @code{default-major-mode}; see @ref{Auto Major Mode}.

When @code{enable-recursive-minibuffers} is non-@code{nil} and the
selected window is either the minibuffer window or is dedicated to its
buffer (@pxref{Dedicated Windows}), @code{switch-to-buffer} calls
@code{pop-to-buffer} (see below) to display the buffer in some other

@deffn Command pop-to-buffer buffer-or-name &optional other-window norecord
This command makes @var{buffer-or-name} the current buffer and switches
to it in some window, preferably not the window previously selected.
The ``popped-to'' window becomes the selected window.  Its frame is
given the X server's focus, if possible; see @ref{Input Focus}.  The return
value is the buffer that was switched to.

If @var{buffer-or-name} is @code{nil}, that means to choose some other
buffer, but you don't specify which.  If @var{buffer-or-name} is a
string that does not name an existing buffer, a buffer by that name is

full-width and/or full-height windows.  If @var{window-or-frame}
specifies a frame, it balances all windows on that frame.  If
@var{window-or-frame} specifies a window, it balances this window and
its ``siblings'' only.  Think of a sibling as the other (original or
new) window with respect to the present one, involved in the process of
splitting; see @ref{Splitting Windows}.  Since a sibling may have been
split again, a window can have more than one sibling.
@end deffn

@deffn Command balance-windows-area
This function attempts to give all windows on the selected frame

buffers are scrolled, and their values of point and the mark; also their
fringes, margins, and scroll bar settings.  It also includes the value
of @code{minibuffer-scroll-window}.  As a special exception, the window
configuration does not record the value of point in the selected window
for the current buffer.  Also, the window configuration does not record
the values of window parameters; see @ref{Window Parameters}.

  You can bring back an entire frame layout by restoring a previously
saved window configuration.  If you want to record the layout of all
frames instead of just one, use a frame configuration instead of a
window configuration; see @ref{Frame Configurations}.

@defun current-window-configuration &optional frame
This function returns a new object representing @var{frame}'s current
window configuration.  @var{frame} defaults to the selected frame.
@end defun