GNU bug report logs - #12181
24.1.50; doc of `switch-to-buffer'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 12181 in the body.
You can then email your comments to 12181 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.1.50; doc of `switch-to-buffer'
Date: Sat, 11 Aug 2012 08:22:57 -0700

The doc, in both the doc string and the Elisp manual, is not clear.
 
It says that the function displays the buffer in the selected window.
But later it says that it might display it in another window or it might
raise an error and not display it at all.
 
The description should be reworded to say that it generally _tries_ to
display the buffer in the selected window.  Otherwise it just sounds
contradictory.
 
Note the evolution:
 
Emacs prior to Emacs 23: We just said that it displayed the buffer in
the selected window.  (We actually said "current" window - back then we
used both "selected" and "current" for both buffers and windows.)
 
Emacs 23: We said the same thing, but we added that if the selected
window is a minibuffer window or is dedicated then we just call
`pop-to-buffer'.  Already that is dodging things a bit and sending the
user off to read about `pop-to-buffer', which itself is complicated
(even if clear).
 
Emacs 24: We added argument FORCE-SAME-WINDOW and complicated the
description some more: it's like Emacs 23, but non-nil FORCE-SAME-WINDOW
raises an error if it cannot be displayed in the selected window.
 
The Emacs 24 description is actually less clear because it does not
refer the reader to the doc for `pop-to-buffer', which doc explains in
detail what happens.  Now, all the reader learns is that the buffer "may
be displayed in another window".  May be?  Under what circumstances?
Another window?  What other window?  Those things were clearer in the
Emacs 23 doc because of the explanation of `pop-to-buffer'.
 
This is all OK in general, but the various possibilities need to be tied
together better.  The description sort of reflects the implementation as
having been a history of patches.
 
It will help to say at the outset that the function _tries_ to use the
selected window.  Then you can speak to what happens if it cannot.  That
"what" should be detailed clearly, or it can refer to functions etc.
whose doc will explain clearly just what happens (as was true in the
Emacs 23 case, where readers could read about `pop-to-buffer').
 

In GNU Emacs 24.1.50.1 (i386-mingw-nt5.1.2600)
 of 2012-08-08 on DANI-PC
Bzr revision: 109511 michael.albinus <at> gmx.de-20120808134045-t26l1voivvzfypey
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -I../../libs/libxpm-3.5.8/include -I../../libs/libxpm-3.5.8/src
 -I../../libs/libpng-1.4.10 -I../../libs/zlib-1.2.6
 -I../../libs/giflib-4.1.4-1/include -I../../libs/jpeg-6b-4/include
 -I../../libs/tiff-3.8.2-1/include
 -I../../libs/libxml2-2.7.8-w32-bin/include/libxml2
 -I../../libs/gnutls-3.0.16/include
 -I../../libs/libiconv-1.14-2-mingw32-dev/include'
 

Message #8 received at 12181 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 12181 <at> debbugs.gnu.org
Subject: Re: bug#12181: 24.1.50; doc of `switch-to-buffer'
Date: Fri, 07 Sep 2012 21:52:12 +0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> It says that the function displays the buffer in the selected window.
> But later it says that it might display it in another window or it might
> raise an error and not display it at all.
>  
> The description should be reworded to say that it generally _tries_ to
> display the buffer in the selected window.  Otherwise it just sounds
> contradictory.

This is pretty pedantic, but I clarified the text anyway.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.