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: Wed, 24 Oct 2018 11:44:56 +0200 Message-ID: <5BD03F18.1020100@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> <5BCF672A.4080605@gmx.at> <83k1m8scq9.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 1540374265 16455 195.159.176.226 (24 Oct 2018 09:44:25 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 24 Oct 2018 09:44: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 Wed Oct 24 11:44: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 1gFFi5-00046t-LW for ged-emacs-devel@m.gmane.org; Wed, 24 Oct 2018 11:44:17 +0200 Original-Received: from localhost ([::1]:47105 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gFFkC-0000Ep-5p for ged-emacs-devel@m.gmane.org; Wed, 24 Oct 2018 05:46:28 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:40697) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gFFit-0007lT-Ur for emacs-devel@gnu.org; Wed, 24 Oct 2018 05:45:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gFFiq-0007G5-MI for emacs-devel@gnu.org; Wed, 24 Oct 2018 05:45:07 -0400 Original-Received: from mout.gmx.net ([212.227.17.21]:44665) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gFFiq-0007FZ-D3; Wed, 24 Oct 2018 05:45:04 -0400 Original-Received: from [192.168.1.101] ([212.95.5.202]) by mail.gmx.com (mrgmx101 [212.227.17.168]) with ESMTPSA (Nemesis) id 0M7kwW-1fKFJf0ZcG-00vND5; Wed, 24 Oct 2018 11:45:03 +0200 Original-Received: from [192.168.1.101] ([212.95.5.202]) by mail.gmx.com (mrgmx101 [212.227.17.168]) with ESMTPSA (Nemesis) id 0M7kwW-1fKFJf0ZcG-00vND5; Wed, 24 Oct 2018 11:45:03 +0200 In-Reply-To: <83k1m8scq9.fsf@gnu.org> X-Provags-ID: V03:K1:tjynmEEXkocSAt+L6bwMRVsc0XHpb1HaLsTsXvvTbc4HjHzi1Ty sx/Vx7XyWZkyZU2oZ8Z0aBGPkOyThDWOShtMGscvy64QtYsPZT6vGhcGumP4R7TbD1IwWVe HpAghxdq31Co3Dzkw/6A8ZKndP8xb4XmMDxfG0TSKk4GP0fyZzbQ1Bpi8nQML2BfjZ5+xcR G06Ua+pZZ874vOJq6hHzg== X-UI-Out-Filterresults: notjunk:1;V01:K0:Lc+fc7FRyrI=:ljxOloMtIH7a9rlTDoGVcd tgRD2uMK2jQFDboladEYkIVIWrWwbHU9/qvEzA6eOt23+bxkXmafrcC8ZSCYkAL4TE54zDfbe G/EsH5nPtHoJ8M8Fgrtyfv/ufPBUO0/IT169X4TJAn+ZB0NT3z6fD+RZsLkTMROMS3jfnAuKY aQ3iw/HHpSKQ7supm4B5Rx81/x++Xl/dZONXTyCiAf8EdtF00hy9JRrO8/MTwXfCgduubZoa+ NMu4CkRj3eZ6brsmTEGCjyb5vMr6oULjPipPqP4LyqfMlW+moCDZY0/192nbO0pVWp02lbaYv OKM+HqX9Ls2VWrXE0jJad6tBaIQxDyf59jMcs7wLRDPTekwW3hBuKyGM4+z3GT6B8m84dqvkI 2fH5ITtQUlmiP1ORP+5sJqWPaEKEIAmTNS4RsLZOSPCB8s2kWgT17Plt1b9lsMMTHhc9WFpJP TSk31JFEuSnZ456hLBXngYHMFXNt7mRrGpJspwkktQy88Ra6ZobaEvsR41UDdkn+H1mJvOdR8 xaR0Fd6COcjbB5KYEo53sBZu9KoDEAwqXa9PtE/aEMzHX3K0FjfM7/0Mpr6XP2PUl+g004BGe 2kVF2FQdJNxwyNx4JBQqD8rKsfrsl67M86IVjhzxHA1EBVrAJ3P75Xp+SbZR5OD0FLaB/b5NV VKddbBmuqUfDpcCqj2UW0L8fm9FY5UahMmF4FYpWaP4B6R+oZFPRZZfpB71dbaCglPP+PnUop hsjMLGQ/whU/8IC/cVS421aL3NI+t4qYXmEOCBNPS7hP+e3r/zldRRvi4fpv8+09v8WXzuxF X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.17.21 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:230620 Archived-At: >> 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? > > They should ask for a separate command, or for a user option to have > the buffer displayed not in the selected window. That option could > (but doesn't have to) be implemented under the hood using action > lists, of course. That user option already exists as 'display-buffer-alist'. That option was invented precisely for that purpose. That option has no other purpose. >> That doc-string is not for users. > > ??? Then for whom are they? For application programmers only. If you look at the history of that function you will see that I added it once, that Chong removed it later and finally re-added it. IIRC Stefan didn't like it for some reason and wanted programmers to write out its specification directly. In retrospect, he was right because 'pop-to-buffer-same-window' does indeed create false assumptions. In short (pop-to-buffer-same-window buffer norecord) which can be rewritten as (pop-to-buffer buffer display-buffer--same-window-action norecord) is _not_ semantically equivalent to (select-window (display-buffer-same-window buffer nil) norecord) That last fact is what 'display-buffer' is all about. 'pop-to-buffer' calls 'display-buffer' so users can customize its behavior. An application calls 'pop-to-buffer' so users can customize its behavior. If we don't agree on this single central issue, it makes no sense to discuss 'display-buffer' any further. 'display-buffer' does not offer anything else. Its sole purpose is to allow users to customize buffer display. >> Such users will have to read the documentation of 'display-buffer'. >> It's their funeral if they don't. > > We disagree. I specifically made the doc strings of intermediate > functions more explicit about what they say to avoid forcing the users > to go all the way to display-buffer. The main reason was that it was > very non-trivial for me, having read the doc string of display-buffer, > to propagate the information back to the higher level functions I was > interested in. And if it was non-trivial for me, it is certainly > non-trivial for less experienced Lispers and users. Sadly we disagree here ... >> Then why do you care to talk about the dedicatedness of windows in the >> doc-string? > > Because that describes what the function does. ... and here ... >> How many people use dedicated windows? When and where do you use >> them? > > I don't see how this is relevant to the discussion. If the code > honors dedicated windows, they are important enough to be mentioned in > the doc string. If you think dedicated windows are not important, why > did you code their support? .. and here. The code that honors dedicated windows is that of 'display-buffer-same-window' and the latter's doc-string describes that. >> IMO the doc-string is just wrong. > > I cannot disagree more, sorry. And since we disagree so much, I guess > we should stop this part of the discussion, and I should probably > refrain from commenting on your manual work. At this moment I can only thank you for all the confidence and patience you've shown in this thread. I'm probably too categorical and also feel too old and tired to go on further with this subject. So let's call it off. If people want to continue with it, feel free to peruse the text I submitted any which way you like. Thanks again, martin