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

Previous Next

Full log

Message #35 received at 9875 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: martin rudalics <rudalics <at> gmx.at>
Cc: 9875 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#9875: 24.0.90;	Confusing description of the "window tree"
	in ELisp manual
Date: Thu, 27 Oct 2011 07:05:18 -0400

> Date: Thu, 27 Oct 2011 11:56:16 +0200
> From: martin rudalics <rudalics <at> gmx.at>
> CC: Stefan Monnier <monnier <at> iro.umontreal.ca>, 9875 <at> 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.

Previous Next

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