[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
bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual, martin rudalics, 2011/10/26
- bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual, Eli Zaretskii, 2011/10/26
- bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual, martin rudalics, 2011/10/27
- bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual, Eli Zaretskii, 2011/10/27
- bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual,
martin rudalics <=
- bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual, Juri Linkov, 2011/10/28
- bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual, Eli Zaretskii, 2011/10/28
- bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual, Drew Adams, 2011/10/28