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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 27 Oct 2011 11:56:16 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: Stefan Monnier <monnier@iro.umontreal.ca>, 9875@debbugs.gnu.org
> 
>  > That's true, but this fact is an implementation detail; we could
>  > easily have the nodes be different Lisp objects.
> 
> Certainly not.  If you look into the window resizing code you will see
> that it treats internal and leaf windows alike.  Changing the underlying
> representation would have meant to double the work done there.

It's clear that representing the non-leaf nodes as window objects was
chosen because it's convenient from the implementation POV.  But that
doesn't mean we need to expose this to every place where we describe
how windows are split and resized.

>  > So I think speaking about "nodes" instead will avoid confusion,
>  > because otherwise whenever we talk about a "window", the reader will
>  > always be in doubt whether this applies only to the "real", i.e. leaf
>  > windows, or to the "internal" ones as well.
> 
> This is usually said in the second sentence of the doc-string.  For
> `split-window' it reads
> 
>    "WINDOW can be any window and defaults to the selected one."

When J.R. Hacker reads about "any window", she will definitely have
only live windows in mind.

> And for `set-window-buffer' we have
> 
>    "WINDOW has to be a live window and defaults to the selected one."

Which immediately begs the question "how can a window not be `live'"?

> Let's not spoil this very simple recipe.

Simple is in the eye of the beholder.

And I was talking about the manual, not the doc strings, btw.