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: Mon, 22 Oct 2018 21:14:52 +0200 Message-ID: <5BCE21AC.6030904@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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1540235649 7979 195.159.176.226 (22 Oct 2018 19:14:09 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 22 Oct 2018 19:14:09 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 22 21:14:04 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 1gEfeO-0001yk-8n for ged-emacs-devel@m.gmane.org; Mon, 22 Oct 2018 21:14:04 +0200 Original-Received: from localhost ([::1]:36782 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEfgU-000159-76 for ged-emacs-devel@m.gmane.org; Mon, 22 Oct 2018 15:16:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48317) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEffL-00014q-8m for emacs-devel@gnu.org; Mon, 22 Oct 2018 15:15:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gEffK-00059i-D2 for emacs-devel@gnu.org; Mon, 22 Oct 2018 15:15:03 -0400 Original-Received: from mout.gmx.net ([212.227.15.15]:52967) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gEffG-00054X-NO; Mon, 22 Oct 2018 15:14:58 -0400 Original-Received: from [192.168.1.101] ([213.162.73.113]) by mail.gmx.com (mrgmx003 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MK0ur-1gDqia00bF-001ROC; Mon, 22 Oct 2018 21:14:57 +0200 Original-Received: from [192.168.1.101] ([213.162.73.113]) by mail.gmx.com (mrgmx003 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MK0ur-1gDqia00bF-001ROC; Mon, 22 Oct 2018 21:14:57 +0200 In-Reply-To: <838t2qt79v.fsf@gnu.org> X-Provags-ID: V03:K1:RZyiaBSlnPmLkJCTKHaU4dhCqbhjD+V2dtzi17nQOzC8xC2m+hQ MQMjxyUfpGkD7mB8rTSHEelZePbz71itjZJMAp7UH6fcVOHVT1UAkS2NwuvNisry2BYoh7T LTn/+ENgeUBT2a1i7+HlDeGdEhMlDQxMd2fvCAcWtusHy/EltLsuOjimL3/uBOTwqCfEr4r ygn2Crz2Tba9aqTkNdw/Q== X-UI-Out-Filterresults: notjunk:1;V01:K0:KTSy/lcZdrI=:eZlqNgzgaNV/yVHrfi5RAR IwXLuL15yAj/pbFAGNTeMLK4XYQfszMobssrTWkl9FX9iflrRQawOuWr0zdCTyOISIRbJrRoG In2rngIglPJCE2GwX5e4pix+FKL9qTgAUuguF9BGuDWuz0b6ptIRs7iUzk/0GuUFjD8kN3WTu t40lBiVQ0ZUOAh2MTJMVZeoB3Toe4N37UuCcfFoWLHtZWZTmdzUEuSdyaW+xZ2raWaC4/c0L4 iIafIxyVNocqphyoab3WAgwzpRZP4jqhOMkY9Aw0NbxenDCF60JKzaksXXZzc4VSf3DNe26pU uUkZepgMT+D1Fph9Wbhoa/R32W8Z+XkriqXbl9Dim/N2SZx2c/sTzZmhNxYLMpOZBvn7NG/+B mb+8t1n1eysqNwrBPT8b9hMIg7RvaF1EZMI5ZsTYu/uWgh0is627FSikqN0rp2yO/F5Yf4nmW luKA91+I64VWbF4CRI22wXlG93a6JwHHU3kxXPLHY39mRGwt1FoEG+kuDZbsy58v239M2u+ZN A5nREN7db0WVzV5QBQDXW9aKUd0VdgnEUtY2daYNI40+uy6u2Z3w1mxJ0NVims4EQzcCwKK4J CF2P54ydDjKRrpjKVyZ5fFIcBAomUBiQTRm7WQklgGi59HDBuNYpPrvKrm6pOh1Nn1OGFfzxZ lkYx11oSSxMvLBhRKNG9rKkieK4qPshpWtmvKGIRi9pyP1+a7vDlpP+I3HcKXbsgoHKM9oXmG PskKihn2BxhpjyKtrpMR843sU4eFBSCcP4Yx35pwM9EnzdOArczZWd8iId4/WVPXzwP1Xs3y X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.15.15 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:230571 Archived-At: >> 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? After, I suppose. It's from a mail Drew posted yesterday. > 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. Sooner or later the number of recognized action alist entries will become too large. >> '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. Complaints are never a good guide. But here it's hard to find the right balance of correctness and completeness on the one side and conciseness on the other. >> While this would be appropriate for 'switch-to-buffer-other-window' i= t >> 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. Trevor Murphy on emacs-devel I just noticed that `find-dired' and friends use `switch-to-buffer' as= a subroutine. Since this does not go through the `display-buffer' mechanism, it=E2=80=99s really hard for me to control where Emacs disp= lays the Find buffer. I=E2=80=99m currently advising `find-dired' to use `pop-to-buffer' instead. to which Stefan replied There's pop-to-buffer-same-window. Which means that people want 'pop-to-buffer-same-window' instead because they can customize it to display the buffer in _another_ window. Which further means that a "not customized" caveat would be counterproductive here. Any explanation of what 'pop-to-buffer-same-window' does without referring the reader to 'display-buffer' is misleading, at the very least. martin