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 14:18:04 +0100 Message-ID: <616655cc-9b87-cb93-6787-11e7037e8cbc@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> 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="3647"; 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 14:19:39 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 1kxVCS-0000oK-ES for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 07 Jan 2021 14:19:36 +0100 Original-Received: from localhost ([::1]:58674 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kxVCR-0006BG-GZ for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 07 Jan 2021 08:19:35 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58310) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kxVBu-00069v-4K for bug-gnu-emacs@gnu.org; Thu, 07 Jan 2021 08:19:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:35254) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kxVBt-0004wL-Ta for bug-gnu-emacs@gnu.org; Thu, 07 Jan 2021 08:19:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kxVBt-0004NA-Pl for bug-gnu-emacs@gnu.org; Thu, 07 Jan 2021 08:19:01 -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 13:19:01 +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.161002549616750 (code B ref 45688); Thu, 07 Jan 2021 13:19:01 +0000 Original-Received: (at 45688) by debbugs.gnu.org; 7 Jan 2021 13:18:16 +0000 Original-Received: from localhost ([127.0.0.1]:46800 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kxVB9-0004M6-LW for submit@debbugs.gnu.org; Thu, 07 Jan 2021 08:18:15 -0500 Original-Received: from mout.gmx.net ([212.227.17.20]:34427) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kxVB4-0004Ln-V0 for 45688@debbugs.gnu.org; Thu, 07 Jan 2021 08:18:15 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1610025485; bh=m/7NWDTb8w+63sQpPIRMqXAB/TGRrwHk7YaK6+y8vaY=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=JIYNoGk/FmCbgbLU52slgBnNUDxABcJeJOywrSZ9Os9NemBEUN5Ok1vQG0huH5mwR I6koTaczP+eHfA1Dx2Gr/bOMTLsoz5SoTyqelG2NMa4Z6Bjm8ZGW+m+2E29Y+uv//r e+d3vOY2gLdnhcFR2t9PnLGYB3cQnc8ZWEw0oD3g= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from [192.168.1.100] ([212.95.5.167]) by mail.gmx.com (mrgmx104 [212.227.17.168]) with ESMTPSA (Nemesis) id 1MmULx-1kFP493Skb-00iVgP; Thu, 07 Jan 2021 14:18:04 +0100 In-Reply-To: <87h7ntynpx.fsf@gnus.org> Content-Language: en-US X-Provags-ID: V03:K1:eka98lVsaL6myujdPbAgoYoWdVvxCPrgsa7Z2+epPDj2Y/I1APQ j+LtXGgvSbfjNhacvSW4CIrevn/ALu0+oo3KOMYhZ2nYypAugpwli7yzcnK/TEo33yrqe23 PnszKRJ+FF0XA7Rh629++gL7bYC+XkTR7OHUqTKvUPRkApHMgvhbd5LzOE08Kk5HW22CGs2 R3bbWoehzRofNwctpR8tw== X-UI-Out-Filterresults: notjunk:1;V03:K0:+HnhxqdOKG8=:WDEGfOdUKAvBlJYiyIiyqb S0mnOUgGlxy+hsai1P6ZsanRzA88FFNeVljEfovQVxN7RAFTgy4G121E+3FUwtYqNsnu2AwG2 BoktGFEacXNkU+jqnbSZeW5568jzNucNrrMGreI4X5x+SnhaYpHXC7UMIpeYilWsNbzCy8QnC 2PUqhorPYM+Xn0zPAe1LIaI1IwW0CUX6AAiqEhdilI4SXPkyHpvrGgptmxOYSlsvMwtsYRjOR u6ASOV4BRosJJJJPBTu5aKFbt8BCZOaNuHantEUAI4oZgnMeoDsL+h5ASEOONFXWLLk1mkH6o mrkfBeZIflD4wV/qjsg6FzR8RVLdJHww5/Fa37PhE6eCvchKO/yUUcVMZRlBldBYa68qaXIic +O6JtpdrQtIzQV08piMCPOhv3vX+/+IdO+lhNGg5rSQP9a+YmIdSxAUaQ23V55nkjwBqDEB9x wrhKqcWCBoU9dDVAmP7NtB6akY+CISEBEY3uWmjTTW/jWGGbYywhS1dW8tm0dBl8youCFOO34 Lqk0Rvt3GEWswb1DVpaFgFmo31AoQSOU7LOqH7QQEQVV/IDhvZZuP12nnysWTz90iZHz0vft0 QioG5ZzM6J/UQzqjgnfI2uegawHhiHlJArDoDtRKRzm02ArjvM2eAp6irRBOrn4JNx2k/uYbj TiyP/klRV79eCALQb3gzQ4Cp3Ww3XSVDiXqk9EmRjyHutoDVAJ9SF0fAPCW0LDWjEcg4/G6UU RNzZMBGL09/BSZ7HA4RMkwlBdmPtyiQjgwmE7g9sdp509exzSD8Jo9pVkSt2qeP1TSLTbaD6 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:197477 Archived-At: > I think the doc string for `display-buffer' is pretty intimidating now= , > and seems more geared towards programmers than usage now. Would it ma= ke > sense to rearrange it a bit? That is, start off with something like: > > ----- > > Display BUFFER-OR-NAME in some window, without selecting it. To chang= e > what window is used, set `display-buffer-overriding-action' to a list > containing one or more of the following functions: > > Action functions and the action they try to perform are: > =E2=80=98display-buffer-same-window=E2=80=99 -- Use the selected win= dow. > =E2=80=98display-buffer-reuse-window=E2=80=99 -- Use a window alread= y showing > the buffer. > =E2=80=98display-buffer-in-previous-window=E2=80=99 -- Use a window = that did > show the buffer before. > > etc etc, and then give the details about ACTION and the rest? By no means. `display-buffer-overriding-action' is _not_ intended for the user. It's an emergency exit for applications. Better not even mention it in the user manual and the doc-string. In every other regard, feel free to change it in a way that sounds less imitating. For example, listing the action functions and alist entries in the doc-string is merely distracting. We started out with small sets and every time a new function or entry was added, we also added it to those lists. And while you're there you could try to make the Emacs manual entry more amenable for its audience. IIUC that's what the blog you mentioned criticized even more than the doc-string. martin