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: Wed, 26 Oct 2011 16:23:05 +0200 Message-ID: <4EA817C9.9030000@gmx.at> References: 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 1319643572 18390 80.91.229.12 (26 Oct 2011 15:39:32 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 26 Oct 2011 15:39:32 +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 Wed Oct 26 17:39:27 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 1RJ5Zf-0000OA-Cz for geb-bug-gnu-emacs@m.gmane.org; Wed, 26 Oct 2011 17:39:27 +0200 Original-Received: from localhost ([::1]:57566 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ5Ze-0002cV-RK for geb-bug-gnu-emacs@m.gmane.org; Wed, 26 Oct 2011 11:39:26 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:50755) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ4O7-0003Cf-V0 for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 10:23:31 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJ4O1-0000D6-Ou for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 10:23:27 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:56630) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ4O1-0000Cy-MO for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 10:23:21 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RJ4Pg-000559-7O for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 10:25:04 -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: Wed, 26 Oct 2011 14:25:04 +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.131963910019521 (code B ref 9875); Wed, 26 Oct 2011 14:25:04 +0000 Original-Received: (at 9875) by debbugs.gnu.org; 26 Oct 2011 14:25:00 +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 1RJ4Pc-00054n-3Z for submit@debbugs.gnu.org; Wed, 26 Oct 2011 10:25:00 -0400 Original-Received: from mailout-de.gmx.net ([213.165.64.23]) by debbugs.gnu.org with smtp (Exim 4.69) (envelope-from ) id 1RJ4PX-00054M-DE for 9875@debbugs.gnu.org; Wed, 26 Oct 2011 10:24:57 -0400 Original-Received: (qmail invoked by alias); 26 Oct 2011 14:23:05 -0000 Original-Received: from 62-47-39-90.adsl.highway.telekom.at (EHLO [62.47.39.90]) [62.47.39.90] by mail.gmx.net (mp067) with SMTP; 26 Oct 2011 16:23:05 +0200 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX195OnE0/JR50ihxIkg/Bz1A84R3Q4LKyumGKv42Qf IyVl7tmQza8Tdp User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) In-Reply-To: X-Y-GMX-Trusted: 0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Wed, 26 Oct 2011 10:25:04 -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:53154 Archived-At: > 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 ... > which makes it all too easy to > confuse them with the leafs of the window tree, each one of which > corresponds to a real live window displayed on the frame. This is > fundamentally wrong, because there's a significant difference between > the "normal" (a.k.a. "live") windows and 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. > The confusion thereafter continues in the next sections of the > "Windows" chapter, as these "windows" are sometimes called "internal > windows", sometimes contrasted with "live" windows. Hopefully wherever such a contrast is required. > 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? > 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 guess what I'm saying is this: let's have a single section named > "The Window Tree" which describes the tree and what can be done with > its nodes from a Lisp program, and let's describe all the other > window-related operations without any reference to the tree or its > nodes. I submit that most Lisp programmers will never need to go to > the level of the tree, unless they want to understand the internal > operation of windows.el or rewrite it from scratch. Given the fact that a function like `frame-root-window' (which would return a "node" in your parlance whenever we have two live windows) is in Emacs since 1992 at least and a documentation of that function has been reqeusted recently here on this forum, I suppose that at least some Lisp programmers need to go to the level of the tree. 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. martin