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 08:28:18 -0700 (PDT) Message-ID: References: <<870b6a90-e498-4ed9-9e41-d498edf33aec@default>> <<83mvxkis5t.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 1440170967 15530 80.91.229.3 (21 Aug 2015 15:29:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 21 Aug 2015 15:29:27 +0000 (UTC) Cc: 21305-done@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Aug 21 17:29:13 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 1ZSoFl-0007zX-0y for geb-bug-gnu-emacs@m.gmane.org; Fri, 21 Aug 2015 17:29:13 +0200 Original-Received: from localhost ([::1]:42095 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSoFk-000794-I5 for geb-bug-gnu-emacs@m.gmane.org; Fri, 21 Aug 2015 11:29:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47665) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSoFe-00075c-H6 for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 11:29:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZSoFb-0005m8-Cc for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 11:29:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:42424) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSoFb-0005m4-9m for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 11:29:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1ZSoFb-0002jV-2b for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 11:29:03 -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 15:29:03 +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-done@debbugs.gnu.org id=D21305.144017090310452 (code D ref 21305); Fri, 21 Aug 2015 15:29:03 +0000 Original-Received: (at 21305-done) by debbugs.gnu.org; 21 Aug 2015 15:28:23 +0000 Original-Received: from localhost ([127.0.0.1]:34633 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZSoEx-0002iW-4l for submit@debbugs.gnu.org; Fri, 21 Aug 2015 11:28:23 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:40832) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZSoEw-0002iN-06 for 21305-done@debbugs.gnu.org; Fri, 21 Aug 2015 11:28:22 -0400 Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t7LFSKqs014381 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 21 Aug 2015 15:28:21 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userv0021.oracle.com (8.13.8/8.13.8) with ESMTP id t7LFSKVE001150 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Fri, 21 Aug 2015 15:28:20 GMT Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by userv0121.oracle.com (8.13.8/8.13.8) with ESMTP id t7LFSJum019671; Fri, 21 Aug 2015 15:28:19 GMT In-Reply-To: <<83mvxkis5t.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: userv0021.oracle.com [156.151.31.71] 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:105664 Archived-At: > > But I think it would be helpful to tell users that the order is > > the same as that described in `Cyclic Window Ordering'. >=20 > What can the users do with that information? (It is already in the > ELisp manual; I'm talking about the doc string here.) 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::). Note that the ALL-FRAMES argument does _not_ behave exactly like in 'get-buffer-window'.=20 > > > Describing the order would require a non-trivial amount of text, > > > so without a good reason, I don't think we should add it. > > > > How is it more difficult than saying that the order is the same as > > that specified in `Cyclic Window Ordering', and xreffing that > > node? >=20 > I consider references to the manual in doc strings a bad habit. 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. It would be helpful, I think, to explicitly say that the order of the windows in the return value (a) starts with the selected window (which you have added) and (b) follows the order cyclic window ordering.