Received: (at 9875) by debbugs.gnu.org; 28 Oct 2011 13:41:04 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Fri Oct 28 09:41:04 2011 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1RJmgC-0000gu-4o for submit <at> debbugs.gnu.org; Fri, 28 Oct 2011 09:41:04 -0400 Received: from rcsinet15.oracle.com ([148.87.113.117]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <drew.adams@HIDDEN>) id 1RJmg9-0000gT-KI for 9875 <at> debbugs.gnu.org; Fri, 28 Oct 2011 09:41:02 -0400 Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by rcsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p9SDd4jW018932 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 28 Oct 2011 13:39:05 GMT Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p9SDd3ev003242 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 28 Oct 2011 13:39:04 GMT Received: from abhmt105.oracle.com (abhmt105.oracle.com [141.146.116.57]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p9SDcvuR022276; Fri, 28 Oct 2011 08:38:58 -0500 Received: from dradamslap1 (/10.159.56.19) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 28 Oct 2011 06:38:57 -0700 From: "Drew Adams" <drew.adams@HIDDEN> To: "'Juri Linkov'" <juri@HIDDEN>, "'Eli Zaretskii'" <eliz@HIDDEN> References: <E1RJ1tK-0002EG-F9@HIDDEN> <4EA817C9.9030000@HIDDEN><83y5w7bn2r.fsf@HIDDEN> <4EA929E6.9080001@HIDDEN><E1RJNhV-0003id-S8@HIDDEN> <87y5w55zfw.fsf@HIDDEN> Subject: RE: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual Date: Fri, 28 Oct 2011 06:38:58 -0700 Message-ID: <839B3C46B8E6433384FACC65D02EBC18@HIDDEN> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <87y5w55zfw.fsf@HIDDEN> Thread-Index: AcyVSpSX97htdn9DS6aJkUyZkUnujwALCQ6Q X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090208.4EAAB07A.0072,ss=1,re=0.000,fgs=0 X-Spam-Score: -6.2 (------) X-Debbugs-Envelope-To: 9875 Cc: 9875 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Sender: debbugs-submit-bounces <at> debbugs.gnu.org Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org X-Spam-Score: -6.2 (------) > The only problem with these diagrams is that ASCII art > doesn't distinguish between internal and live windows: > ______________________________________ > | ______ ____________________________ | > || || __________________________ || > || ||| ___________ ___________ ||| > || |||| || |||| > || |||| || |||| > || ||||_____W6____||_____W7____|||| > || |||____________W4____________||| > || || __________________________ || > || ||| ||| > || |||____________W5____________||| > ||__W2__||_____________W3_____________ | > |__________________W1__________________| > > It would help to draw live and internal windows with > different lines, e.g. > > ______________________________________ > |******** ____________________________ | > |* *| __________________________ || > |* *||**************************||| > |* *||* ** *||| > |* *||* ** *||| > |* *||******W6***********W7*****||| > |* *||____________W4____________||| > |* *|****************************|| > |* *|* *|| > |* *|*************W5*************|| > |***W2***|_____________W3_____________ | > |__________________W1__________________| > > but this is ugly and I can't find a better way to draw them. Just use a different label/name convention: IW3 (or I3 or N3 or ...) for internal windows. (Mention the convention in the text, of course.)
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.Received: (at 9875) by debbugs.gnu.org; 28 Oct 2011 09:46:58 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Fri Oct 28 05:46:58 2011 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1RJj1d-0002sv-Oj for submit <at> debbugs.gnu.org; Fri, 28 Oct 2011 05:46:58 -0400 Received: from mtaout21.012.net.il ([80.179.55.169]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <eliz@HIDDEN>) id 1RJj1b-0002sm-7T for 9875 <at> debbugs.gnu.org; Fri, 28 Oct 2011 05:46:56 -0400 Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0LTR00L00S472M00@HIDDEN> for 9875 <at> debbugs.gnu.org; Fri, 28 Oct 2011 11:43:22 +0200 (IST) Received: from HOME-C4E4A596F7 ([77.124.212.197]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0LTR00KDGSC9Y250@HIDDEN>; Fri, 28 Oct 2011 11:43:22 +0200 (IST) Date: Fri, 28 Oct 2011 11:43:30 +0200 From: Eli Zaretskii <eliz@HIDDEN> Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual In-reply-to: <87y5w55zfw.fsf@HIDDEN> X-012-Sender: halo1@HIDDEN To: Juri Linkov <juri@HIDDEN> Message-id: <831utxbge5.fsf@HIDDEN> References: <E1RJ1tK-0002EG-F9@HIDDEN> <4EA817C9.9030000@HIDDEN> <83y5w7bn2r.fsf@HIDDEN> <4EA929E6.9080001@HIDDEN> <E1RJNhV-0003id-S8@HIDDEN> <87y5w55zfw.fsf@HIDDEN> X-Spam-Score: -2.1 (--) X-Debbugs-Envelope-To: 9875 Cc: rudalics@HIDDEN, 9875 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Reply-To: Eli Zaretskii <eliz@HIDDEN> List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Sender: debbugs-submit-bounces <at> debbugs.gnu.org Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org X-Spam-Score: -2.1 (--) > From: Juri Linkov <juri@HIDDEN> > Cc: martin rudalics <rudalics@HIDDEN>, 9875 <at> debbugs.gnu.org > Date: Fri, 28 Oct 2011 11:04:35 +0300 > > > It is unnatural to talk about "size" or "side" of a window that > > doesn't really exist on the screen! > > FWIW, I have no problem imagining a window that doesn't really exist > on the screen. I also "have no problem" imagining that, but it requires my brain muscles to make a conscious effort each time I meet the word "window". Such efforts should not be required when reading about such a basic concept. > The only problem with these diagrams is that ASCII art > doesn't distinguish between internal and live windows: Both Texinfo and Emacs's Info reader support images for quite some time.
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 28 Oct 2011 08:22:38 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Oct 28 04:22:38 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJhi0-0000vv-Cl
for submit <at> debbugs.gnu.org; Fri, 28 Oct 2011 04:22:37 -0400
Received: from smarty.dreamhost.com ([208.113.175.8])
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <juri@HIDDEN>) id 1RJhhx-0000vm-Nk
for 9875 <at> debbugs.gnu.org; Fri, 28 Oct 2011 04:22:34 -0400
Received: from ps18281.dreamhostps.com (ps18281.dreamhost.com [69.163.218.105])
by smarty.dreamhost.com (Postfix) with ESMTP id B60636E80A3;
Fri, 28 Oct 2011 01:20:39 -0700 (PDT)
Received: from localhost (ps18281.dreamhostps.com [69.163.218.105])
by ps18281.dreamhostps.com (Postfix) with ESMTP id 73543451C00D;
Fri, 28 Oct 2011 01:20:38 -0700 (PDT)
From: Juri Linkov <juri@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90;
Confusing description of the "window tree" in ELisp manual
Organization: JURTA
References: <E1RJ1tK-0002EG-F9@HIDDEN> <4EA817C9.9030000@HIDDEN>
<83y5w7bn2r.fsf@HIDDEN> <4EA929E6.9080001@HIDDEN>
<E1RJNhV-0003id-S8@HIDDEN>
Date: Fri, 28 Oct 2011 11:04:35 +0300
In-Reply-To: <E1RJNhV-0003id-S8@HIDDEN> (Eli Zaretskii's message of
"Thu, 27 Oct 2011 07:00:45 -0400")
Message-ID: <87y5w55zfw.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.90 (x86_64-pc-linux-gnu)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -2.7 (--)
X-Debbugs-Envelope-To: 9875
Cc: martin rudalics <rudalics@HIDDEN>, 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.7 (--)
> It is unnatural to talk about "size" or "side" of a window that
> doesn't really exist on the screen!
FWIW, I have no problem imagining a window that doesn't really exist
on the screen. I imagine it as an "abstract window" with invisible
outlines that group visible windows. So I have no problem understanding
"internal windows" when reading the documentation.
It seems the source of your complaints is the duality of window
representation: data and view. When manipulating the window tree
(e.g. when saving/restoring the window tree) it makes sense to think
in terms of data - window tree with nodes. But when manipulating
windows of the screen (e.g. when splitting windows), it makes sense
to think in terms of visual representation where "internal windows"
are distinct objects (albeit invisible).
So thinking about "internal windows" requires imagination skills.
But diagrams in the Info manual help greatly.
The only problem with these diagrams is that ASCII art
doesn't distinguish between internal and live windows:
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
|| ||| ___________ ___________ |||
|| |||| || ||||
|| |||| || ||||
|| ||||_____W6____||_____W7____||||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
It would help to draw live and internal windows with different lines, e.g.
______________________________________
|******** ____________________________ |
|* *| __________________________ ||
|* *||**************************|||
|* *||* ** *|||
|* *||* ** *|||
|* *||******W6***********W7*****|||
|* *||____________W4____________|||
|* *|****************************||
|* *|* *||
|* *|*************W5*************||
|***W2***|_____________W3_____________ |
|__________________W1__________________|
but this is ugly and I can't find a better way to draw them.
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 13:18:37 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 09:18:37 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJPqv-0007i2-Jp
for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 09:18:37 -0400
Received: from mailout-de.gmx.net ([213.165.64.22])
by debbugs.gnu.org with smtp (Exim 4.69)
(envelope-from <rudalics@HIDDEN>) id 1RJPqt-0007ho-Li
for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 09:18:36 -0400
Received: (qmail invoked by alias); 27 Oct 2011 13:16:41 -0000
Received: from 62-47-54-146.adsl.highway.telekom.at (EHLO [62.47.54.146])
[62.47.54.146]
by mail.gmx.net (mp018) with SMTP; 27 Oct 2011 15:16:41 +0200
X-Authenticated: #14592706
X-Provags-ID: V01U2FsdGVkX1/5dXFYrHP58Y85y9xM2Ibae9h1ElWLP3SzgSDF1x
/hzkfmmOWtOR4M
Message-ID: <4EA959B8.4030402@HIDDEN>
Date: Thu, 27 Oct 2011 15:16:40 +0200
From: martin rudalics <rudalics@HIDDEN>
User-Agent: Thunderbird 2.0.0.21 (Windows/20090302)
MIME-Version: 1.0
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree"
in ELisp manual
References: <E1RJ1tK-0002EG-F9@HIDDEN> <jwvd3dj2651.fsf-monnier+emacs@HIDDEN>
<83zkgnbo50.fsf@HIDDEN> <jwvmxcnxupo.fsf-monnier+emacs@HIDDEN>
<E1RJKNI-0005C0-47@HIDDEN> <4EA92AC0.1040803@HIDDEN>
<E1RJNlu-0000Kx-K9@HIDDEN>
In-Reply-To: <E1RJNlu-0000Kx-K9@HIDDEN>
Content-Type: text/plain; charset=ISO-8859-15; format=flowed
Content-Transfer-Encoding: 7bit
X-Y-GMX-Trusted: 0
X-Spam-Score: -2.5 (--)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org, monnier@HIDDEN
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.5 (--)
> It's clear that representing the non-leaf nodes as window objects was
> chosen because it's convenient from the implementation POV. But that
> doesn't mean we need to expose this to every place where we describe
> how windows are split and resized.
True. But the Elisp manual is about reading and writing Elisp code.
And the necessary distinction in descriptions is in just one word -
"any" or "live".
>> This is usually said in the second sentence of the doc-string. For
>> `split-window' it reads
>>
>> "WINDOW can be any window and defaults to the selected one."
>
> When J.R. Hacker reads about "any window", she will definitely have
> only live windows in mind.
And what would be so bad about that? A lost opportunity. When Joe
grows up he will read the text more carefully and maybe even appreciate
what he finds there.
>> And for `set-window-buffer' we have
>>
>> "WINDOW has to be a live window and defaults to the selected one."
>
> Which immediately begs the question "how can a window not be `live'"?
And how could you live with a text like
For practical purposes, a window exists only while it is displayed in
a frame. Once removed from the frame, the window is effectively deleted
and should not be used, _even though there may still be references to
it_ from other Lisp objects; see *Note Deleting Windows::. Restoring a
saved window configuration is the only way for a window no longer on the
screen to come back to life; see *Note Window Configurations::.
all those years?
> Simple is in the eye of the beholder.
>
> And I was talking about the manual, not the doc strings, btw.
Which have to be consistent, btw.
martin
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 13:18:11 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 09:18:11 2011 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1RJPqV-0007hR-2u for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 09:18:11 -0400 Received: from mailout-de.gmx.net ([213.165.64.23]) by debbugs.gnu.org with smtp (Exim 4.69) (envelope-from <rudalics@HIDDEN>) id 1RJPqT-0007hG-AB for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 09:18:10 -0400 Received: (qmail invoked by alias); 27 Oct 2011 13:16:14 -0000 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 Message-ID: <4EA9599D.5030004@HIDDEN> Date: Thu, 27 Oct 2011 15:16:13 +0200 From: martin rudalics <rudalics@HIDDEN> User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) MIME-Version: 1.0 To: Eli Zaretskii <eliz@HIDDEN> Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual References: <E1RJ1tK-0002EG-F9@HIDDEN> <4EA817C9.9030000@HIDDEN> <83y5w7bn2r.fsf@HIDDEN> <4EA929E6.9080001@HIDDEN> <E1RJNhV-0003id-S8@HIDDEN> In-Reply-To: <E1RJNhV-0003id-S8@HIDDEN> Content-Type: text/plain; charset=ISO-8859-15; format=flowed Content-Transfer-Encoding: 7bit X-Y-GMX-Trusted: 0 X-Spam-Score: -2.5 (--) X-Debbugs-Envelope-To: 9875 Cc: 9875 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Sender: debbugs-submit-bounces <at> debbugs.gnu.org Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org X-Spam-Score: -2.5 (--) >> 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-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 13:00:29 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 09:00:29 2011 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1RJPZM-0007Hp-1o for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 09:00:29 -0400 Received: from fencepost.gnu.org ([140.186.70.10] ident=Debian-exim) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <eliz@HIDDEN>) id 1RJPZJ-0007Hi-Rx for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 09:00:26 -0400 Received: from eliz by fencepost.gnu.org with local (Exim 4.71) (envelope-from <eliz@HIDDEN>) id 1RJPXZ-0000EZ-0f; Thu, 27 Oct 2011 08:58:37 -0400 Date: Thu, 27 Oct 2011 08:58:37 -0400 Message-Id: <E1RJPXZ-0000EZ-0f@HIDDEN> From: Eli Zaretskii <eliz@HIDDEN> To: Stefan Monnier <monnier@HIDDEN> In-reply-to: <jwvmxcmvcfv.fsf-monnier+emacs@HIDDEN> (message from Stefan Monnier on Thu, 27 Oct 2011 08:36:40 -0400) Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual References: <E1RJ1tK-0002EG-F9@HIDDEN> <jwvd3dj2651.fsf-monnier+emacs@HIDDEN> <83zkgnbo50.fsf@HIDDEN> <jwvmxcnxupo.fsf-monnier+emacs@HIDDEN> <E1RJKNI-0005C0-47@HIDDEN> <4EA92AC0.1040803@HIDDEN> <E1RJNlu-0000Kx-K9@HIDDEN> <jwvmxcmvcfv.fsf-monnier+emacs@HIDDEN> X-Spam-Score: -6.6 (------) X-Debbugs-Envelope-To: 9875 Cc: rudalics@HIDDEN, 9875 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Reply-To: Eli Zaretskii <eliz@HIDDEN> List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Sender: debbugs-submit-bounces <at> debbugs.gnu.org Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org X-Spam-Score: -6.6 (------) > From: Stefan Monnier <monnier@HIDDEN> > Cc: martin rudalics <rudalics@HIDDEN>, 9875 <at> debbugs.gnu.org > Date: Thu, 27 Oct 2011 08:36:40 -0400 > > > Which immediately begs the question "how can a window not be `live'"? > > C-h f window-live-p RET I know that, sigh...
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 12:38:37 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 08:38:37 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJPEC-0006lM-PS
for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 08:38:37 -0400
Received: from ironport2-out.teksavvy.com ([206.248.154.181]
helo=ironport2-out.pppoe.ca)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <monnier@HIDDEN>) id 1RJPEB-0006lB-A4
for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 08:38:35 -0400
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: AmcSALZPqU5MCrTo/2dsb2JhbABCqE0BgQ6BBoFyAQEEAVYjBQsLNBIUGA0kiBW1AIh+BKFDhEU
X-IronPort-AV: E=Sophos;i="4.69,413,1315195200"; d="scan'208";a="144747513"
Received: from 76-10-180-232.dsl.teksavvy.com (HELO pastel.home)
([76.10.180.232])
by ironport2-out.pppoe.ca with ESMTP/TLS/ADH-AES256-SHA;
27 Oct 2011 08:36:40 -0400
Received: by pastel.home (Postfix, from userid 20848)
id 6F6C159208; Thu, 27 Oct 2011 08:36:40 -0400 (EDT)
From: Stefan Monnier <monnier@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90;
Confusing description of the "window tree" in ELisp manual
Message-ID: <jwvmxcmvcfv.fsf-monnier+emacs@HIDDEN>
References: <E1RJ1tK-0002EG-F9@HIDDEN>
<jwvd3dj2651.fsf-monnier+emacs@HIDDEN> <83zkgnbo50.fsf@HIDDEN>
<jwvmxcnxupo.fsf-monnier+emacs@HIDDEN>
<E1RJKNI-0005C0-47@HIDDEN> <4EA92AC0.1040803@HIDDEN>
<E1RJNlu-0000Kx-K9@HIDDEN>
Date: Thu, 27 Oct 2011 08:36:40 -0400
In-Reply-To: <E1RJNlu-0000Kx-K9@HIDDEN> (Eli Zaretskii's message of
"Thu, 27 Oct 2011 07:05:18 -0400")
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.90 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -2.7 (--)
X-Debbugs-Envelope-To: 9875
Cc: martin rudalics <rudalics@HIDDEN>, 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.7 (--)
> Which immediately begs the question "how can a window not be `live'"?
C-h f window-live-p RET
This has existed for a long time,
Stefan
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 12:37:10 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 08:37:10 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJPCo-0006jK-22
for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 08:37:10 -0400
Received: from ironport2-out.teksavvy.com ([206.248.154.183]
helo=ironport2-out.pppoe.ca)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <monnier@HIDDEN>) id 1RJPCl-0006j8-Id
for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 08:37:08 -0400
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: AmcSALZPqU5MCrTo/2dsb2JhbABCqE0BgQ6BBoFyAQEEAVYjBQsLNBIUGA0kiBW1AIh+BKFDhEU
X-IronPort-AV: E=Sophos;i="4.69,413,1315195200"; d="scan'208";a="144746878"
Received: from 76-10-180-232.dsl.teksavvy.com (HELO pastel.home)
([76.10.180.232])
by ironport2-out.pppoe.ca with ESMTP/TLS/ADH-AES256-SHA;
27 Oct 2011 08:35:12 -0400
Received: by pastel.home (Postfix, from userid 20848)
id 3ED7E59208; Thu, 27 Oct 2011 08:35:12 -0400 (EDT)
From: Stefan Monnier <monnier@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90;
Confusing description of the "window tree" in ELisp manual
Message-ID: <jwvsjmevckh.fsf-monnier+emacs@HIDDEN>
References: <E1RJ1tK-0002EG-F9@HIDDEN>
<jwvd3dj2651.fsf-monnier+emacs@HIDDEN> <83zkgnbo50.fsf@HIDDEN>
<jwvmxcnxupo.fsf-monnier+emacs@HIDDEN>
<E1RJKNI-0005C0-47@HIDDEN>
Date: Thu, 27 Oct 2011 08:35:12 -0400
In-Reply-To: <E1RJKNI-0005C0-47@HIDDEN> (Eli Zaretskii's message of
"Thu, 27 Oct 2011 03:27:40 -0400")
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.90 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -2.7 (--)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.7 (--)
> That sounds mysterious, since it remains unclear what kind of thing is
> this "parent".
Sorry, I meant "parent window".
Stefan
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 11:07:12 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 07:07:12 2011 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1RJNnj-0003zR-0E for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 07:07:12 -0400 Received: from fencepost.gnu.org ([140.186.70.10] ident=Debian-exim) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <eliz@HIDDEN>) id 1RJNnf-0003zG-Rb for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 07:07:09 -0400 Received: from eliz by fencepost.gnu.org with local (Exim 4.71) (envelope-from <eliz@HIDDEN>) id 1RJNlu-0000Kx-K9; Thu, 27 Oct 2011 07:05:18 -0400 Date: Thu, 27 Oct 2011 07:05:18 -0400 Message-Id: <E1RJNlu-0000Kx-K9@HIDDEN> From: Eli Zaretskii <eliz@HIDDEN> To: martin rudalics <rudalics@HIDDEN> In-reply-to: <4EA92AC0.1040803@HIDDEN> (message from martin rudalics on Thu, 27 Oct 2011 11:56:16 +0200) Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual References: <E1RJ1tK-0002EG-F9@HIDDEN> <jwvd3dj2651.fsf-monnier+emacs@HIDDEN> <83zkgnbo50.fsf@HIDDEN> <jwvmxcnxupo.fsf-monnier+emacs@HIDDEN> <E1RJKNI-0005C0-47@HIDDEN> <4EA92AC0.1040803@HIDDEN> X-Spam-Score: -6.6 (------) X-Debbugs-Envelope-To: 9875 Cc: 9875 <at> debbugs.gnu.org, monnier@HIDDEN X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Reply-To: Eli Zaretskii <eliz@HIDDEN> List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Sender: debbugs-submit-bounces <at> debbugs.gnu.org Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org X-Spam-Score: -6.6 (------) > Date: Thu, 27 Oct 2011 11:56:16 +0200 > From: martin rudalics <rudalics@HIDDEN> > CC: Stefan Monnier <monnier@HIDDEN>, 9875 <at> debbugs.gnu.org > > > That's true, but this fact is an implementation detail; we could > > easily have the nodes be different Lisp objects. > > Certainly not. If you look into the window resizing code you will see > that it treats internal and leaf windows alike. Changing the underlying > representation would have meant to double the work done there. It's clear that representing the non-leaf nodes as window objects was chosen because it's convenient from the implementation POV. But that doesn't mean we need to expose this to every place where we describe how windows are split and resized. > > So I think speaking about "nodes" instead will avoid confusion, > > because otherwise whenever we talk about a "window", the reader will > > always be in doubt whether this applies only to the "real", i.e. leaf > > windows, or to the "internal" ones as well. > > This is usually said in the second sentence of the doc-string. For > `split-window' it reads > > "WINDOW can be any window and defaults to the selected one." When J.R. Hacker reads about "any window", she will definitely have only live windows in mind. > And for `set-window-buffer' we have > > "WINDOW has to be a live window and defaults to the selected one." Which immediately begs the question "how can a window not be `live'"? > Let's not spoil this very simple recipe. Simple is in the eye of the beholder. And I was talking about the manual, not the doc strings, btw.
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 11:02:42 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 07:02:42 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJNjN-0003sF-OO
for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 07:02:42 -0400
Received: from fencepost.gnu.org ([140.186.70.10] ident=Debian-exim)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <eliz@HIDDEN>) id 1RJNjG-0003s0-GM
for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 07:02:36 -0400
Received: from eliz by fencepost.gnu.org with local (Exim 4.71)
(envelope-from <eliz@HIDDEN>)
id 1RJNhV-0003id-S8; Thu, 27 Oct 2011 07:00:45 -0400
Date: Thu, 27 Oct 2011 07:00:45 -0400
Message-Id: <E1RJNhV-0003id-S8@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
To: martin rudalics <rudalics@HIDDEN>
In-reply-to: <4EA929E6.9080001@HIDDEN> (message from martin rudalics on Thu,
27 Oct 2011 11:52:38 +0200)
Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree"
in ELisp manual
References: <E1RJ1tK-0002EG-F9@HIDDEN> <4EA817C9.9030000@HIDDEN>
<83y5w7bn2r.fsf@HIDDEN> <4EA929E6.9080001@HIDDEN>
X-Spam-Score: -6.6 (------)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
Reply-To: Eli Zaretskii <eliz@HIDDEN>
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -6.6 (------)
> Date: Thu, 27 Oct 2011 11:52:38 +0200
> From: martin rudalics <rudalics@HIDDEN>
> CC: 9875 <at> debbugs.gnu.org
>
> 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? 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.
> >> Many important functions like `split-window', `delete-window', the
> >> window resize functions, and obviously the new window tree functions
> >> including `walk-window-tree' apply to both live and internal windows.
> >
> > That's true, but it only makes the whole issue more confusing. I can
> > easily and intuitively understand the expected effect of splitting a
> > live window. But what does it mean to "split" a window that is not
> > displayed at all? I don't know, and the manual doesn't explain.
>
> The section on window splitting contains some five examples with
> drawings that explain what happens in this case. What more can I do?
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. 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.
> > It
> > only has this rather cryptic blurb:
> >
> > If WINDOW is live, properties of the new window like margins and
> > scroll bars are inherited from WINDOW. If WINDOW is an internal
> > window, these properties, as well as the buffer shown in the new
> > window, are inherited from the window selected on WINDOW's frame.
>
> What precisely is cryptic here?
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?
. 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?
. what other properties, besides margins and scroll bars are
inherited from the selected window?
. what buffer will be shown in the new window when WINDOW is a live
one?
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.
> > All the rest of the documentation of this function doesn't make any
> > sense for an "internal window"; the description can only be understood
> > in the context of a live window. Take this part, for example:
> >
> > If SIDE is `t' or `right' the new window will be positioned on the
> > right side of WINDOW. The value `left' means the new window will
> > be located on the left side of WINDOW. In both cases SIZE
> > specifies the new number of columns for WINDOW (or the new window
> > provided SIZE is negative) including space reserved for margins,
> > fringes and the scroll bar or a divider column.
> >
> > I cannot interpret this for a non-live window. I could try _guessing_
> > what this means in that case, but why should I need to guess when I'm
> > reading the manual?
>
> 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!
> > More importantly, does Joe R. Hacker, a casual Lisp programmer, really
> > need to know what this does to an "internal" window? And if he
> > doesn't, maybe we will be much better off not to include those
> > "internal" windows in the domain of these functions, simply by not
> > calling them "windows"?
>
> This means that Joe would not be able to split the root window of a
> frame, a thing I do quite frequently to get a live window at a side 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.
> > How can one _create_ a _new_ parent? A parent can only be a parent if
> > it has children. You can create children of an existing parent, but
> > you cannot create a _new_ parent for existing children. This is a
> > single most confusing sentence in this section. It doesn't help that
> > is also the most important sentence for understanding what window-nest
> > does.
>
> 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.
> >> Simply that functions accepting an internal window as argument would
> >> have to say "the argument can be a window or a node" which doesn't
> >> strike me as very constructive. In particular not so because I then
> >> would have to explain in the doc-string what a "node" is.
> >
> > I don't see any issue here. Just say, somewhere close to the end of
> > the doc string, something like "the argument WINDOW can also be a node
> > of the frame's window tree". It's very easy to understand.
>
> I suppose you make the implicit assumption that the leaves of a tree are
> not considered nodes of the tree.
Okay, "the argument WINDOW can also be a non-leaf node of the frame's
window tree", if you must.
> > I didn't suggest removing the information from the docs. I only asked
> > to (1) rename "internal windows" into "nodes of the window tree",
> > which is what they are,
>
> 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.
> Internal windows are elementary for understanding _how_ `split-window',
> `delete-window' and window resizing work.
Well, feel free to close this bug report, then. This old fart now
knows how to read these sections, although it will always cost me a
non-trivial effort to mentally translate the text into what I consider
the right representation of the ideas. I tried to explain why it
could be an obstacle for others. I obviously fail to convince you.
Maybe we should have a second opinion.
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 09:58:15 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 05:58:14 2011 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1RJMj0-0002KN-7k for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 05:58:14 -0400 Received: from mailout-de.gmx.net ([213.165.64.23]) by debbugs.gnu.org with smtp (Exim 4.69) (envelope-from <rudalics@HIDDEN>) id 1RJMix-0002KA-Ar for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 05:58:12 -0400 Received: (qmail invoked by alias); 27 Oct 2011 09:56:17 -0000 Received: from 62-47-54-146.adsl.highway.telekom.at (EHLO [62.47.54.146]) [62.47.54.146] by mail.gmx.net (mp041) with SMTP; 27 Oct 2011 11:56:17 +0200 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX19CYEw1VB5C4II9RzXn8B5lgWKrv0t16B3IoAfTvq xZXb8dKgYyF2JI Message-ID: <4EA92AC0.1040803@HIDDEN> Date: Thu, 27 Oct 2011 11:56:16 +0200 From: martin rudalics <rudalics@HIDDEN> User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) MIME-Version: 1.0 To: Eli Zaretskii <eliz@HIDDEN> Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual References: <E1RJ1tK-0002EG-F9@HIDDEN> <jwvd3dj2651.fsf-monnier+emacs@HIDDEN> <83zkgnbo50.fsf@HIDDEN> <jwvmxcnxupo.fsf-monnier+emacs@HIDDEN> <E1RJKNI-0005C0-47@HIDDEN> In-Reply-To: <E1RJKNI-0005C0-47@HIDDEN> Content-Type: text/plain; charset=ISO-8859-15; format=flowed Content-Transfer-Encoding: 7bit X-Y-GMX-Trusted: 0 X-Spam-Score: -2.5 (--) X-Debbugs-Envelope-To: 9875 Cc: 9875 <at> debbugs.gnu.org, Stefan Monnier <monnier@HIDDEN> X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Sender: debbugs-submit-bounces <at> debbugs.gnu.org Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org X-Spam-Score: -2.5 (--) > That's true, but this fact is an implementation detail; we could > easily have the nodes be different Lisp objects. Certainly not. If you look into the window resizing code you will see that it treats internal and leaf windows alike. Changing the underlying representation would have meant to double the work done there. > So I think speaking about "nodes" instead will avoid confusion, > because otherwise whenever we talk about a "window", the reader will > always be in doubt whether this applies only to the "real", i.e. leaf > windows, or to the "internal" ones as well. This is usually said in the second sentence of the doc-string. For `split-window' it reads "WINDOW can be any window and defaults to the selected one." And for `set-window-buffer' we have "WINDOW has to be a live window and defaults to the selected one." Let's not spoil this very simple recipe. martin
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 09:54:36 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 05:54:36 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJMfT-0002Eb-Sm
for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 05:54:36 -0400
Received: from mailout-de.gmx.net ([213.165.64.23])
by debbugs.gnu.org with smtp (Exim 4.69)
(envelope-from <rudalics@HIDDEN>) id 1RJMfS-0002EP-7N
for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 05:54:35 -0400
Received: (qmail invoked by alias); 27 Oct 2011 09:52:40 -0000
Received: from 62-47-54-146.adsl.highway.telekom.at (EHLO [62.47.54.146])
[62.47.54.146]
by mail.gmx.net (mp025) with SMTP; 27 Oct 2011 11:52:40 +0200
X-Authenticated: #14592706
X-Provags-ID: V01U2FsdGVkX1+tDb0j5yit9Wv/1JeBDbpIyB+JMre1wC1FIu5+jR
PHfk1+vKZz7t/d
Message-ID: <4EA929E6.9080001@HIDDEN>
Date: Thu, 27 Oct 2011 11:52:38 +0200
From: martin rudalics <rudalics@HIDDEN>
User-Agent: Thunderbird 2.0.0.21 (Windows/20090302)
MIME-Version: 1.0
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree"
in ELisp manual
References: <E1RJ1tK-0002EG-F9@HIDDEN> <4EA817C9.9030000@HIDDEN>
<83y5w7bn2r.fsf@HIDDEN>
In-Reply-To: <83y5w7bn2r.fsf@HIDDEN>
Content-Type: text/plain; charset=ISO-8859-15; format=flowed
Content-Transfer-Encoding: 7bit
X-Y-GMX-Trusted: 0
X-Spam-Score: -2.5 (--)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.5 (--)
>> > go wrong. The main problem is that the non-leaf nodes of the window
>> > tree are referred to as "windows",
>>
>> ... as "internal windows" more precisely ...
>
> No, as _windows_. Here's a typical example:
>
> All other windows of a frame with the exception of the minibuffer
> window are subwindows of the frame's root window. A window is
> considered a "subwindow" of another window if it occupies a part of
> that other window's screen area.
>
> The functions described next allow to access the members of a window
> tree and take an arbitrary window as argument.
>
> -- Function: window-parent &optional window
> Return WINDOW's parent in the window tree. The optional argument
> WINDOW can denote an arbitrary window and defaults to the selected
> one. The return value is `nil' if WINDOW is a minibuffer window
> or the root window of its frame and an internal window otherwise.
>
> Parent windows do not appear on the screen. The screen area of a
> parent window is the rectangular part of the window's frame occupied by
> the window's "child windows", that is, the set of windows having that
> window as their parent. Each parent window has at least two child
> windows, so there are no "Matryoshka" windows. Minibuffer windows do
> not have child windows.
>
> All this text freely talks about "windows" when it really means the
> nodes of the window tree.
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.
instead of
A node of the window tree or a live window are considered a
"subwindow" or "a subnode of the window tree" of a node of the window
tree if they occupy a part of that node's screen area.
>> Many important functions like `split-window', `delete-window', the
>> window resize functions, and obviously the new window tree functions
>> including `walk-window-tree' apply to both live and internal windows.
>
> That's true, but it only makes the whole issue more confusing. I can
> easily and intuitively understand the expected effect of splitting a
> live window. But what does it mean to "split" a window that is not
> displayed at all? I don't know, and the manual doesn't explain.
The section on window splitting contains some five examples with
drawings that explain what happens in this case. What more can I do?
> It
> only has this rather cryptic blurb:
>
> If WINDOW is live, properties of the new window like margins and
> scroll bars are inherited from WINDOW. If WINDOW is an internal
> window, these properties, as well as the buffer shown in the new
> window, are inherited from the window selected on WINDOW's frame.
What precisely is cryptic here?
> All the rest of the documentation of this function doesn't make any
> sense for an "internal window"; the description can only be understood
> in the context of a live window. Take this part, for example:
>
> If SIDE is `t' or `right' the new window will be positioned on the
> right side of WINDOW. The value `left' means the new window will
> be located on the left side of WINDOW. In both cases SIZE
> specifies the new number of columns for WINDOW (or the new window
> provided SIZE is negative) including space reserved for margins,
> fringes and the scroll bar or a divider column.
>
> I cannot interpret this for a non-live window. I could try _guessing_
> what this means in that case, but why should I need to guess when I'm
> reading the manual?
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".
Note that the present inheritance mechanism is annoying in the first
place because it makes us calculate the size of the new window based on
properties of the window to split. In at least one case this has made
me rewrite these calculations when a user wanted to split off a two
lines high window from a window with a headerline.
> More importantly, does Joe R. Hacker, a casual Lisp programmer, really
> need to know what this does to an "internal" window? And if he
> doesn't, maybe we will be much better off not to include those
> "internal" windows in the domain of these functions, simply by not
> calling them "windows"?
This means that Joe would not be able to split the root window of a
frame, a thing I do quite frequently to get a live window at a side of
the frame.
> How can one _create_ a _new_ parent? A parent can only be a parent if
> it has children. You can create children of an existing parent, but
> you cannot create a _new_ parent for existing children. This is a
> single most confusing sentence in this section. It doesn't help that
> is also the most important sentence for understanding what window-nest
> does.
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.
>> Simply that functions accepting an internal window as argument would
>> have to say "the argument can be a window or a node" which doesn't
>> strike me as very constructive. In particular not so because I then
>> would have to explain in the doc-string what a "node" is.
>
> I don't see any issue here. Just say, somewhere close to the end of
> the doc string, something like "the argument WINDOW can also be a node
> of the frame's window tree". It's very easy to understand.
I suppose you make the implicit assumption that the leaves of a tree are
not considered nodes of the tree. I do not understand that assumption.
Where did you get it from?
> I didn't suggest removing the information from the docs. I only asked
> to (1) rename "internal windows" into "nodes of the window tree",
> which is what they are,
This would be misleading. Live windows are also nodes of the window
tree.
> and (2) have a single section in the manual
> that describes the window tree and the functions that operate on it,
> instead of spreading that over several sections. The information you
> want that person to have will still be available. But it will be out
> of the way of all the other 99% of Lisp programmers who have no need
> to know all that, and don't need to be confused by these "internal"
> windows.
Internal windows are elementary for understanding _how_ `split-window',
`delete-window' and window resizing work.
martin
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 27 Oct 2011 07:29:31 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 27 03:29:31 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJKP5-0007Lr-2V
for submit <at> debbugs.gnu.org; Thu, 27 Oct 2011 03:29:31 -0400
Received: from fencepost.gnu.org ([140.186.70.10] ident=Debian-exim)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <eliz@HIDDEN>) id 1RJKP1-0007Lj-Hz
for 9875 <at> debbugs.gnu.org; Thu, 27 Oct 2011 03:29:28 -0400
Received: from eliz by fencepost.gnu.org with local (Exim 4.71)
(envelope-from <eliz@HIDDEN>)
id 1RJKNI-0005C0-47; Thu, 27 Oct 2011 03:27:40 -0400
Date: Thu, 27 Oct 2011 03:27:40 -0400
Message-Id: <E1RJKNI-0005C0-47@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
To: Stefan Monnier <monnier@HIDDEN>
In-reply-to: <jwvmxcnxupo.fsf-monnier+emacs@HIDDEN> (message from Stefan
Monnier on Wed, 26 Oct 2011 18:21:01 -0400)
Subject: Re: bug#9875: 24.0.90;
Confusing description of the "window tree" in ELisp manual
References: <E1RJ1tK-0002EG-F9@HIDDEN>
<jwvd3dj2651.fsf-monnier+emacs@HIDDEN> <83zkgnbo50.fsf@HIDDEN>
<jwvmxcnxupo.fsf-monnier+emacs@HIDDEN>
X-Spam-Score: -6.6 (------)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
Reply-To: Eli Zaretskii <eliz@HIDDEN>
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -6.6 (------)
> From: Stefan Monnier <monnier@HIDDEN>
> Cc: 9875 <at> debbugs.gnu.org
> Date: Wed, 26 Oct 2011 18:21:01 -0400
>
> >> I think the first step is to choose a single name for those, and then
> >> use it systematically. I think we should simply call "window" the
> >> traditional "real" "live" "leaf" windows that display a buffer. As for
> >> the other ones, we could go for "internal window", but I think "parent
> >> window" is better, tho maybe someone has a better idea ("compound
> >> window", "super window", ... ?)
>
> > How about "window tree node" or just "node"?
>
> Just "node" is much too vague for my taste.
I meant to use "node" only when "window tree node" was mentioned in
close proximity. For example:
-- User Option: window-nest
If this variable is `nil', `split-window' creates a new node in
the window tree if and only if the old window had no parent node
or shall be split orthogonally to the combination it is part of.
If this variable is non-`nil', `split-window' always creates a
new node that becomes the parent node of the new window. If this
variable is always non-`nil', a frame's window tree is a binary
tree so every node in the tree but the frame's window tree root
has exactly one sibling node.
Compare this with what's currently in the manual:
-- User Option: window-nest
If this variable is `nil', `split-window' creates a new parent
window if and only if the old window has no parent window or shall
be split orthogonally to the combination it is part of. If this
variable is non-`nil', `split-window' always creates a new parent
window. If this variable is always non-`nil', a frame's window
tree is a binary tree so every window but the frame's root window
has exactly one sibling.
> "Window tree node" is a bit better but doesn't make it clear it's
> not a leaf and is a window object.
We will make that clear in the section where we describe the window
tree. Once explained, it doesn't need to be mentioned again, if we
abstain as much as possible from mentioning the nodes of the tree in
other sections.
> For that reason I prefer "window parent".
That sounds mysterious, since it remains unclear what kind of thing is
this "parent". "Parent node of the window" or "window's parent node"
is better.
> > That's what they are, right?
>
> They aren't just "node" (i.e. some intermediate element pointing to
> others), they have most properties of windows, such as sizes and
> positions (tho they don't display any buffer).
That's true, but this fact is an implementation detail; we could
easily have the nodes be different Lisp objects. E.g., some of the
attributes without which a live window is unthinkable are nil in these
"windows". And it doesn't help that we don't say anywhere which
window attributes are non-trivially relevant to these "internal
windows".
So I think speaking about "nodes" instead will avoid confusion,
because otherwise whenever we talk about a "window", the reader will
always be in doubt whether this applies only to the "real", i.e. leaf
windows, or to the "internal" ones as well.
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 26 Oct 2011 22:22:56 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Oct 26 18:22:56 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJBs7-0001kk-24
for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 18:22:56 -0400
Received: from ironport2-out.teksavvy.com ([206.248.154.183]
helo=ironport2-out.pppoe.ca)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <monnier@HIDDEN>) id 1RJBs4-0001kT-7M
for 9875 <at> debbugs.gnu.org; Wed, 26 Oct 2011 18:22:53 -0400
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: Ak0JAEOHqE5MCrTo/2dsb2JhbABCqD+BD4EGgW4BAQQBViMFCws0EhQYDSSIE7VBiGoEoUCERQ
X-IronPort-AV: E=Sophos;i="4.69,411,1315195200"; d="scan'208";a="144656438"
Received: from 76-10-180-232.dsl.teksavvy.com (HELO pastel.home)
([76.10.180.232])
by ironport2-out.pppoe.ca with ESMTP/TLS/ADH-AES256-SHA;
26 Oct 2011 18:21:01 -0400
Received: by pastel.home (Postfix, from userid 20848)
id 5B6D959011; Wed, 26 Oct 2011 18:21:01 -0400 (EDT)
From: Stefan Monnier <monnier@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90;
Confusing description of the "window tree" in ELisp manual
Message-ID: <jwvmxcnxupo.fsf-monnier+emacs@HIDDEN>
References: <E1RJ1tK-0002EG-F9@HIDDEN>
<jwvd3dj2651.fsf-monnier+emacs@HIDDEN> <83zkgnbo50.fsf@HIDDEN>
Date: Wed, 26 Oct 2011 18:21:01 -0400
In-Reply-To: <83zkgnbo50.fsf@HIDDEN> (Eli Zaretskii's message of "Wed, 26 Oct
2011 20:31:39 +0200")
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.90 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -2.7 (--)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.7 (--)
>> I think the first step is to choose a single name for those, and then
>> use it systematically. I think we should simply call "window" the
>> traditional "real" "live" "leaf" windows that display a buffer. As for
>> the other ones, we could go for "internal window", but I think "parent
>> window" is better, tho maybe someone has a better idea ("compound
>> window", "super window", ... ?)
> How about "window tree node" or just "node"?
Just "node" is much too vague for my taste. "Window tree node" is a bit
better but doesn't make it clear it's not a leaf and is a window object.
For that reason I prefer "window parent".
> That's what they are, right?
They aren't just "node" (i.e. some intermediate element pointing to
others), they have most properties of windows, such as sizes and
positions (tho they don't display any buffer).
Stefan
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 26 Oct 2011 18:56:52 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Oct 26 14:56:52 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJ8ei-0002y2-Ko
for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 14:56:52 -0400
Received: from mtaout20.012.net.il ([80.179.55.166])
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <eliz@HIDDEN>) id 1RJ8ef-0002xo-ME
for 9875 <at> debbugs.gnu.org; Wed, 26 Oct 2011 14:56:51 -0400
Received: from conversion-daemon.a-mtaout20.012.net.il by
a-mtaout20.012.net.il (HyperSendmail v2007.08) id
<0LTO00N00SGB4V00@HIDDEN> for
9875 <at> debbugs.gnu.org; Wed, 26 Oct 2011 20:54:29 +0200 (IST)
Received: from HOME-C4E4A596F7 ([77.124.212.197]) by a-mtaout20.012.net.il
(HyperSendmail v2007.08) with ESMTPA id
<0LTO00MXGSISSF50@HIDDEN>;
Wed, 26 Oct 2011 20:54:29 +0200 (IST)
Date: Wed, 26 Oct 2011 20:54:36 +0200
From: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90;
Confusing description of the "window tree" in ELisp manual
In-reply-to: <4EA817C9.9030000@HIDDEN>
X-012-Sender: halo1@HIDDEN
To: martin rudalics <rudalics@HIDDEN>
Message-id: <83y5w7bn2r.fsf@HIDDEN>
References: <E1RJ1tK-0002EG-F9@HIDDEN> <4EA817C9.9030000@HIDDEN>
X-Spam-Score: -2.1 (--)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
Reply-To: Eli Zaretskii <eliz@HIDDEN>
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.1 (--)
> Date: Wed, 26 Oct 2011 16:23:05 +0200
> From: martin rudalics <rudalics@HIDDEN>
> CC: 9875 <at> debbugs.gnu.org
>
> > This node starts fine, by describing window-frame and window-list.
> > Then it begins to describe the "window tree", and that's where things
> > go wrong. The main problem is that the non-leaf nodes of the window
> > tree are referred to as "windows",
>
> ... as "internal windows" more precisely ...
No, as _windows_. Here's a typical example:
All other windows of a frame with the exception of the minibuffer
window are subwindows of the frame's root window. A window is
considered a "subwindow" of another window if it occupies a part of
that other window's screen area.
The functions described next allow to access the members of a window
tree and take an arbitrary window as argument.
-- Function: window-parent &optional window
Return WINDOW's parent in the window tree. The optional argument
WINDOW can denote an arbitrary window and defaults to the selected
one. The return value is `nil' if WINDOW is a minibuffer window
or the root window of its frame and an internal window otherwise.
Parent windows do not appear on the screen. The screen area of a
parent window is the rectangular part of the window's frame occupied by
the window's "child windows", that is, the set of windows having that
window as their parent. Each parent window has at least two child
windows, so there are no "Matryoshka" windows. Minibuffer windows do
not have child windows.
All this text freely talks about "windows" when it really means the
nodes of the window tree.
> Many important functions like `split-window', `delete-window', the
> window resize functions, and obviously the new window tree functions
> including `walk-window-tree' apply to both live and internal windows.
That's true, but it only makes the whole issue more confusing. I can
easily and intuitively understand the expected effect of splitting a
live window. But what does it mean to "split" a window that is not
displayed at all? I don't know, and the manual doesn't explain. It
only has this rather cryptic blurb:
If WINDOW is live, properties of the new window like margins and
scroll bars are inherited from WINDOW. If WINDOW is an internal
window, these properties, as well as the buffer shown in the new
window, are inherited from the window selected on WINDOW's frame.
All the rest of the documentation of this function doesn't make any
sense for an "internal window"; the description can only be understood
in the context of a live window. Take this part, for example:
If SIDE is `t' or `right' the new window will be positioned on the
right side of WINDOW. The value `left' means the new window will
be located on the left side of WINDOW. In both cases SIZE
specifies the new number of columns for WINDOW (or the new window
provided SIZE is negative) including space reserved for margins,
fringes and the scroll bar or a divider column.
I cannot interpret this for a non-live window. I could try _guessing_
what this means in that case, but why should I need to guess when I'm
reading the manual?
More importantly, does Joe R. Hacker, a casual Lisp programmer, really
need to know what this does to an "internal" window? And if he
doesn't, maybe we will be much better off not to include those
"internal" windows in the domain of these functions, simply by not
calling them "windows"?
> > The confusion
> > culminates in "Splitting Windows", where many issues are described via
> > window-parent and what is called "creating a new parent".
>
> Yes. And I probably gave too many examples for this in the expectation
> that readers would study them and get a feeling for what internal
> windows are needed for. But what is the culminating confusion here?
> Could you provide at least one example?
How can one _create_ a _new_ parent? A parent can only be a parent if
it has children. You can create children of an existing parent, but
you cannot create a _new_ parent for existing children. This is a
single most confusing sentence in this section. It doesn't help that
is also the most important sentence for understanding what window-nest
does.
> > I submit these confusing references to the nodes of the window tree as
> > "windows" should be removed. If we want to talk about the window
> > tree, let's talk about a tree with nodes; let's not call them
> > "windows". I know that each node is exposed to Lisp as a window
> > object, but (a) I'm not sure this is a good idea either, and (b) what
> > harm will be done if we mention this factoid in some place and
> > immediately forget about it?
>
> Simply that functions accepting an internal window as argument would
> have to say "the argument can be a window or a node" which doesn't
> strike me as very constructive. In particular not so because I then
> would have to explain in the doc-string what a "node" is.
I don't see any issue here. Just say, somewhere close to the end of
the doc string, something like "the argument WINDOW can also be a node
of the frame's window tree". It's very easy to understand.
> Let's take an example: I wrote two functions called `window-state-get'
> and `window-state-put' in the hope that eventually someone uses these
> functions in order to write window configurations to a file and reuse
> them in a later session. If we find someone to do that, that person
> must be interested in internal windows, because these are part of the
> state and prescribe how to obtain the original configuration from that
> state. Debugging or patching these functions without knowing about
> internal windows is virtually impossible.
I didn't suggest removing the information from the docs. I only asked
to (1) rename "internal windows" into "nodes of the window tree",
which is what they are, and (2) have a single section in the manual
that describes the window tree and the functions that operate on it,
instead of spreading that over several sections. The information you
want that person to have will still be available. But it will be out
of the way of all the other 99% of Lisp programmers who have no need
to know all that, and don't need to be confused by these "internal"
windows.
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 26 Oct 2011 18:33:46 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Oct 26 14:33:46 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJ8IM-0002QK-ID
for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 14:33:46 -0400
Received: from mtaout22.012.net.il ([80.179.55.172])
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <eliz@HIDDEN>) id 1RJ8IL-0002Q7-CA
for 9875 <at> debbugs.gnu.org; Wed, 26 Oct 2011 14:33:45 -0400
Received: from conversion-daemon.a-mtaout22.012.net.il by
a-mtaout22.012.net.il (HyperSendmail v2007.08) id
<0LTO00F00RECU500@HIDDEN> for
9875 <at> debbugs.gnu.org; Wed, 26 Oct 2011 20:31:32 +0200 (IST)
Received: from HOME-C4E4A596F7 ([77.124.212.197]) by a-mtaout22.012.net.il
(HyperSendmail v2007.08) with ESMTPA id
<0LTO00F1ORGJSE20@HIDDEN>;
Wed, 26 Oct 2011 20:31:32 +0200 (IST)
Date: Wed, 26 Oct 2011 20:31:39 +0200
From: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90;
Confusing description of the "window tree" in ELisp manual
In-reply-to: <jwvd3dj2651.fsf-monnier+emacs@HIDDEN>
X-012-Sender: halo1@HIDDEN
To: Stefan Monnier <monnier@HIDDEN>
Message-id: <83zkgnbo50.fsf@HIDDEN>
References: <E1RJ1tK-0002EG-F9@HIDDEN>
<jwvd3dj2651.fsf-monnier+emacs@HIDDEN>
X-Spam-Score: -2.1 (--)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
Reply-To: Eli Zaretskii <eliz@HIDDEN>
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.1 (--)
> From: Stefan Monnier <monnier@HIDDEN>
> Cc: 9875 <at> debbugs.gnu.org
> Date: Wed, 26 Oct 2011 10:17:18 -0400
>
> I think the first step is to choose a single name for those, and then
> use it systematically. I think we should simply call "window" the
> traditional "real" "live" "leaf" windows that display a buffer. As for
> the other ones, we could go for "internal window", but I think "parent
> window" is better, tho maybe someone has a better idea ("compound
> window", "super window", ... ?)
How about "window tree node" or just "node"? That's what they are,
right?
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.Received: (at 9875) by debbugs.gnu.org; 26 Oct 2011 14:25:00 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Wed Oct 26 10:25:00 2011 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1RJ4Pc-00054n-3Z for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 10:25:00 -0400 Received: from mailout-de.gmx.net ([213.165.64.23]) by debbugs.gnu.org with smtp (Exim 4.69) (envelope-from <rudalics@HIDDEN>) id 1RJ4PX-00054M-DE for 9875 <at> debbugs.gnu.org; Wed, 26 Oct 2011 10:24:57 -0400 Received: (qmail invoked by alias); 26 Oct 2011 14:23:05 -0000 Received: from 62-47-39-90.adsl.highway.telekom.at (EHLO [62.47.39.90]) [62.47.39.90] by mail.gmx.net (mp067) with SMTP; 26 Oct 2011 16:23:05 +0200 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX195OnE0/JR50ihxIkg/Bz1A84R3Q4LKyumGKv42Qf IyVl7tmQza8Tdp Message-ID: <4EA817C9.9030000@HIDDEN> Date: Wed, 26 Oct 2011 16:23:05 +0200 From: martin rudalics <rudalics@HIDDEN> User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) MIME-Version: 1.0 To: Eli Zaretskii <eliz@HIDDEN> Subject: Re: bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual References: <E1RJ1tK-0002EG-F9@HIDDEN> In-Reply-To: <E1RJ1tK-0002EG-F9@HIDDEN> Content-Type: text/plain; charset=ISO-8859-15; format=flowed Content-Transfer-Encoding: 7bit X-Y-GMX-Trusted: 0 X-Spam-Score: -2.5 (--) X-Debbugs-Envelope-To: 9875 Cc: 9875 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Sender: debbugs-submit-bounces <at> debbugs.gnu.org Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org X-Spam-Score: -2.5 (--) > This node starts fine, by describing window-frame and window-list. > Then it begins to describe the "window tree", and that's where things > go wrong. The main problem is that the non-leaf nodes of the window > tree are referred to as "windows", ... as "internal windows" more precisely ... > which makes it all too easy to > confuse them with the leafs of the window tree, each one of which > corresponds to a real live window displayed on the frame. This is > fundamentally wrong, because there's a significant difference between > the "normal" (a.k.a. "live") windows and the nodes of the window > tree. Many important functions like `split-window', `delete-window', the window resize functions, and obviously the new window tree functions including `walk-window-tree' apply to both live and internal windows. > The confusion thereafter continues in the next sections of the > "Windows" chapter, as these "windows" are sometimes called "internal > windows", sometimes contrasted with "live" windows. Hopefully wherever such a contrast is required. > The confusion > culminates in "Splitting Windows", where many issues are described via > window-parent and what is called "creating a new parent". Yes. And I probably gave too many examples for this in the expectation that readers would study them and get a feeling for what internal windows are needed for. But what is the culminating confusion here? Could you provide at least one example? > I submit these confusing references to the nodes of the window tree as > "windows" should be removed. If we want to talk about the window > tree, let's talk about a tree with nodes; let's not call them > "windows". I know that each node is exposed to Lisp as a window > object, but (a) I'm not sure this is a good idea either, and (b) what > harm will be done if we mention this factoid in some place and > immediately forget about it? Simply that functions accepting an internal window as argument would have to say "the argument can be a window or a node" which doesn't strike me as very constructive. In particular not so because I then would have to explain in the doc-string what a "node" is. > I guess what I'm saying is this: let's have a single section named > "The Window Tree" which describes the tree and what can be done with > its nodes from a Lisp program, and let's describe all the other > window-related operations without any reference to the tree or its > nodes. I submit that most Lisp programmers will never need to go to > the level of the tree, unless they want to understand the internal > operation of windows.el or rewrite it from scratch. Given the fact that a function like `frame-root-window' (which would return a "node" in your parlance whenever we have two live windows) is in Emacs since 1992 at least and a documentation of that function has been reqeusted recently here on this forum, I suppose that at least some Lisp programmers need to go to the level of the tree. Let's take an example: I wrote two functions called `window-state-get' and `window-state-put' in the hope that eventually someone uses these functions in order to write window configurations to a file and reuse them in a later session. If we find someone to do that, that person must be interested in internal windows, because these are part of the state and prescribe how to obtain the original configuration from that state. Debugging or patching these functions without knowing about internal windows is virtually impossible. martin
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
Received: (at 9875) by debbugs.gnu.org; 26 Oct 2011 14:19:09 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Oct 26 10:19:09 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1RJ4Jx-0004wi-J6
for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 10:19:09 -0400
Received: from ironport2-out.teksavvy.com ([206.248.154.181]
helo=ironport2-out.pppoe.ca)
by debbugs.gnu.org with esmtp (Exim 4.69)
(envelope-from <monnier@HIDDEN>) id 1RJ4Ju-0004wK-RK
for 9875 <at> debbugs.gnu.org; Wed, 26 Oct 2011 10:19:08 -0400
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: Ak0JAHoVqE5MCrTo/2dsb2JhbABCqC+BD4EGgW4BAQQBViMFCws0EhQYDSSIE7ULiGoEoUCERQ
X-IronPort-AV: E=Sophos;i="4.69,409,1315195200"; d="scan'208";a="144559990"
Received: from 76-10-180-232.dsl.teksavvy.com (HELO pastel.home)
([76.10.180.232])
by ironport2-out.pppoe.ca with ESMTP/TLS/ADH-AES256-SHA;
26 Oct 2011 10:17:18 -0400
Received: by pastel.home (Postfix, from userid 20848)
id 0A42E58BBC; Wed, 26 Oct 2011 10:17:18 -0400 (EDT)
From: Stefan Monnier <monnier@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#9875: 24.0.90;
Confusing description of the "window tree" in ELisp manual
Message-ID: <jwvd3dj2651.fsf-monnier+emacs@HIDDEN>
References: <E1RJ1tK-0002EG-F9@HIDDEN>
Date: Wed, 26 Oct 2011 10:17:18 -0400
In-Reply-To: <E1RJ1tK-0002EG-F9@HIDDEN> (Eli Zaretskii's message of
"Wed, 26 Oct 2011 07:43:30 -0400")
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.90 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -2.7 (--)
X-Debbugs-Envelope-To: 9875
Cc: 9875 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.7 (--)
> This node starts fine, by describing window-frame and window-list.
> Then it begins to describe the "window tree", and that's where things
> go wrong. The main problem is that the non-leaf nodes of the window
> tree are referred to as "windows", which makes it all too easy to
> confuse them with the leafs of the window tree, each one of which
I think the first step is to choose a single name for those, and then
use it systematically. I think we should simply call "window" the
traditional "real" "live" "leaf" windows that display a buffer. As for
the other ones, we could go for "internal window", but I think "parent
window" is better, tho maybe someone has a better idea ("compound
window", "super window", ... ?)
Stefan
bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.Received: (at submit) by debbugs.gnu.org; 26 Oct 2011 11:45:27 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Wed Oct 26 07:45:27 2011 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1RJ1vD-0001Mx-5n for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 07:45:27 -0400 Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <eliz@HIDDEN>) id 1RJ1vA-0001Mk-59 for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 07:45:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from <eliz@HIDDEN>) id 1RJ1tO-0007Vy-Va for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 07:43:36 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-3.4 required=5.0 tests=ALL_TRUSTED,BAYES_00, RP_MATCHES_RCVD autolearn=unavailable version=3.3.1 Received: from lists.gnu.org ([140.186.70.17]:34914) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <eliz@HIDDEN>) id 1RJ1tO-0007Ve-Ty for submit <at> debbugs.gnu.org; Wed, 26 Oct 2011 07:43:34 -0400 Received: from eggs.gnu.org ([140.186.70.92]:45760) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <eliz@HIDDEN>) id 1RJ1tM-0004VD-9H for bug-gnu-emacs@HIDDEN; Wed, 26 Oct 2011 07:43:34 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from <eliz@HIDDEN>) id 1RJ1tK-0007Pw-MZ for bug-gnu-emacs@HIDDEN; Wed, 26 Oct 2011 07:43:32 -0400 Received: from fencepost.gnu.org ([140.186.70.10]:47023) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <eliz@HIDDEN>) id 1RJ1tK-0007Ps-Kt for bug-gnu-emacs@HIDDEN; Wed, 26 Oct 2011 07:43:30 -0400 Received: from eliz by fencepost.gnu.org with local (Exim 4.71) (envelope-from <eliz@HIDDEN>) id 1RJ1tK-0002EG-F9 for bug-gnu-emacs@HIDDEN; Wed, 26 Oct 2011 07:43:30 -0400 Date: Wed, 26 Oct 2011 07:43:30 -0400 Message-Id: <E1RJ1tK-0002EG-F9@HIDDEN> From: Eli Zaretskii <eliz@HIDDEN> To: bug-gnu-emacs@HIDDEN Subject: 24.0.90; Confusing description of the "window tree" in ELisp manual X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.17 X-Spam-Score: -6.6 (------) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Reply-To: Eli Zaretskii <eliz@HIDDEN> List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Sender: debbugs-submit-bounces <at> debbugs.gnu.org Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org X-Spam-Score: -6.6 (------) emacs -Q C-h i m elisp RET g Windows and Frames RET This node starts fine, by describing window-frame and window-list. Then it begins to describe the "window tree", and that's where things go wrong. The main problem is that the non-leaf nodes of the window tree are referred to as "windows", which makes it all too easy to confuse them with the leafs of the window tree, each one of which corresponds to a real live window displayed on the frame. This is fundamentally wrong, because there's a significant difference between the "normal" (a.k.a. "live") windows and the nodes of the window tree. The confusion thereafter continues in the next sections of the "Windows" chapter, as these "windows" are sometimes called "internal windows", sometimes contrasted with "live" windows. The confusion culminates in "Splitting Windows", where many issues are described via window-parent and what is called "creating a new parent". I submit these confusing references to the nodes of the window tree as "windows" should be removed. If we want to talk about the window tree, let's talk about a tree with nodes; let's not call them "windows". I know that each node is exposed to Lisp as a window object, but (a) I'm not sure this is a good idea either, and (b) what harm will be done if we mention this factoid in some place and immediately forget about it? I guess what I'm saying is this: let's have a single section named "The Window Tree" which describes the tree and what can be done with its nodes from a Lisp program, and let's describe all the other window-related operations without any reference to the tree or its nodes. I submit that most Lisp programmers will never need to go to the level of the tree, unless they want to understand the internal operation of windows.el or rewrite it from scratch. In GNU Emacs 24.0.90.87 (x86_64-unknown-linux-gnu, GTK+ Version 2.20.1) of 2011-10-26 on fencepost.gnu.org configured using `configure '--enable-asserts' '--enable-checking' '--with-gif=no' '--with-tiff=no' 'CFLAGS=-ggdb -g3 -O0 -DGLYPH_DEBUG=1'' Important settings: value of $LC_ALL: nil value of $LC_COLLATE: nil value of $LC_CTYPE: nil value of $LC_MESSAGES: nil value of $LC_MONETARY: nil value of $LC_NUMERIC: nil value of $LC_TIME: nil value of $LANG: nil value of $XMODIFIERS: nil locale-coding-system: nil default enable-multibyte-characters: t Major mode: RMAIL Minor modes in effect: shell-dirtrack-mode: t display-time-mode: t show-paren-mode: t savehist-mode: t tooltip-mode: t mouse-wheel-mode: t tool-bar-mode: t menu-bar-mode: t file-name-shadow-mode: t global-font-lock-mode: t font-lock-mode: t auto-composition-mode: t auto-encryption-mode: t auto-compression-mode: t line-number-mode: t Recent input: ESC O A ESC O A ESC O A ESC O A ESC O A ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O D ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B C-e SPC a b o u t ESC q ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC < C-c C-c d C-u 1 0 2 2 j C-x C-s ESC ! ESC O A RET ESC x ESC O A RET ESC O A ESC O A ESC O A RET C-s 0 6 : 2 0 : 1 4 C-s C-s ESC O B ESC [ 6 ~ ESC O A ESC O B C-x C-x C-w C-x C-s C-x k RET C-u g ESC O A RET SPC C-z C-z C-z C-z d SPC SPC d d d d SPC d d d d d d d d d C-x C-s C-x b RET ESC < u ESC O A ESC O A ESC O A ESC O A RET SPC SPC SPC SPC SPC SPC C-x b RET ESC x r e p o r t - e m TAB RET Recent messages: Computing summary lines...done 14 new messages read Showing message 1025 Showing message 1025...done Showing message 1036 Showing message 1036...done No following nondeleted message Saving file /home/e/eliz/INBOX... Wrote /home/e/eliz/INBOX [2 times] Mark set Load-path shadows: None found. Features: (shadow emacsbug iso-transl info multi-isearch pp help-mode view help-fns dabbrev newcomment flyspell ispell shell pcomplete comint ring rmailsum qp rmailmm message sendmail regexp-opt format-spec rfc822 mml easymenu mml-sec mm-decode mm-bodies mm-encode mailabbrev gmm-utils mailheader mail-parse rfc2231 rmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils time paren cus-start cus-load time-date savehist saveplace tooltip ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image fringe lisp-mode register page menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak czech european ethiopic indian cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev minibuffer loaddefs button faces cus-face files text-properties overlay sha1 md5 base64 format env code-pages mule custom widget hashtable-print-readable backquote make-network-process dynamic-setting font-render-setting move-toolbar gtk x-toolkit x multi-tty emacs)
Eli Zaretskii <eliz@HIDDEN>:bug-gnu-emacs@HIDDEN.
Full text available.bug-gnu-emacs@HIDDEN:bug#9875; Package emacs.
Full text available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997 nCipher Corporation Ltd,
1994-97 Ian Jackson.