diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 23da5634889..adb52dc7f2b 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,20 @@ +2012-11-23 Martin Rudalics + + * windows.texi (Basic Windows): Fix typo. + (Windows and Frames): Fix example. Move description of + window-in-direction here. + (Recombining Windows): Fix example. + (Buffers and Windows): Fix description of + replace-buffer-in-windows. + (Switching Buffers): Reword. + (Display Action Functions): Minor adjustments. + (Choosing Window Options): Minor fixes. + (Window History): Minor rewording. + (Dedicated Windows): Correct and reword part describing how + dedicatedness affects functions removing buffers or windows. + * buffers.texi (The Buffer List): Fix description of + bury-buffer. + 2012-11-23 Chong Yidong * modes.texi (%-Constructs): Fix statement about mode construct diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 4a556895de7..6462788b34e 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -886,7 +886,7 @@ This buffer therefore becomes the least desirable candidate for @code{other-buffer} to return. The argument can be either a buffer itself or the name of one. -This functions operates on each frame's @code{buffer-list} parameter as +This function operates on each frame's @code{buffer-list} parameter as well as the fundamental buffer list; therefore, the buffer that you bury will come last in the value of @code{(buffer-list @var{frame})} and in the value of @code{(buffer-list)}. In addition, it also puts the buffer @@ -896,15 +896,15 @@ History}) provided it is shown in that window. If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the current buffer. In addition, if the current buffer is displayed in the selected window, this makes sure that the window is either deleted or -another buffer is shown in it. More precisely, if the window is -dedicated (@pxref{Dedicated Windows}) and there are other windows on its -frame, the window is deleted. If the window is both dedicated and the -only window on its frame's terminal, the function specified by -@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal -with the window. If the window is not dedicated to its buffer, it calls -@code{switch-to-prev-buffer} (@pxref{Window History}) to show another -buffer in that window. If @var{buffer-or-name} is displayed in some -other window, it remains displayed there. +another buffer is shown in it. More precisely, if the selected window +is dedicated (@pxref{Dedicated Windows}) and there are other windows on +its frame, the window is deleted. If it is the only window on its frame +and that frame is not the only frame on its terminal, the frame is +``dismissed'' by calling the function specified by +@code{frame-auto-hide-function} (@pxref{Quitting Windows}). Otherwise, +it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show +another buffer in that window. If @var{buffer-or-name} is displayed in +some other window, it remains displayed there. To replace a buffer in all the windows that display it, use @code{replace-buffer-in-windows}, @xref{Buffers and Windows}. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 46b31ef0d9f..224c4736c92 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -51,9 +51,9 @@ is displayed in windows. @section Basic Concepts of Emacs Windows @cindex window -A @dfn{window} is a area of the screen that is used to display a -buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a -special Lisp object type. +A @dfn{window} is an area of the screen that is used to display a buffer +(@pxref{Buffers}). In Emacs Lisp, windows are represented by a special +Lisp object type. @cindex multiple windows Windows are grouped into frames (@pxref{Frames}). Each frame @@ -247,12 +247,12 @@ following example: @end smallexample @noindent -The root window of this frame is an internal window, @code{W1}. Its +The root window of this frame is an internal window, @var{W1}. Its child windows form a horizontal combination, consisting of the live -window @code{W2} and the internal window @code{W3}. The child windows -of @code{W3} form a vertical combination, consisting of the live -windows @code{W4} and @code{W5}. Hence, the live windows in this -window tree are @code{W2} @code{W4}, and @code{W5}. +window @var{W2} and the internal window @var{W3}. The child windows +of @var{W3} form a vertical combination, consisting of the live +windows @var{W4} and @var{W5}. Hence, the live windows in this +window tree are @var{W2} @var{W4}, and @var{W5}. The following functions can be used to retrieve a child window of an internal window, and the siblings of a child window. @@ -308,8 +308,8 @@ The functions @code{window-next-sibling} and and previous window, respectively, in the cyclic ordering of windows (@pxref{Cyclic Window Ordering}). - You can use the following functions to find the first live window on -a frame, and to retrieve the entire window tree of a frame: + You can use the following functions to find the first live window on a +frame and the window nearest to a given window. @defun frame-first-window &optional frame-or-window This function returns the live window at the upper left corner of the @@ -318,9 +318,32 @@ frame specified by @var{frame-or-window}. The argument to the selected frame. If @var{frame-or-window} specifies a window, this function returns the first window on that window's frame. Under the assumption that the frame from our canonical example is selected -@code{(frame-first-window)} returns @code{W2}. +@code{(frame-first-window)} returns @var{W2}. @end defun +@cindex window in direction +@defun window-in-direction direction &optional window ignore +This function returns the nearest live window in direction +@var{direction} as seen from the position of @code{window-point} in +window @var{window}. The argument @var{direction} must be one of +@code{above}, @code{below}, @code{left} or @code{right}. The optional +argument @var{window} must denote a live window and defaults to the +selected one. + +This function does not return a window whose @code{no-other-window} +parameter is non-@code{nil} (@pxref{Window Parameters}). If the nearest +window's @code{no-other-window} parameter is non-@code{nil}, this +function tries to find another window in the indicated direction whose +@code{no-other-window} parameter is @code{nil}. If the optional +argument @var{ignore} is non-@code{nil}, a window may be returned even +if its @code{no-other-window} parameter is non-@code{nil}. + +If it doesn't find a suitable window, this function returns @code{nil}. +@end defun + +The following function allows to retrieve the entire window tree of a +frame: + @defun window-tree &optional frame This function returns a list representing the window tree for frame @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to @@ -925,9 +948,9 @@ are the opposite of what they are in those other functions. @node Recombining Windows @section Recombining Windows -When deleting the last sibling of a window @code{W}, its parent window -is deleted too, with @code{W} replacing it in the window tree. This -means that @code{W} must be recombined with its parent's siblings to +When deleting the last sibling of a window @var{W}, its parent window +is deleted too, with @var{W} replacing it in the window tree. This +means that @var{W} must be recombined with its parent's siblings to form a new window combination (@pxref{Windows and Frames}). In some occasions, deleting a live window may even entail the deletion of two internal windows. @@ -952,20 +975,20 @@ internal windows. @end smallexample @noindent -Deleting @code{W5} in this configuration normally causes the deletion of -@code{W3} and @code{W4}. The remaining live windows @code{W2}, -@code{W6} and @code{W7} are recombined to form a new horizontal -combination with parent @code{W1}. +Deleting @var{W5} in this configuration normally causes the deletion of +@var{W3} and @var{W4}. The remaining live windows @var{W2}, +@var{W6} and @var{W7} are recombined to form a new horizontal +combination with parent @var{W1}. Sometimes, however, it makes sense to not delete a parent window like -@code{W4}. In particular, a parent window should not be removed when it +@var{W4}. In particular, a parent window should not be removed when it was used to preserve a combination embedded in a combination of the same type. Such embeddings make sense to assure that when you split a window and subsequently delete the new window, Emacs reestablishes the layout of the associated frame as it existed before the splitting. - Consider a scenario starting with two live windows @code{W2} and -@code{W3} and their parent @code{W1}. + Consider a scenario starting with two live windows @var{W2} and +@var{W3} and their parent @var{W1}. @smallexample @group @@ -988,7 +1011,7 @@ of the associated frame as it existed before the splitting. @end smallexample @noindent -Split @code{W2} to make a new window @code{W4} as follows. +Split @var{W2} to make a new window @var{W4} as follows. @smallexample @group @@ -1013,8 +1036,8 @@ Split @code{W2} to make a new window @code{W4} as follows. @noindent Now, when enlarging a window vertically, Emacs tries to obtain the corresponding space from its lower sibling, provided such a window -exists. In our scenario, enlarging @code{W4} will steal space from -@code{W3}. +exists. In our scenario, enlarging @var{W4} will steal space from +@var{W3}. @smallexample @group @@ -1037,8 +1060,8 @@ exists. In our scenario, enlarging @code{W4} will steal space from @end smallexample @noindent -Deleting @code{W4} will now give its entire space to @code{W2}, -including the space earlier stolen from @code{W3}. +Deleting @var{W4} will now give its entire space to @var{W2}, +including the space earlier stolen from @var{W3}. @smallexample @group @@ -1061,12 +1084,12 @@ including the space earlier stolen from @code{W3}. @end smallexample @noindent -This can be counterintutive, in particular if @code{W4} were used for +This can be counterintutive, in particular if @var{W4} were used for displaying a buffer only temporarily (@pxref{Temporary Displays}), and you want to continue working with the initial layout. The behavior can be fixed by making a new parent window when splitting -@code{W2}. The variable described next allows to do that. +@var{W2}. The variable described next allows to do that. @defopt window-combination-limit This variable controls whether splitting a window shall make a new @@ -1108,7 +1131,7 @@ internal window. This affects how the window tree is rearranged when the child windows are deleted (see below). @end defopt - If @code{window-combination-limit} is @code{t}, splitting @code{W2} in + If @code{window-combination-limit} is @code{t}, splitting @var{W2} in the initial configuration of our scenario would have produced this: @smallexample @@ -1132,12 +1155,12 @@ the initial configuration of our scenario would have produced this: @end smallexample @noindent -A new internal window @code{W5} has been created; its children are -@code{W2} and the new live window @code{W4}. Now, @code{W2} is the only -sibling of @code{W4}, so enlarging @code{W4} will try to shrink -@code{W2}, leaving @code{W3} unaffected. Observe that @code{W5} +A new internal window @var{W5} has been created; its children are +@var{W2} and the new live window @var{W4}. Now, @var{W2} is the only +sibling of @var{W4}, so enlarging @var{W4} will try to shrink +@var{W2}, leaving @var{W3} unaffected. Observe that @var{W5} represents a vertical combination of two windows embedded in the -vertical combination @code{W1}. +vertical combination @var{W1}. @cindex window combination limit @defun set-window-combination-limit window limit @@ -1162,9 +1185,9 @@ windows of @var{window} are never automatically recombined with its siblings. If, in the configuration shown at the beginning of this section, the -combination limit of @code{W4} (the parent window of @code{W6} and -@code{W7}) is @code{t}, deleting @code{W5} will not implicitly delete -@code{W4} too. +combination limit of @var{W4} (the parent window of @var{W6} and +@var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete +@var{W4} too. @end defun Alternatively, the problems sketched above can be avoided by always @@ -1215,7 +1238,7 @@ the following frame layout. @noindent If @code{window-combination-resize} is @code{nil}, splitting window -@code{W3} leaves the size of @code{W2} unchanged: +@var{W3} leaves the size of @var{W2} unchanged: @smallexample @group @@ -1238,7 +1261,7 @@ If @code{window-combination-resize} is @code{nil}, splitting window @end smallexample @noindent -If @code{window-combination-resize} is @code{t}, splitting @code{W3} +If @code{window-combination-resize} is @code{t}, splitting @var{W3} instead leaves all three live windows with approximately the same height: @@ -1263,7 +1286,7 @@ height: @end smallexample @noindent -Deleting any of the live windows @code{W2}, @code{W3} or @code{W4} will +Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will distribute its space proportionally among the two remaining live windows. @@ -1510,25 +1533,6 @@ windows to search, and have the same meanings as in @code{next-window}. @end defun -@cindex window in direction -@defun window-in-direction direction &optional window ignore -This function returns the nearest window in direction @var{direction} as -seen from the position of @code{window-point} in window @var{window}. -The argument @var{direction} must be one of @code{above}, @code{below}, -@code{left} or @code{right}. The optional argument @var{window} must -denote a live window and defaults to the selected one. - -This function does not return a window whose @code{no-other-window} -parameter is non-@code{nil}. If the nearest window's -@code{no-other-window} parameter is non-@code{nil}, this function tries -to find another window in the indicated direction whose -@code{no-other-window} parameter is @code{nil}. If the optional -argument @var{ignore} is non-@code{nil}, a window may be returned even -if its @code{no-other-window} parameter is non-@code{nil}. - -If it doesn't find a suitable window, this function returns @code{nil}. -@end defun - @node Buffers and Windows @section Buffers and Windows @@ -1631,28 +1635,30 @@ behave exactly like in @code{get-buffer-window}. @deffn Command replace-buffer-in-windows &optional buffer-or-name This command replaces @var{buffer-or-name} with some other buffer, in -all windows displaying it. @var{buffer-or-name} should be a buffer, -or the name of an existing buffer; if omitted or @code{nil}, it -defaults to the current buffer. +all windows displaying it. @var{buffer-or-name} should be a buffer, or +the name of an existing buffer; if omitted or @code{nil}, it defaults to +the current buffer. The replacement buffer in each window is chosen via @code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated -window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated -Windows}), unless it is the only window on its frame---if it is the -only window, and that frame is not the only frame on its terminal, the -frame is ``dismissed'' by calling the function specified by -@code{frame-auto-hide-function} (@pxref{Quitting Windows}). If the -dedicated window is the only window on the only frame on its terminal, -the buffer is replaced anyway. +window displaying @var{buffer-or-name} is deleted if possible +(@pxref{Dedicated Windows}). If such a window is the only window on its +frame and there are other frames on the same terminal, the frame is +deleted as well. If the dedicated window is the only window on the only +frame on its terminal, the buffer is replaced anyway. @end deffn + @node Switching Buffers @section Switching to a Buffer in a Window @cindex switching to a buffer @cindex displaying a buffer - This section describes high-level functions for switching to a -specified buffer in some window. +This section describes high-level functions for switching to a specified +buffer in some window. In general, ``switching to a buffer'' means to +(1) show the buffer in some window, (2) make that window the selected +window (and its frame the selected frame), and (3) make the buffer the +current buffer. Do @emph{not} use these functions to make a buffer temporarily current just so a Lisp program can access or modify it. They have @@ -1664,9 +1670,9 @@ to make a buffer current to modify it in Lisp, use @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window This command attempts to display @var{buffer-or-name} in the selected -window, and makes it the current buffer. It is often used -interactively (as the binding of @kbd{C-x b}), as well as in Lisp -programs. The return value is the buffer switched to. +window and make it the current buffer. It is often used interactively +(as the binding of @kbd{C-x b}), as well as in Lisp programs. The +return value is the buffer switched to. If @var{buffer-or-name} is @code{nil}, it defaults to the buffer returned by @code{other-buffer} (@pxref{The Buffer List}). If @@ -1690,9 +1696,8 @@ normally tries to display the buffer in some other window, by invoking instead. @end deffn -By default, @code{switch-to-buffer} sets @code{window-point} of the -window used to the buffer's position of @code{point}. This behavior can -be tuned using the following option. +By default, @code{switch-to-buffer} shows the buffer at its position of +@code{point}. This behavior can be tuned using the following option. @defopt switch-to-buffer-preserve-window-point If this variable is @code{nil}, @code{switch-to-buffer} displays the @@ -1710,13 +1715,13 @@ selected window or never appeared in it before, or if buffer. @end defopt -The next two functions are similar to @code{switch-to-buffer}, except -for the described features. +The next two commands are similar to @code{switch-to-buffer}, except for +the described features. @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord -This function makes the buffer specified by @var{buffer-or-name} -current and displays it in some window other than the selected window. -It uses the function @code{pop-to-buffer} internally (see below). +This function displays the buffer specified by @var{buffer-or-name} in +some window other than the selected window. It uses the function +@code{pop-to-buffer} internally (see below). If the selected window already displays the specified buffer, it continues to do so, but another window is nonetheless found to display @@ -1727,9 +1732,9 @@ meanings as in @code{switch-to-buffer}. @end deffn @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord -This function makes the buffer specified by @var{buffer-or-name} -current and displays it, usually in a new frame. It uses the function -@code{pop-to-buffer} (see below). +This function displays the buffer specified by @var{buffer-or-name} in a +new frame. It uses the function @code{pop-to-buffer} internally (see +below). If the specified buffer is already displayed in another window, in any frame on the current terminal, this switches to that window instead of @@ -1987,8 +1992,8 @@ of the window; its return value is ignored. @end itemize This function can fail if no window splitting can be performed for some -reason (e.g. if there is just one frame and it has an -@code{unsplittable} frame parameter; @pxref{Buffer Parameters}). +reason (e.g. if the selected frame has an @code{unsplittable} frame +parameter; @pxref{Buffer Parameters}). @end defun @defun display-buffer-below-selected buffer alist @@ -2035,14 +2040,15 @@ example. @noindent Evaluating the form above will cause @code{display-buffer} to proceed as -follows: If `*foo*' already appears on a visible or iconified frame, it -will reuse its window. Otherwise, it will try to pop up a new window -or, if that is impossible, a new frame. If all these steps fail, it -will proceed using whatever @code{display-buffer-base-action} and +follows: If a buffer called *foo* already appears on a visible or +iconified frame, it will reuse its window. Otherwise, it will try to +pop up a new window or, if that is impossible, a new frame and show the +buffer there. If all these steps fail, it will proceed using whatever +@code{display-buffer-base-action} and @code{display-buffer-fallback-action} prescribe. Furthermore, @code{display-buffer} will try to adjust a reused window -(provided `*foo*' was put by @code{display-buffer} there before) or a +(provided *foo* was put by @code{display-buffer} there before) or a popped-up window as follows: If the window is part of a vertical combination, it will set its height to ten lines. Note that if, instead of the number ``10'', we specified the function @@ -2077,10 +2083,10 @@ and @code{split-width-threshold} (@pxref{Choosing Window Options}). @end example @noindent -Evaluating this form will cause @code{display-buffer} to first try -reusing a window showing @code{*foo*} on the selected frame. -If no such window exists, it will try to split the selected window or, -if that is impossible, use the window below the selected window. +This form will have @code{display-buffer} first try reusing a window +that shows *foo* on the selected frame. If there's no such window, it +will try to split the selected window or, if that is impossible, use the +window below the selected window. If there's no window below the selected one, or the window below the selected one is dedicated to its buffer, @code{display-buffer} will @@ -2119,8 +2125,8 @@ make a new window for displaying a buffer. It is used by the the window (@pxref{Display Action Functions}). The default value is @code{split-window-sensibly}, which is documented -below. The value must be a function that takes one argument, a -window, and return either a new window (which is used to display the +below. The value must be a function that takes one argument, a window, +and return either a new window (which will be used to display the desired buffer) or @code{nil} (which means the splitting failed). @end defopt @@ -2198,15 +2204,15 @@ Parameters}), which is used by the default function in @defopt same-window-buffer-names A list of buffer names for buffers that should be displayed in the selected window. If a buffer's name is in this list, -@code{display-buffer} handles the buffer by switching to it in the -selected window. +@code{display-buffer} handles the buffer by showing it in the selected +window. @end defopt @defopt same-window-regexps A list of regular expressions that specify buffers that should be displayed in the selected window. If the buffer's name matches any of the regular expressions in this list, @code{display-buffer} handles the -buffer by switching to it in the selected window. +buffer by showing it in the selected window. @end defopt @defun same-window-p buffer-name @@ -2219,22 +2225,23 @@ put it in the selected window. @section Window History @cindex window history -Each window remembers the buffers it has previously displayed, and the order -in which these buffers were removed from it. This history is used, -for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and -Windows}). This list is automatically maintained by Emacs, but you can -use the following functions to explicitly inspect or alter it: +Each window remembers in a list the buffers it has previously displayed, +and the order in which these buffers were removed from it. This history +is used, for example, by @code{replace-buffer-in-windows} +(@pxref{Buffers and Windows}). The list is automatically maintained by +Emacs, but you can use the following functions to explicitly inspect or +alter it: @defun window-prev-buffers &optional window This function returns a list specifying the previous contents of -@var{window}, which should be a live window and defaults to the -selected window. +@var{window}. The optional argument @var{window} should be a live +window and defaults to the selected one. 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 -that buffer was last shown. +that buffer was last shown in @var{window}. The list is ordered so that earlier elements correspond to more recently-shown buffers, and the first element usually corresponds to the @@ -2331,29 +2338,31 @@ Functions for displaying a buffer can be told to not use specific windows by marking these windows as @dfn{dedicated} to their buffers. @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated window for displaying another buffer in it. @code{get-lru-window} and -@code{get-largest-window} (@pxref{Selecting Windows}) do not consider -dedicated windows as candidates when their @var{dedicated} argument is -non-@code{nil}. The behavior of @code{set-window-buffer} +@code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not +consider dedicated windows as candidates when their @var{dedicated} +argument is non-@code{nil}. The behavior of @code{set-window-buffer} (@pxref{Buffers and Windows}) with respect to dedicated windows is slightly different, see below. -When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to -delete a dedicated window and that window is the only window on its -frame, it deletes the window's frame too, provided there are other -frames left. @code{replace-buffer-in-windows} (@pxref{Switching -Buffers}) tries to delete all dedicated windows showing its buffer -argument. When such a window is the only window on its frame, that -frame is deleted, provided there are other frames left. If there are -no more frames left, some other buffer is displayed in the window, and -the window is marked as non-dedicated. + Functions supposed to remove a buffer from a window or a window from +a frame can behave specially when a window they operate on is dedicated. +We will distinguish three basic cases, namely where (1) the window is +not the only window on its frame, (2) the window is the only window on +its frame but there are other frames on the same terminal left, and (3) +the window is the only window on the only frame on the same terminal. -When you kill a buffer (@pxref{Killing Buffers}) displayed in a -dedicated window, any such window usually gets deleted too, since -@code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning -up windows. Burying a buffer (@pxref{The Buffer List}) deletes the -selected window if it is dedicated to that buffer. If, however, that -window is the only window on its frame, @code{bury-buffer} displays -another buffer in it and iconifies the frame. + In particular, @code{delete-windows-on} (@pxref{Deleting Windows}) +handles case (2) by deleting the associated frame and case (3) by +showing another buffer in that frame's only window. The function +@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. + + When @code{bury-buffer} (@pxref{The Buffer List}) operates on the +selected window (which shows the buffer that shall be buried), it +handles case (2) by calling @code{frame-auto-hide-function} +(@pxref{Quitting Windows}) to deal with the selected frame. The other +two cases are handled as with @code{replace-buffer-in-windows}. @defun window-dedicated-p &optional window This function returns non-@code{nil} if @var{window} is dedicated to its