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#17718: 24.4.50; doc string of `display-buffer-alist' Date: Fri, 6 Jun 2014 09:47:59 -0700 (PDT) Message-ID: <33d1b1fa-aff4-4c92-8b10-d8784145954c@default> 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 1402073479 5008 80.91.229.3 (6 Jun 2014 16:51:19 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 6 Jun 2014 16:51:19 +0000 (UTC) To: 17718@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jun 06 18:51:12 2014 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 1WsxME-00065G-71 for geb-bug-gnu-emacs@m.gmane.org; Fri, 06 Jun 2014 18:51:10 +0200 Original-Received: from localhost ([::1]:48465 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WsxMD-00008p-L8 for geb-bug-gnu-emacs@m.gmane.org; Fri, 06 Jun 2014 12:51:09 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59486) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WsxKL-0006LD-Er for bug-gnu-emacs@gnu.org; Fri, 06 Jun 2014 12:49:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WsxKB-0000Ee-4Q for bug-gnu-emacs@gnu.org; Fri, 06 Jun 2014 12:49:13 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:48624) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WsxKB-0000EZ-1L for bug-gnu-emacs@gnu.org; Fri, 06 Jun 2014 12:49:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1WsxKA-00021I-Kl for bug-gnu-emacs@gnu.org; Fri, 06 Jun 2014 12:49:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 06 Jun 2014 16:49:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 17718 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.14020733227720 (code B ref -1); Fri, 06 Jun 2014 16:49:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 6 Jun 2014 16:48:42 +0000 Original-Received: from localhost ([127.0.0.1]:39774 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WsxJp-00020R-Ig for submit@debbugs.gnu.org; Fri, 06 Jun 2014 12:48:42 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:57514) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WsxJm-00020B-KN for submit@debbugs.gnu.org; Fri, 06 Jun 2014 12:48:39 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WsxJW-0008Vb-Km for submit@debbugs.gnu.org; Fri, 06 Jun 2014 12:48:32 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:56252) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WsxJW-0008VX-ID for submit@debbugs.gnu.org; Fri, 06 Jun 2014 12:48:22 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59132) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WsxJN-0004TW-Ii for bug-gnu-emacs@gnu.org; Fri, 06 Jun 2014 12:48:22 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WsxJE-0008Qh-QL for bug-gnu-emacs@gnu.org; Fri, 06 Jun 2014 12:48:13 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:47792) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WsxJE-0008QV-JZ for bug-gnu-emacs@gnu.org; Fri, 06 Jun 2014 12:48:04 -0400 Original-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 ; Fri, 6 Jun 2014 16:48:03 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 s56Gm193016324 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Fri, 6 Jun 2014 16:48:02 GMT Original-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 ; Fri, 6 Jun 2014 16:48:00 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6691.5000 (x86)] 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-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:90143 Archived-At: 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@gmx.de-20140601104945-g88x0mwrxorz302h 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''