Improve documentation of window parameters

* doc/lispref/windows.texi (Cyclic Window Ordering): Describe
the effect of the 'other-window' window parameter.
(Window Parameters): Improve the descriptions of window
parameters.  Move the detailed description of the
'quit-restore' window parameter from here...
(Quitting Windows): ...to here.  (Bug#35063)
This commit is contained in:
Eli Zaretskii 2019-04-06 11:04:37 +03:00
parent 6dc42c562c
commit 92ce2dd48b

View file

@ -1956,7 +1956,13 @@ The optional argument @var{all-frames} has the same meaning as in
@code{next-window}. @code{next-window}.
This function does not select a window that has a non-@code{nil} This function does not select a window that has a non-@code{nil}
@code{no-other-window} window parameter (@pxref{Window Parameters}). @code{no-other-window} window parameter (@pxref{Window Parameters}),
provided that @code{ignore-window-parameters} is @code{nil}.
If the @code{other-window} parameter of the selected window is a
function, and @code{ignore-window-parameters} is @code{nil}, that
function will be called with the arguments @var{count} and
@var{all-frames} instead of the normal operation of this function.
@end deffn @end deffn
@defun walk-windows fun &optional minibuf all-frames @defun walk-windows fun &optional minibuf all-frames
@ -3903,8 +3909,33 @@ described next to deal with the window and its buffer.
This function handles @var{window} and its buffer after quitting. The This function handles @var{window} and its buffer after quitting. The
optional argument @var{window} must be a live window and defaults to optional argument @var{window} must be a live window and defaults to
the selected one. The function's behavior is determined by the four the selected one. The function's behavior is determined by the four
elements of the @code{quit-restore} window parameter (@pxref{Window elements of the list specified by the @code{quit-restore} window
Parameters}), which is set to @code{nil} afterwards. parameter (@pxref{Window Parameters}), which is set to @code{nil}
afterwards.
The first element of the @code{quit-restore} parameter is one of the
symbols @code{window}, meaning that the window has been specially
created by @code{display-buffer}; @code{frame}, a separate frame has
been created; @code{same}, the window has only ever displayed this
buffer; or @code{other}, the window showed another buffer before.
@code{frame} and @code{window} affect how the window is quit, while
@code{same} and @code{other} affect the redisplay of buffers
previously shown in this window.
The second element is either one of the symbols @code{window} or
@code{frame}, or a list whose elements are the buffer shown in the
window before, that buffer's window start and window point positions,
and the window's height at that time. If that buffer is still live
when the window is quit, then the function @code{quit-restore-window}
reuses the window to display the buffer.
The third element is the window selected at the time the parameter was
created. If @code{quit-restore-window} deletes the window passed to
it as argument, it then tries to reselect this window.
The fourth element is the buffer whose display caused the creation of
this parameter. @code{quit-restore-window} deletes the specified window
only if it still shows that buffer.
The window is deleted entirely if: 1) the first element of the The window is deleted entirely if: 1) the first element of the
@code{quit-restore} parameter is one of 'window or 'frame, 2) the @code{quit-restore} parameter is one of 'window or 'frame, 2) the
@ -5754,8 +5785,8 @@ and heights, if possible. Frames are not resized by this function.
@section Window Parameters @section Window Parameters
@cindex window parameters @cindex window parameters
This section describes how window parameters can be used to associate This section describes the window parameters that can be used to
additional information with windows. associate additional information with windows.
@defun window-parameter window parameter @defun window-parameter window parameter
This function returns @var{window}'s value for @var{parameter}. The This function returns @var{window}'s value for @var{parameter}. The
@ -5888,44 +5919,21 @@ parameter is installed and updated by the function
@vindex quit-restore@r{, a window parameter} @vindex quit-restore@r{, a window parameter}
This parameter is installed by the buffer display functions This parameter is installed by the buffer display functions
(@pxref{Choosing Window}) and consulted by @code{quit-restore-window} (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
(@pxref{Quitting Windows}). It contains four elements: (@pxref{Quitting Windows}). It is a list of four elements, see the
description of @code{quit-restore-window} in @ref{Quitting Windows}
for details.
The first element is one of the symbols @code{window}, meaning that @item window-side
the window has been specially created by @code{display-buffer}; @itemx window-slot
@code{frame}, a separate frame has been created; @code{same}, the
window has only ever displayed this buffer; or @code{other}, the
window showed another buffer before. @code{frame} and @code{window}
affect how the window is quit, while @code{same} and @code{other}
affect the redisplay of buffers previously shown in this window.
The second element is either one of the symbols @code{window} or
@code{frame}, or a list whose elements are the buffer shown in the
window before, that buffer's window start and window point positions,
and the window's height at that time. If that buffer is still live
when the window is quit, then the function @code{quit-restore-window}
reuses the window to display the buffer.
The third element is the window selected at the time the parameter was
created. If @code{quit-restore-window} deletes the window passed to
it as argument, it then tries to reselect this window.
The fourth element is the buffer whose display caused the creation of
this parameter. @code{quit-restore-window} deletes the specified window
only if it still shows that buffer.
See the description of @code{quit-restore-window} in @ref{Quitting
Windows} for details.
@item window-side window-slot
@vindex window-side@r{, a window parameter} @vindex window-side@r{, a window parameter}
@vindex window-slot@r{, a window parameter} @vindex window-slot@r{, a window parameter}
These parameters are used for implementing side windows (@pxref{Side These parameters are used internally for implementing side windows
Windows}). (@pxref{Side Windows}).
@item window-atom @item window-atom
@vindex window-atom@r{, a window parameter} @vindex window-atom@r{, a window parameter}
This parameter is used for implementing atomic windows, see @ref{Atomic This parameter is used internally for implementing atomic windows, see
Windows}. @ref{Atomic Windows}.
@item mode-line-format @item mode-line-format
@vindex mode-line-format@r{, a window parameter} @vindex mode-line-format@r{, a window parameter}
@ -5947,11 +5955,12 @@ affected.
@item min-margins @item min-margins
@vindex min-margins@r{, a window parameter} @vindex min-margins@r{, a window parameter}
The value of this parameter is a cons cell whose @sc{car} and @sc{cdr}, The value of this parameter is a cons cell whose @sc{car} and
if non-@code{nil}, specify the minimum values (in columns) for the left @sc{cdr}, if non-@code{nil}, specify the minimum values (in columns)
and right margin of this window. When present, Emacs will use these for the left and right margin of this window (@pxref{Display Margins}.
values instead of the actual margin widths for determining whether a When present, Emacs will use these values instead of the actual margin
window can be split or shrunk horizontally. widths for determining whether a window can be split or shrunk
horizontally.
Emacs never auto-adjusts the margins of any window after splitting or Emacs never auto-adjusts the margins of any window after splitting or
resizing it. It is the sole responsibility of any application setting resizing it. It is the sole responsibility of any application setting