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:13 +0200
User-agent: Thunderbird 2.0.0.21 (Windows/20090302)

>> The term "window" stands for an "arbitrary window" that is either an
>> internal or a leaf window.  I want to be able to write text like
>>
>>     A window is considered a "subwindow" of another window if it occupies
>>     a part of that other window's screen area.
>
> Why do you need to talk about subwindows at all?

Because I didn't give this a thought yet ;-)

> AFAICS, this is used
> (in about 5 more places, which is not a lot) in the context of
> explaining the behavior when two or more windows are sibling leafs in
> the tree.  If so, then using "sibling leaf nodes in the tree" will
> explain it nicely.

A subwindow can be an internal window.

> I appreciate your efforts.  But this bug is not about lack of effort.
> This bug report is about methodological shortcomings of the result.
> In a nutshell, by using terminology that is contrary to everyday
> language and semantics, the current text makes it hard to understand,
> because it goes against the intuitive meaning of "window" every reader
> has wired into her mind.

Then this problem existed through the term `frame-root-window' for more
than twenty years without anyone ever complaining.  Ever tried

(windowp (frame-root-window))

in Emacs < 24?  And when the function `window-tree' was added a couple
of Emacsen ago, no one complained about its documentation either.

> No amount of explanations and examples will
> ever be able to fight the natural tendency of our brains to think of
> the white color when we read about "white", even if you define it as
> something else and give a lot of examples.

An object can be white even if it's hidden beneath another one.

> You need to read this in context.  Here's the beginning of the
> description:
>
>  -- Command: split-window &optional window size side
>      This function creates a new window adjacent to WINDOW.  It returns
>      the new window which is always a live window.
>
> So now, when I read the above paragraph about live and internal
> windows, I'm left with the following unsolved mysteries:
>
>  . what does it mean "adjacent to WINDOW" when WINDOW is an internal
>    one?

The same as for a live window.  Internal windows have edges just as live
windows do.

>  . what happens to original WINDOW, as result of the split, if it was
>    an internal one? does it occlude the new window or doesn't it, for
>    example?

It's shrunk just as a live window.

>  . what other properties, besides margins and scroll bars are
>    inherited from the selected window?

All those it would inherit from WINDOW if WINDOW were live.

>  . what buffer will be shown in the new window when WINDOW is a live
>    one?

WINDOW's buffer.

> The text is cryptic because it leaves me with all those questions.
> Significantly, if WINDOW is a live window, none of these questions
> comes up, because it is clear what to expect.

Not for me.  I don't know, for example, if the new window will get a
header line or not.

>> If you refer to this part "including space reserved for margins, fringes
>> and the scroll bar or a divider column" then it's explaind in the text
>> you considered cryptic above, namely that "these properties, as well as
>> the buffer shown in the new window, are inherited from the window
>> selected on WINDOW's frame".
>
> No, I mean all of it: right, left, size, space reserved for margins,
> fringes, scroll bars -- these attributes make no sense for a window
> that isn't displayed.  They are just copies or sums of the attributes
> of _real_ live windows that are children of this internal window.  It
> is unnatural to talk about "size" or "side" of a window that doesn't
> really exist on the screen!

Nevertheless internal windows have sizes and sides and I continuously
work with them.  To know whether an arbitrary window is full-width I
compare its width to that of the frame's root window (and not to the
width of the frame).

> Which probably means we should have a function for that kind of thing,
> so that J.R. Hacker could be oblivious to these intimate details.

We had plenty of that in the buffer display code people didn't like.

>> Splitting a window creates a new parent window due to the fact that
>> splitting has to preserve the "identity" of the window that is split.
>> Hence, the new parent window is spliced into the window tree in a
>> single, atomic (on the Elisp level) action.  This means that I indeed
>> "create a _new_ parent for" an already existing child or root window.
>
> My point was that it is much easier and much more clear to say that a
> new node is inserted into the window tree.  _That_ is something no
> programmer needs explained.

But normally a tree is expanded by converting a leaf node into an
internal node.  Just that Emacs has different requirements ...

> Okay, "the argument WINDOW can also be a non-leaf node of the frame's
> window tree", if you must.

So Joe has to to be familiar with "nodes" and the "window tree" when
reading the doc-string of `delete-window'?

>> This would be misleading.  Live windows are also nodes of the window
>> tree.
>
> Our manuals are full of such "misleading" text.  We don't need to be
> 100% accurate in the mathematical sense of the word, just accurate
> enough to get the idea across to the reader.

But when we write new text we should try to be as accurate as possible.
Don't you agree?

martin




reply via email to

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