GNU bug report logs - #9875
24.0.90; Confusing description of the "window tree" in ELisp manual

Previous Next

Full log

View this message in rfc822 format

From: martin rudalics <rudalics <at> gmx.at>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 9875 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: bug#9875: 24.0.90;	Confusing description of the "window tree" in ELisp manual
Date: Thu, 27 Oct 2011 15:16:40 +0200

> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.