From: Eli Zaretskii Date: Sat, 6 Apr 2019 08:04:37 +0000 (+0300) Subject: Improve documentation of window parameters X-Git-Tag: emacs-26.2~16 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=92ce2dd;p=emacs.git 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) --- diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 7f0fcffaaf1..27940e12c79 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1956,7 +1956,13 @@ The optional argument @var{all-frames} has the same meaning as in @code{next-window}. 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 @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 optional argument @var{window} must be a live window and defaults to the selected one. The function's behavior is determined by the four -elements of the @code{quit-restore} window parameter (@pxref{Window -Parameters}), which is set to @code{nil} afterwards. +elements of the list specified by the @code{quit-restore} window +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 @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 @cindex window parameters -This section describes how window parameters can be used to associate -additional information with windows. +This section describes the window parameters that can be used to +associate additional information with windows. @defun window-parameter window parameter 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} This parameter is installed by the buffer display functions (@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 -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. - -See the description of @code{quit-restore-window} in @ref{Quitting -Windows} for details. - -@item window-side window-slot +@item window-side +@itemx window-slot @vindex window-side@r{, a window parameter} @vindex window-slot@r{, a window parameter} -These parameters are used for implementing side windows (@pxref{Side -Windows}). +These parameters are used internally for implementing side windows +(@pxref{Side Windows}). @item window-atom @vindex window-atom@r{, a window parameter} -This parameter is used for implementing atomic windows, see @ref{Atomic -Windows}. +This parameter is used internally for implementing atomic windows, see +@ref{Atomic Windows}. @item mode-line-format @vindex mode-line-format@r{, a window parameter} @@ -5947,11 +5955,12 @@ affected. @item min-margins @vindex min-margins@r{, a window parameter} -The value of this parameter is a cons cell whose @sc{car} and @sc{cdr}, -if non-@code{nil}, specify the minimum values (in columns) for the left -and right margin of this window. When present, Emacs will use these -values instead of the actual margin widths for determining whether a -window can be split or shrunk horizontally. +The value of this parameter is a cons cell whose @sc{car} and +@sc{cdr}, if non-@code{nil}, specify the minimum values (in columns) +for the left and right margin of this window (@pxref{Display Margins}. +When present, Emacs will use these values instead of the actual margin +widths for determining whether a window can be split or shrunk +horizontally. Emacs never auto-adjusts the margins of any window after splitting or resizing it. It is the sole responsibility of any application setting