From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.bugs Subject: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual Date: Thu, 27 Oct 2011 11:52:38 +0200 Message-ID: <4EA929E6.9080001@gmx.at> References: <4EA817C9.9030000@gmx.at> <83y5w7bn2r.fsf@gnu.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-15; format=flowed Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1319709208 16124 80.91.229.12 (27 Oct 2011 09:53:28 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 27 Oct 2011 09:53:28 +0000 (UTC) Cc: 9875@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Oct 27 11:53:21 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 1RJMeH-00084c-00 for geb-bug-gnu-emacs@m.gmane.org; Thu, 27 Oct 2011 11:53:21 +0200 Original-Received: from localhost ([::1]:59384 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJMeG-00045K-KX for geb-bug-gnu-emacs@m.gmane.org; Thu, 27 Oct 2011 05:53:20 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:53533) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJMeD-000413-0b for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 05:53:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJMeA-0002RO-Py for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 05:53:16 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:52892) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJMeA-0002RK-OF for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 05:53:14 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RJMfu-0002Ff-2b for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 05:55:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: martin rudalics Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 27 Oct 2011 09:55: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.13197092768597 (code B ref 9875); Thu, 27 Oct 2011 09:55:02 +0000 Original-Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 09:54:36 +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 1RJMfT-0002Eb-Sm for submit@debbugs.gnu.org; Thu, 27 Oct 2011 05:54:36 -0400 Original-Received: from mailout-de.gmx.net ([213.165.64.23]) by debbugs.gnu.org with smtp (Exim 4.69) (envelope-from ) id 1RJMfS-0002EP-7N for 9875@debbugs.gnu.org; Thu, 27 Oct 2011 05:54:35 -0400 Original-Received: (qmail invoked by alias); 27 Oct 2011 09:52:40 -0000 Original-Received: from 62-47-54-146.adsl.highway.telekom.at (EHLO [62.47.54.146]) [62.47.54.146] by mail.gmx.net (mp025) with SMTP; 27 Oct 2011 11:52:40 +0200 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX1+tDb0j5yit9Wv/1JeBDbpIyB+JMre1wC1FIu5+jR PHfk1+vKZz7t/d User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) In-Reply-To: <83y5w7bn2r.fsf@gnu.org> X-Y-GMX-Trusted: 0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Thu, 27 Oct 2011 05:55: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:53196 Archived-At: >> > go wrong. The main problem is that the non-leaf nodes of the window >> > tree are referred to as "windows", >> >> ... as "internal windows" more precisely ... > > No, as _windows_. Here's a typical example: > > All other windows of a frame with the exception of the minibuffer > window are subwindows of the frame's root window. A window is > considered a "subwindow" of another window if it occupies a part of > that other window's screen area. > > The functions described next allow to access the members of a window > tree and take an arbitrary window as argument. > > -- Function: window-parent &optional window > Return WINDOW's parent in the window tree. The optional argument > WINDOW can denote an arbitrary window and defaults to the selected > one. The return value is `nil' if WINDOW is a minibuffer window > or the root window of its frame and an internal window otherwise. > > Parent windows do not appear on the screen. The screen area of a > parent window is the rectangular part of the window's frame occupied by > the window's "child windows", that is, the set of windows having that > window as their parent. Each parent window has at least two child > windows, so there are no "Matryoshka" windows. Minibuffer windows do > not have child windows. > > All this text freely talks about "windows" when it really means the > nodes of the window tree. 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. instead of A node of the window tree or a live window are considered a "subwindow" or "a subnode of the window tree" of a node of the window tree if they occupy a part of that node's screen area. >> 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? > 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? > 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". Note that the present inheritance mechanism is annoying in the first place because it makes us calculate the size of the new window based on properties of the window to split. In at least one case this has made me rewrite these calculations when a user wanted to split off a two lines high window from a window with a headerline. > 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. > 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. >> 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. I do not understand that assumption. Where did you get it from? > 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. > and (2) have a single section in the manual > that describes the window tree and the functions that operate on it, > instead of spreading that over several sections. The information you > want that person to have will still be available. But it will be out > of the way of all the other 99% of Lisp programmers who have no need > to know all that, and don't need to be confused by these "internal" > windows. Internal windows are elementary for understanding _how_ `split-window', `delete-window' and window resizing work. martin