From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Documenting buffer display Date: Sat, 20 Oct 2018 16:21:40 +0300 Message-ID: <834ldgvjmj.fsf@gnu.org> References: <5BCB1D82.3020108@gmx.at> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1540041640 7501 195.159.176.226 (20 Oct 2018 13:20:40 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 20 Oct 2018 13:20:40 +0000 (UTC) Cc: emacs-devel@gnu.org To: martin rudalics Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Oct 20 15:20:35 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 1gDrBD-0001s9-GX for ged-emacs-devel@m.gmane.org; Sat, 20 Oct 2018 15:20:35 +0200 Original-Received: from localhost ([::1]:55220 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gDrDJ-00061Z-Pm for ged-emacs-devel@m.gmane.org; Sat, 20 Oct 2018 09:22:45 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:60310) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gDrCc-00061T-KT for emacs-devel@gnu.org; Sat, 20 Oct 2018 09:22:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gDrCY-0001rR-S2 for emacs-devel@gnu.org; Sat, 20 Oct 2018 09:22:02 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:39870) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gDrCY-0001qn-NO; Sat, 20 Oct 2018 09:21:58 -0400 Original-Received: from [176.228.60.248] (port=4618 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gDrCY-0005I9-AC; Sat, 20 Oct 2018 09:21:58 -0400 In-reply-to: <5BCB1D82.3020108@gmx.at> (message from martin rudalics on Sat, 20 Oct 2018 14:20:18 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:230523 Archived-At: > Date: Sat, 20 Oct 2018 14:20:18 +0200 > From: martin rudalics > > Attached find a rewrite of the documentation of buffer display > functions to be applied against the release branch. > > Work in progress. Proofreading and suggestions welcome. Thanks, please find a few comments below. > +@node Displaying Buffers > +@section Displaying a Buffer in a Suitable Window 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. > +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. > + > +@menu > +* Choosing Window:: How to choose a window for displaying a buffer. > +* 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". > +see @ref{Precedence of Action Functions} for an example. Please put a comma after the right brace here. > +@node Action Functions > +@subsection Action Functions for Buffer Display I think @cindex entries here about "action functions" and "display action functions" are in order. > 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. > +display, and @var{alist}, an action alist. As a rule, each action > +function is supposed to return a window displaying @var{buffer} if it > +succeeds and @code{nil} if it fails (for the sole exception to this > +rule see the last function listed > +below---@code{display-buffer-no-window}). I think this exception is better described with the function; here it is just a distraction. The general rule should be: describe the normal case in detail, and leave the exceptional cases for note-like text near the end. > +If there is no such window, this function tries to create a new window > +by splitting the selected one and display @var{buffer} there. It will > +also adjust that window's size provided @var{alist} contains a suitable > +@code{window-height} or @code{window-width} entry, see above. Here and elsewhere, you mix 2 different styles: one using present tense ("tries", "fails"), the other using future tense ("will adjust"). I think we prefer to use the former consistently. > +@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. > + 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. > +Let's now consider the following form: > + > +@example > +(display-buffer (get-buffer-create "*foo*")) > +@end example > + > +@noindent > +Put this form into the buffer @file{*scratch*} of an uncustomized > +Emacs session you just started and evaluate it: @code{display-buffer} > +will fail to reuse a window showing @file{*foo*} but succeed in > +popping up a new window. If you evaluate the form again, nothing will > +change---@code{display-buffer} reused the window already showing > +@file{*foo*} because that action was applicable and had the highest > +precedence among all applicable actions. FWIW, I find such tutorial-like style 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. It could even annoy, if the reader is in a hurry. Suggest to rewrite as reference text instead. I'm sure this stuff can be described other than by example. > +@node The Zen of Buffer Display > +@subsection The Zen of Buffer Display This section is also in dire need of useful index entries. > +@example > +'(display-buffer-below-selected) > +@end example > + > +on the other hand specifies one action function and an empty action @noindent is missing here. > +alist. To combine the effects of the above two specifications one > +would write the form > + > +@example > +'(display-buffer-below-selected (inhibit-same-window . t)) > +@end example > + > +to add another action function one would write And here. > +@example > +@group > +'((display-buffer-below-selected display-buffer-at-bottom) > + (inhibit-same-window . t)) > +@end group > +@end example > + > +and to add another alist entry one would write And here. 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. Thanks again for working on this.