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, 18 Jan 2015 13:12:03 -0800 (PST) Message-ID: References: <<5526ae92-4543-48d1-b553-7524dd9ff984@default>> <<834mrw6542.fsf@gnu.org>> <> <<83387g56f4.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 1421615597 3749 80.91.229.3 (18 Jan 2015 21:13:17 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 18 Jan 2015 21:13: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 Sun Jan 18 22:13: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 1YCx9j-0004Y7-PS for geb-bug-gnu-emacs@m.gmane.org; Sun, 18 Jan 2015 22:13:12 +0100 Original-Received: from localhost ([::1]:34710 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCx9j-0002c5-2L for geb-bug-gnu-emacs@m.gmane.org; Sun, 18 Jan 2015 16:13:11 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42786) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCx9d-0002bE-Bo for bug-gnu-emacs@gnu.org; Sun, 18 Jan 2015 16:13:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YCx9a-0003e3-3r for bug-gnu-emacs@gnu.org; Sun, 18 Jan 2015 16:13:05 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:51945) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCx9Z-0003dW-WC for bug-gnu-emacs@gnu.org; Sun, 18 Jan 2015 16:13:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1YCx9Z-0002sw-PO for bug-gnu-emacs@gnu.org; Sun, 18 Jan 2015 16:13:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 18 Jan 2015 21:13:01 +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.142161553811028 (code B ref 19571); Sun, 18 Jan 2015 21:13:01 +0000 Original-Received: (at 19571) by debbugs.gnu.org; 18 Jan 2015 21:12:18 +0000 Original-Received: from localhost ([127.0.0.1]:60806 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YCx8s-0002rn-37 for submit@debbugs.gnu.org; Sun, 18 Jan 2015 16:12:18 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:51608) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YCx8q-0002rY-26 for 19571@debbugs.gnu.org; Sun, 18 Jan 2015 16:12:16 -0500 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t0ILC9LM025185 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 18 Jan 2015 21:12:10 GMT Original-Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id t0ILC8e1019697 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sun, 18 Jan 2015 21:12:09 GMT Original-Received: from abhmp0011.oracle.com (abhmp0011.oracle.com [141.146.116.17]) by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id t0ILC7KU019101; Sun, 18 Jan 2015 21:12:08 GMT In-Reply-To: <<83387g56f4.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: acsinet22.oracle.com [141.146.126.238] 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:98455 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? > > > > > > 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. >=20 > Since (see above) "ACTION is a cons cell (FUNCTION . ALIST)", > describing ACTION also describes ALIST, which is part of ACTION. IOW, > "everything in the ACTION paragraph" includes ALIST. The very next sentence I wrote is key: Nothing says that the ALIST here is related to the ALIST mentioned for `display-buffer', at all. That's the point. If ALIST here is the same as ALIST in the `display-buffer' description, then it is sufficient to refer to the latter. And in that case, it is wise remove anything else said for `d-b-a' about ALIST - it can only confuse, if the `d-b' description of ALIST is necessary & sufficient. If the ALIST for `d-b' is only related, but not quite the same thing, then please describe the ALIST for `d-b-a' fully in its own doc. If helpful, please say also how it is related to the ALIST described for `d-b'. As I said: Or if it is related somehow, nothing says how it is related. > The documentation of 'display-buffer' describes ACTION, and as part of > that describes ALIST. Nothing says that the ACTION described for `display-buffer-alist' is the same as the ACTION described for `display-buffer'. Same problem - see above. If they are exactly the same, then it is enough to say that - "Go see the doc of `display-buffer' for ACTION and ALIST" - and do not describe ACTION and ALIST beyond that. If they are similar but not the same in all respects, then either say nothing, in the `d-b-a' doc, about the `d-b' ACTION and ALIST components or explain the relation between those names for `d-b-a' and the same names for `d-b'. > This explicitly tells that ALIST is passed as argument to each > function in the list, and should be interpreted and handled by these > functions. And now it should be clear why ALIST is arbitrary: its > form and semantics are entirely up to the author of the called > functions. That tells us nothing about `display-buffer-alist'. And in particular nothing about the ACTION and ALIST that are mentioned in the description of `display-buffer-alist'. > > 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? >=20 > I don't understand the cause of your confusion about the form. The > form of an alist is well known (and the doc string of 'display-buffer' > even spells out its full name -- "association list" -- to make it even > more clear. What else should or could be said about the _form_ of an > alist whose components are up to the person or program that creates > that alist?? What is missing is the relation between the alists mentioned in the doc of `display-buffer-alist' and the alists mentioned in the doc of `display-buffer'. It is not enough to talk about "alists" in both cases, and to mention structure components that happen to be called "ACTION" and "ALIST" in both cases. And to mumble something vague about "an alist of the same form as ALIST" (whose form is completely unspecified). Something needs to be said about the relation between each of these components for `d-b-a' and for `d-b'. Or else "ACTION" and "ALIST" need to be defined for `d-b-a'. > > 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. >=20 > I'm sorry, but I don't see how your report could be used to improve > the docs. You claim that information is missing which is actually > there, and I pointed it out above. No, you did not. You simply pointed out the obvious, which was the point of departure for the bug description: the same names are used in two different doc descriptions, and one description refers to the other. It is not clear that the terms (which are formal parameter/structure names) stand for the same things. > You didn't identify any confusing parts in the docs,=20 I certainly tried to. I would not have bothered to file a bug report if I didn't think the doc was confusing. I don't intentionally waste your time and my own. > Would you please re-read the doc strings with the above in mind, and > point out what's confusing and/or suggest how to improve the existing > documentation? See above. If it helps, great. If not, so be it. To repeat: 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.