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: Wed, 26 Oct 2011 20:54:36 +0200 Message-ID: <83y5w7bn2r.fsf@gnu.org> References: <4EA817C9.9030000@gmx.at> Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: dough.gmane.org 1319655333 15074 80.91.229.12 (26 Oct 2011 18:55:33 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 26 Oct 2011 18:55:33 +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 Wed Oct 26 20:55:28 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 1RJ8dI-0003Oz-Mz for geb-bug-gnu-emacs@m.gmane.org; Wed, 26 Oct 2011 20:55:24 +0200 Original-Received: from localhost ([::1]:36013 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ8dI-0002nG-3Y for geb-bug-gnu-emacs@m.gmane.org; Wed, 26 Oct 2011 14:55:24 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:57947) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ8dE-0002n0-Bu for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 14:55:21 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJ8dC-0004zo-Jj for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 14:55:20 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:55433) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ8dC-0004zj-Aw for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 14:55:18 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RJ8er-0002yO-T8 for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 14:57:01 -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: Wed, 26 Oct 2011 18:57:01 +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.131965541211413 (code B ref 9875); Wed, 26 Oct 2011 18:57:01 +0000 Original-Received: (at 9875) by debbugs.gnu.org; 26 Oct 2011 18:56:52 +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 1RJ8ei-0002y2-Ko for submit@debbugs.gnu.org; Wed, 26 Oct 2011 14:56:52 -0400 Original-Received: from mtaout20.012.net.il ([80.179.55.166]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RJ8ef-0002xo-ME for 9875@debbugs.gnu.org; Wed, 26 Oct 2011 14:56:51 -0400 Original-Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0LTO00N00SGB4V00@a-mtaout20.012.net.il> for 9875@debbugs.gnu.org; Wed, 26 Oct 2011 20:54:29 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([77.124.212.197]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0LTO00MXGSISSF50@a-mtaout20.012.net.il>; Wed, 26 Oct 2011 20:54:29 +0200 (IST) In-reply-to: <4EA817C9.9030000@gmx.at> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Wed, 26 Oct 2011 14:57:01 -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:53169 Archived-At: > Date: Wed, 26 Oct 2011 16:23:05 +0200 > From: martin rudalics > CC: 9875@debbugs.gnu.org > > > This node starts fine, by describing window-frame and window-list. > > Then it begins to describe the "window tree", and that's where things > > 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. > 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. 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. 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? 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"? > > The confusion > > culminates in "Splitting Windows", where many issues are described via > > window-parent and what is called "creating a new parent". > > Yes. And I probably gave too many examples for this in the expectation > that readers would study them and get a feeling for what internal > windows are needed for. But what is the culminating confusion here? > Could you provide at least one example? 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. > > I submit these confusing references to the nodes of the window tree as > > "windows" should be removed. If we want to talk about the window > > tree, let's talk about a tree with nodes; let's not call them > > "windows". I know that each node is exposed to Lisp as a window > > object, but (a) I'm not sure this is a good idea either, and (b) what > > harm will be done if we mention this factoid in some place and > > immediately forget about it? > > 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. > Let's take an example: I wrote two functions called `window-state-get' > and `window-state-put' in the hope that eventually someone uses these > functions in order to write window configurations to a file and reuse > them in a later session. If we find someone to do that, that person > must be interested in internal windows, because these are part of the > state and prescribe how to obtain the original configuration from that > state. Debugging or patching these functions without knowing about > internal windows is virtually impossible. 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, 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.