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 22:07:58 +0300 Message-ID: <83k1m8scq9.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> <83sh0wsnd6.fsf@gnu.org> <5BCF672A.4080605@gmx.at> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1540321581 25672 195.159.176.226 (23 Oct 2018 19:06:21 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 23 Oct 2018 19:06:21 +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 21:06:17 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 1gF20N-0006XA-Cz for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 21:06:15 +0200 Original-Received: from localhost ([::1]:43843 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gF22U-0002DD-1C for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 15:08:26 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45376) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gF22M-0002D4-WE for emacs-devel@gnu.org; Tue, 23 Oct 2018 15:08:20 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gF22F-0001Bw-Gh for emacs-devel@gnu.org; Tue, 23 Oct 2018 15:08:14 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:57755) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gF22F-0001BY-Bj; Tue, 23 Oct 2018 15:08:11 -0400 Original-Received: from [176.228.60.248] (port=3199 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gF22E-0007eX-Pz; Tue, 23 Oct 2018 15:08:11 -0400 In-reply-to: <5BCF672A.4080605@gmx.at> (message from martin rudalics on Tue, 23 Oct 2018 20:23:38 +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:230608 Archived-At: > Date: Tue, 23 Oct 2018 20:23:38 +0200 > From: martin rudalics > CC: emacs-devel@gnu.org > > >> 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. I hope it isn't a scoop that our former maintainer's opinions are not the only ones on the block. > > 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. I'm not saying that we should provide such variants for every buffer-display function. I'm saying that if it makes sense in the case of find-dired and other similar commands, there's nothing wrong with having such variants. > 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. Nor does every command have to have a keybinding by default. > > 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 I was mostly talking about doc strings. > 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. Then we agree. And consequently, the fact that what I wrote in the doc string about pop-to-buffer-same-window doesn't cover such customizations should not be a reason to say the doc string is misleading or confusing, do we agree about that? > > 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? 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. > > 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. ??? Then for whom are they? > 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. That is not a useful documentation, IMO. It sacrifices usefulness on the altar of 100% accuracy, instead of being much more useful for the price of being only 99% accurate. > *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. The one-sentence qualification goes a long way towards warning of this rare possibility. I see no reason to expand more about that, as doing that runs the risk of drowning the main scenario in the sea of relatively unimportant details. > > 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. 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. > > 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? Because that describes what the function does. > 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? > 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. Thanks.