bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: martin rudalics
Subject: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual
Date: Thu, 27 Oct 2011 15:16:40 +0200
User-agent: Thunderbird 2.0.0.21 (Windows/20090302)

> 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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]