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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 26 Oct 2011 11:22:04 +0200
> From: martin rudalics <rudalics@gmx.at>
> Cc: Christoph Scholtes <cschol2112@googlemail.com>, 9873@debbugs.gnu.org
> 
>  >> Thanks Juanma, this fixes the problem. I am not sure I understand what
>  >> other implications this has, though.

Lucky you.  I didn't understand a thing about it.

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

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

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

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.