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 07:43:30 -0400 Message-ID: Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: dough.gmane.org 1319629473 6708 80.91.229.12 (26 Oct 2011 11:44:33 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 26 Oct 2011 11:44:33 +0000 (UTC) To: 9875@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Oct 26 13:44: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 1RJ1uE-0005Sj-GK for geb-bug-gnu-emacs@m.gmane.org; Wed, 26 Oct 2011 13:44:26 +0200 Original-Received: from localhost ([::1]:47204 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ1uD-0004Ws-MY for geb-bug-gnu-emacs@m.gmane.org; Wed, 26 Oct 2011 07:44:25 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:46074) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ1u9-0004WY-2R for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 07:44:22 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJ1u7-0007k8-PX for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 07:44:21 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:37852) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ1u7-0007jw-NZ for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 07:44:19 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RJ1vl-0001Np-S6 for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 07:46: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 11:46:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 9875 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.13196295275271 (code B ref -1); Wed, 26 Oct 2011 11:46:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 26 Oct 2011 11:45:27 +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 1RJ1vD-0001Mx-5n for submit@debbugs.gnu.org; Wed, 26 Oct 2011 07:45:27 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RJ1vA-0001Mk-59 for submit@debbugs.gnu.org; Wed, 26 Oct 2011 07:45:25 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJ1tO-0007Vy-Va for submit@debbugs.gnu.org; Wed, 26 Oct 2011 07:43:36 -0400 Original-Received: from lists.gnu.org ([140.186.70.17]:34914) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ1tO-0007Ve-Ty for submit@debbugs.gnu.org; Wed, 26 Oct 2011 07:43:34 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:45760) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ1tM-0004VD-9H for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 07:43:34 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJ1tK-0007Pw-MZ for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 07:43:32 -0400 Original-Received: from fencepost.gnu.org ([140.186.70.10]:47023) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJ1tK-0007Ps-Kt for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 07:43:30 -0400 Original-Received: from eliz by fencepost.gnu.org with local (Exim 4.71) (envelope-from ) id 1RJ1tK-0002EG-F9 for bug-gnu-emacs@gnu.org; Wed, 26 Oct 2011 07:43:30 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Wed, 26 Oct 2011 07:46: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:53147 Archived-At: emacs -Q C-h i m elisp RET g Windows and Frames RET 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", 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. 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. The confusion culminates in "Splitting Windows", where many issues are described via window-parent and what is called "creating a new parent". 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? 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. In GNU Emacs 24.0.90.87 (x86_64-unknown-linux-gnu, GTK+ Version 2.20.1) of 2011-10-26 on fencepost.gnu.org configured using `configure '--enable-asserts' '--enable-checking' '--with-gif=no' '--with-tiff=no' 'CFLAGS=-ggdb -g3 -O0 -DGLYPH_DEBUG=1'' Important settings: value of $LC_ALL: nil value of $LC_COLLATE: nil value of $LC_CTYPE: nil value of $LC_MESSAGES: nil value of $LC_MONETARY: nil value of $LC_NUMERIC: nil value of $LC_TIME: nil value of $LANG: nil value of $XMODIFIERS: nil locale-coding-system: nil default enable-multibyte-characters: t Major mode: RMAIL Minor modes in effect: shell-dirtrack-mode: t display-time-mode: t show-paren-mode: t savehist-mode: t tooltip-mode: t mouse-wheel-mode: t tool-bar-mode: t menu-bar-mode: t file-name-shadow-mode: t global-font-lock-mode: t font-lock-mode: t auto-composition-mode: t auto-encryption-mode: t auto-compression-mode: t line-number-mode: t Recent input: ESC O A ESC O A ESC O A ESC O A ESC O A ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B C-e SPC a b o u t ESC q ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC < C-c C-c d C-u 1 0 2 2 j C-x C-s ESC ! ESC O A RET ESC x ESC O A RET ESC O A ESC O A ESC O A RET C-s 0 6 : 2 0 : 1 4 C-s C-s ESC O B ESC [ 6 ~ ESC O A ESC O B C-x C-x C-w C-x C-s C-x k RET C-u g ESC O A RET SPC C-z C-z C-z C-z d SPC SPC d d d d SPC d d d d d d d d d C-x C-s C-x b RET ESC < u ESC O A ESC O A ESC O A ESC O A RET SPC SPC SPC SPC SPC SPC C-x b RET ESC x r e p o r t - e m TAB RET Recent messages: Computing summary lines...done 14 new messages read Showing message 1025 Showing message 1025...done Showing message 1036 Showing message 1036...done No following nondeleted message Saving file /home/e/eliz/INBOX... Wrote /home/e/eliz/INBOX [2 times] Mark set Load-path shadows: None found. Features: (shadow emacsbug iso-transl info multi-isearch pp help-mode view help-fns dabbrev newcomment flyspell ispell shell pcomplete comint ring rmailsum qp rmailmm message sendmail regexp-opt format-spec rfc822 mml easymenu mml-sec mm-decode mm-bodies mm-encode mailabbrev gmm-utils mailheader mail-parse rfc2231 rmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils time paren cus-start cus-load time-date savehist saveplace tooltip ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image fringe lisp-mode register page menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak czech european ethiopic indian cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev minibuffer loaddefs button faces cus-face files text-properties overlay sha1 md5 base64 format env code-pages mule custom widget hashtable-print-readable backquote make-network-process dynamic-setting font-render-setting move-toolbar gtk x-toolkit x multi-tty emacs)