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: Sun, 21 Oct 2018 15:56:32 +0300 Message-ID: <83mur7tq4f.fsf@gnu.org> References: <5BCB1D82.3020108@gmx.at> <834ldgvjmj.fsf@gnu.org> <5BCB6DAE.30209@gmx.at> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1540127475 8416 195.159.176.226 (21 Oct 2018 13:11:15 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 21 Oct 2018 13:11:15 +0000 (UTC) Cc: emacs-devel@gnu.org To: martin rudalics Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Oct 21 15:11:10 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 1gEDVe-00026O-4M for ged-emacs-devel@m.gmane.org; Sun, 21 Oct 2018 15:11:10 +0200 Original-Received: from localhost ([::1]:58808 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEDXk-0003kc-DI for ged-emacs-devel@m.gmane.org; Sun, 21 Oct 2018 09:13:20 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39637) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEDQf-0004yl-Da for emacs-devel@gnu.org; Sun, 21 Oct 2018 09:06:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gEDHk-00037J-TR for emacs-devel@gnu.org; Sun, 21 Oct 2018 08:56:52 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:57447) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEDHk-00037F-Pb; Sun, 21 Oct 2018 08:56:48 -0400 Original-Received: from [176.228.60.248] (port=4184 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gEDHk-0004vx-Bf; Sun, 21 Oct 2018 08:56:48 -0400 In-reply-to: <5BCB6DAE.30209@gmx.at> (message from martin rudalics on Sat, 20 Oct 2018 20:02:22 +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:230540 Archived-At: > Date: Sat, 20 Oct 2018 20:02:22 +0200 > From: martin rudalics > CC: emacs-devel@gnu.org > > > 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. Will do as the time passes ;-) > > 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. For that, I'd need to have a good understanding of the overall structure of the material. I don't have that now; I thought you, as the author, did. Failing that, we could postpone this issue to later, it's relatively minor one. > >> +* 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? I'd go with "Buffer Display Actions" and "Buffer Display Functions". > >> +@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? Yes. Index entries should be where the feature is described in the most detailed way. The other places should have cross-references to that main description. > >> 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? Yes. > >> +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). I know. I meant something like @vindex pop-up-windows@r{, replacement for} > > FWIW, I find such tutorial-like style > > I initially wanted to call this section "A Tutorial for ...". I'm not against tutorials; far from that. I just think they should be separate from Reference manuals. Reference manuals can then point to tutorials for examples. But that doesn't mean a Reference manual can consider itself done by providing a "lip service" in the form of such a tutorial reference. A good Reference manual should still describe the feature in a clear and useful way. Reference manual's main audience are people who already have some, perhaps even good, idea about the feature, and need help in finding exactly the right tools, out of those available, to do the jop at hand. Tutorials, by contrast, target newbies who have no clue: walking those through a large enough set of well-explained examples will bring them up to speed, so they could proceed to the Reference manual. > Readers in a hurry are not supposed to read that section. I think it's a mistake to take that stand when writing a Reference manual. > 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. It's not easy, I will give you that. But that doesn't mean we should give up. One thing to remember is that the manual is not the only place where the documentation could live: there are doc strings as well. Some of the details might be better suited to doc strings. > 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). I didn't say those tips are useless, far from it. I just ended up having an impression that I've read a list of tips that I will have to re-read again when I need to find something in it. So I suggested to think about some way of organizing them, so that similar and related stuff is closer to one another. Anyway, I don't want to discourage you by being my usual perfectionist self. I think it's great you are working on improving these docs, and I think we are lucky to have you and your expertise on these matters. So if you can take anything at all from my comments, I'm happy; the rest can be improved later, if we find a how. Thanks.