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: Tue, 23 Oct 2018 20:25:57 +0200 Message-ID: <5BCF67B5.3010602@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: quoted-printable X-Trace: blaine.gmane.org 1540319093 24079 195.159.176.226 (23 Oct 2018 18:24:53 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 23 Oct 2018 18: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 Tue Oct 23 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 1gF1MG-00069e-RZ for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 20:24:49 +0200 Original-Received: from localhost ([::1]:43735 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gF1OM-0001pe-Lu for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 14:26:58 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35458) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gF1Ng-0001QO-3Q for emacs-devel@gnu.org; Tue, 23 Oct 2018 14:26:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gF1NZ-0006hH-D8 for emacs-devel@gnu.org; Tue, 23 Oct 2018 14:26:13 -0400 Original-Received: from mout.gmx.net ([212.227.17.21]:60811) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gF1NW-0006eu-2n; Tue, 23 Oct 2018 14:26:07 -0400 Original-Received: from [192.168.1.101] ([213.162.73.191]) by mail.gmx.com (mrgmx102 [212.227.17.168]) with ESMTPSA (Nemesis) id 0MMYZG-1gFafV27ji-008I3B; Tue, 23 Oct 2018 20:26:03 +0200 Original-Received: from [192.168.1.101] ([213.162.73.191]) by mail.gmx.com (mrgmx102 [212.227.17.168]) with ESMTPSA (Nemesis) id 0MMYZG-1gFafV27ji-008I3B; Tue, 23 Oct 2018 20:26:03 +0200 In-Reply-To: <20181023155231.GB7594@ACM> X-Provags-ID: V03:K1:mTRULEosX+ogaBfdNJIHRjHctTaI/eFEJbohneeIGf5oFw7mjAx Ovvj55sC5xLM1Yx/2EFcvmD5rxZPUxAl2O1CikIn/1uqybqZoO9mQ7CSyfXYdvAd44BVd7c xCrAjyXquIvTUwUe5lxrqzfi0dWf3jDmW+zd66FkTRcuAHuhL25okz5lalenZ0BwiyrndrI m/OsiPVIyYPaHaqoEGR+A== X-UI-Out-Filterresults: notjunk:1;V01:K0:c47u9RHCx0Q=:uz2lJwrSTu1M6gKW2cz2is Dhz4cM2PDmUMhpp7w+BQSEL0rIk8bYsE/2ep00vn0M4R+GbJ0+4qAlB0QvN4c5WM5Li7rs+P9 phIOqZdCo87VWnZunqSEB/1RAz+KjQvXEvW17CntsoTcnzOuM+O+/zF6BwxI8YvO7yigPLOmn oRrW9Xn/ZitnKy/Nfc453P1grW0uQK97PfJlu0bV/7fR+wSnmvDNCPawmLPKllVLBbDvVLMvm I9Qe+LJYeqe4reGu213V5iEoGCAxrnbNKS07DHQFJQmbO1U/MrNvXglcarlyQIiY1YsNxJdbh zPWP43A2i9dCtVm2g/PEw1acyJPUfDhQONQ06wOJHE8BPIXI4PZKxmBSiTfcZLJw5KxyG6U/h DqPdW6kQHkkU10U7RnW3WgZyuw6z1CLw1IF35LwOFNQ5Gu1UPpw+yxdz06A5SBv/GTr6bKSev lWnTkf8/Agt3f/1ZZzrZUAHQsapxPa6q2vQOW7ENn7xq/SKUNEqFDHz5LuiIsN0smNgTWGDI3 MVS1LWd4WN+QyNypGGESRHKtRinJOkVh1+qsEM80I/edpGreK5EcR/S6n96edYCfdFI7sVjjP ceN3c4ZWDkaAW8NDyhsS2/GQkirKoyiJDAr694bt+V/9R7lWpVS02ZRG4LNLjfNKAIce4EqFZ z6lX8mndpnIekwJBwz5a1oepy2bCzfWpX5ABczIobusFQQXSHbjwRuNmNNXWl6zxj5Ov3miX4 wPCiU2WuIOjrTkUGg9r5CcfjaYLAoZ1mY1/BT4E+eJmt6jtjM/bVDEfwfIVXq5ercJ2AIphZ X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.17.21 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:230606 Archived-At: > All the same, there are some concrete things in display-buffer's doc > string I would like to comment on. Thanks for these comments. > (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. I would like to remove the description of the ALIST entries. At least these =E2=80=98window-height=E2=80=99 -- Value specifies either an integer (t= he number of lines of a new window), a floating point number (the fraction of a new window with respect to the height of the frame=E2=80=99s root window) or a function to be called with one argument - a new window. The function is supposed to adjust the height of the window; its return value is ignored. Suitable functions are =E2=80=98shrink-window-if-larger-than-buffer=E2= =80=99 and =E2=80=98fit-window-to-buffer=E2=80=99. =E2=80=98window-width=E2=80=99 -- Value specifies either an integer (th= e number of columns of a new window), a floating point number (the fraction of a new window with respect to the width of the frame=E2=80=99s root window) or a function to be called with one argument - a new window. The function is supposed to adjust the width of the window; its return value is ignored. occupy too much space and are hardly indispensable for understanding 'display-buffer'. WDYT? > (ii) The optional argument FRAME gets combined with other ALIST entrie= s. > But where? Is it considered before or after the other entries? It's inserted into the list of 'reusable-frames' after "most of" the other entries. So any separate specification of 'reusable-frames' will usually override it. Something similar holds for a non-nil non-list value of the ACTION argument. Search for 'extra-action' in the code. Applications should use neither the one nor the other. > (iii) "If ACTION is non-nil .... where FUNCTION is either a function o= r > a list of functions ....". Would it not be better to call this elemen= t > "FUNCTIONS" (plural)? I have no opinion in this regard. If you feel strongly about it, please change it. > (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)"? I now try to say in the manual in more detail where and how ALIST is constructed and used. Inherently, an eventually fully constructed ALIST is passed to all action functions 'display-buffer' eventually calls. But specifying how such an ALIST is constructed cannot be part of the doc-string. I now give one example of a fully constructed ALIST in the manual. And what an action function does with an entry is described individually for each action function. > (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. Maybe. There was a time when 'display-buffer' was considered to never fail. Even now it hardly ever fails to display a buffer. You need quite a couple of ropes to accomplish that. > (vi) (Same paragraph): isn't there a missing "...otherwise the functio= n > will throw an error" after the bit about (allow-no-window . t)? 'display-buffer' doesn't throw an error, hopefully. If it fails it returns nil. > (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. Please change this as you see fit. > (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. Yes. I'll try to fix this as soon as I understand the semantics. (And please try my patch, read the new sections and send fixes for the mo= re embarrassing errors.) Thanks, martin