Subject: Re: bug#9873: 24.0.90; dired - window changes size when trying to delete more than one file

From: martin rudalics <[email-masked]>
Date: Wed, 26 Oct 2011 16:22:59 +0200

>> The Elisp manual should cover `window-nest' in some detail.  Please have
 >> a look.
 >
 > IMNSHO, the doc string needs "Some Work"®, as right now it's
 > impenetrable for mere mortals (this being is a user option).  Users
 > aren't, and shouldn't be, aware that windows are arranged in a tree.
 > Without a very good understanding of that, talking about "a new parent
 > window" and "binary tree of windows" misses the target by a very large
 > measure.

Describing what `window-nest' does without referring to the window tree
is virtually impossible (aat least for me).

 > Besides, user options should be first and foremost be described in the
 > user manual, not in the ELisp manual.

Agreed.  But since I apparently failed to convey the semantics of this
variable in the Elisp manual, someone else will have to take care of
writing such a description ;-)

 > After reading what's written in the ELisp manual (and digressing to
 > "Windows and Frames" for a while, to understand what the heck it is
 > talking about when it says "parent window"), I do understand what the
 > variable does in terms of the window tree, but still cannot tell I
 > understand its effects in practice, beyond the specific example of
 > splitting and unsplitting windows that is described there in detail.
 > Is this the only user-visible effect of this variable?

No.  Suppose a window W is a vertical combination of two windows W1 and
W2 and W2 is a vertical combination of two windows W3 and W4.  In this
case resizing W will equally affect W1 and W2 and consequently W1 more
than W3 or W4.  This is different from the case where W is a vertical
combination of three live windows W1, W3 and W4.

 > If so, why not
 > name it something that is related to resizing or splitting, and why
 > not say that in the doc string, instead of describing the window tree
 > and the "parent window" which a user will never see and does not care
 > about in the first place?  Since when do we explain user-level
 > features in terms of abstract data types and structures that are all
 > but invisible to users??

This is the Elisp manual and I have been trying to explain all related
terms in the section "Windows and Frames".  If there's something
missing, including cross references to that section, you're welcome to
fix that.

 > I'm sorry for being so blunt, but it's the first time I've read in an
 > Emacs manual a whole section, which does a very good job at describing
 > what it sets out to describe, but is completely useless for me as a
 > guide for understanding the practical implications of a certain user
 > option.

One practical implication of not having that option is evident from the
example.  If it has further implications, then that's something we will
find out as soon as people have started to customize it.

martin