emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] /srv/bzr/emacs/trunk r105904: Window-related updates to NE


From: Chong Yidong
Subject: [Emacs-diffs] /srv/bzr/emacs/trunk r105904: Window-related updates to NEWS and Emacs manual.
Date: Sat, 24 Sep 2011 14:19:20 -0400
User-agent: Bazaar (2.3.1)

------------------------------------------------------------
revno: 105904
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-09-24 14:19:20 -0400
message:
  Window-related updates to NEWS and Emacs manual.
  
  * etc/NEWS: Reorganize, placing user options in Changes section.
  
  * doc/emacs/buffers.texi (Select Buffer): Clarify description of
  buffer-switching commands.  Add xref to Window Display node.
  Don't repeat confirm-nonexistent-file-or-buffer description from
  Visiting node.  Remove even-window-heights.
  
  * doc/emacs/frames.texi (Special Buffer Frames): Add xref to Window Choice.
  
  * doc/emacs/windows.texi (Pop Up Window): Defer discussion of window
  splitting to the Window Choice node.  Add index entries.
  (Force Same Window): Node deleted.
  (Displaying Buffers, Window Choice): New nodes.
modified:
  doc/emacs/ChangeLog
  doc/emacs/buffers.texi
  doc/emacs/emacs.texi
  doc/emacs/frames.texi
  doc/emacs/windows.texi
  etc/NEWS
=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-09-18 20:01:37 +0000
+++ b/doc/emacs/ChangeLog       2011-09-24 18:19:20 +0000
@@ -1,3 +1,17 @@
+2011-09-24  Chong Yidong  <address@hidden>
+
+       * windows.texi (Pop Up Window): Defer discussion of window
+       splitting to the Window Choice node.  Add index entries.
+       (Force Same Window): Node deleted.
+       (Displaying Buffers, Window Choice): New nodes.
+
+       * buffers.texi (Select Buffer): Clarify description of
+       buffer-switching commands.  Add xref to Window Display node.
+       Don't repeat confirm-nonexistent-file-or-buffer description from
+       Visiting node.  Remove even-window-heights.
+
+       * frames.texi (Special Buffer Frames): Add xref to Window Choice.
+
 2011-09-18  Chong Yidong  <address@hidden>
 
        * cmdargs.texi (Icons X): Fix description of Emacs icon.

=== modified file 'doc/emacs/buffers.texi'
--- a/doc/emacs/buffers.texi    2011-08-28 21:07:10 +0000
+++ b/doc/emacs/buffers.texi    2011-09-24 18:19:20 +0000
@@ -91,9 +91,9 @@
 @var{bufname} @key{RET}}.  This runs the command
 @code{switch-to-buffer} with argument @var{bufname}.  While entering
 the buffer name, you can use the usual minibuffer completion and
-history commands (@pxref{Minibuffer}).  An empty argument to @kbd{C-x
-b} specifies the buffer that was current most recently among those not
-now displayed in any window.
+history commands (@pxref{Minibuffer}).  An empty input specifies the
+buffer that was current most recently among those not now displayed in
+any window.
 
 @cindex minibuffer confirmation
 @cindex confirming in the minibuffer
@@ -107,16 +107,8 @@
 realizing that @key{TAB} did not complete far enough to yield the
 desired buffer name (@pxref{Completion}).  Emacs asks for confirmation
 by putting the message @samp{[Confirm]} in the minibuffer; type
address@hidden again to confirm and visit the buffer.
-
address@hidden confirm-nonexistent-file-or-buffer
-  The variable @code{confirm-nonexistent-file-or-buffer} controls
-whether Emacs asks for confirmation before visiting a buffer that did
-not previously exist.  The default value, @code{after-completion},
-gives the behavior we have just described.  If the value is
address@hidden, Emacs never asks for confirmation; for any other
address@hidden value, Emacs always asks for confirmation.  This
-variable also affects the @code{find-file} command (@pxref{Visiting}).
address@hidden again to confirm and visit the buffer.  @xref{Visiting}, for
+information about modifying this behavior.
 
   One reason to create a new buffer is to use it for making temporary
 notes.  If you try to save it, Emacs asks for the file name to use.
@@ -136,36 +128,26 @@
 
 @kindex C-x 4 b
 @findex switch-to-buffer-other-window
address@hidden even-window-heights
   To select a buffer in a window other than the current one, type
 @kbd{C-x 4 b} (@code{switch-to-buffer-other-window}).  This prompts
 for a buffer name using the minibuffer, displays that buffer in
-another window, and selects that window.  By default, if displaying
-the buffer causes two vertically adjacent windows to be displayed, the
-heights of those windows are evened out; to countermand that and
-preserve the window configuration, set the variable
address@hidden to @code{nil}.
+another window, and selects that window.
 
 @kindex C-x 5 b
 @findex switch-to-buffer-other-frame
   Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame})
 prompts for a buffer name, displays that buffer in another frame, and
-selects that frame.
+selects that frame.  If the buffer is already being shown in a window
+on another frame, Emacs selects that window and frame instead of
+creating a new frame.
+
+  @xref{Displaying Buffers}, for how the @kbd{C-x 4 b} and @kbd{C-x 5
+b} commands get the window and/or frame to display in.
 
   In addition, @kbd{C-x C-f}, and any other command for visiting a
 file, can also be used to switch to an existing file-visiting buffer.
 @xref{Visiting}.
 
address@hidden display-buffer-reuse-frames
-  You can control how certain buffers are handled by these commands by
-customizing the variables @code{special-display-buffer-names},
address@hidden, @code{same-window-buffer-names}, and
address@hidden  See @ref{Force Same Window}, and
address@hidden Buffer Frames}, for more about these variables.  In
-addition, if the value of @code{display-buffer-reuse-frames} is
address@hidden, and the buffer you want to switch to is already
-displayed in some frame, Emacs will just raise that frame.
-
 @findex goto-line
   @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix
 argument, reads a number @var{n} using the minibuffer, selects the

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-08-28 21:07:10 +0000
+++ b/doc/emacs/emacs.texi      2011-09-24 18:19:20 +0000
@@ -488,9 +488,8 @@
 * Split Window::        New windows are made by splitting existing windows.
 * Other Window::        Moving to another window or doing something to it.
 * Pop Up Window::       Finding a file or buffer in another window.
-* Force Same Window::   Forcing certain buffers to appear in the selected
-                          window rather than in another window.
 * Change Window::       Deleting windows and changing their sizes.
+* Displaying Buffers::  How Emacs picks a window for displaying a buffer.
 * Window Convenience::  Convenience functions for window handling.
 
 Frames and Graphical Displays

=== modified file 'doc/emacs/frames.texi'
--- a/doc/emacs/frames.texi     2011-09-12 14:48:34 +0000
+++ b/doc/emacs/frames.texi     2011-09-24 18:19:20 +0000
@@ -850,11 +850,12 @@
 
 @vindex special-display-buffer-names
   You can make certain chosen buffers, which Emacs normally displays
-in ``another window,'' appear in special frames of their own.  To do
-this, set the variable @code{special-display-buffer-names} to a list
-of buffer names; any buffer whose name is in that list automatically
-gets a special frame, when an Emacs command wants to display it ``in
-another window.''
+in ``some other window'' (@pxref{Displaying Buffers}), appear in
+special frames of their own.  To do this, set the variable
address@hidden to a list of buffer names; any
+buffer whose name is in that list automatically gets a special frame.
address@hidden Choice}, for how this fits in with the other ways for
+Emacs to choose a window to display in.
 
   For example, if you set the variable this way,
 
@@ -906,13 +907,6 @@
 calling @var{function}; its first argument is the buffer, and its
 remaining arguments are @var{args}.
 
-   An analogous feature lets you specify buffers which should be
-displayed in the selected window.  @xref{Force Same Window}.  The
-same-window feature takes precedence over the special-frame feature;
-therefore, if you add a buffer name to
address@hidden and it has no effect, check to see
-whether that feature is also in use for the same buffer name.
-
 @node Frame Parameters
 @section Setting Frame Parameters
 @cindex Auto-Raise mode

=== modified file 'doc/emacs/windows.texi'
--- a/doc/emacs/windows.texi    2011-05-17 02:26:56 +0000
+++ b/doc/emacs/windows.texi    2011-09-24 18:19:20 +0000
@@ -18,9 +18,8 @@
 * Split Window::        New windows are made by splitting existing windows.
 * Other Window::        Moving to another window or doing something to it.
 * Pop Up Window::       Finding a file or buffer in another window.
-* Force Same Window::   Forcing certain buffers to appear in the selected
-                          window rather than in another window.
 * Change Window::       Deleting windows and changing their sizes.
+* Displaying Buffers::  How Emacs picks a window for displaying a buffer.
 * Window Convenience::  Convenience functions for window handling.
 @end menu
 
@@ -191,84 +190,47 @@
 
 @cindex selecting buffers in other windows
 @kindex C-x 4
-  @kbd{C-x 4} is a prefix key for commands that select another window
-(splitting the window if there is only one) and select a buffer in that
-window.  Different @kbd{C-x 4} commands have different ways of finding the
-buffer to select.
+  @kbd{C-x 4} is a prefix key for a variety of commands that switch to
+a buffer in a different window---either another existing window, or a
+new window created by splitting the selected window.  @xref{Window
+Choice}, for how Emacs picks or creates the window to use.
 
 @table @kbd
address@hidden switch-to-buffer-other-window
 @item C-x 4 b @var{bufname} @key{RET}
-Select buffer @var{bufname} in another window.  This runs
address@hidden
+Select buffer @var{bufname} in another window
+(@code{switch-to-buffer-other-window}).
+
address@hidden display-buffer
 @item C-x 4 C-o @var{bufname} @key{RET}
-Display buffer @var{bufname} in another window, but
-don't select that buffer or that window.  This runs
address@hidden
+Display buffer @var{bufname} in some window, without trying to select
+it (@code{display-buffer}).  @xref{Displaying Buffers}, for details
+about how the window is chosen.
+
address@hidden find-file-other-window
 @item C-x 4 f @var{filename} @key{RET}
-Visit file @var{filename} and select its buffer in another window.  This
-runs @code{find-file-other-window}.  @xref{Visiting}.
+Visit file @var{filename} and select its buffer in another window
+(@code{find-file-other-window}).  @xref{Visiting}.
+
address@hidden dired-other-window
 @item C-x 4 d @var{directory} @key{RET}
-Select a Dired buffer for directory @var{directory} in another window.
-This runs @code{dired-other-window}.  @xref{Dired}.
+Select a Dired buffer for directory @var{directory} in another window
+(@code{dired-other-window}).  @xref{Dired}.
+
address@hidden mail-other-window
 @item C-x 4 m
-Start composing a mail message in another window.  This runs
address@hidden; its same-window analogue is @kbd{C-x m}
-(@pxref{Sending Mail}).
+Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending
+Mail}), but in another window (@code{mail-other-window}).
+
address@hidden find-tag-other-window
 @item C-x 4 .
-Find a tag in the current tags table, in another window.  This runs
address@hidden, the multiple-window variant of @kbd{M-.}
-(@pxref{Tags}).
+Find a tag in the current tags table, similar to @kbd{M-.}
+(@pxref{Tags}), but in another window (@code{find-tag-other-window}).
 @item C-x 4 r @var{filename} @key{RET}
 Visit file @var{filename} read-only, and select its buffer in another
-window.  This runs @code{find-file-read-only-other-window}.
address@hidden
+window (@code{find-file-read-only-other-window}).  @xref{Visiting}.
 @end table
 
address@hidden split-height-threshold
address@hidden split-width-threshold
-  By default, these commands split the window vertically when there is
-only one.  You can customize the variables @code{split-height-threshold}
-and @code{split-width-threshold} to split the window horizontally
-instead.
-
-
address@hidden Force Same Window
address@hidden Forcing Display in the Same Window
-
-  Certain Emacs commands switch to a specific buffer with special
-contents.  For example, @kbd{M-x shell} switches to a buffer named
address@hidden  By convention, all these commands are written to pop up
-the buffer in a separate window.  But you can specify that certain of
-these buffers should appear in the selected window.
-
address@hidden same-window-buffer-names
-  If you add a buffer name to the list @code{same-window-buffer-names},
-the effect is that such commands display that particular buffer by
-switching to it in the selected window.  For example, if you add the
-element @code{"*grep*"} to the list, the @code{grep} command will
-display its output buffer in the selected window.
-
-  The default value of @code{same-window-buffer-names} is not
address@hidden: it specifies buffer names @samp{*info*}, @samp{*mail*} and
address@hidden (as well as others used by more obscure Emacs packages).
-This is why @kbd{M-x shell} normally switches to the @samp{*shell*}
-buffer in the selected window.  If you delete this element from the
-value of @code{same-window-buffer-names}, the behavior of @kbd{M-x
-shell} will change---it will pop up the buffer in another window
-instead.
-
address@hidden same-window-regexps
-  You can specify these buffers more generally with the variable
address@hidden  Set it to a list of regular expressions;
-then any buffer whose name matches one of those regular expressions is
-displayed by switching to it in the selected window.  (Once again, this
-applies only to buffers that normally get displayed for you in a
-separate window.)  The default value of this variable specifies Telnet
-and rlogin buffers.
-
-  An analogous feature lets you specify buffers which should be
-displayed in their own individual frames.  @xref{Special Buffer Frames}.
-
 @node Change Window
 @section Deleting and Rearranging Windows
 
@@ -356,6 +318,113 @@
   Mouse clicks on the mode line provide another way to change window
 heights and to delete windows.  @xref{Mode Line Mouse}.
 
address@hidden Displaying Buffers
address@hidden Displaying a Buffer in a Window
+
+  It is a common Emacs operation to display or ``pop up'' some buffer
+in response to a user command.  There are several different ways by
+which commands do this.
+
+  Many commands, like @kbd{C-x C-f} (@code{find-file}), display the
+buffer by ``taking over'' the selected window, expecting that the
+user's attention will be diverted to that buffer.  These commands
+usually work by calling @code{switch-to-buffer} internally
+(@pxref{Select Buffer}).
+
address@hidden display-buffer
+  Some commands try to display ``intelligently'', trying not to take
+over the selected window, e.g. by splitting the selected window and
+displaying the desired buffer in the child window.  Such commands,
+which include the various help commands (@pxref{Help}), work by
+calling @code{display-buffer} internally.  @xref{Window Choice}, for
+details.
+
+  Other commands do the same as @code{display-buffer}, and
+additionally select the displaying window so that you can begin
+editing its buffer.  The command @kbd{C-x `} (@code{next-error}) is
+one example (@pxref{Compilation Mode}).  Such commands work by calling
address@hidden internally.  @xref{Displaying Buffers,,Displaying
+Buffers in Windows, elisp, The Emacs Lisp Reference Manual}.
+
+  Commands with names ending in @code{-other-window} behave like
address@hidden, except that they never display in the selected
+window.  Several of these commands are bound in the @kbd{C-x 4} prefix
+key (@pxref{Pop Up Window}).
+
+  Commands with names ending in @code{-other-frame} behave like
address@hidden, except that they (i) never display in the
+selected window and (ii) prefer to create a new frame to display the
+desired buffer instead of splitting a window---as though the variable
address@hidden is set to @code{t} (@pxref{Window Choice}).
+Several of these commands are bound in the @kbd{C-x 5} prefix key.
+
address@hidden
+* Window Choice::   How @code{display-buffer} works.
address@hidden menu
+
address@hidden Window Choice
address@hidden How @code{display-buffer} works
address@hidden display-buffer
+
+The @code{display-buffer} command (as well as commands that call it
+internally) chooses a window to display using the following steps:
+
address@hidden
address@hidden same-window-buffer-names
address@hidden same-window-regexps
address@hidden
+First, check if the buffer should be displayed in the selected window
+regardless of other considerations.  You can tell Emacs to do this by
+adding the desired buffer's name to the list
address@hidden, or adding a matching regular
+expression to the list @code{same-window-regexps}.  By default, these
+variables are @code{nil}, so this step is skipped.
+
address@hidden display-buffer-reuse-frames
address@hidden
+Otherwise, if the buffer is already displayed in an existing window,
+``reuse'' that window.  Normally, only windows on the selected frame
+are considered, but windows on other frames are also reusable if you
+change @code{display-buffer-reuse-frames} to @code{t}, or if you
+change @code{pop-up-frames} (see below) to @code{t}.
+
address@hidden
+Otherwise, if you specified that the buffer should be displayed in a
+special frame by customizing @code{special-display-buffer-names} or
address@hidden, do so.  @xref{Special Buffer Frames}.
+
address@hidden pop-up-frames
address@hidden
+Otherwise, optionally create a new frame and display the buffer there.
+By default, this step is skipped.  To enable it, change the variable
address@hidden to a address@hidden value.  The special value
address@hidden means to do this only on graphical displays.
+
address@hidden
+Otherwise, try to create a new window by splitting the selected
+window, and display the buffer in that new window.
+
address@hidden split-height-threshold
address@hidden split-width-threshold
+The split can be either vertical or horizontal, depending on the
+variables @code{split-height-threshold} and
address@hidden  These variables should have integer
+values.  If @code{split-height-threshold} is smaller than the selected
+window's height, the split puts the new window below.  Otherwise, if
address@hidden is smaller than the window's width, the
+split puts the new window on the right.  If neither condition holds,
+Emacs tries to split so that the new window is below---but only if the
+window was not split before (to avoid excessive splitting).
+
address@hidden
+Otherwise, display the buffer in an existing window on the selected
+frame.
+
address@hidden
+If all the above methods fail for whatever reason, create a new frame
+and display the buffer there.
address@hidden itemize
+
 @node Window Convenience
 @section Window Handling Convenience Features and Customization
 

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-09-24 14:38:16 +0000
+++ b/etc/NEWS  2011-09-24 18:19:20 +0000
@@ -386,6 +386,45 @@
 *** `menu-bar-select-buffer-function' lets you choose another operation
 instead of `switch-to-buffer' when selecting an item in the Buffers menu.
 
+** Window changes
+
++++
+*** Resizing an Emacs frame now preserves proportional window sizes,
+modulo restrictions like window minimum sizes and fixed-size windows.
+
+*** The behavior of `display-buffer' is now customizable in detail.
+
+**** New option `display-buffer-base-action' specifies a list of
+user-determined display "actions" (functions and optional arguments
+for choosing the displaying window).
+
+This takes precedence over the default display action, which is
+specified by `display-buffer-fallback-action'.
+
+**** New option `display-buffer-alist' maps buffer name regexps to
+display actions, taking precedence over `display-buffer-base-action'.
+
++++
+*** New option `window-nest'.
+The new option `window-nest' allows to return the space obtained for
+resizing or creating a window more reliably to the window from which
+such space was obtained.
+
++++
+*** New option `window-splits'.
+The new option `window-splits' allows to split a window that otherwise
+cannot be split because it's too small by stealing space from other
+windows in the same combination.
+
++++
+*** New commands `maximize-window' and `minimize-window'.
+These maximize and minize the size of a window within its frame.
+
++++
+*** New commands `switch-to-prev-buffer' and `switch-to-next-buffer'.
+These functions allow to navigate through the live buffers that have
+been shown in a specific window.
+
 ** The inactive minibuffer has its own major mode `minibuffer-inactive-mode'.
 This is handy for minibuffer-only frames, and is also used for the "mouse-1
 pops up *Messages*" feature, which can now easily be changed.
@@ -1003,18 +1042,6 @@
 window into two side-by-side windows as before.
 
 +++
-*** New option `window-nest'.
-The new option `window-nest' allows to return the space obtained for
-resizing or creating a window more reliably to the window from which
-such space was obtained.
-
-+++
-*** New option `window-splits'.
-The new option `window-splits' allows to split a window that otherwise
-cannot be split because it's too small by stealing space from other
-windows in the same combination.
-
-+++
 *** `split-window-above-each-other' and `split-window-side-by-side'.
 The commands `split-window-vertically' and `split-window-horizontally'
 have been renamed to `split-window-above-each-other' and
@@ -1028,12 +1055,6 @@
 longer delete any windows when they become too small.
 
 +++
-*** Frame/window resizing.
-Resizing an Emacs frame now preserves the proportional sizes of
-subwindows modulo restrictions imposed by window minimum sizes and
-fixed-size windows.
-
-+++
 *** `adjust-window-trailing-edge' adjustments.
 `adjust-window-trailing-edge' can now deal with fixed-size windows and
 is able to resize other windows if a window adjacent to the trailing
@@ -1042,11 +1063,6 @@
 windows which was introduced in Emacs 22.
 
 +++
-*** Commands for maximizing and minimizing windows.
-New functions to maximize and minimize a window within its frame are
-provided, namely `maximize-window' and `minimize-window'.
-
-+++
 *** Window-local buffer lists.
 Windows now have local buffer lists.  This means that removing a buffer
 from display in a window will preferably show the buffer previously
@@ -1054,17 +1070,31 @@
 positions.  This also means that the same buffer may be automatically
 shown twice even if it already appears in another window.
 
-+++
-*** New commands `switch-to-prev-buffer' and `switch-to-next-buffer'.
-These functions allow to navigate through the live buffers that have
-been shown in a specific window.
-
 *** `switch-to-buffer' has a new optional argument FORCE-SAME-WINDOW,
 which if non-nil requires the buffer to be displayed in the currently
 selected window, signaling an error otherwise.  If nil, another window
 can be used, e.g. if the selected one is strongly dedicated.
 
-*** FIXME: buffer-display-alist changes
+*** `split-window-vertically' and `split-window-horizontally' renamed
+to `split-window-above-each-other' and `split-window-side-by-side'
+respectively.  The old names are kept as aliases.
+
+*** Display actions
+
+**** The second arg to `display-buffer' and `pop-to-buffer' is now
+named ACTION, and takes a display action of the same form as
+`display-buffer-base-action' (see Changes, above).  A non-nil,
+non-list value is treated specially, as the old meaning.
+
+**** New variable `display-buffer-overriding-action'.
+
+**** The procedure of `display-buffer' etc. to choose a window is
+determined by combining `display-buffer-overriding-action',
+`display-buffer-alist', the ACTION arg, `display-buffer-base-action',
+and `display-buffer-fallback-action'.  The second and fourth of these
+are user-customizable variables.
+
+See the docstring of `display-buffer' for details.
 
 ** Completion
 


reply via email to

[Prev in Thread] Current Thread [Next in Thread]