[Emacs-diffs] /srv/bzr/emacs/trunk r109930: Minor doc fix for switch-to-buffer.

[Chong Yidong]

------------------------------------------------------------
revno: 109930
fixes bug: http://debbugs.gnu.org/12181
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2012-09-07 21:53:21 +0800
message:
  Minor doc fix for switch-to-buffer.
  
  * doc/lispref/windows.texi (Display Action Functions)
  (Choosing Window Options): Remove obsolete variable
  display-buffer-reuse-frames.
  (Switching Buffers): Minor doc tweak for switch-to-buffer.
  
  * lisp/window.el (switch-to-buffer): Doc fix.
modified:
  doc/lispref/ChangeLog
  doc/lispref/windows.texi
  lisp/ChangeLog
  lisp/window.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-09-07 10:36:39 +0000
+++ b/doc/lispref/ChangeLog     2012-09-07 13:53:21 +0000
@@ -5,6 +5,7 @@
        * windows.texi (Display Action Functions)
        (Choosing Window Options): Remove obsolete variable
        display-buffer-reuse-frames.
+       (Switching Buffers): Minor doc tweak for switch-to-buffer.
 
        * positions.texi (Narrowing): Document buffer-narrowed-p.
 

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2012-09-07 10:27:11 +0000
+++ b/doc/lispref/windows.texi  2012-09-07 13:53:21 +0000
@@ -1492,12 +1492,10 @@
 @code{set-buffer}.  @xref{Current Buffer}.
 
 @deffn Command switch-to-buffer buffer-or-name &optional norecord 
force-same-window
-This function displays @var{buffer-or-name} in the selected window,
-and makes it the current buffer.  (In contrast, @code{set-buffer}
-makes the buffer current but does not display it; @pxref{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.
+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.
 
 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
 returned by @code{other-buffer} (@pxref{The Buffer List}).  If
@@ -1506,17 +1504,18 @@
 buffer's major mode is determined by the variable @code{major-mode}
 (@pxref{Major Modes}).
 
-Normally the specified buffer is put at the front of the buffer
+Normally, the specified buffer is put at the front of the buffer
 list---both the global buffer list and the selected frame's buffer
 list (@pxref{The Buffer List}).  However, this is not done if the
 optional argument @var{norecord} is address@hidden
 
-If this function is unable to display the buffer in the selected
-window---usually because the selected window is a minibuffer window or
-is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then
-it normally tries to display the buffer in some other window, in the
-manner of @code{pop-to-buffer} (see below).  However, if the optional
-argument @var{force-same-window} is address@hidden, it signals an error
+Sometimes, @code{switch-to-buffer} may be unable to display the buffer
+in the selected window.  This happens if the selected window is a
+minibuffer window, or if the selected window is strongly dedicated to
+its buffer (@pxref{Dedicated Windows}).  In that case, the command
+normally tries to display the buffer in some other window, by invoking
address@hidden (see below).  However, if the optional argument
address@hidden is address@hidden, it signals an error
 instead.
 @end deffn
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-09-07 10:53:29 +0000
+++ b/lisp/ChangeLog    2012-09-07 13:53:21 +0000
@@ -1,5 +1,7 @@
 2012-09-07  Chong Yidong  <address@hidden>
 
+       * window.el (switch-to-buffer): Doc fix (Bug#12181).
+
        * files.el (after-find-file): Don't fail on a read-only buffer if
        require-final-newline is `visit' or `visit-save' (Bug#11156).
 

=== modified file 'lisp/window.el'
--- a/lisp/window.el    2012-09-05 09:22:20 +0000
+++ b/lisp/window.el    2012-09-07 13:53:21 +0000
@@ -5642,26 +5642,28 @@
 
 (defun switch-to-buffer (buffer-or-name &optional norecord force-same-window)
   "Switch to buffer BUFFER-OR-NAME in the selected window.
-If called interactively, prompt for the buffer name using the
+If the selected window cannot display the specified
+buffer (e.g. if it is a minibuffer window or strongly dedicated
+to another buffer), call `pop-to-buffer' to select the buffer in
+another window.
+
+If called interactively, read the buffer name using the
 minibuffer.  The variable `confirm-nonexistent-file-or-buffer'
 determines whether to request confirmation before creating a new
 buffer.
 
-BUFFER-OR-NAME may be a buffer, a string (a buffer name), or
-nil.  If BUFFER-OR-NAME is a string that does not identify an
-existing buffer, create a buffer with that name.  If
-BUFFER-OR-NAME is nil, switch to the buffer returned by
-`other-buffer'.
-
-Optional argument NORECORD non-nil means do not put the buffer
-specified by BUFFER-OR-NAME at the front of the buffer list and
-do not make the window displaying it the most recently selected
-one.
-
-If FORCE-SAME-WINDOW is non-nil, BUFFER-OR-NAME must be displayed
-in the selected window; signal an error if that is
-impossible (e.g. if the selected window is minibuffer-only).  If
-nil, BUFFER-OR-NAME may be displayed in another window.
+BUFFER-OR-NAME may be a buffer, a string (a buffer name), or nil.
+If BUFFER-OR-NAME is a string that does not identify an existing
+buffer, create a buffer with that name.  If BUFFER-OR-NAME is
+nil, switch to the buffer returned by `other-buffer'.
+
+If optional argument NORECORD is non-nil, do not put the buffer
+at the front of the buffer list, and do not make the window
+displaying it the most recently selected one.
+
+If optional argument FORCE-SAME-WINDOW is non-nil, the buffer
+must be displayed in the selected window; if that is impossible,
+signal an error rather than calling `pop-to-buffer'.
 
 Return the buffer switched to."
   (interactive