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#21305: 25.0.50; `get-buffer-window-list' doc - what order? Date: Fri, 21 Aug 2015 12:18:37 -0700 (PDT) Message-ID: <616a08e1-5256-45ba-9249-e220a6c97a89@default> References: <<870b6a90-e498-4ed9-9e41-d498edf33aec@default>> <<83mvxkis5t.fsf@gnu.org>> <> <<83lhd4ijh3.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1440184767 14656 80.91.229.3 (21 Aug 2015 19:19:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 21 Aug 2015 19:19:27 +0000 (UTC) Cc: 21305@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Aug 21 21:19:14 2015 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 1ZSrqL-0006PM-NS for geb-bug-gnu-emacs@m.gmane.org; Fri, 21 Aug 2015 21:19:13 +0200 Original-Received: from localhost ([::1]:43343 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSrqL-00062i-1O for geb-bug-gnu-emacs@m.gmane.org; Fri, 21 Aug 2015 15:19:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43575) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSrqE-00061f-5n for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 15:19:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZSrqA-0002Gw-Vj for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 15:19:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:42557) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSrqA-0002Gs-I4 for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 15:19:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1ZSrq9-000812-QW for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 15:19:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 21 Aug 2015 19:19:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 21305 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 21305-submit@debbugs.gnu.org id=B21305.144018472430790 (code B ref 21305); Fri, 21 Aug 2015 19:19:01 +0000 Original-Received: (at 21305) by debbugs.gnu.org; 21 Aug 2015 19:18:44 +0000 Original-Received: from localhost ([127.0.0.1]:34767 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZSrpr-00080X-IC for submit@debbugs.gnu.org; Fri, 21 Aug 2015 15:18:43 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:27566) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZSrpp-00080P-Tz for 21305@debbugs.gnu.org; Fri, 21 Aug 2015 15:18:42 -0400 Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t7LJIdLd023483 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 21 Aug 2015 19:18:40 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserv0021.oracle.com (8.13.8/8.13.8) with ESMTP id t7LJIdNI019232 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Fri, 21 Aug 2015 19:18:39 GMT Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by userv0122.oracle.com (8.13.8/8.13.8) with ESMTP id t7LJIcqW013266; Fri, 21 Aug 2015 19:18:39 GMT In-Reply-To: <<83lhd4ijh3.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (x86)] X-Source-IP: aserv0021.oracle.com [141.146.126.233] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 208.118.235.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:105681 Archived-At: > > In the manual? Where? I don't see it, so far (in the build I > > have from 7/31. I do see that the manual says this, but this > > speaks only to the meaning of these two arguments - it says > > nothing about the order of the windows in the returned value. > > > > The arguments MINIBUF and ALL-FRAMES have the same meanings as > > ^^^^^^^^^^^^^^^^^^^^^^ > > in the function 'next-window' (*note Cyclic Window Ordering::). >=20 > In the cross-referenced node. It sends you to that node for an entirely different purpose - not for information about the order of the returned value. The xref is even part of the _same sentence_ as the statement about the args. It is not a separate sentence telling to go see that node for more info about the function as a whole. And it certainly is not hinting that you will discover there something about the order of the function's return value. If I tell you that you can get a great bagel at Schlomo's Deli, would you expect that you might also get a great car wash there? > > I meant in the manual. There is an xref to that node, but it is > > given only for info about arguments MINIBUF and ALL-FRAMES. >=20 > No, it's not. It actually tells you that this function traverses > the window as next-window does. The xref'd node does. But the xref is explicitly "given only for info about arguments MINIBUF and ALL-FRAMES." A minor change would make it clear that that node also tells you something about the order of the return value. (It would still be better to document the return value completely in the source node, and send readers to the xref for _additional_ info. > Once again, I think this order is random for all practical purposes, > as far as the caller is concerned. I was actually surprised to see > it documented in the manual. Again, either Emacs decides that it wants to specify nothing about the order, and says it is unspecified, or it decides it wants to tell users what the order is (and so commits, to some extent, to that order, e.g., including for the future). It's your choice. What is the design? Do you want to expose this as by design, and tell users about it so they can take advantage of it, or do you want to tell users not to depend on the currently implemented order?