From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined Date: Mon, 12 Jan 2015 18:07:27 +0200 Message-ID: <83387g56f4.fsf@gnu.org> References: <5526ae92-4543-48d1-b553-7524dd9ff984@default> <834mrw6542.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1421078900 23243 80.91.229.3 (12 Jan 2015 16:08:20 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 12 Jan 2015 16:08:20 +0000 (UTC) Cc: 19571@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jan 12 17:08: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 1YAhXJ-0006YO-TS for geb-bug-gnu-emacs@m.gmane.org; Mon, 12 Jan 2015 17:08:14 +0100 Original-Received: from localhost ([::1]:34890 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAhXJ-0003IA-2d for geb-bug-gnu-emacs@m.gmane.org; Mon, 12 Jan 2015 11:08:13 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52432) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAhXF-0003I5-KH for bug-gnu-emacs@gnu.org; Mon, 12 Jan 2015 11:08:10 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YAhX8-0005bl-J7 for bug-gnu-emacs@gnu.org; Mon, 12 Jan 2015 11:08:09 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:45767) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAhX8-0005bb-G6 for bug-gnu-emacs@gnu.org; Mon, 12 Jan 2015 11:08:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1YAhX8-0008Q3-3t for bug-gnu-emacs@gnu.org; Mon, 12 Jan 2015 11:08:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 12 Jan 2015 16:08: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.142107885232324 (code B ref 19571); Mon, 12 Jan 2015 16:08:02 +0000 Original-Received: (at 19571) by debbugs.gnu.org; 12 Jan 2015 16:07:32 +0000 Original-Received: from localhost ([127.0.0.1]:54628 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAhWd-0008PH-QQ for submit@debbugs.gnu.org; Mon, 12 Jan 2015 11:07:32 -0500 Original-Received: from mtaout28.012.net.il ([80.179.55.184]:38827) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAhWZ-0008P0-TR for 19571@debbugs.gnu.org; Mon, 12 Jan 2015 11:07:30 -0500 Original-Received: from conversion-daemon.mtaout28.012.net.il by mtaout28.012.net.il (HyperSendmail v2007.08) id <0NI200100N5BBC00@mtaout28.012.net.il> for 19571@debbugs.gnu.org; Mon, 12 Jan 2015 18:05:20 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by mtaout28.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NI200JDJNCWYF60@mtaout28.012.net.il>; Mon, 12 Jan 2015 18:05:20 +0200 (IST) In-reply-to: X-012-Sender: halo1@inter.net.il 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:98266 Archived-At: > Date: Sun, 11 Jan 2015 21:14:47 -0800 (PST) > From: Drew Adams > Cc: 19571@debbugs.gnu.org > > > > 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. 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. > 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 documentation of 'display-buffer' describes ACTION, and as part of that describes ALIST. See below. > The ALIST mentioned for `display-buffer' is described in its doc > string only as "an arbitrary association list (alist)." Arbitrary. That's not all 'display-buffer's doc has to say about ALIST. It also says: The `display-buffer' function builds a function list and an alist by combining the functions and alists specified in `display-buffer-overriding-action', `display-buffer-alist', the ACTION argument, `display-buffer-base-action', and `display-buffer-fallback-action' (in order). Then it calls each function in the combined function list in turn, passing the buffer as the first argument and the combined alist as the second argument, until one of the functions returns non-nil. 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. > 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? 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?? > 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. 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. You didn't identify any confusing parts in the docs, nor suggested improvements to the existing text. 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?