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#9979: 24.0.91; doc string of `save-window-excursion' Date: Mon, 7 Nov 2011 08:33:58 -0800 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1320683731 22224 80.91.229.12 (7 Nov 2011 16:35:31 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 7 Nov 2011 16:35:31 +0000 (UTC) Cc: 9979@debbugs.gnu.org To: "'Stefan Monnier'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Nov 07 17:35:27 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1RNSAQ-0007AX-OA for geb-bug-gnu-emacs@m.gmane.org; Mon, 07 Nov 2011 17:35:26 +0100 Original-Received: from localhost ([::1]:55534 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RNSAQ-0004qt-7e for geb-bug-gnu-emacs@m.gmane.org; Mon, 07 Nov 2011 11:35:26 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:44398) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RNSAG-0004qV-6m for bug-gnu-emacs@gnu.org; Mon, 07 Nov 2011 11:35:24 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RNSAA-0001zB-7j for bug-gnu-emacs@gnu.org; Mon, 07 Nov 2011 11:35:15 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:56510) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RNSAA-0001z6-65 for bug-gnu-emacs@gnu.org; Mon, 07 Nov 2011 11:35:10 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RNSCw-0001ig-5d for bug-gnu-emacs@gnu.org; Mon, 07 Nov 2011 11:38:02 -0500 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: Mon, 07 Nov 2011 16:38:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 9979 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 9979-submit@debbugs.gnu.org id=B9979.13206838346555 (code B ref 9979); Mon, 07 Nov 2011 16:38:02 +0000 Original-Received: (at 9979) by debbugs.gnu.org; 7 Nov 2011 16:37:14 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RNSC3-0001hY-MS for submit@debbugs.gnu.org; Mon, 07 Nov 2011 11:37:14 -0500 Original-Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RNSBv-0001h4-SX for 9979@debbugs.gnu.org; Mon, 07 Nov 2011 11:37:06 -0500 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id pA7GY5M2030986 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 7 Nov 2011 16:34:06 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id pA7GY4Pw007409 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 7 Nov 2011 16:34:04 GMT Original-Received: from abhmt118.oracle.com (abhmt118.oracle.com [141.146.116.70]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id pA7GXwqg004004; Mon, 7 Nov 2011 10:33:59 -0600 Original-Received: from dradamslap1 (/130.35.178.194) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 07 Nov 2011 08:33:58 -0800 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcydVBAcuUrJuF/AS6+PuNc08EMkhgAFIKpg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090203.4EB8087E.006E,ss=1,re=0.000,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Mon, 07 Nov 2011 11:38:02 -0500 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:53664 Archived-At: > > The following point appears to be the _only_ real content > > in this paragraph: Do not use this to try to prevent opening > > a new window, since... > > > > But that too does not really say what you want (IIUC). No > > one would use this to try to _prevent_ opening a new window. > > This No one seems to write an awful lot of Elisp code, sadly. If you think that, then it is OK to add that to a list of things you want to mention that the macro does _not_ do. But it is not adequate to state _only_ that, as the doc for the macro. That's pretty much what is happening here. It is not even adequate to state only a whole list of things that the macro does _not_ do. In any case, most important for such a list would be to mention that the macro has no effect on windows in other frames. Above all, the doc needs to state what the macro _does_ do. There, the doc string falls down. See the Elisp manual for a better and more succinct explanation of what the macro does. The first line of the doc string is also incorrect. The macro does not "preserve" window sizes and contents. Preserving implies that these do not change at any time during the macro call. It does not preserve these, but it _restores_ them, after they have perhaps been changed by the BODY. And again, it's important to mention that it is only the windows of the selected frame (not other frames) that are restored. A statement that the macro "preserves" a window config is in fact _precisely_ the kind of thing that can lead users to think that it _prevents_ opening a new window. Preserving the config would indeed prevent new windows opening.