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: Thu, 08 Nov 2018 20:25:20 +0100 Message-ID: <5BE48DA0.9070107@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> <5BCE21AC.6030904@gmx.at> <831s8hu6i8.fsf@gnu.org> <5BCEE2B5.9090205@gmx.at> <20181023155231.GB7594@ACM> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1541705093 23283 195.159.176.226 (8 Nov 2018 19:24:53 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 8 Nov 2018 19:24:53 +0000 (UTC) Cc: Eli Zaretskii , emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Nov 08 20:24:49 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 1gKpv7-0005ur-3h for ged-emacs-devel@m.gmane.org; Thu, 08 Nov 2018 20:24:49 +0100 Original-Received: from localhost ([::1]:58757 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gKpxD-0008KC-HJ for ged-emacs-devel@m.gmane.org; Thu, 08 Nov 2018 14:26:59 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46633) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gKpwZ-0008K1-Gk for emacs-devel@gnu.org; Thu, 08 Nov 2018 14:26:22 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gKpwM-0003dR-Fy for emacs-devel@gnu.org; Thu, 08 Nov 2018 14:26:10 -0500 Original-Received: from mout.gmx.net ([212.227.15.15]:32907) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gKpw5-0002kC-Gj; Thu, 08 Nov 2018 14:25:49 -0500 Original-Received: from [192.168.1.100] ([213.162.73.5]) by mail.gmx.com (mrgmx002 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MKIEQ-1gKHhL2l9i-001hqq; Thu, 08 Nov 2018 20:25:25 +0100 In-Reply-To: <20181023155231.GB7594@ACM> X-Provags-ID: V03:K1:YDW3kTO1GiT31WmLmSX5hI8ZRzoM8tQsE/Lt/xZY2l7WD+/3r/f K0rQ41PIr+tDpzCasBSmo9ClPpWFCEqQt7CZX9m7MfbLr7vqgoXtUF7oYMcBgwNYE89NzgR Whn8yTjpnT8Oa0YQ0NvIIvVQOmOJYem+u+qk9mHcfbtEy+lt0Gre+ZHkN2rJ4HPR137j+/Y LjLFzWC+PXfSmzNVq6+NQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:c0CnoBCxTeA=:cWxTlrEcCnKpBejkptwlgC FQAeQHaXFEsKbrM3YdfeSOVqdjyjaactZ7DjuSMowXclFlRYZBbqJktPI5CzrL4Y/YADCJq6f EwTex0JNCbwZj1yaLta58QKz40Av+ZfEoU2B4jmP/enDFpdug7QWBPUfcfo8uCvjZNn1G2Zdl WF9XUXMtZHgpOcv8v/FwwNzR9OVL53qA7dhsfisOYHr+OkU0uVcEgZxTaxVhF6BqrlxoJz+vS Yg2X/oKLAqLoo/LG+HbQaJj0ie0HKArhOgNbhmPWji7GCyAtLzg1h7p7TMIRP9Zy3eJ6Hq9YJ Wkvx9dzXlSx5wuT3rhZswCw8TnEyq1n0eyLYSOTHl804CMoTQN/lGwYrVZNnXrsugOuXl5f0d j1IOIQX/VI2sR1mwDb0BmfZa7FLOJSXYzPpVkXj3dK3NuDORiVlQaEApshnks11C/oty4eIA7 tdLhXrRAO4Si07191oCF0yzOT/hRPxq8x5IpZC4HJjYyvwIq/VGlcUUQ2Jsjl0zdiDm9X3p5M wViHI64bt6cd3wb85ohLIhLltvN+IGZT4X6Gw2HtUTz9OtXz63JlE5cF2fH65lCXVfJZiWl+4 zJ+/x+ijD2kvK0Cy6d/eDK392gabVo/AoCnSb+2lA3vCAyegV80t2hXfqClxs63BNNPHtyje/ g5YqQy/mcEtklr4UnEqfzYjWv0w40gA4RZ2QUrmwauW1BoSX94qx8YIkbkFJF0zRbB7/GzBRL gK5WYz65Bk4aq6lj5nzpcNeaD95AVsWqJEOwzoLgzoMgcADy2Urqo2kofGDfRFmJARu4jt6W 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:231059 Archived-At: > All the same, there are some concrete things in display-buffer's doc > string I would like to comment on. I hope I addressed all issues. Please have a look. > (i) PLEASE do not delete the extensive description of the ACTION > argument. Without it, the function would be more difficult to > understand, even if the doc string were shorter. > > (ii) The optional argument FRAME gets combined with other ALIST entries. > But where? Is it considered before or after the other entries? I think it says that now. > (iii) "If ACTION is non-nil .... where FUNCTION is either a function or > a list of functions ....". Would it not be better to call this element > "FUNCTIONS" (plural)? > > (iv) "If ACTION is non-nil .... ALIST is an arbitrary association > list...". This is unfinished. Could it not say, for example, "... an > arbitrary association list which FOO uses to BAR BAZ (see below)"? > > (v) "Based on those arguments, it should display the buffer and return > the window.". Possibly better would be "it should TRY TO display the > buffer and return the window.". Maybe. > > (vi) (Same paragraph): isn't there a missing "...otherwise the function > will throw an error" after the bit about (allow-no-window . t)? I'm not quite sure what you meant here. 'display-buffer' will return nil after one of its action functions "successfully" processed the 'allow-no-window' entry and will also return nil if it didn't find a window (which is quite difficult to achieve). But by design it never throws an error. > (vii) `reusable frames': it sort of seems that a list of frames could be > given as the cdr of this entry. That is not the case. Maybe the text > could become: "value, AN ATOM, specifies frame(s) to search...". This > will remove that uncertainty over the possibility of a list of frames, > forcing the reader to follow the hyperlink to get details. I use the tem "set" now. > (viii) `allow-no-window' is a little unclear on what happens when a > function fails to display and return a window. The text implies that > the window remains undisplayed, whereas I think that instead the next > function is tried, and so on, until one returns a window. The window remains undisplayed if this entry is actually processed by an action function and 'display-buffer' returns immediately thereafter. No further action functions are tried in that case. martin