From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.bugs Subject: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual Date: Thu, 27 Oct 2011 15:16:13 +0200 Message-ID: <4EA9599D.5030004@gmx.at> References: <4EA817C9.9030000@gmx.at> <83y5w7bn2r.fsf@gnu.org> <4EA929E6.9080001@gmx.at> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-15; format=flowed Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1319721454 8361 80.91.229.12 (27 Oct 2011 13:17:34 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 27 Oct 2011 13:17:34 +0000 (UTC) Cc: 9875@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Oct 27 15:17:29 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1RJPpl-0008OE-VD for geb-bug-gnu-emacs@m.gmane.org; Thu, 27 Oct 2011 15:17:26 +0200 Original-Received: from localhost ([::1]:34403 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJPpl-0004P9-E3 for geb-bug-gnu-emacs@m.gmane.org; Thu, 27 Oct 2011 09:17:25 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:51144) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJPpf-0004Kb-Dq for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 09:17:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJPpZ-0001hu-K0 for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 09:17:19 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:49320) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJPpZ-0001hp-GU for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 09:17:13 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RJPrJ-0007ig-UF for bug-gnu-emacs@gnu.org; Thu, 27 Oct 2011 09:19:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: martin rudalics Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 27 Oct 2011 13:19:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 9875 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 9875-submit@debbugs.gnu.org id=B9875.131972149129604 (code B ref 9875); Thu, 27 Oct 2011 13:19:01 +0000 Original-Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 13:18:11 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RJPqV-0007hR-2u for submit@debbugs.gnu.org; Thu, 27 Oct 2011 09:18:11 -0400 Original-Received: from mailout-de.gmx.net ([213.165.64.23]) by debbugs.gnu.org with smtp (Exim 4.69) (envelope-from ) id 1RJPqT-0007hG-AB for 9875@debbugs.gnu.org; Thu, 27 Oct 2011 09:18:10 -0400 Original-Received: (qmail invoked by alias); 27 Oct 2011 13:16:14 -0000 Original-Received: from 62-47-54-146.adsl.highway.telekom.at (EHLO [62.47.54.146]) [62.47.54.146] by mail.gmx.net (mp003) with SMTP; 27 Oct 2011 15:16:14 +0200 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX1+22NRZlYy2ZH/YT7d/lFJgG8QLp4OzKlq2QmsfSQ TDYmvxHh5cNpNP User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) In-Reply-To: X-Y-GMX-Trusted: 0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Thu, 27 Oct 2011 09:19:01 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:53206 Archived-At: >> 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