[Emacs-diffs] Changes to emacs/doc/lispref/windows.texi,v

[Martin Rudalics]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Martin Rudalics <m061211>       08/11/16 10:15:30

Index: windows.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/windows.texi,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -b -r1.20 -r1.21
--- windows.texi        9 Nov 2008 21:22:41 -0000       1.20
+++ windows.texi        16 Nov 2008 10:15:30 -0000      1.21
@@ -113,8 +113,8 @@
 
 @deffn Command split-window &optional window size horizontal
 This function splits a new window out of @var{window}'s screen area.  It
-returns the new window.  @var{window} defaults to the selected window.
-When you split the selected window, it remains selected.
+returns the new window.  The default for @var{window} is the selected
+window.  When you split the selected window, it remains selected.
 
 If @var{horizontal} is address@hidden, then @var{window} splits into two
 side by side windows.  The original window keeps the leftmost @var{size}
@@ -329,21 +329,21 @@
 
 @deffn Command delete-window &optional window
 This function removes @var{window} from display and returns @code{nil}.
address@hidden defaults to the selected window.  An error is signaled if
address@hidden is the only window on its frame.
+The default for @var{window} is the selected window.  An error is
+signaled if @var{window} is the only window on its frame.
 @end deffn
 
 @deffn Command delete-other-windows &optional window
 This function makes @var{window} the only window on its frame, by
-deleting the other windows in that frame.  @var{window} defaults to the
-selected window.  The return value is @code{nil}.
+deleting the other windows in that frame.  The default for @var{window}
+is the selected window.  The return value is @code{nil}.
 @end deffn
 
 @deffn Command delete-windows-on &optional buffer-or-name frame
 This function deletes all windows showing @var{buffer-or-name}.  If
-there are no windows showing @var{buffer-or-name}, it does nothing.
address@hidden may be a buffer or the name of an existing buffer
-and defaults to the current buffer.
+there are no windows showing @var{buffer-or-name}, it does nothing.  The
+optional argument @var{buffer-or-name} may be a buffer or the name of an
+existing buffer and defaults to the current buffer.
 
 @code{delete-windows-on} operates frame by frame.  If a frame has
 several windows showing different buffers, then those showing
@@ -356,11 +356,11 @@
 (@pxref{Dedicated Windows}), and there are other frames left, that
 window's frame is deleted.
 
-The argument @var{frame} specifies which frames to operate on.  This
-function does not use it in quite the same way as the other functions
-which scan all windows; specifically, the values @code{t} and @code{nil}
-have the opposite of their meanings in other functions.  Here are the
-full details:
+The optional argument @var{frame} specifies which frames to operate on.
+This function does not use it in quite the same way as the other
+functions which scan all windows; specifically, the values @code{t} and
address@hidden have the opposite of their meanings in other functions.  Here
+are the full details:
 
 @itemize @bullet
 @item
@@ -453,10 +453,10 @@
 only window.  A newly created window becomes the least recently used
 window until it is selected.  A minibuffer window is never a candidate.
 A dedicated window (@pxref{Dedicated Windows}) is never a candidate
-unless the @var{dedicated} argument is address@hidden, so if all
-existing windows are dedicated, the function returns @code{nil}.
+unless the optional argument @var{dedicated} is address@hidden
 
-The argument @var{frame} specifies which windows are considered.
+The optional argument @var{frame} specifies which windows are
+considered.
 
 @itemize @bullet
 @item
@@ -477,15 +477,14 @@
 width).  If there are no side-by-side windows, then this is the window
 with the most lines.  A minibuffer window is never a candidate.  A
 dedicated window (@pxref{Dedicated Windows}) is never a candidate unless
-the @var{dedicated} argument is address@hidden, so if all existing
-windows are dedicated, the function returns @code{nil}.
+the optional argument @var{dedicated} is address@hidden
 
 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 (@pxref{Cyclic Window Ordering}).
 
-The argument @var{frame} specifies which set of windows to consider, see
address@hidden above.
+The optional argument @var{frame} specifies which set of windows to
+consider, see @code{get-lru-window} above.
 @end defun
 
 @cindex window that satisfies a predicate
@@ -531,22 +530,23 @@
 @cindex minibuffer window, and @code{next-window}
 This function returns the window following @var{window} in the cyclic
 ordering of windows.  This is the window @kbd{C-x o} selects if typed
-when @var{window} is selected.  @var{window} defaults to the selected
-window.
+when @var{window} is selected.  The default for @var{window} is the
+selected window.
 
-The value of the argument @var{minibuf} specifies whether the minibuffer
-is included in the window order.  Normally, when @var{minibuf} is
address@hidden, 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}.)
+The value of the optional argument @var{minibuf} specifies whether the
+minibuffer is included in the window order.  Normally, when
address@hidden 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
address@hidden)
 
 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.
 
-The argument @var{all-frames} specifies which frames to consider.  Here
-are the possible values and their meanings:
+The optional argument @var{all-frames} specifies which frames to
+consider.  Here are the possible values and their meanings:
 
 @table @asis
 @item @code{nil}
@@ -607,7 +607,7 @@
 the selected window.  In an interactive call, @var{count} is the numeric
 prefix argument.
 
-The argument @var{all-frames} has the same meaning as in
+The optional argument @var{all-frames} has the same meaning as in
 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
 is always effectively @code{nil}.  This function returns @code{nil}.
 @end deffn
@@ -625,8 +625,8 @@
 
 @defun window-list &optional frame minibuf window
 This function returns a list of all windows on @var{frame}, starting
-with @var{window}.  @var{frame} defaults to the selected frame;
address@hidden defaults to the selected window.
+with @var{window}.  The default for @var{frame} is the selected frame;
+the default for @var{window} is the selected window.
 
 The value of @var{minibuf} specifies if the minibuffer window shall be
 included in the result list.  If @var{minibuf} is @code{t}, the result
@@ -657,10 +657,13 @@
 
 @defun set-window-buffer window buffer-or-name &optional keep-margins
 This function makes @var{window} display @var{buffer-or-name} as its
-contents.  It returns @code{nil}.  @var{buffer-or-name} must be a
-buffer, or the name of an existing buffer.  This is the fundamental
-primitive for changing which buffer is displayed in a window, and all
-ways of doing that call this function.
+contents.  It returns @code{nil}.  The default for @var{window} is the
+selected window.  The argument @var{buffer-or-name} must specify a
+buffer or the name of an existing buffer.
+
address@hidden is the fundamental primitive for changing which
+buffer is displayed in a window, and all ways of doing that call this
+function.
 
 @example
 @group
@@ -675,12 +678,12 @@
 However, if @var{keep-margins} is address@hidden, display margins and
 fringe widths of @var{window} remain unchanged.  @xref{Fringes}.
 
-This function signals an error when @var{window} is @dfn{strongly}
-dedicated to its buffer (@pxref{Dedicated Windows}) and does not already
-display @var{buffer-or-name}.
address@hidden signals an error when @var{window} is
address@hidden dedicated to its buffer (@pxref{Dedicated Windows}) and
+does not already display @var{buffer-or-name}.
 
-This function runs @code{window-scroll-functions} before running
address@hidden
+Note that this function runs @code{window-scroll-functions} before
+running @code{window-configuration-change-hook}.
 @end defun
 
 @defvar buffer-display-count
@@ -690,8 +693,8 @@
 @end defvar
 
 @defun window-buffer &optional window
-This function returns the buffer that @var{window} is displaying.
address@hidden defaults to the selected window.
+This function returns the buffer that @var{window} is displaying.  The
+default for @var{window} is the selected window.
 
 @example
 @group
@@ -708,9 +711,9 @@
 cyclic ordering of windows, starting from the selected window.
 @xref{Cyclic Window Ordering}.
 
address@hidden may be a buffer or a buffer name and defaults to
-the current buffer.  The argument @var{all-frames} specifies which
-windows to consider:
+The argument @var{BUFFER-OR-NAME} may be a buffer or a buffer name and
+defaults to the current buffer.  The optional argument @var{all-frames}
+specifies which windows to consider:
 
 @itemize @bullet
 @item
@@ -734,8 +737,8 @@
 
 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
 This function returns a list of all windows currently displaying
address@hidden  @var{buffer-or-name} may be a buffer or the name
-of an existing buffer and defaults to the current buffer.
address@hidden  The argument @var{buffer-or-name} may be a buffer
+or the name of an existing buffer and defaults to the current buffer.
 
 The two remaining arguments work like the same-named arguments of
 @code{next-window}; they are @emph{not} like the optional arguments of
@@ -783,7 +786,7 @@
 displays the buffer in the selected window.  This means that a human can
 see the buffer and subsequent keyboard commands will apply to it.
 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
-the current buffer but does not display it in the selected window,
+the current buffer but does not display it in the selected window;
 see @ref{Current Buffer}.
 
 If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a
@@ -877,8 +880,8 @@
 don't care which other buffer is used; you just want to make sure that
 @var{buffer-or-name} is no longer displayed.
 
address@hidden may be a buffer or the name of an existing buffer
-and defaults to the current buffer.
+The argument @var{buffer-or-name} may be a buffer or the name of an
+existing buffer and defaults to the current buffer.
 
 If a window displaying @var{buffer-or-name} is dedicated
 (@pxref{Dedicated Windows}), and is not the only window on its frame,
@@ -903,8 +906,8 @@
 This command makes @var{buffer-or-name} appear in some window, but it
 does not select that window and does not make the buffer specified by
 @var{buffer-or-name} current.  The identity of the selected window is
-unaltered by this function.  @var{buffer-or-name} must be a buffer, or
-the name of an existing buffer.
+unaltered by this function.  The argument @var{buffer-or-name} must be a
+buffer or the name of an existing buffer.
 
 @var{not-this-window} address@hidden means to display the specified
 buffer in a window other than the selected one, even if it is already
@@ -916,11 +919,11 @@
 @code{display-buffer} returns the window chosen to display
 @var{buffer-or-name}.
 
-If the argument @var{frame} is address@hidden, it specifies which frames
-to check when deciding whether the buffer is already displayed.  If the
-buffer is already displayed in some window on one of these frames,
address@hidden simply returns that window.  Here are the possible
-values of @var{frame}:
+If the optional argument @var{frame} is address@hidden, it specifies
+which frames to check when deciding whether the buffer is already
+displayed.  If the buffer is already displayed in some window on one of
+these frames, @code{display-buffer} simply returns that window.  Here
+are the possible values of @var{frame}:
 
 @itemize @bullet
 @item
@@ -1214,8 +1217,8 @@
 buffer and @code{nil} otherwise.  More precisely, the return value is
 the value assigned by the last call of @code{set-window-dedicated-p} for
 @var{window} or @code{nil} if that function was never called with
address@hidden as its argument.  @var{window} defaults to the selected
-window.
address@hidden as its argument.  The default for @var{window} is the
+selected window.
 @end defun
 
 @defun set-window-dedicated-p window flag
@@ -1269,8 +1272,8 @@
 @defun window-point &optional window
 This function returns the current position of point in @var{window}.
 For a nonselected window, this is the value point would have (in that
-window's buffer) if that window were selected.  @var{window} defaults to
-the selected window.
+window's buffer) if that window were selected.  The default for
address@hidden is the selected window.
 
 When @var{window} is the selected window and its buffer is also the
 current buffer, the value returned is the same as point in that buffer.
@@ -1344,7 +1347,7 @@
 @cindex window end position
 @defun window-end &optional window update
 This function returns the position where display of its buffer ends in
address@hidden  @var{window} defaults to the selected window.
address@hidden  The default for @var{window} is the selected window.
 
 Simply changing the buffer text or moving point does not update the
 value that @code{window-end} returns.  The value is updated only when
@@ -1470,13 +1473,13 @@
 @end defun
 
 @defun window-line-height &optional line window
-This function returns information about text line @var{line} in @var{window}.
-If @var{line} is one of @code{header-line} or @code{mode-line},
address@hidden returns information about the corresponding
-line of the window.  Otherwise, @var{line} is a text line number
-starting from 0.  A negative number counts from the end of the window.
-The argument @var{line} defaults to the current line in @var{window};
address@hidden, to the selected window.
+This function returns the height of text line @var{line} in
address@hidden  If @var{line} is one of @code{header-line} or
address@hidden, @code{window-line-height} returns information about
+the corresponding line of the window.  Otherwise, @var{line} is a text
+line number starting from 0.  A negative number counts from the end of
+the window.  The default for @var{line} is the current line in
address@hidden; the default for @var{window} is the selected window.
 
 If the display is not up to date, @code{window-line-height} returns
 @code{nil}.  In that case, @code{pos-visible-in-window-p} may be used
@@ -1726,8 +1729,8 @@
 
 @defun window-vscroll &optional window pixels-p
 This function returns the current vertical scroll position of
address@hidden  @var{window} defaults to the selected window.  If
address@hidden is address@hidden, the return value is measured in
address@hidden  The default for @var{window} is the selected window.
+If @var{pixels-p} is address@hidden, the return value is measured in
 pixels, rather than in units of the normal line height.
 
 @example
@@ -1845,8 +1848,8 @@
 @defun window-hscroll &optional window
 This function returns the total leftward horizontal scrolling of
 @var{window}---the number of columns by which the text in @var{window}
-is scrolled left past the left margin.  @var{window} defaults to the
-selected window.
+is scrolled left past the left margin.  The default for
address@hidden is the selected window.
 
 The return value is never negative.  It is zero when no horizontal
 scrolling has been done in @var{window} (which is usually the case).
@@ -1925,8 +1928,8 @@
 This function returns the number of lines in @var{window}, including its
 mode line and header line, if any.  If @var{window} fills its entire
 frame except for the echo area, this is typically one less than the
-value of @code{frame-height} on that frame.  @var{window} defaults to
-the selected window.
+value of @code{frame-height} on that frame.  The default for
address@hidden is the selected window.
 
 @example
 @group
@@ -1950,8 +1953,8 @@
 @end defun
 
 @defun window-width &optional window
-This function returns the number of columns in @var{window}.
address@hidden defaults to the selected window.
+This function returns the number of columns in @var{window}.  The
+default for @var{window} is the selected window.
 
 The return value does not include the window's scroll bar or the column
 of @samp{|} characters that separates side-by-side windows.  Moreover,
@@ -1971,13 +1974,13 @@
 
 @defun window-full-width-p &optional window
 This function returns address@hidden if @var{window} is as wide as the
-frame that contains it; otherwise @code{nil}.  @var{window} defaults to
-the selected window.
+frame that contains it; otherwise @code{nil}.  The default for
address@hidden is the selected window.
 @end defun
 
 @defun window-edges &optional window
 This function returns a list of the edge coordinates of @var{window}.
address@hidden defaults to the selected window.
+The default for @var{window} is the selected window.
 
 The order of the list is @code{(@var{left} @var{top} @var{right}
 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
@@ -2163,7 +2166,8 @@
 
 @defun fit-window-to-buffer &optional window max-height min-height
 This function makes @var{window} the right height to display its
-contents exactly.  @var{window} defaults to the selected window.
+contents exactly.  The default for @var{window} is the selected
+window.
 
 The argument @var{max-height} specifies the maximum height the window
 is allowed to be; @code{nil} means use the frame height.  The argument
@@ -2175,8 +2179,8 @@
 @deffn Command shrink-window-if-larger-than-buffer &optional window
 This command shrinks @var{window} vertically to be as small as possible
 while still showing the full contents of its buffer---but not less than
address@hidden lines.  @var{window} defaults to the selected
-window.
address@hidden lines.  The default for @var{window} is
+the selected window.
 
 However, this command does nothing if the window is already too small to
 display the whole text of the buffer, or if part of the contents are
@@ -2223,8 +2227,8 @@
 @code{window-min-height} automatically deletes it, and no window may be
 created shorter than this.  The value is measured in line units.  When
 the window wants a mode line and/or a header line, they are counted as
-one line each.  The default value of this variable is @code{4}.  A value
-less than @code{1} is ignored.
+one line each.  The default value is @code{4}.  A value less than
address@hidden is ignored.
 @end defopt
 
 @defopt window-min-width
@@ -2367,7 +2371,8 @@
 
 @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.
+window configuration.  The default for @var{frame} is the selected
+frame.
 @end defun
 
 @defun set-window-configuration configuration
@@ -2475,22 +2480,22 @@
 additional information with windows.
 
 @defun window-parameter window parameter
-This function returns @var{window}'s value for @var{parameter}.
address@hidden defaults to the selected window.  If @var{window} has no
-setting for @var{parameter}, this function returns @code{nil}.
+This function returns @var{window}'s value for @var{parameter}.  The
+default for @var{window} is the selected window.  If @var{window}
+has no setting for @var{parameter}, this function returns @code{nil}.
 @end defun
 
 @defun window-parameters &optional window
 This function returns all parameters of @var{window} and their values.
address@hidden defaults to the selected window.  The return value is an
-association list of elements of the form @code{(@var{parameter}
+The default for @var{window} is the selected window.  The return value
+is an association list of elements of the form @code{(@var{parameter}
 . @var{value})}.
 @end defun
 
 @defun set-window-parameter window parameter value
 This function sets @var{window}'s value of @var{parameter} to
address@hidden and returns @var{value}.  @var{window} defaults to the
-selected window.
address@hidden and returns @var{value}.  The default for @var{window}
+is the selected window.
 @end defun
 
 Currently, window parameters are not saved in window configurations and