From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Documenting buffer display Date: Tue, 23 Oct 2018 15:52:31 +0000 Message-ID: <20181023155231.GB7594@ACM> 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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1540310487 25680 195.159.176.226 (23 Oct 2018 16:01:27 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 23 Oct 2018 16:01:27 +0000 (UTC) User-Agent: Mutt/1.10.1 (2018-07-13) Cc: Eli Zaretskii , emacs-devel@gnu.org To: martin rudalics Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Oct 23 18:01:23 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 1gEz7S-0006ac-Pv for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 18:01:22 +0200 Original-Received: from localhost ([::1]:42935 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEz9Z-0007tl-8O for ged-emacs-devel@m.gmane.org; Tue, 23 Oct 2018 12:03:33 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46717) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEz7x-0006hg-VG for emacs-devel@gnu.org; Tue, 23 Oct 2018 12:01:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gEz7q-0007Fe-Ta for emacs-devel@gnu.org; Tue, 23 Oct 2018 12:01:53 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:57237 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1gEz7q-0006xo-Ao for emacs-devel@gnu.org; Tue, 23 Oct 2018 12:01:46 -0400 Original-Received: (qmail 38644 invoked by uid 3782); 23 Oct 2018 16:01:18 -0000 Original-Received: from acm.muc.de (p5B14757B.dip0.t-ipconnect.de [91.20.117.123]) by colin.muc.de (tmda-ofmipd) with ESMTP; Tue, 23 Oct 2018 18:01:17 +0200 Original-Received: (qmail 13313 invoked by uid 1000); 23 Oct 2018 15:52:31 -0000 Content-Disposition: inline In-Reply-To: <5BCEE2B5.9090205@gmx.at> X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.1 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:230592 Archived-At: Hello, Martin. On Tue, Oct 23, 2018 at 10:58:29 +0200, martin rudalics wrote: [ .... ] > Then why do we have all this dispute about 'display-buffer'? > According to the majority of people because its documentation is > confusing, wrong, incomplete, implicit, arcane or just bad. I was one of the people recently criticising these things. I think I went over the top in what I said, so apologies for that. The documentation is difficult because the function does so much. Yet display-buffer is a coherent do-one-thing-and-do-it-well function, and I think any replacement for it would not be as good. All the same, there are some concrete things in display-buffer's doc string I would like to comment on. (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? (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)? (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. (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. > martin -- Alan Mackenzie (Nuremberg, Germany).