From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual Date: Thu, 27 Oct 2011 07:00:45 -0400 Message-ID: References: <4EA817C9.9030000@gmx.at> <83y5w7bn2r.fsf@gnu.org> <4EA929E6.9080001@gmx.at> Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: dough.gmane.org 1319713288 12681 80.91.229.12 (27 Oct 2011 11:01:28 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 27 Oct 2011 11:01:28 +0000 (UTC) Cc: 9875@debbugs.gnu.org To: martin rudalics Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Oct 27 13:01:24 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1RJNi6-0007kW-Bd for geb-bug-gnu-emacs@m.gmane.org; Thu, 27 Oct 2011 13:01:23 +0200 Original-Received: from localhost ([::1]:47577 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJNi5-0003Tk-PO for geb-bug-gnu-emacs@m.gmane.org; Thu, 27 Oct 2011 07:01:21 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:56049) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJNi1-0003TP-PA for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 07:01:19 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJNhz-0008PW-W8 for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 07:01:17 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:38152) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJNhz-0008PR-QG for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 07:01:15 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RJNji-0003t8-PY for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 07:03:03 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 27 Oct 2011 11:03:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 9875 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 9875-submit@debbugs.gnu.org id=B9875.131971336214899 (code B ref 9875); Thu, 27 Oct 2011 11:03:02 +0000 Original-Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 11:02:42 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RJNjN-0003sF-OO for submit@debbugs.gnu.org; Thu, 27 Oct 2011 07:02:42 -0400 Original-Received: from fencepost.gnu.org ([140.186.70.10] ident=Debian-exim) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RJNjG-0003s0-GM for 9875@debbugs.gnu.org; Thu, 27 Oct 2011 07:02:36 -0400 Original-Received: from eliz by fencepost.gnu.org with local (Exim 4.71) (envelope-from ) id 1RJNhV-0003id-S8; Thu, 27 Oct 2011 07:00:45 -0400 In-reply-to: <4EA929E6.9080001@gmx.at> (message from martin rudalics on Thu, 27 Oct 2011 11:52:38 +0200) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Thu, 27 Oct 2011 07:03:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:53200 Archived-At: > Date: Thu, 27 Oct 2011 11:52:38 +0200 > From: martin rudalics > CC: 9875@debbugs.gnu.org > > The term "window" stands for an "arbitrary window" that is either an > internal or a leaf window. I want to be able to write text like > > A window is considered a "subwindow" of another window if it occupies > a part of that other window's screen area. Why do you need to talk about subwindows at all? AFAICS, this is used (in about 5 more places, which is not a lot) in the context of explaining the behavior when two or more windows are sibling leafs in the tree. If so, then using "sibling leaf nodes in the tree" will explain it nicely. > >> Many important functions like `split-window', `delete-window', the > >> window resize functions, and obviously the new window tree functions > >> including `walk-window-tree' apply to both live and internal windows. > > > > That's true, but it only makes the whole issue more confusing. I can > > easily and intuitively understand the expected effect of splitting a > > live window. But what does it mean to "split" a window that is not > > displayed at all? I don't know, and the manual doesn't explain. > > The section on window splitting contains some five examples with > drawings that explain what happens in this case. What more can I do? I appreciate your efforts. But this bug is not about lack of effort. This bug report is about methodological shortcomings of the result. In a nutshell, by using terminology that is contrary to everyday language and semantics, the current text makes it hard to understand, because it goes against the intuitive meaning of "window" every reader has wired into her mind. No amount of explanations and examples will ever be able to fight the natural tendency of our brains to think of the white color when we read about "white", even if you define it as something else and give a lot of examples. > > It > > only has this rather cryptic blurb: > > > > If WINDOW is live, properties of the new window like margins and > > scroll bars are inherited from WINDOW. If WINDOW is an internal > > window, these properties, as well as the buffer shown in the new > > window, are inherited from the window selected on WINDOW's frame. > > What precisely is cryptic here? You need to read this in context. Here's the beginning of the description: -- Command: split-window &optional window size side This function creates a new window adjacent to WINDOW. It returns the new window which is always a live window. So now, when I read the above paragraph about live and internal windows, I'm left with the following unsolved mysteries: . what does it mean "adjacent to WINDOW" when WINDOW is an internal one? . what happens to original WINDOW, as result of the split, if it was an internal one? does it occlude the new window or doesn't it, for example? . what other properties, besides margins and scroll bars are inherited from the selected window? . what buffer will be shown in the new window when WINDOW is a live one? The text is cryptic because it leaves me with all those questions. Significantly, if WINDOW is a live window, none of these questions comes up, because it is clear what to expect. > > All the rest of the documentation of this function doesn't make any > > sense for an "internal window"; the description can only be understood > > in the context of a live window. Take this part, for example: > > > > If SIDE is `t' or `right' the new window will be positioned on the > > right side of WINDOW. The value `left' means the new window will > > be located on the left side of WINDOW. In both cases SIZE > > specifies the new number of columns for WINDOW (or the new window > > provided SIZE is negative) including space reserved for margins, > > fringes and the scroll bar or a divider column. > > > > I cannot interpret this for a non-live window. I could try _guessing_ > > what this means in that case, but why should I need to guess when I'm > > reading the manual? > > If you refer to this part "including space reserved for margins, fringes > and the scroll bar or a divider column" then it's explaind in the text > you considered cryptic above, namely that "these properties, as well as > the buffer shown in the new window, are inherited from the window > selected on WINDOW's frame". No, I mean all of it: right, left, size, space reserved for margins, fringes, scroll bars -- these attributes make no sense for a window that isn't displayed. They are just copies or sums of the attributes of _real_ live windows that are children of this internal window. It is unnatural to talk about "size" or "side" of a window that doesn't really exist on the screen! > > More importantly, does Joe R. Hacker, a casual Lisp programmer, really > > need to know what this does to an "internal" window? And if he > > doesn't, maybe we will be much better off not to include those > > "internal" windows in the domain of these functions, simply by not > > calling them "windows"? > > This means that Joe would not be able to split the root window of a > frame, a thing I do quite frequently to get a live window at a side of > the frame. Which probably means we should have a function for that kind of thing, so that J.R. Hacker could be oblivious to these intimate details. > > How can one _create_ a _new_ parent? A parent can only be a parent if > > it has children. You can create children of an existing parent, but > > you cannot create a _new_ parent for existing children. This is a > > single most confusing sentence in this section. It doesn't help that > > is also the most important sentence for understanding what window-nest > > does. > > Splitting a window creates a new parent window due to the fact that > splitting has to preserve the "identity" of the window that is split. > Hence, the new parent window is spliced into the window tree in a > single, atomic (on the Elisp level) action. This means that I indeed > "create a _new_ parent for" an already existing child or root window. My point was that it is much easier and much more clear to say that a new node is inserted into the window tree. _That_ is something no programmer needs explained. > >> Simply that functions accepting an internal window as argument would > >> have to say "the argument can be a window or a node" which doesn't > >> strike me as very constructive. In particular not so because I then > >> would have to explain in the doc-string what a "node" is. > > > > I don't see any issue here. Just say, somewhere close to the end of > > the doc string, something like "the argument WINDOW can also be a node > > of the frame's window tree". It's very easy to understand. > > I suppose you make the implicit assumption that the leaves of a tree are > not considered nodes of the tree. Okay, "the argument WINDOW can also be a non-leaf node of the frame's window tree", if you must. > > I didn't suggest removing the information from the docs. I only asked > > to (1) rename "internal windows" into "nodes of the window tree", > > which is what they are, > > This would be misleading. Live windows are also nodes of the window > tree. Our manuals are full of such "misleading" text. We don't need to be 100% accurate in the mathematical sense of the word, just accurate enough to get the idea across to the reader. > Internal windows are elementary for understanding _how_ `split-window', > `delete-window' and window resizing work. Well, feel free to close this bug report, then. This old fart now knows how to read these sections, although it will always cost me a non-trivial effort to mentally translate the text into what I consider the right representation of the ideas. I tried to explain why it could be an obstacle for others. I obviously fail to convince you. Maybe we should have a second opinion.