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: Sat, 20 Oct 2018 20:02:22 +0200 Message-ID: <5BCB6DAE.30209@gmx.at> References: <5BCB1D82.3020108@gmx.at> <834ldgvjmj.fsf@gnu.org> 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 1540058528 3117 195.159.176.226 (20 Oct 2018 18:02:08 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 20 Oct 2018 18:02:08 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Oct 20 20:02:04 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 1gDvZc-0000hK-7m for ged-emacs-devel@m.gmane.org; Sat, 20 Oct 2018 20:02:04 +0200 Original-Received: from localhost ([::1]:56142 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gDvbi-00035l-Kn for ged-emacs-devel@m.gmane.org; Sat, 20 Oct 2018 14:04:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58896) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gDvbN-0002mb-7K for emacs-devel@gnu.org; Sat, 20 Oct 2018 14:03:58 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gDvaB-0003Wl-Ja for emacs-devel@gnu.org; Sat, 20 Oct 2018 14:02:44 -0400 Original-Received: from mout.gmx.net ([212.227.15.19]:42499) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gDva7-0003Ni-FA; Sat, 20 Oct 2018 14:02:36 -0400 Original-Received: from [192.168.1.100] ([213.162.73.147]) by mail.gmx.com (mrgmx002 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MHX4u-1gCoaS2lI4-003OWm; Sat, 20 Oct 2018 20:02:24 +0200 Original-Received: from [192.168.1.100] ([213.162.73.147]) by mail.gmx.com (mrgmx002 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MHX4u-1gCoaS2lI4-003OWm; Sat, 20 Oct 2018 20:02:24 +0200 In-Reply-To: <834ldgvjmj.fsf@gnu.org> X-Provags-ID: V03:K1:KAEs/sVIEDlgWP/UhM3xYO+90UnIf1HZbNgPVJUYlWZfnPUwlqB q9pcfuYJxuObsAbhJMDDZimoXD4cZkjZtCR4+8NWMG9xXHZWMM6/RdGv5EpyiXiEEXd9E0a 30oI2ZgYP0iILf3ZKiEMMfevmcHdhvYXc+iQfCkgPYyzmYThj9KLztHbo/UDZYweWe2+rCk reqqWSFxUeVfQsPblwxzQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:RHn1ToqJ6e8=:IPhZLIyYut+YZCMfQdAY+b MtC4s9j42Llz0vuzjcEwY/W9LEVYQAPm+w2zPBPog5PasnMgVyxhq7kQP++6q6LQq0Yc2hQ9E fdO2pgoEEqzNF8erVJenzhrD+rvAZdqkaIBi2PLNcCAIcWao0eEnCLmwSPUDQof11TXm2BTP8 iLKae5GISQma6NQWwUmL2if9y+VAd6KBN7wAkIUKi+KAGP4E7YHErLg2yjE38T1qJNwC+9UdE YNN9R08hY9GuJ5AHy37bJu2L8fXcHVmiJe0D2ep16R14sLGSLN6O7GtIZbW4nCCFCdzUKG1uy xdGfRg95nd76MyQQjOZ6+l7UP33rQ1TK6qUVjB22xBmQuZjjxWZ67OVP39pAe2VagD6q69oqS VdoGdJ7thfL54xCowL42jpf8+PIV1jE8XpxY42LkeYjlOenL6tqojQWR6lrlI3k4AkdMZB94u QR5eJSpRZKETl9gXiTI5tpjygg/Q2hgxTx8oBnlf1lhOTRYwV6mzu8/SY2U6r93aezwz6jPBy xJUjb+XI9Dijjn4r6ZhlXxA/B57L6sDiRN2XzPWS7wtBfEO1ZiP49n/UtOF1iLpaaAnh8LU22 KWIWi0hJe/gdvYhvgkuDLJvZ6TY8ajU3+ap8h9u2LVR8cNrysQDePbIxi9kFoVhcGr6CW3QMp HF4UEiIiCG+Fi51RS9YWgwk6s78qxyBKtIH4SJdOJeY9ED1c2evVfxuIM+rue0olWad72iN6D ZRR3Q8wFOJNO8Qa2j2yDkMyIDOZTGv4ZXp/5QiE2JTiAeePJHkqV4wrjQ9oY/Me11u+hd2hU X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.15.19 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:230527 Archived-At: > Thanks, please find a few comments below. Thanks for the comments. Everything not cited below will be corrected in your sense. > Please consider adding one or more @cindex entries here, so that > readers could get here when they look for topics described in this > section. Similarly for each of the new subsections. I haven't done any indexing yet. Suggestions, like the ones you provide below, are highly welcome. >> +In this section we describe how Emacs finds or creates a window >> +suitable for displaying a buffer. We first introduce the function >> +@code{display-buffer}---the workhorse for choosing such a window. >> +Next, action functions---auxiliary functions called by >> +@code{display-buffer} to find or create a suitable window---are >> +presented. Then we describe action alists---special association lists >> +used to fine-tune the behavior of action functions. >> + >> + We continue with the description of additional options to customize >> +the behavior of @code{display-buffer}. Then a series of examples will >> +try to explain the precedence among action functions in a single call >> +of @code{display-buffer}. We conclude this section with some >> +guidelines for managing the complexity of buffer display. > > I suggest to rewrite this text in terms of what the reader might be > looking for, or as a list of tasks related to the material in the > section. The way the text is written now, it is an overview of the > topics covered by the section, without any explicit relation to what > the reader may want to do or learn about. Such "abstract" overviews > are IME much less useful. Fully agreed but I ran out of ideas here. It would be a great help if you or anyone else came up with a rough sketch of what to do instead. >> +* Action Functions:: Support functions for buffer display. >> +* Action Alists:: Alists for fine-tuning buffer display. > > I question the wisdom of removing "Display" from the names of these > nodes. "Action Functions" and "Action Alists" are IMO too general, > and might clash with some other kind of "actions". Agreed. But IMO "display action function" is even worse because "display" has a very different connotation in Emacs. So I can only propose "buffer display action function" or "display buffer action function" instead. WDYT? >> +@node Action Functions >> +@subsection Action Functions for Buffer Display > > I think @cindex entries here about "action functions" and "display > action functions" are in order. They are already indexed in Choosing Window thusly @cindex display action @cindex action function, for @code{display-buffer} @cindex action alist, for @code{display-buffer} so you suggest to move the indices to the corresponding sections? >> The following basic action functions are defined in Emacs. Each of > > "Action function" is a term introduced in this section, right? If so, > its first instance should be in @dfn, and this section should define > the term. They are defined in Choosing Window thusly Here, @var{function} is either a function or a list of functions, which we refer to as @dfn{action functions}; @var{alist} is an association list, which we refer to as an @dfn{action alist}. so you suggest to move the @dfns to the corresponding sections as well and leave only the cross references in Choosing Window? >> +@node Action Alists >> +@subsection Action Alists for Buffer Display >> + >> +An action alist (@pxref{Choosing Window}) is an association list >> +mapping predefined symbols recognized by action functions to values > > Here you provide the definition of "action alist", so its first > instance should be in @dfn, and there should be a @cindex entry here. Same as for "Action Functions" above. >> + Many efforts in the design of @code{display-buffer} have been given >> +to maintain compatibility with code that uses older options like >> +@code{pop-up-windows}, @code{pop-up-frames}, >> +@code{pop-up-frame-alist}, @code{same-window-buffer-names} and >> +@code{same-window-regexps}. Applications and users should refrain > > The text below this should have index entries for the obsolete > variables you describe. OK (they are not obsolete yet, BTW). > FWIW, I find such tutorial-like style I initially wanted to call this section "A Tutorial for ...". > not really appropriate for a > reference manual. For starters, it takes more space; more > importantly, it gets to the point only implicitly and requires the > reader to participate in the discovery. Yes to all. And I expect everyone who complained in the past about how difficult it is to work with 'display-buffer' to do exactly that - participate in the discovery (just as I did when I wrote those examples). Please keep in mind: I didn't invent the action functions, frequently argued that people won't like them and that it will be hard to document them. In fact, writing action functions can be a pain and examples are one way to relieve that pain. Even if it takes space to write the examples and time to read them. > It could even annoy, if the > reader is in a hurry. Readers in a hurry are not supposed to read that section. If necessary, I can put an according warning at its start. > Suggest to rewrite as reference text instead. > I'm sure this stuff can be described other than by example. On this list people have asked for examples quite often. Roland Winkler: The current discussion of 'display-buffer-alist' in the elisp manual appears rather technical, suited only for expert users. On the other hand, the variable is declared with defcustom, as if individual users should customize it to their personal liking. N. Jackson in the same thread: Perhaps `display-buffer-alist' is sufficient for the BBDB case. As its documentation is a little unclear (while recursive code is okay, recursive documentation is a little bit trying), it would be nice to see an example of how this might be done. Honestly, I have no idea how to do if not with the help of a detailed sequence of examples. The "Precedence ..." section is IMO one way to discover how 'display-buffer' works and why it works the way it does. If anyone comes up with a better idea I'll be all ears. > And a final remark: the last two subsections you added read like more > or less arbitrary collection of tips and tricks. While it's okay to > do that, I wonder whether such a long list of tricks means there might > be some more meaningful organization of most of this material. Just a > thought. Have a look at two recent threads. This one is by Florian Weimer on help-gnu-emacs: I see. Further questions: How can I restore the window configuration after the process terminates? Is there something similar to save-excursion? To which Stefan Monnier answers: If you don't care about other people's configs and you only use a single frame, there's save-window-excursion (but for configs like mine, every use of save-window-excursion is generally a source of problems). A simpler solution to "undo" a pop-to-buffer is to (bury-buffer). Now the canonical mechanism provided by 'pop-to-buffer' is to use 'quit-window' but how do I tell that to our former maintainer and how do I put that in the manual? So I mention it in the Zen section. Or take this one by Alan: I've thought about this overnight. And I think the answer is no, it would not be better to use pop-to-buffer. At least, not if an ACTION argument needs to be constructed. The specification of the ACTION argument seems so arcane, so implicit, so difficult to use, that it will be simpler just to write a function such as edebug-pop-to-buffer. edebug-pop-to-buffer will also be much easier to understand and maintain than an equivalent using pop-to-buffer with an ACTION. In short, pop-to-buffer and display-buffer with ACTION seem to be "pyrrhic functions". At least, that's how I see it from reading the doc, not having yet tried to use them. Also, edebug-pop-to-buffer already exists and works. There are around 479 calls to these two functions in the Emacs source. A quick eyeballing of the grep results found just one single use of ACTION, in replace.el. I dare say there are more, but very few altogether. Maybe some of the tips and tricks I propose here will help Alan to avoid sleepless nights (and Stefan when quitting an edebug session will yet another time try to restore his window configuration on the wrong frame). martin