GNU bug report logs - #17718
24.4.50; doc string of `display-buffer-alist'

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: minor; Reported by: Drew Adams <drew.adams@HIDDEN>; dated Fri, 6 Jun 2014 16:49:02 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 17718 <at> debbugs.gnu.org:


Received: (at 17718) by debbugs.gnu.org; 6 Jun 2014 17:06:52 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Jun 06 13:06:52 2014
Received: from localhost ([127.0.0.1]:39785 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1WsxbQ-0002cL-5h
	for submit <at> debbugs.gnu.org; Fri, 06 Jun 2014 13:06:52 -0400
Received: from userp1040.oracle.com ([156.151.31.81]:51364)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <drew.adams@HIDDEN>) id 1WsxbN-0002c1-Vl
 for 17718 <at> debbugs.gnu.org; Fri, 06 Jun 2014 13:06:50 -0400
Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237])
 by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id
 s56H6hQY024128
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK)
 for <17718 <at> debbugs.gnu.org>; Fri, 6 Jun 2014 17:06:44 GMT
Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86])
 by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s56H6gfP016266
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO)
 for <17718 <at> debbugs.gnu.org>; Fri, 6 Jun 2014 17:06:42 GMT
Received: from abhmp0018.oracle.com (abhmp0018.oracle.com [141.146.116.24])
 by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id s56H6dlf013027
 for <17718 <at> debbugs.gnu.org>; Fri, 6 Jun 2014 17:06:40 GMT
MIME-Version: 1.0
Message-ID: <3a8df84f-d080-48aa-9667-1fe6a154fc36@default>
Date: Fri, 6 Jun 2014 10:06:39 -0700 (PDT)
From: Drew Adams <drew.adams@HIDDEN>
To: 17718 <at> debbugs.gnu.org
Subject: RE: bug#17718: 24.4.50; doc string of `display-buffer-alist'
References: <33d1b1fa-aff4-4c92-8b10-d8784145954c@default>
In-Reply-To: <33d1b1fa-aff4-4c92-8b10-d8784145954c@default>
X-Priority: 3
X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8  (707110) [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: -3.0 (---)
X-Debbugs-Envelope-To: 17718
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.0 (---)

Same problem for `display-buffer-base-action':

 User-specified default action for `display-buffer'.
 It should be a cons cell (FUNCTION . ALIST), where FUNCTION is a
 function or a list of functions.  Each function should accept two
 arguments: a buffer to display and an alist similar to ALIST.
 See `display-buffer' for details.

Again, ALIST is not described, and neither is the alist that is
the second arg to FUNCTION.  And neither is FUNCTION (what it is
for, what it does with its args, etc.)

And no, just punting to "See `display-buffer' for details" does
not help.  None of this is described in its doc.  The
`display-buffer' doc sting just punts, itself, saying that it
"combines" a bunch of stuff, including `display-buffer-base-action'.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#17718; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 6 Jun 2014 16:48:42 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Jun 06 12:48:42 2014
Received: from localhost ([127.0.0.1]:39774 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1WsxJp-00020R-Ig
	for submit <at> debbugs.gnu.org; Fri, 06 Jun 2014 12:48:42 -0400
Received: from eggs.gnu.org ([208.118.235.92]:57514)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <drew.adams@HIDDEN>) id 1WsxJm-00020B-KN
 for submit <at> debbugs.gnu.org; Fri, 06 Jun 2014 12:48:39 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1WsxJW-0008Vb-Km
 for submit <at> debbugs.gnu.org; Fri, 06 Jun 2014 12:48:32 -0400
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_40 autolearn=disabled
 version=3.3.2
Received: from lists.gnu.org ([2001:4830:134:3::11]:56252)
 by eggs.gnu.org with esmtp (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1WsxJW-0008VX-ID
 for submit <at> debbugs.gnu.org; Fri, 06 Jun 2014 12:48:22 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:59132)
 by lists.gnu.org with esmtp (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1WsxJN-0004TW-Ii
 for bug-gnu-emacs@HIDDEN; Fri, 06 Jun 2014 12:48:22 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1WsxJE-0008Qh-QL
 for bug-gnu-emacs@HIDDEN; Fri, 06 Jun 2014 12:48:13 -0400
Received: from userp1040.oracle.com ([156.151.31.81]:47792)
 by eggs.gnu.org with esmtp (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1WsxJE-0008QV-JZ
 for bug-gnu-emacs@HIDDEN; Fri, 06 Jun 2014 12:48:04 -0400
Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238])
 by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id
 s56Gm2sG004662
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK)
 for <bug-gnu-emacs@HIDDEN>; Fri, 6 Jun 2014 16:48:03 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 s56Gm193016324
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO)
 for <bug-gnu-emacs@HIDDEN>; Fri, 6 Jun 2014 16:48:02 GMT
Received: from abhmp0018.oracle.com (abhmp0018.oracle.com [141.146.116.24])
 by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id s56Gm0Xg008543
 for <bug-gnu-emacs@HIDDEN>; Fri, 6 Jun 2014 16:48:00 GMT
MIME-Version: 1.0
Message-ID: <33d1b1fa-aff4-4c92-8b10-d8784145954c@default>
Date: Fri, 6 Jun 2014 09:47:59 -0700 (PDT)
From: Drew Adams <drew.adams@HIDDEN>
To: bug-gnu-emacs@HIDDEN
Subject: 24.4.50; doc string of `display-buffer-alist'
X-Priority: 3
X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8  (707110) [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-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 <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -4.0 (----)

Not comprehensible - to me at least.

Consider just "ALIST" in the description.  It is described nowhere.
Worse: it is used to describe other things, so that they too are
effectively undefined  and incomprehensible.

What is the cdr of ACTION?  It's ALIST, whatever that is (presumably an
alist of some kind).  What is done with that ALIST?  No idea.

What is the car of ACTION?  It's a function that accepts a buffer and an
alist "of the same form as ALIST".  Huh?  And what form is that?  ALIST
is not described anywhere.

Then you get "`display-buffer' scans this alist..."  Which alist?  There
are at least 3 different alists mentioned in this doc string:

* The alist that is the value of the user option.
* The alist that is the cdr of ACTION.
* The alist that is the argument to FUNCTION, which is the car of
  ACTION.

And the doc says nothing about the alist that gets passed to FUNCTION.
Even if you can somehow figure out the form of FUNCTION's second arg,
you have no idea what buffer and what alist are passed to it.  How,
based on that, you might decide on a (FUNCTION . ALIST) to use is a
mystery.

And the description of this option in the Elisp manual is even less
specific, and does not clear things up.

I'm sorry, but the doc for `display-buffer-alist' (and `display-buffer')
is still gobbledygook, even after repeated requests by users to please
clear it up.  It's a wonder that anyone can make sense of this.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-01 on ODIEONE
Bzr revision: 117212 michael.albinus@HIDDEN
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=3D/c/Devel/emacs/snapshot/trunk
 --enable-checking=3Dyes,glyphs 'CFLAGS=3D-O0 -g3'
 LDFLAGS=3D-Lc:/Devel/emacs/lib 'CPPFLAGS=3D-DGC_MCHECK=3D1
 -Ic:/Devel/emacs/include''




Acknowledgement sent to Drew Adams <drew.adams@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#17718; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Fri, 31 Oct 2014 17:00:04 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.