From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#26233: 26.0.50; [PATCH] Improve documentation for display-buffer-alist Date: Sun, 26 Mar 2017 10:45:51 -0700 (PDT) Message-ID: <740b3d43-ebea-4bad-9021-2b865a103cfe@default> References: <<87o9wq6c31.fsf@wi.uni-muenster.de> <1a350894-ae16-4706-888f-6575cdc559ec@default>> <<878tnt6bdi.fsf@informationelle-selbstbestimmung-im-internet.de>> <<83shm1bvud.fsf@gnu.org>> <58D77E01.6000105@gmx.at> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1490550434 21600 195.159.176.226 (26 Mar 2017 17:47:14 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 26 Mar 2017 17:47:14 +0000 (UTC) Cc: 26233@debbugs.gnu.org To: martin rudalics , Eli Zaretskii , Jens Lechtenboerger Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Mar 26 19:47:09 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1csCFv-00050w-Cc for geb-bug-gnu-emacs@m.gmane.org; Sun, 26 Mar 2017 19:47:07 +0200 Original-Received: from localhost ([::1]:41780 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1csCG1-0007EH-ET for geb-bug-gnu-emacs@m.gmane.org; Sun, 26 Mar 2017 13:47:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:60844) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1csCFt-0007E9-AA for bug-gnu-emacs@gnu.org; Sun, 26 Mar 2017 13:47:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1csCFq-0000P1-5v for bug-gnu-emacs@gnu.org; Sun, 26 Mar 2017 13:47:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:47936) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1csCFq-0000Ow-1f for bug-gnu-emacs@gnu.org; Sun, 26 Mar 2017 13:47:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1csCFp-0003cc-Mj for bug-gnu-emacs@gnu.org; Sun, 26 Mar 2017 13:47:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 26 Mar 2017 17:47:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 26233 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 26233-submit@debbugs.gnu.org id=B26233.149055036413854 (code B ref 26233); Sun, 26 Mar 2017 17:47:01 +0000 Original-Received: (at 26233) by debbugs.gnu.org; 26 Mar 2017 17:46:04 +0000 Original-Received: from localhost ([127.0.0.1]:46135 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1csCEt-0003bN-MM for submit@debbugs.gnu.org; Sun, 26 Mar 2017 13:46:04 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:28346) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1csCEs-0003ae-3r for 26233@debbugs.gnu.org; Sun, 26 Mar 2017 13:46:02 -0400 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v2QHjsao028102 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 26 Mar 2017 17:45:55 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v2QHjsYL007738 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Sun, 26 Mar 2017 17:45:54 GMT Original-Received: from abhmp0014.oracle.com (abhmp0014.oracle.com [141.146.116.20]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id v2QHjqmY026382; Sun, 26 Mar 2017 17:45:53 GMT In-Reply-To: <58D77E01.6000105@gmx.at> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.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" Xref: news.gmane.org gmane.emacs.bugs:130981 Archived-At: > > 2. I _did_ object at the time. >=20 > Sorry, but the time was 2011 and at that time I wrote ... >=20 > Your approach will divide Emacs users into two groups: A wide majority > that continues to use the old options and a small minority able to > write their own alist based functions. >=20 > ... and ... >=20 > Most of what you propose above is easily available in Emacs 23 via > `special-display-regexps'. An application would just temporarily add > the buffer, the function, and the alist to the head of that and get the > behavior without setting any arguments. Is it really worth inventing a > new `display-buffer' in order to resolve such cosmetic issues? I had to search the bugs list and emacs-devel to find that quote, since you provided no URL for it. To be clear, the "you" and "your" in your quote was apparently Stefan, not me. > You did not bother to participate in that discussion and so > you did not object at the time. Actually, I _did_ participate in that discussion, quite actively. I sent 13 messages to that thread. Starting with this reply to Juanma, who replied to you: J> IMHO, you've taken a lot of time to think of this, and the added J> complexity, if any, is added flexibility. I think we should strive to J> make the current funcionality of your changes clearer and better J> documented. If we stat removing things now, we'll be doomed to re-add J> them some day, not long, when people starts to ask for ways to make it J> work like it was before (you've seen enough of my private bug reports J> to know how true that is ;-) D> I tend to agree with what Juanma says here, though I'm not D> really able to judge what is needed, myself. I expect that D> Martin has looked at the various requirements more than anyone D> else, and I imagine he has done a good job of coming up with D> a coherent solution that covers them. We definitely do not D> want to start over from scratch and risk destabilizing things D> a great deal. D> D> That said, there is a lot to understand, and I'm guessing that D> we, including Martin, might not see clearly what TRT is until, D> in fact, we start trying to explain/describe it better. It's clear that from the very beginning (1) I supported your work toward `display-buffer-alist' improvement, (2) I agreed with those who said that we need to "make the current funcionality of your changes clearer and better documented, and (3) I agreed with Juanma's statement that: If we start removing things now, we'll be doomed to re-add them some day, not long, when people starts to ask for ways to make it work like it was before It's time to "re-add" `special-display-*' support, I think, i.e., to un-deprecate it (since it is still supported and it still works well). I don't think that we have today a use of `display-buffer-alist' that rivals the use of the `special-display-*' options for handling their use cases. And I think we should add those features back with full support (they are not gone, but they have been deprecated). Note, BTW, this from Juanma, which pretty much sparked the discussion: J> From someone who has read the docstring of J> `display-buffer-alist' once too many and gleaned way too J> little meaning from it (no offense, Martin, I love your J> work, just not this variable's doc)... FWIW, I agreed with that sentiment then, and I still do. The following is also from that thread, this time as a reply to your statement that I am the _only one_ to object (so clearly, I did object). You were replying to Stefan, who said that the new code was more complex: M>> I don't know how many times I went through the code of M>> `special-display-buffer-names' but I know that I still M>> don't understand it. S> S> Yup, and your code is even more complex. M> Let's agree to disagree on that. M> =20 M> `special-display-buffer-names' had only one serious user, M> namely Drew Adams. I know that because my rewrite had a M> number of bugs which we eliminated in a period of two M> weeks mostly by trial and error. In all that time no one M> else complained. I suppose you use it as well but since you M> apparently advice `display-buffer' (or some subset of its M> routines) you were not hit by these bugs. M>=20 M> `special-display-buffer-names' is complex because it prescribes M> behavior for reusing the same window, reusing some other window M> on the same frame, popping up a new window, reusing a window on M> another frame and popping up a new frame. That's the kind of M> expressiveness Drew needs because he's got no other choice. M> It's far too expressive for all other users. D> A comment, since my case has been identified as unique - D>=20 D> 1. `special-display-buffer-names' is _very_, very old. It has D> been in GNU Emacs as far back as the introduction of frames, I D> believe. Someone can check the origin and the original design D> arguments; I'm no expert on this. =20 D>=20 D> 2. AFAIK, from the outset it has been just as "complex" as it D> is today - all of the possibilities have been there since Day D> One. They were not added incrementally because someone thought D> that it would be neat to add a bell here or a whistle there. D> They were thought to be important by the _original designers_, D> many, many moon ago. D>=20 D> 3. The point is that I did not invent `special-display-buffer-names', D> and it was not invented for me. ;-) I have made use of it for D> decades (since at least Emacs 19, maybe 18, IIRC), and I have D> always made the _same_ use of it. D>=20 D> 4. Here is the _only_ use I make of it - Drew's weirdo use case. D> I use only the form (BUFFER FUNCTION OTHER-ARGS...), and only D> for two buffers: *Help* and *Completions*. ... D> HTH. Personally, I do not consider my use of D> `special-display-buffer-names' to be strange or outlandish - it D> seems pretty simple to me. D> D> If it is true that I am the only one to use this feature, so be D> it. But that in itself does not make this feature or my use of D> it "complex". And I would even guess that if more things worked D> better in GNU Emacs wrt frames (as opposed to just windows) then D> you might see more people using this feature. D>=20 D> FWIW, my code for this works in Emacs 20 through 23, and it also D> works with Emacs 24 after Martin's efforts to fix some initial D> bugs (thank you, Martin!). And it works cross-platform, AFAIK. D> Not so far out, really. Going back further, you will see this, from me, in the May 2009 thread "display-buffer cleverness - how to tame?": D> If the new `display-buffer' approach is so complex that just D> describing a simple way to get back the old behavior is too D> difficult (even for the implementor!), then, yes, I think we D> have a problem. 8 years later, we're still there, it seems. And before that, in the same 2009 thread: D> I'm sure the new display-buffer behavior is an improvement D> in some way, but it seems too clever by half, at least in D> one context I have. D>=20 D> I'm not suggesting the smarter behavior should be reverted D> (I'd have to understand it first, to be able to suggest D> that ;-)). I just want to know which settings I need, to D> get back the previous behavior for some code I have that D> (apparently) depends on it. Now back to the present - > > `display-buffer-alist' is notoriously difficult to > > understand and make use of. As one example, though I've > > asked several times how to use it to get the same effect > > provided by these options I've never gotten a response. > > > > That's the first step for Emacs to take, IMO, after > > undeprecating these options (as well as anything else > > "special-display", of course, such as > > `special-display-alist'): State in the doc exactly how > > they correspond to a special case of using > > `display-buffer-alist'. _Show_ the equivalence. >=20 > Despite the fact that many years ago I moved these options and the > corresponding functions from C to Elisp, I still don't understand them > and very likely never will. If you asked me how to obtain a specific > behavior with =E2=80=98display-buffer-alist=E2=80=99, I might be able to = come up with an > answer. I'm still hoping that _someone_ can explain how to get the behavior of the deprecated simple constructs using the proclaimed replacement and generalization, `display-buffer-alist'. > In any case I deeply regret that I ever got involved in this. I'm sorry you feel that way. I, for one, am very glad you did get involved in this. It is a _good_ thing to have improved and generalized `display-buffer-alist'. You did a _lot_ of good work, which everyone has recognized and which Emacs users now benefit from. And it is a good thing (after several requests over the years, by multiple users) that we now have better doc for it. (It could be better yet, I think; I still find it hard to follow.) The missing pieces are to (1) un-deprecate `special-display-*' and (2) document the relation between the `special-display-*' features and `display-buffer-alist'. If there is _no_ relation between the two, then that's all the more reason to un-deprecate `special-display-*'. If the relation is too complicated for anyone to understand or document then that too is all the more reason to fully support and document `special-display-*'. Let me end here with another quote from myself from that 2011 thread, to make clear (again) how I feel about your work on this: D> Let me be clear again that I have confidence in what you're D> doing, Martin. I agree with you and others that things are D> currently quite complex for users, and I'm one of those who D> does not yet understand how to use `display-buffer-alist'. D>=20 D> But I expect that with time, discussion, and experiment we D> can iron things out and simplify somewhat (at least the doc, D> and perhaps the design/UI). D>=20 D> Let me be clear too that I appreciate your trying to handle D> the complexity, to deal with all of the various use cases, D> and to maintain coherence wrt previous behavior. D>=20 D> I do _not_ want to see things get dumbed down just because D> we haven't yet found an ideal way to present them (UI, doc). D> The first task should be to handle all of the use cases. D> Only secondly should we try to simplify, and do so without D> sacrificing use cases. D>=20 D> Please continue to explain patiently to us all what we D> don't understand, and please continue to resist simplistic D> "solutions" proposed by _any_ of us who understand this D> stuff less than you do. Keep up the good work, and do not D> hurry or simplify prematurely or simplistically just D> because someone points out that things are, so far, D> complex for users. There's no hurry.