From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#12181: 24.1.50; doc of `switch-to-buffer' Date: Sat, 11 Aug 2012 08:22:57 -0700 Message-ID: <524DDEA121B9498F842F2E873C14B37E@us.oracle.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1344698638 17942 80.91.229.3 (11 Aug 2012 15:23:58 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 11 Aug 2012 15:23:58 +0000 (UTC) To: 12181@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Aug 11 17:23:52 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1T0DXV-0008Ks-MX for geb-bug-gnu-emacs@m.gmane.org; Sat, 11 Aug 2012 17:23:45 +0200 Original-Received: from localhost ([::1]:38657 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T0DXU-0003tv-K8 for geb-bug-gnu-emacs@m.gmane.org; Sat, 11 Aug 2012 11:23:44 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:40186) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T0DXR-0003tQ-Eh for bug-gnu-emacs@gnu.org; Sat, 11 Aug 2012 11:23:42 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1T0DXQ-0004Mg-EH for bug-gnu-emacs@gnu.org; Sat, 11 Aug 2012 11:23:41 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:40037) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T0DXQ-0004Mc-Am for bug-gnu-emacs@gnu.org; Sat, 11 Aug 2012 11:23:40 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1T0DfV-0002AY-Ls for bug-gnu-emacs@gnu.org; Sat, 11 Aug 2012 11:32:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 11 Aug 2012 15:32:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 12181 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: Original-Received: via spool by submit@debbugs.gnu.org id=B.13446991008295 (code B ref -1); Sat, 11 Aug 2012 15:32:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 11 Aug 2012 15:31:40 +0000 Original-Received: from localhost ([127.0.0.1]:49580 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1T0DfA-00029k-Aq for submit@debbugs.gnu.org; Sat, 11 Aug 2012 11:31:40 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:48757) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1T0Df8-00029d-5B for submit@debbugs.gnu.org; Sat, 11 Aug 2012 11:31:38 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1T0DX0-0004JA-LL for submit@debbugs.gnu.org; Sat, 11 Aug 2012 11:23:16 -0400 Original-Received: from lists.gnu.org ([208.118.235.17]:48221) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T0DX0-0004J6-IS for submit@debbugs.gnu.org; Sat, 11 Aug 2012 11:23:14 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:40045) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T0DWy-0003sa-7w for bug-gnu-emacs@gnu.org; Sat, 11 Aug 2012 11:23:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1T0DWx-0004Ij-5k for bug-gnu-emacs@gnu.org; Sat, 11 Aug 2012 11:23:12 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]:33776) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T0DWw-0004If-V6 for bug-gnu-emacs@gnu.org; Sat, 11 Aug 2012 11:23:11 -0400 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by acsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q7BFN8mf031536 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sat, 11 Aug 2012 15:23:09 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id q7BFN7Ip015345 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 11 Aug 2012 15:23:07 GMT Original-Received: from abhmt119.oracle.com (abhmt119.oracle.com [141.146.116.71]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id q7BFN5A2018609 for ; Sat, 11 Aug 2012 10:23:07 -0500 Original-Received: from dradamslap1 (/10.159.168.229) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 11 Aug 2012 08:23:04 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: Ac131S+/yfdDKe2XR4uStDkbI0R9Pw== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 1) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:63042 Archived-At: 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@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'