Package: emacs;
Reported by: Eli Zaretskii <eliz <at> gnu.org>
Date: Wed, 26 Oct 2011 11:46:01 UTC
Severity: minor
Found in version 24.0.90
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
From: Eli Zaretskii <eliz <at> gnu.org> To: bug-gnu-emacs <at> gnu.org Subject: 24.0.90; Confusing description of the "window tree" in ELisp manual Date: Wed, 26 Oct 2011 07:43:30 -0400
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)
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.