From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.bugs Subject: bug#45688: 28.0.50; New action for display-buffer? Date: Thu, 7 Jan 2021 16:17:52 +0100 Message-ID: <3a1fc415-75f1-8b91-216d-0cad63a3eaa0@gmx.at> References: <87im8a1dff.fsf@gnus.org> <6d33f679-925e-78ee-2055-0520538f48f5@gmx.at> <87ble217jy.fsf@gnus.org> <8bc28c07-a4af-f58d-97f5-9d0a89ff58fe@gmx.at> <87h7ntynpx.fsf@gnus.org> <616655cc-9b87-cb93-6787-11e7037e8cbc@gmx.at> <87sg7c3isu.fsf@gnus.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="10396"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 45688@debbugs.gnu.org To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jan 07 16:19:17 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kxX4G-0002YP-FZ for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 07 Jan 2021 16:19:16 +0100 Original-Received: from localhost ([::1]:51896 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kxX4F-0005UW-Gu for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 07 Jan 2021 10:19:15 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:40494) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kxX42-0005QU-Fh for bug-gnu-emacs@gnu.org; Thu, 07 Jan 2021 10:19:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:36775) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kxX42-0007z9-8E for bug-gnu-emacs@gnu.org; Thu, 07 Jan 2021 10:19:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kxX42-0007kY-33 for bug-gnu-emacs@gnu.org; Thu, 07 Jan 2021 10:19:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 07 Jan 2021 15:19:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 45688 X-GNU-PR-Package: emacs Original-Received: via spool by 45688-submit@debbugs.gnu.org id=B45688.161003268229718 (code B ref 45688); Thu, 07 Jan 2021 15:19:02 +0000 Original-Received: (at 45688) by debbugs.gnu.org; 7 Jan 2021 15:18:02 +0000 Original-Received: from localhost ([127.0.0.1]:48321 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kxX33-0007j9-Rv for submit@debbugs.gnu.org; Thu, 07 Jan 2021 10:18:02 -0500 Original-Received: from mout.gmx.net ([212.227.15.15]:56127) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kxX31-0007in-NT for 45688@debbugs.gnu.org; Thu, 07 Jan 2021 10:18:00 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1610032673; bh=NDpygpibSJiKJ/GgCK4SIv1wAdcB7+4aitmXZFQUO9s=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=LSKVdQFuuH3IGrD/u47ZHjSiCF+uq2geFTpcKS27zHKp/pvXInIgODiqOdJJh8HrJ HoyjU8GBgOKIQSoTzju/WPfrvstYZTVt4tO7OTzhGvIIrhIC0FasMfyVvE80HEZno1 +ZqyViNbCyw3s0iuYxPszqNlW40pLdGiibBSlHzo= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from [192.168.1.100] ([212.95.5.167]) by mail.gmx.com (mrgmx005 [212.227.17.190]) with ESMTPSA (Nemesis) id 1MUXtS-1kXAUT1JL6-00QUJC; Thu, 07 Jan 2021 16:17:53 +0100 In-Reply-To: <87sg7c3isu.fsf@gnus.org> Content-Language: en-US X-Provags-ID: V03:K1:5LcPDLalYl3P4KfS3IzjOz3zuuHVJEINfofUdQkUeZulzKZScRd S210t49r9LL4Qn/wymw52fz6u47Rc40SngVDxzRCrR0QbScmVHMJHs/lP3H92lk2YP0Tv/b JMo4q9cSGiMjJlBVwvc285t+nDr6T1dm1Y7dDt5LDRWJs8RYgYXAQTtST5pfJQHPGuKovb4 B4IsB4W+DeAsJN5jt5iVQ== X-UI-Out-Filterresults: notjunk:1;V03:K0:jhBigScxzBI=:zOlScZBf2R9AOi3NYqr8qL GPn+Ov2RZlCx/hVA0ibtIXqSssPYp1O2iNYhW/0oLUcEU511JVWGx0JTxecDwmAxVcvZQufMv OQiNQUdgCMaTMjBE66zT/QhdKtq7jQS1nFJYFLXfVKVGS8pf3nszcdcTVr4RQdzN6wT4OGuNS wp2C2MEM59HV1T0JAJCpWhycHPmFKfTgrYX4k4TM+2a8lrlwFwnz+CFv4f+4BJ4ve3hE9biJm wkJlwJBZ2QNRONqqSfiqG02cQDz0dl5e7OKgoa8B6z81hNFTlOU5xvIlbkFc8Qwy/xpH4Bwxa KZLFO2RhHjqXoNB5XEeD3ptFbFlW+akvBnv6mUcguwmL57W/Z6HGaRF5kgesVhmpRmei6OZHd mkogVLAzI6em3WYiRu8S9foRslGao7zfk3mdJ49yQxBLtZTjz3RLuXXk4ntdb41wt867UdOvl w8tZ3DxBUS2UvtVqbYmtNdqYB9Lne27pgcohF+b+8fUUxIhIqGNeXPpNkWlg9caTFBBSVvBZ8 mBpbAJyHQsXy/97UVbQWWMOKlbqbCLmkkg37l31jIHFVCliQcNhVd7funj8bcQDrnhEYUW46/ hIXRQOPi3fy9hj6qtjo+w+P33r6joAhvT8R/31JZE/xUQ9rbMe0c8GcryCnvSsihmU/iLkO/Z 1mAURB62ZwO0fPsTtNFk/n14Fnv15AX1OC+2Zulm/Y/4We4Nayc0Nj2d+E76C9EircypL2gIV BdA6Ql5Q6iQI6ddCfjWRUyk+/gaKPNVuNheknRVS5HagHyZ4ZteNkQlpmlCZrxlyEm4lqkKC X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:197487 Archived-At: >> By no means. `display-buffer-overriding-action' is _not_ intended fo= r >> the user. It's an emergency exit for applications. Better not even >> mention it in the user manual and the doc-string. > > See, I didn't even get that bit from the doc string. :-) Given that 'display-buffer-overriding-action' figures first in =E2=80=98display-buffer=E2=80=99 builds a list of action functions and= an action alist by combining any action functions and alists specified by =E2=80=98display-buffer-overriding-action=E2=80=99, =E2=80=98display-b= uffer-alist=E2=80=99, the ACTION argument, =E2=80=98display-buffer-base-action=E2=80=99, and =E2=80=98display-buffer-fallback-action=E2=80=99 (in order). Then it = calls each function in the combined function list in turn, passing the buffer as the first argument and the combined action alist as the second argument, until one of the functions returns non-nil. your interpretation is quite logical. The problem here is that we talk in operative terms like "builds" "combining" "calls" "passing" which hardly contributes anything to the understanding of an average user. In a first approximation it should suffice to talk here about `display-buffer-alist' and the ACTION argument only and ... >> In every other regard, feel free to change it in a way that sounds le= ss >> imitating. For example, listing the action functions and alist entri= es >> in the doc-string is merely distracting. We started out with small s= ets >> and every time a new function or entry was added, we also added it to= >> those lists. > > It's an overwhelming doc string, but I think listing the action > functions is one of the best bits about it. :-) =2E.. here I'd just say what they can do - reuse the selected window, a window showing the buffer already, some other window, pop up a new window on this or another frame. > I've now shuffled it > to the front, and given a bit more introductory text to make it sound > less intimidating. > >> And while you're there you could try to make the Emacs >> manual entry more amenable for its audience. IIUC that's what the bl= og >> you mentioned criticized even more than the doc-string. > > Yeah, the manual is rather abrupt here, too, but the entire thing is > really complicated, and caters for many different use cases, so I don'= t > really even know where to begin. By dropping what you understand least. If this makes it an empty entrance, start from scratch with what you wanted to know first. If anything is incorrect, I'll fix it. But making this readable for a user is next to impossible, at least for me (I'm repeating myself whenever I talk about this subject). Have a look at the Elisp manual where I try, maybe it helps. martin