From unknown Sun Jun 22 17:15:22 2025 X-Loop: help-debbugs@gnu.org Subject: bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 12 Jan 2015 02:13:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 19571 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 19571@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.142102875312276 (code B ref -1); Mon, 12 Jan 2015 02:13:02 +0000 Received: (at submit) by debbugs.gnu.org; 12 Jan 2015 02:12:33 +0000 Received: from localhost ([127.0.0.1]:53893 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAUUa-0003Bv-7O for submit@debbugs.gnu.org; Sun, 11 Jan 2015 21:12:32 -0500 Received: from eggs.gnu.org ([208.118.235.92]:47147) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAUUX-0003Bf-9w for submit@debbugs.gnu.org; Sun, 11 Jan 2015 21:12:30 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YAUUN-0007eE-Dn for submit@debbugs.gnu.org; Sun, 11 Jan 2015 21:12:23 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=BAYES_20 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:38887) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAUUN-0007eA-An for submit@debbugs.gnu.org; Sun, 11 Jan 2015 21:12:19 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:48861) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAUUI-0008Rj-M6 for bug-gnu-emacs@gnu.org; Sun, 11 Jan 2015 21:12:19 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YAUUD-0007dm-Lh for bug-gnu-emacs@gnu.org; Sun, 11 Jan 2015 21:12:14 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:44759) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAUUD-0007dh-FM for bug-gnu-emacs@gnu.org; Sun, 11 Jan 2015 21:12:09 -0500 Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t0C2C7gr003002 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 12 Jan 2015 02:12:08 GMT Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by ucsinet22.oracle.com (8.14.5+Sun/8.14.5) with ESMTP id t0C2C6GP004696 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Mon, 12 Jan 2015 02:12:07 GMT Received: from abhmp0001.oracle.com (abhmp0001.oracle.com [141.146.116.7]) by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id t0C2C5FI004666 for ; Mon, 12 Jan 2015 02:12:05 GMT MIME-Version: 1.0 Message-ID: <5526ae92-4543-48d1-b553-7524dd9ff984@default> Date: Sun, 11 Jan 2015 18:12:04 -0800 (PST) From: Drew Adams X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8.2 (807160) [OL 12.0.6691.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.0 (----) 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? In GNU Emacs 25.0.50.1 (i686-pc-mingw32) of 2014-10-20 on LEG570 Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --enable-checking=3Dyes,glyphs CPPFLAGS=3D-DGLYPH_DEBUG=3D1' From unknown Sun Jun 22 17:15:22 2025 X-Loop: help-debbugs@gnu.org Subject: bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 12 Jan 2015 03:39: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: To: Drew Adams Cc: 19571@debbugs.gnu.org Reply-To: Eli Zaretskii Received: via spool by 19571-submit@debbugs.gnu.org id=B19571.142103389220272 (code B ref 19571); Mon, 12 Jan 2015 03:39:02 +0000 Received: (at 19571) by debbugs.gnu.org; 12 Jan 2015 03:38:12 +0000 Received: from localhost ([127.0.0.1]:53913 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAVpU-0005Gu-2H for submit@debbugs.gnu.org; Sun, 11 Jan 2015 22:38:12 -0500 Received: from mtaout20.012.net.il ([80.179.55.166]:44042) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAVpQ-0005GO-1v for 19571@debbugs.gnu.org; Sun, 11 Jan 2015 22:38:09 -0500 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0NI100K00O2XP200@a-mtaout20.012.net.il> for 19571@debbugs.gnu.org; Mon, 12 Jan 2015 05:38:01 +0200 (IST) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NI100K34ORCSR00@a-mtaout20.012.net.il>; Mon, 12 Jan 2015 05:38:01 +0200 (IST) Date: Mon, 12 Jan 2015 05:38:05 +0200 From: Eli Zaretskii In-reply-to: <5526ae92-4543-48d1-b553-7524dd9ff984@default> X-012-Sender: halo1@inter.net.il Message-id: <834mrw6542.fsf@gnu.org> References: <5526ae92-4543-48d1-b553-7524dd9ff984@default> X-Spam-Score: 1.0 (+) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) > Date: Sun, 11 Jan 2015 18:12:04 -0800 (PST) > From: Drew Adams > > > 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. From unknown Sun Jun 22 17:15:22 2025 X-Loop: help-debbugs@gnu.org Subject: bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined 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: To: Eli Zaretskii Cc: 19571@debbugs.gnu.org Received: via spool by 19571-submit@debbugs.gnu.org id=B19571.142103969729092 (code B ref 19571); Mon, 12 Jan 2015 05:15:02 +0000 Received: (at 19571) by debbugs.gnu.org; 12 Jan 2015 05:14:57 +0000 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 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 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 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 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 MIME-Version: 1.0 Message-ID: Date: Sun, 11 Jan 2015 21:14:47 -0800 (PST) From: Drew Adams References: <<5526ae92-4543-48d1-b553-7524dd9ff984@default>> <<834mrw6542.fsf@gnu.org>> 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)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) > > 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. From unknown Sun Jun 22 17:15:22 2025 X-Loop: help-debbugs@gnu.org Subject: bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined 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: To: Drew Adams Cc: 19571@debbugs.gnu.org Reply-To: Eli Zaretskii Received: via spool by 19571-submit@debbugs.gnu.org id=B19571.142107885232324 (code B ref 19571); Mon, 12 Jan 2015 16:08:02 +0000 Received: (at 19571) by debbugs.gnu.org; 12 Jan 2015 16:07:32 +0000 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 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 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) 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) Date: Mon, 12 Jan 2015 18:07:27 +0200 From: Eli Zaretskii In-reply-to: X-012-Sender: halo1@inter.net.il Message-id: <83387g56f4.fsf@gnu.org> References: <5526ae92-4543-48d1-b553-7524dd9ff984@default> <834mrw6542.fsf@gnu.org> X-Spam-Score: 1.0 (+) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) > 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? From unknown Sun Jun 22 17:15:22 2025 X-Loop: help-debbugs@gnu.org Subject: bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined 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: To: Eli Zaretskii Cc: 19571@debbugs.gnu.org Received: via spool by 19571-submit@debbugs.gnu.org id=B19571.142161553811028 (code B ref 19571); Sun, 18 Jan 2015 21:13:01 +0000 Received: (at 19571) by debbugs.gnu.org; 18 Jan 2015 21:12:18 +0000 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 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 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 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 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 MIME-Version: 1.0 Message-ID: Date: Sun, 18 Jan 2015 13:12:03 -0800 (PST) From: Drew Adams References: <<5526ae92-4543-48d1-b553-7524dd9ff984@default>> <<834mrw6542.fsf@gnu.org>> <> <<83387g56f4.fsf@gnu.org>> 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)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) > > > > 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. From unknown Sun Jun 22 17:15:22 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.503 (Entity 5.503) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Drew Adams Subject: bug#19571: closed (Re: bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined) Message-ID: References: <83vbk2ycsl.fsf@gnu.org> <5526ae92-4543-48d1-b553-7524dd9ff984@default> X-Gnu-PR-Message: they-closed 19571 X-Gnu-PR-Package: emacs Reply-To: 19571@debbugs.gnu.org Date: Mon, 19 Jan 2015 16:08:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1421683682-9080-1" This is a multi-part message in MIME format... ------------=_1421683682-9080-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 19571@debbugs.gnu.org. --=20 19571: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D19571 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1421683682-9080-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 19571-done) by debbugs.gnu.org; 19 Jan 2015 16:07:43 +0000 Received: from localhost ([127.0.0.1]:33355 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YDEre-0002Lt-FV for submit@debbugs.gnu.org; Mon, 19 Jan 2015 11:07:42 -0500 Received: from mtaout29.012.net.il ([80.179.55.185]:42489) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YDEra-0002LZ-Qv for 19571-done@debbugs.gnu.org; Mon, 19 Jan 2015 11:07:40 -0500 Received: from conversion-daemon.mtaout29.012.net.il by mtaout29.012.net.il (HyperSendmail v2007.08) id <0NIF00300LT3YB00@mtaout29.012.net.il> for 19571-done@debbugs.gnu.org; Mon, 19 Jan 2015 18:04:12 +0200 (IST) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by mtaout29.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NIF004RELZ0RB10@mtaout29.012.net.il>; Mon, 19 Jan 2015 18:04:12 +0200 (IST) Date: Mon, 19 Jan 2015 18:07:22 +0200 From: Eli Zaretskii Subject: Re: bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined In-reply-to: X-012-Sender: halo1@inter.net.il To: Drew Adams Message-id: <83vbk2ycsl.fsf@gnu.org> References: <5526ae92-4543-48d1-b553-7524dd9ff984@default> <834mrw6542.fsf@gnu.org> <83387g56f4.fsf@gnu.org> X-Spam-Score: 1.0 (+) X-Debbugs-Envelope-To: 19571-done Cc: 19571-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: Eli Zaretskii List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) > Date: Sun, 18 Jan 2015 13:12:03 -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. > > 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. It's the same word, and there are no other ALISTs around, so why wouldn't it be? We use the same word for the same thing all over the place, and the last thing I'd imagine is that someone could not understand they mean the same. > 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. OK, closing. ------------=_1421683682-9080-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 12 Jan 2015 02:12:33 +0000 Received: from localhost ([127.0.0.1]:53893 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAUUa-0003Bv-7O for submit@debbugs.gnu.org; Sun, 11 Jan 2015 21:12:32 -0500 Received: from eggs.gnu.org ([208.118.235.92]:47147) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YAUUX-0003Bf-9w for submit@debbugs.gnu.org; Sun, 11 Jan 2015 21:12:30 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YAUUN-0007eE-Dn for submit@debbugs.gnu.org; Sun, 11 Jan 2015 21:12:23 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=BAYES_20 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:38887) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAUUN-0007eA-An for submit@debbugs.gnu.org; Sun, 11 Jan 2015 21:12:19 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:48861) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAUUI-0008Rj-M6 for bug-gnu-emacs@gnu.org; Sun, 11 Jan 2015 21:12:19 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YAUUD-0007dm-Lh for bug-gnu-emacs@gnu.org; Sun, 11 Jan 2015 21:12:14 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:44759) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YAUUD-0007dh-FM for bug-gnu-emacs@gnu.org; Sun, 11 Jan 2015 21:12:09 -0500 Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t0C2C7gr003002 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 12 Jan 2015 02:12:08 GMT Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by ucsinet22.oracle.com (8.14.5+Sun/8.14.5) with ESMTP id t0C2C6GP004696 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Mon, 12 Jan 2015 02:12:07 GMT Received: from abhmp0001.oracle.com (abhmp0001.oracle.com [141.146.116.7]) by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id t0C2C5FI004666 for ; Mon, 12 Jan 2015 02:12:05 GMT MIME-Version: 1.0 Message-ID: <5526ae92-4543-48d1-b553-7524dd9ff984@default> Date: Sun, 11 Jan 2015 18:12:04 -0800 (PST) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 25.0.50; `display-buffer-alist': ALIST is completely undefined X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8.2 (807160) [OL 12.0.6691.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.0 (----) 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? In GNU Emacs 25.0.50.1 (i686-pc-mingw32) of 2014-10-20 on LEG570 Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --enable-checking=3Dyes,glyphs CPPFLAGS=3D-DGLYPH_DEBUG=3D1' ------------=_1421683682-9080-1--