From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.devel Subject: Re: Documenting buffer display Date: Tue, 23 Oct 2018 20:23:38 +0200 Message-ID: <5BCF672A.4080605@gmx.at> 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> <83sh0wsnd6.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1540318945 13115 195.159.176.226 (23 Oct 2018 18:22:25 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 23 Oct 2018 18:22:25 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Oct 23 20:22:21 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 1gF1Js-0003C5-Oo for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 20:22:20 +0200 Original-Received: from localhost ([::1]:43721 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gF1Lu-00011P-42 for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 14:24:26 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34801) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gF1LJ-0000iY-6N for emacs-devel@gnu.org; Tue, 23 Oct 2018 14:23:50 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gF1LI-0004qL-1A for emacs-devel@gnu.org; Tue, 23 Oct 2018 14:23:49 -0400 Original-Received: from mout.gmx.net ([212.227.17.20]:41291) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gF1LE-0004nb-Br; Tue, 23 Oct 2018 14:23:44 -0400 Original-Received: from [192.168.1.101] ([213.162.73.191]) by mail.gmx.com (mrgmx101 [212.227.17.168]) with ESMTPSA (Nemesis) id 0LdLw5-1foRws0RoP-00iV5j; Tue, 23 Oct 2018 20:23:43 +0200 Original-Received: from [192.168.1.101] ([213.162.73.191]) by mail.gmx.com (mrgmx101 [212.227.17.168]) with ESMTPSA (Nemesis) id 0LdLw5-1foRws0RoP-00iV5j; Tue, 23 Oct 2018 20:23:43 +0200 In-Reply-To: <83sh0wsnd6.fsf@gnu.org> X-Provags-ID: V03:K1:2oqxp2wabVbnhcfCKXK24qvKjAyCnpGgQJTP5M/LqmjK03fM70U L7aSxNjOK2RtgChiBr30CXwhqu6k7wj3MClLdcONdT+DSpPXOd1+uid98gVQ9eyBueMzKGT lPjB/z2wO1ENrCIH1F527RyJlsP+kv4ryYFyekRwyVRYW/6YOOxdtjdVC1xUAHwlAFICKpI Ea/GVBjT7XBkzm0FVuF2g== X-UI-Out-Filterresults: notjunk:1;V01:K0:aTkZJimuBrk=:Qvv64yF0SKKsB8dncotFi9 cnxlB9UqVW2ysGuUsg8NECZYfdKXbjZOxxId/jPi+UOiJ4PUB1sHjjhPEGFtU228l3YXhuGBw t/JpHNAPmgSxyjSQ3eyW7oJXyuBMHUjWu5komkbJbEXHrR5PhUILPtxti0qnkHXUHCqornrv0 kDLPAS725GdRt5vuVDm/o/GHyZW3V+UCG2GgXoU5/L5au6TNmQFohCrYJmTLKDs3ghYngmx+8 fU49sAzt9nrUNFOrOq+rnBxwDBtTmP3m+JCQ9Boi+eSUNkGeyFlzDYJPEkuFkyKBrbKLQxHVs rPCnVcttsOx8c+sM09d4KBp5oyYSA704K5KeNmllTgytCK+u1qzqA8lvcrRi2wdtdUjxfpZUM VieKrGmJivtZjKBPiLIjrhuuORo7gAd+ca9b24MdgrGbFQwJgy2bdESh8tr9vWBRvfMtiPkWK 6mtMwQYZ/VY8jcuahTICTHpSqbsqBnMHsfy7a0Qjhym8bCkwQ28lLaGCBANbQ1rpxf8z16z1J bgF1T/D3bDLMYijhCS4QIyT5gG/HBEYifaeMOeZ2Mr2VuclP2LrRmUYuxG87T4X+uLx+qx5Hw SEKzCLyQDK+McmQIF1v0KiroP90J2oMuOwjFjdTaoowRPtlBCS/BvCdqqrTuQUQxpazcTPCLX Rlx2iO4/re2YK8FSIMtE2+tkmeJs88ozdXMsSS/DLXQEGJYtp/wet6x7mY4MEgQ4C8oF92TXT MC4uxkwIKysyNEKztV8Y/rJvzDm8WkdO0U5aOhEFB7xaalkJCUSk+Yh0u0RanOn+hL47JpXB X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.17.20 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:230605 Archived-At: >> 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? The latter. 'display-buffer-overriding-action' is a variable reserved for applications as the manual should now state more clearly: `display-buffer-overriding-action', on the other hand, is reserved for applications - who seldom use that option and if they use it, then with utmost care. >> 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. Our former maintainer strongly objected the introduction of such commands and it's not very easy for me to adapt. In particular because I have absolutely no opinion in this regard - I never use such commands consciously. > 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. The problem is that in most buffer display cases no alternative '-other-frame', '-other-window', '-same-window' constructs are provided. If there were a systematic way to provide them and if there were suitably mnemonic key-bindings for such commands, things would be certainly different. > FWIW, I think it's wrong to advertise display-buffer-overriding-action, ... as you can read above I advertise the opposite ... > 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. And the manual should say now Users should not pose too many and too severe restrictions on how arbitrary buffers get displayed. Otherwise, they will risk to lose the characteristics of showing a buffer for a certain purpose. > 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. What do you suppose a user to do if 'pop-to-buffer-same-window' is the _only_ alternative an application offers to display a buffer? > My POV on this functionality is that the overriding action lists are > mainly for Lisp programs, Right. But you should have read the manual before. > 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. Why. You only repeated what the manual already should say now. > 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. That doc-string is not for users. It could say that applications cannot expect that the buffer is displayed in the selected window or that the dedicatedness of that window is respected because a user's customization may override everything that function specifies. > 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. *Find* will continue to pop up in the selected window in the vast majority of cases. Just that an application cannot be sure that it will pop up there in _all_ cases. > 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. Such users will have to read the documentation of 'display-buffer'. It's their funeral if they don't. > 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. Then why do you care to talk about the dedicatedness of windows in the doc-string? How many people use dedicated windows? When and where do you use them? >> 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). I don't think that "confusion" is the right word. IMO the doc-string is just wrong. But I didn't want to say that. > In any case, would you agree that qualifications such as the one > proposed above will go a long way towards fixing those issues? I sketched above what I would write instead. >> 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. I meant the disputes excerpts of which I cited here in various occasions and which amount to the next two lines. >> 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. I'll remind you the next time this issue comes up. At least Alan just wrote about the doc-strings. martin