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

[martin rudalics <rudalics@gmx.at>]

 > 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.

True.  But the Elisp manual is about reading and writing Elisp code.
And the necessary distinction in descriptions is in just one word -
"any" or "live".

 >> 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 what would be so bad about that?  A lost opportunity.  When Joe
grows up he will read the text more carefully and maybe even appreciate
what he finds there.

 >> 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'"?

And how could you live with a text like

    For practical purposes, a window exists only while it is displayed in
a frame.  Once removed from the frame, the window is effectively deleted
and should not be used, _even though there may still be references to
it_ from other Lisp objects; see *Note Deleting Windows::.  Restoring a
saved window configuration is the only way for a window no longer on the
screen to come back to life; see *Note Window Configurations::.

all those years?

 > Simple is in the eye of the beholder.
 >
 > And I was talking about the manual, not the doc strings, btw.

Which have to be consistent, btw.

martin