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: Mon, 22 Oct 2018 16:55:56 +0300 Message-ID: <838t2qt79v.fsf@gnu.org> References: <5BCB1D82.3020108@gmx.at> <834ldgvjmj.fsf@gnu.org> <5BCB6DAE.30209@gmx.at> <83mur7tq4f.fsf@gnu.org> <5BCD92FF.8070905@gmx.at> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1540216880 28617 195.159.176.226 (22 Oct 2018 14:01:20 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 22 Oct 2018 14:01:20 +0000 (UTC) Cc: emacs-devel@gnu.org To: martin rudalics Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 22 16:01:16 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 1gEalf-0007Jd-FS for ged-emacs-devel@m.gmane.org; Mon, 22 Oct 2018 16:01:15 +0200 Original-Received: from localhost ([::1]:35436 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEanl-0002rV-Td for ged-emacs-devel@m.gmane.org; Mon, 22 Oct 2018 10:03:25 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:40435) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEagz-0005v9-Ly for emacs-devel@gnu.org; Mon, 22 Oct 2018 09:56:29 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gEagn-0007ig-VS for emacs-devel@gnu.org; Mon, 22 Oct 2018 09:56:20 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:52650) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEagm-0007he-6s; Mon, 22 Oct 2018 09:56:13 -0400 Original-Received: from [176.228.60.248] (port=2093 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gEagj-0005sx-Mc; Mon, 22 Oct 2018 09:56:12 -0400 In-reply-to: <5BCD92FF.8070905@gmx.at> (message from martin rudalics on Mon, 22 Oct 2018 11:06:07 +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:230555 Archived-At: > Date: Mon, 22 Oct 2018 11:06:07 +0200 > From: martin rudalics > CC: emacs-devel@gnu.org > > > I'm not against tutorials; far from that. I just think they should be > > separate from Reference manuals. Reference manuals can then point to > > tutorials for examples. > > I could put the last two sections into the "Tips and Conventions" > chapter. Or do we have another place where to put tutorial-like text? No, I don't think we have any place for tutorial-like stuff. Tips is something different. > My basic idea was to put the description proper into the first three, > four sections and leave the last two, three sections to those puzzled > by the technical level used in the decription. I guess I'll have to re-read the text once it's installed, maybe I failed to catch the spirit reading the diffs (which included a lot of whitespace changes, so it wasn't always easy to find the real changes). > But asking again: How else would you address a complaint like > > Telling someone that they must instead use > `display-buffer' ACTION hoops to accomplish > the same thing leads them down the garden path, > on a wild goose chase, over the river & through > the woods, and around Robin Hood's barn. IMO. > > if not with the help of an example where every single step can be > executed right in place and the effect of that step seen right away? Was that complain before or after I reworked the doc strings? > Well, Alan's impression was that > > The doc string of display-buffer is a bit of a heavy read at this time > of night. > > and I'm currently contemplating to remove the description of action > alist entries from it. I recommend against the removal. People who are tired at night (myself included) are free not to read the doc string, but that doesn't mean there's something wrong with it. A flexible interface always requires a long documentation. > 'display-buffer' is a function that delegates > its work to action functions (Drew's garden path) and guides the > latter with the help of action alists which have now their separate > entry in the Elisp manual. The "further down" in the garden path an > information is found, the more Drew will complain. The "further up" > everybody else will complain. Complaints are not the only thing to guide us in this case. > Unlike `pop-to-buffer', this function prefers using the selected > window over popping up a new window or frame. Specifically, if > the selected window is neither a minibuffer window (as reported > by `window-minibuffer-p'), nor is dedicated to another buffer > (see `window-dedicated-p'), BUFFER will be displayed in the > currently selected window; otherwise it will be displayed in > another window. > > While this would be appropriate for 'switch-to-buffer-other-window' it > may be wrong for 'pop-to-buffer-same-window' as soon as the user has > customized 'display-buffer-alist'. We can't avoid the garden path of > 'display-buffer' here and elsewhere. I don't think we cannot avoid it, we just need to qualify what I wrote with the "not customized" caveat. Nothing a single sentence couldn't fix.