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#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined Date: Sun, 11 Jan 2015 21:14:47 -0800 (PST) Message-ID: References: <<5526ae92-4543-48d1-b553-7524dd9ff984@default>> <<834mrw6542.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 1421039717 26933 80.91.229.3 (12 Jan 2015 05:15:17 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 12 Jan 2015 05:15:17 +0000 (UTC) Cc: 19571@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jan 12 06:15:10 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 1YAXLJ-0000dN-Qh for geb-bug-gnu-emacs@m.gmane.org; Mon, 12 Jan 2015 06:15:10 +0100 Original-Received: from localhost ([::1]:60410 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAXLI-0008KR-Uk for geb-bug-gnu-emacs@m.gmane.org; Mon, 12 Jan 2015 00:15:08 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38944) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAXLE-0008J5-EM for bug-gnu-emacs@gnu.org; Mon, 12 Jan 2015 00:15:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YAXLD-0001A8-Bw for bug-gnu-emacs@gnu.org; Mon, 12 Jan 2015 00:15:04 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:45080) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAXLD-00019X-87 for bug-gnu-emacs@gnu.org; Mon, 12 Jan 2015 00:15:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1YAXLC-0007Zg-Gg for bug-gnu-emacs@gnu.org; Mon, 12 Jan 2015 00:15:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 12 Jan 2015 05:15:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 19571 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 19571-submit@debbugs.gnu.org id=B19571.142103969729092 (code B ref 19571); Mon, 12 Jan 2015 05:15:02 +0000 Original-Received: (at 19571) by debbugs.gnu.org; 12 Jan 2015 05:14:57 +0000 Original-Received: from localhost ([127.0.0.1]:53941 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAXL7-0007Z8-3F for submit@debbugs.gnu.org; Mon, 12 Jan 2015 00:14:57 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:45556) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAXL5-0007Yv-Bw for 19571@debbugs.gnu.org; Mon, 12 Jan 2015 00:14:55 -0500 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t0C5EmdZ030009 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 12 Jan 2015 05:14:49 GMT Original-Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id t0C5Emro014968 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Mon, 12 Jan 2015 05:14:48 GMT Original-Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id t0C5EmHV014959; Mon, 12 Jan 2015 05:14:48 GMT In-Reply-To: <<834mrw6542.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8.2 (807160) [OL 12.0.6691.5000 (x86)] X-Source-IP: acsinet21.oracle.com [141.146.126.237] 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: 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:98242 Archived-At: > > ALIST is mentioned only here: > > > > ACTION is a cons cell (FUNCTION . ALIST), where FUNCTION is a > > function or a list of functions. Each such function should > > accept two arguments: a buffer to display and an alist of the > > same form as ALIST. See `display-buffer' for details. > > > > "of the same form as ALIST"? Really? What form is that? Where is > > *anything* said about the form of ALIST? >=20 > It's an alist. And you are referred to the documentation of > 'display-buffer' for details. I see nothing wrong with that. No, you are referred to `display-buffer' for ACTION - for info about everything in the ACTION paragraph. Nothing says that the ALIST here is related to the ALIST mentioned for `display-buffer', at all. Or if it is related somehow, nothing says how it is related. The ALIST mentioned for `display-buffer' is described in its doc string only as "an arbitrary association list (alist)." Arbitrary. That doesn't jibe well with "of the same form as ALIST" in the description of `display-buffer-alist', which suggests that the ALIST mentioned for `display-buffer-alist' has some particular form, unspecified here. Or else it suggests that, whatever the form an ALIST for `display-buffer-alist' might have in any given concrete instance, the alist to be accepted as arg to each FUNCTION must have that same form. In that case, we are left wondering, not about some predefined but unspecified form that ALIST must have, but rather what could possibly even be meant by the "form" that it takes concretely. IOW, we wonder what kind of form conformance is required for the alist arg that FUNCTION must accept - in what way must it agree with the "form" of ALIST? My guess is that, at the very least, there is some misleading text to remove here. The description now is a puzzle. If there is nothing to say about ALIST, so that it is simply an "arbitrary" alist, then I'd say that nothing more should be said about it - certainly nothing suggesting that it might need to have a particular form. If there is some agreement ("form" or otherwise) that must be had between ALIST and the alist arg accepted by FUNCTION, then please spell out what is meant by that. For example, if the keys in the alist accepted by FUNCTION must be a subset of the keys in the actual ALIST for `display-buffer-alist', then say that. (That's just a made-up example - I have no idea what the real constraint being suggested here might be.) But do with the doc string what you like. If you find it perfectly clear, more power to you. I'm just reporting that I find it confusing and not so helpful. HTH.