From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Documenting buffer display Date: Tue, 23 Oct 2018 18:18:13 +0300 Message-ID: <83sh0wsnd6.fsf@gnu.org> References: <5BCB1D82.3020108@gmx.at> <834ldgvjmj.fsf@gnu.org> <5BCB6DAE.30209@gmx.at> <83mur7tq4f.fsf@gnu.org> <5BCD92FF.8070905@gmx.at> <838t2qt79v.fsf@gnu.org> <5BCE21AC.6030904@gmx.at> <831s8hu6i8.fsf@gnu.org> <5BCEE2B5.9090205@gmx.at> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1540310482 25314 195.159.176.226 (23 Oct 2018 16:01:22 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 23 Oct 2018 16:01:22 +0000 (UTC) Cc: emacs-devel@gnu.org To: martin rudalics Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Oct 23 18:01:18 2018 Return-path: Envelope-to: ged-emacs-devel@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 1gEz7L-0006SZ-MH for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 18:01:15 +0200 Original-Received: from localhost ([::1]:42934 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEz9S-0007nu-Aa for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 12:03:26 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36803) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEyhz-0006fR-78 for emacs-devel@gnu.org; Tue, 23 Oct 2018 11:35:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gEyRs-0005yJ-5Y for emacs-devel@gnu.org; Tue, 23 Oct 2018 11:18:26 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:52938) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEyRs-0005yD-1M; Tue, 23 Oct 2018 11:18:24 -0400 Original-Received: from [176.228.60.248] (port=4797 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gEyRr-0001Sl-Kq; Tue, 23 Oct 2018 11:18:23 -0400 In-reply-to: <5BCEE2B5.9090205@gmx.at> (message from martin rudalics on Tue, 23 Oct 2018 10:58:29 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:230591 Archived-At: > Date: Tue, 23 Oct 2018 10:58:29 +0200 > From: martin rudalics > CC: emacs-devel@gnu.org > > (pop-to-buffer (get-buffer-create "*Find*") > '(display-buffer-same-window (inhibit-same-window))) > > … so that Emacs would still try very hard to display the Find buffer > in the current window, but I could nevertheless override that by > customizing `display-buffer-alist'. > > And that's where 'pop-to-buffer-same-window' kicks in by accomplishing > _two_ things at the same time: It allows the author of 'find-dired' > and its "normal" users to continue working as if nothing changed at > all. And it allows users like Trevor to customize the way *Find* is > displayed at their discretion. "Customize", as in setting display-buffer-overriding-action or display-buffer-alist, you mean? > An earlier approach to provide such behavior was to add functions like > 'find-dired-other-window' and 'find-dired-other-frame' maybe with > appropriate key bindings. Nothing's wrong with that, IMNSHO: we do that for many other commands, so it is a kind-of de-facto Emacs tradition/standard. > The shortcomings of that approach are: > > (1) The number of predefined functions to display a buffer is usually > tripled. > > (2) The user may have to memorize key bindings for three functions > instead of one. > > (3) These three functions still do not cover the entire spectrum of > behaviors users want like showing the buffer on a specific side of > the selected window or frame. But there's also a huge advantage: users who are not very proficient in Lisp will both discover the functionality and use it much easier. Especially since we have many other commands factored in that way. By contrast, constructing display-buffer actions is not for the faint at heart. > With 'pop-to-buffer-same-window' all 'find-dired' does now is to > _propose_ the selected window as the most suitable candidate for > displaying *Find*. OTOH there's no more guarantee that *Find* will > actually appear in the selected window. The ultimate decision of > where *Find* will appear is left to the user. FWIW, I think it's wrong to advertise display-buffer-overriding-action, and even display-buffer-alist, as the main way of user-level tweaking commands into doing something completely different from what they were coded to do. I could argue that if such overrides are to be used as a matter of routine, then the whole "middle layer" of display-buffer-SOMETHING functions, including pop-to-buffer-same-window, is entirely redundant, because many users will override their preferences anyway. My POV on this functionality is that the overriding action lists are mainly for Lisp programs, not for users, and that those Lisp programs don't abuse the feature to completely subvert certain display-buffer function to do the opposite of what their names say. But I digress. > The doc-string of 'pop-to-buffer-same-window' is useful for two kinds > of persons: > > (1) The author of 'find-dired' who now would be aware of the fact that > *Find* will not be necessarily shown in the selected window. He will > be warned by the word "preferably" in > > "Select buffer BUFFER in some window, preferably the same one." > > but he won't care about whether the default behavior avoids the > selected window if its dedicated. In fact, he has to be prepared for > the worst like *Find* popping up on a new frame or *Find* being > displayed in the selected window despite the fact that it is dedicated > to some other buffer. > > (2) Users who want to know how to _change_ the default behavior by > customizing 'display-buffer-alist'. Such people typically want to > show *Find* in some other window so they won't care about the > dedicated status of the selected window either. So would adding to the doc string something like this: (This default behavior can be changed by customizing `display-buffer-overriding-action' and `display-buffer-alist'.) take care of your concerns? This is that "single sentence" I had in mind a few messages back. IOW, I assume that in 90% of the cases the *Find* buffer _will_ pop up in the selected window, and that the other 10% are mostly due to users who should be knowing what they are doing, and if they don't, it's their funeral. If *Find* does _not_ pop up in the selected window in the vast majority of cases, then IMO find-dired has a bug that needs to be fixed. And I submit that you forget one very important class of readers: those who are neither the author of find-dired nor those who want to tweak the heck out of find-dired. They are those who want to understand _why_ find-dired works like it does, or _how_ does it cause the buffer to be displayed in that particular window. IOW, those who see a call to pop-to-buffer-same-window and want to understand what that does and which other variables/functions affect what it does. This is the primary audience for doc strings. > But your change strengthens the view that 'display-buffer' behaves as > requested by its caller. It usually does, or at least should, IMO. It is IMO wrong to make the documentation too complex in order to be 110% accurate, if that accuracy comes at a price of leaving the reader without a more-or-less clear mental picture regarding what a feature does in 90% of use case. Rare corner cases should be "banished" to footnotes and parenthesized notes, or even omitted altogether, if they complicate the main use cases too much. This is one such case: it makes little sense to me to waste too much of the reader's prime time in order to explain how a function designed to display a buffer in the selected window could be tweaked into doing the opposite. > That view inevitably leads to confusion. Are you sure "confusion" is the right word here? If so, please elaborate, because I think you meant something like "inaccurate information" (and IMO the inaccuracy is very minor). In any case, would you agree that qualifications such as the one proposed above will go a long way towards fixing those issues? > >> Any explanation of what 'pop-to-buffer-same-window' does without > >> referring the reader to 'display-buffer' is misleading, at the very > >> least. > > > > I obviously disagree, as I did just that, and I object calling the > > current text "misleading". > > Then why do we have all this dispute about 'display-buffer'? You mean, the discussion about the changes in the manual? Because you asked for review and comments. > According to the majority of people because its documentation is > confusing, wrong, incomplete, implicit, arcane or just bad. Are you talking about the doc strings or about the manual? If about doc strings, then I'd like to hear or read those complaints, if they are still valid after my recent changes. I hope you trust me that I wouldn't have left unfixed any doc strings matching any of the above complaints.