bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual

[Eli Zaretskii]

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)