From cee2e90d475f6d9dbdb7e92a127b65faa342665c Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Fri, 7 Sep 2012 21:53:21 +0800 Subject: [PATCH] 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. Fixes: debbugs:12181 --- doc/lispref/ChangeLog | 1 + doc/lispref/windows.texi | 25 ++++++++++++------------- lisp/ChangeLog | 2 ++ lisp/window.el | 34 ++++++++++++++++++---------------- 4 files changed, 33 insertions(+), 29 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 37e96dde07..9a747838c2 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -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. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 52bdc9a5fa..ea48a46359 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1492,12 +1492,10 @@ to make a buffer current to modify it in Lisp, use @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, this function creates a new buffer with that name; the new 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 non-@code{nil}. -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 non-@code{nil}, 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 +@code{pop-to-buffer} (see below). However, if the optional argument +@var{force-same-window} is non-@code{nil}, it signals an error instead. @end deffn diff --git a/lisp/ChangeLog b/lisp/ChangeLog index db3a3f5d04..95a6c1e717 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,7 @@ 2012-09-07 Chong Yidong + * 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). diff --git a/lisp/window.el b/lisp/window.el index 66b86f45e7..0e03268029 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -5642,26 +5642,28 @@ buffer with the name BUFFER-OR-NAME and return that buffer." (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 -- 2.20.1